KERNEL side of the opaque wire: turn any IAddon into a line server.
A proprietary addon is written against this library's PORTABLE stratum and
compiled by cljw build into one native binary. That binary's whole job is
(serve! my-addon): read a request line, dispatch it to the addon through
IAddon, write a response line. The host mounts hive-addon.opaque.addon on the
other end, which speaks the same lines. Neither side knows anything about the
other beyond hive-addon.opaque.codec.
REQUIRES ONLY protocol + codec, both malli-free, so the compiled kernel carries no schema runtime and no validation code. The schemas describing these shapes live host-side (hive-addon.opaque.schema).
The kernel SELF-DESCRIBES. describe projects the addon's whole pure
surface, so a mount manifest never enumerates the kernel's tools and cannot
fall out of date with the binary it names.
A JVM+cljw claim, not a three-host one: this namespace dispatches through a protocol defined in ANOTHER namespace, which cljrs cannot yet do. Reader conditionals here must be TOTAL. See hive-addon.mount.portable-test.
KERNEL side of the opaque wire: turn any IAddon into a line server. A proprietary addon is written against this library's PORTABLE stratum and compiled by `cljw build` into one native binary. That binary's whole job is `(serve! my-addon)`: read a request line, dispatch it to the addon through IAddon, write a response line. The host mounts hive-addon.opaque.addon on the other end, which speaks the same lines. Neither side knows anything about the other beyond hive-addon.opaque.codec. REQUIRES ONLY protocol + codec, both malli-free, so the compiled kernel carries no schema runtime and no validation code. The schemas describing these shapes live host-side (hive-addon.opaque.schema). The kernel SELF-DESCRIBES. `describe` projects the addon's whole pure surface, so a mount manifest never enumerates the kernel's tools and cannot fall out of date with the binary it names. A JVM+cljw claim, not a three-host one: this namespace dispatches through a protocol defined in ANOTHER namespace, which cljrs cannot yet do. Reader conditionals here must be TOTAL. See hive-addon.mount.portable-test.
(describe addon)Project addon's pure surface onto the wire.
Everything here is a value the host can act on without another round trip: identity, type, capabilities, the tool list minus its handlers, the exclusion set, the schema extensions, and how each hook travels. The proxy rebuilds the callable half (tool handlers, fn-valued hooks) as callbacks over this wire.
Project `addon`'s pure surface onto the wire. Everything here is a value the host can act on without another round trip: identity, type, capabilities, the tool list minus its handlers, the exclusion set, the schema extensions, and how each hook travels. The proxy rebuilds the callable half (tool handlers, fn-valued hooks) as callbacks over this wire.
(handle addon request)Dispatch one decoded request against addon, answering a response MAP.
The op set is closed (codec/ops), so this case is total by construction and
its default branch reports a vocabulary mismatch rather than a bug: it is
what a kernel says to a host built against a newer proxy.
Dispatch one decoded request against `addon`, answering a response MAP. The op set is closed (codec/ops), so this `case` is total by construction and its default branch reports a vocabulary mismatch rather than a bug: it is what a kernel says to a host built against a newer proxy.
(handle-line addon line)Read one request line and answer one response LINE. The whole kernel protocol in one function, for a host that owns its own loop.
Read one request line and answer one response LINE. The whole kernel protocol in one function, for a host that owns its own loop.
(optional addon f fallback)Call f on addon, answering fallback when the addon does not implement
that method.
excluded-tools and hooks are optional per the protocol, and the host
registry already defaults them for a legacy addon. The kernel must default
them the same way, or an addon that mounts in-process would stop mounting the
moment it is compiled opaque, which is exactly the regression a marketplace
artifact cannot afford.
An error that is NOT a missing method is rethrown: a broken hooks must not
masquerade as an absent one.
Call `f` on `addon`, answering `fallback` when the addon does not implement that method. `excluded-tools` and `hooks` are optional per the protocol, and the host registry already defaults them for a legacy addon. The kernel must default them the same way, or an addon that mounts in-process would stop mounting the moment it is compiled opaque, which is exactly the regression a marketplace artifact cannot afford. An error that is NOT a missing method is rethrown: a broken `hooks` must not masquerade as an absent one.
(respond addon line)Read one request line and answer the response MAP, never throwing.
Three failures are turned into responses rather than propagated, because a kernel that dies on a bad line takes the whole addon down with it: an unreadable line, a line that is not a request map, and a throw from inside the addon's own method. Only the last can echo an op.
Read one request line and answer the response MAP, never throwing. Three failures are turned into responses rather than propagated, because a kernel that dies on a bad line takes the whole addon down with it: an unreadable line, a line that is not a request map, and a throw from inside the addon's own method. Only the last can echo an op.
(serve! addon)Serve addon over stdin/stdout until EOF or a shutdown request.
Call this AT TOP LEVEL in the kernel entry namespace, not from a -main.
Measured on cljw: a build artifact receives no command-line-args and its
main is never invoked, while a top-level read-line loop works. An entry
that defines an uncalled -main compiles cleanly and then does nothing, which
is the worst possible failure for a shipped binary.
The loop stops after answering :addon/shutdown!, so the client closing the pipe is not the only way for the process to end.
Serve `addon` over stdin/stdout until EOF or a shutdown request. Call this AT TOP LEVEL in the kernel entry namespace, not from a `-main`. Measured on cljw: a `build` artifact receives no *command-line-args* and its main is never invoked, while a top-level `read-line` loop works. An entry that defines an uncalled -main compiles cleanly and then does nothing, which is the worst possible failure for a shipped binary. The loop stops after answering :addon/shutdown!, so the client closing the pipe is not the only way for the process to end.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |