vaelii.impl.serve — com.vaelii/vaelii 0.13.0

Headless EDN-over-HTTP daemon: one JVM owns one KB and serves it to remote clients (vaelii.impl.client). A thin reitit-ring + jetty layer over vaelii.core, the network dual of the in-process API.

Wire format is EDN. A sentence is a symbol s-expression — (dog Muffet), ?x, (genl dog animal) — which EDN round-trips losslessly; JSON would mangle the symbols. The body of every call is {:op <keyword> :args [...]}, and the reply is {:ok true :result …} or {:ok false :error "…"}. EDN is read with clojure.edn/read-string (never clojure.core/read-string), so an untrusted body cannot evaluate code — EDN has no reader-eval.

A refusal's :type is a plain keyword — :body-too-large, :not-edn, :cross-origin, :bad-host — and so is the :type an engine ex-info carries through. The protocol is what a client written against another build discriminates on, so it cannot be qualified by the namespace that happens to serve it: a ::-qualified keyword names this namespace, and a client matching on it would be matching on where the daemon's code lives.

The daemon is the single writer (docs/storage.md, the single-writer contract): it owns the one process allowed to mutate the store, so it serializes every op through one monitor. Concurrent client writes therefore apply one at a time and cannot interleave; reads pay the same lock, which is conservative but keeps the contract simple.

Only the allowlisted ops are reachable (ops). Each is a vaelii.core fn with the KB supplied by the daemon — the client sends only the op and the remaining args — so no client can reach an arbitrary var. Sentex records in a result are projected to plain maps before they hit the wire (the sentex-map contract), so the client reads them back without the impl record class.

The change feed is the one thing that is not a vaelii.core fn (feed-ops), and it is a table of its own for that reason: core/watch takes a callback, so what a remote caller holds open instead is a subscription with a cursor — :watch, :poll, :unwatch, :watchers, over the per-handler registry app builds (vaelii.impl.subscribe, docs/feed.md). A :poll that waits runs outside the monitor; everything else about them is an ordinary EDN op.

One shared bearer token authenticates the caller. With VAELII_API_TOKEN set (guard/api-token), every request presents Authorization: Bearer <token> or is answered 401 with a WWW-Authenticate: Bearer challenge; GET /health is the one route that answers without it. One token for the process, not a session and not an identity — per-caller identity is a reverse proxy's job, and this is the check that has to exist below it. Binding anything but loopback requires a token (-main refuses to start otherwise); on the loopback default it is optional, and a daemon without one is drivable by every process on the machine.

vaelii.impl.guard covers what a token does not, and matters most on the open loopback daemon: POST /op requires Content-Type: application/edn, refuses a cross-origin Origin, and answers only to a Host naming the interface it was started on. Together those stop a page the operator happens to visit from driving the KB over loopback — which binding to loopback alone does not.

-main clj

(-main & args)

Run the daemon in the foreground. Args: [port [dir]] [--listen ADDR], in any order — dir selects the durable :disk-log backend (recovered on open, so it persists across restarts); with no dir the KB is in-memory and lives only as long as the process.

lein run -m vaelii.impl.serve 4200 /var/lib/vaelii lein run -m vaelii.impl.serve 4200 /var/lib/vaelii --listen 0.0.0.0 ; opt-in

It binds loopback unless --listen says otherwise, for the reason on loopback above: POST /op writes, and it is the KB's only writer. What it binds and what it requires are one decision (auth-posture), so they are stated together:

• --listen names a non-loopback address ⇒ VAELII_API_TOKEN is required. Without one it is a line on stderr and exit 2, a code of its own so a supervisor tells a missing credential from the configuration typos below.
• Loopback — the default, and --listen 127.0.0.1 said out loud — ⇒ the token is used when set, and its absence is a startup warning naming the flag that would require one.

Naming an address also drops the Host allowlist (guard/allowed-hosts), since the name you reach it by is then yours to know; set VAELII_ALLOWED_HOSTS to keep the check. Left unset, the daemon starts anyway — a reverse proxy setting its own Host needs exactly this — and host-posture turns the gap into a startup warning rather than a silence. A --listen with no address, an unknown flag, or a stray argument is one line and exit 1, like the port typo below.

