Skip to content
KN-86 Deckline

emacs-request

What it is

Section titled “What it is”

emacs-request is the long-standing async HTTP library for Emacs. It abstracts over two transport backends (curl for speed and feature completeness; url.el for pure-Emacs no-external-dependency operation) behind a single ergonomic API: request "URL" :type "GET" :parser 'json-read :success (cl-function (lambda (&key data &allow-other-keys) ...)). Parsers for JSON, XML, plain text; configurable timeouts; cookie jars; multipart form upload; OAuth-friendly header injection. Asynchronous by default — the callback fires when the response arrives.

For KN-86 this is the reference pattern for “Lisp-driven async HTTP from inside the runtime” — the pattern the embedded Lisp scripting layer (per the Batch-4 synthesis recommendation) needs to support if carts are ever to fetch live data.

Key takeaways for KN-86

Section titled “Key takeaways for KN-86”
  • Async HTTP as a Lisp primitive surface. When KN-86 carts need live data (a CIPHER feed updated from a remote service, mission-template updates, an optional weather/news ambient surface), the request-response pattern needs to be exposed through NoshAPI as async Lisp — not blocking, not main-thread. emacs-request’s API shape (:type :parser :success :error :timeout) is the right level of abstraction for the NoshAPI primitive.
  • Pluggable backends matter. emacs-request supports both curl and url.el because some users want pure-Emacs (no curl required) and some users want speed. KN-86’s analog: the on-device runtime should support both a system curl invocation (when wifi is available and the Pi has the binary) and a pure-runtime HTTP client (a small implementation built into nOSh, fewer dependencies, no shell-out). The Lisp-facing surface is the same; the backend is configurable.
  • Built-in parsers for common content types. JSON, XML, plain text. KN-86 should ship at minimum: JSON parsing (carts will use it), CSV parsing (cheap, useful for ambient data sources), and plain text. CIPHER fragments fetched as plain text from a remote service is the canonical example.
  • Cookie jars + OAuth headers + multipart form upload. Probably not v0.1 KN-86 (no need for auth-mediated data sources on launch), but the API surface should make these extensible — a :headers keyword arg that takes an alist of HTTP headers is sufficient to express OAuth-flavored requests without baking OAuth knowledge into the runtime.
  • Async callbacks vs. promises. emacs-request uses callbacks (:success + :error). KEC Lisp on KN-86 can adopt the same shape — (request "URL" :type 'GET :on-success (lambda (data) ...)). No need for a promise/future system at this layer; cart code is small enough that callbacks are clearer than abstraction.

Image

Section titled “Image”

No image downloaded.

Notes

Section titled “Notes”
  • Direct citation for ADR-0005’s prior-art section when scoping NoshAPI HTTP primitives.
  • Cross-link [emacs-request → cart-pattern]: the cart that consumes an ambient CIPHER feed from a remote service is the canonical “async data fetch + render” example. A reference cart in the SDK demonstrating the pattern is high-value documentation.
  • Cross-link worldmonitor.md — worldmonitor is “what you can do with massive data fetching at scale.” emacs-request is “the pattern that gets you the first byte over the wire.” Same problem, different scales.
  • Cross-link nba-go.md — nba-go is a Node working example of fetch upstream, parse, render. emacs-request is the Lisp-side reference for the same pattern.
  • Open question for ADR scoping: how does the runtime gate network access for carts? A cart with no business making external requests shouldn’t be silently capable of doing so. A capability-token approach (the cart declares what services it wants to reach in its manifest; the runtime enforces) is the right shape but is out-of-scope for v0.1. Park.