app clj

(app kb)

(app kb {:keys [host] :or {host loopback} :as opts})

The ring handler for a KB — pure request -> response, so it is tested without a socket. One monitor per handler serializes the ops (the single-writer contract).

:host names the interface this handler will be served on, which fixes the Host values it answers to (guard/allowed-hosts). On the loopback default that refuses a rebound DNS name, the one attack same-origin? cannot see.

:token is the shared bearer token every request must present. Omitted, it is VAELII_API_TOKEN (guard/api-token), so a daemon and a client on one host agree without either being configured; an explicit nil serves open, which is what a test of the other refusals needs — a handler that 401s first exercises none of them.

feed-ops clj

The change-feed operations, keyed by op keyword — (fn [ctx args]) over a ctx of {:kb :registry :monitor}.

Each says its own relationship to the daemon's write monitor, which is the one thing about them that is not like an engine op. :watch and :unwatch take it: they are instantaneous, and taking it makes the boundary exact — every settle that finished before a :watch returned is outside the subscription's feed, and every one that starts after it is inside. :poll must not, because a long poll parks: inside the monitor it would block every writer for the duration of its wait, turning a feature about liveness into a global stall. :watchers does not either — it reads the registry and expires what has expired, and a listing that had to queue behind a bulk load is a listing an operator asks for while the daemon is busy.

http-threads clj

How many worker threads the daemon's HTTP server runs.

Stated rather than defaulted, because it is one half of a pair: a parked long poll holds one of these for the length of its wait, so subscribe/max-parked has to stay well under it or the feature that exists for liveness becomes the thing that stalls the daemon. Left implicit the two numbers were 50 and 64, the wrong way round, and nothing said so — 55 parked polls took /health from 62 ms to 26 s. serve_test pins the relationship.

kbless-ops clj

The ops whose vaelii.core fn takes no KB (op* above). Held as data rather than left implicit in the closures, because two generators read this table and both have to know whether an op's first vaelii.core parameter is the KB the daemon supplies or an argument the caller sends: vaelii.impl.client's wrappers (arity for arity) and vaelii.impl.llm.tools' schemas (parameter by parameter).

op-names clj

Every op keyword this daemon answers, sorted — the vaelii.core allowlist and the daemon's own together. What an :unknown-op refusal hands back, so a caller discovering the surface sees one roster rather than the larger half of two.

ops clj

The reachable operations, keyed by op keyword. Reads, writes, and introspection — the working set a remote caller needs; extend by adding a vaelii.core fn here.

Every entry is wrapped by bounded, which is a no-op for an op search-bounds does not name.

port clj

(port server)

The actual TCP port a started Server is listening on — the ephemeral one when it was started with :port 0, read off its first connector.

search-bounds clj

Which of the two ceilings apply to which op, and under which key the op reads it.

A read that expands rules runs on the daemon's single write monitor, so its cost is not the caller's alone: every other request queues behind it. The two dials a caller sets are the two ceilings — :max-ms (config/max-query-ms) and :max-depth (config/max-query-depth) — and this table says which door reads which, because the option rosters differ (query-opt-keys has no :max-ms to fill in, search-tree's has both, an anytime budget map is :max-ms and takes no default of its own).

A door with no bound of its own is not on it, which is a fact about the door rather than a category: :sentexes-matching has no dial to raise, so there is nothing to clamp. The four backward-search doors do have one (core/ask-opt-keys, core/prove-opt-keys), and are held to the ceiling like the rest — :ask and :ask? to the clock alone, since nothing in the prover registry expands a rule.

start clj

(start kb {:keys [port host] :or {port 4200 host loopback} :as opts})

Start the daemon over kb and return the running jetty Server (:join? false, so the caller controls its lifetime — a test stops it in a finally). :port 0 binds an ephemeral port; read the actual one with port.

:host defaults to loopback; pass an address ("0.0.0.0") to bind publicly, and read the note on loopback before doing so. :token is app's, forwarded only when the key is there, so an omitted one still reads VAELII_API_TOKEN and an explicit nil still serves open.