Embeddable runtime API for stube.
This is the namespace host applications reach for when they want to
drop stube into an existing Ring app, Integrant system, or test
harness. Every fn here is a thin facade over dev.zeko.stube.runtime;
the indirection used to go through requiring-resolve for a load-order
concern that no longer applies, see ADR 0006.
A host typically uses three or four functions:
(def k (embed/make-kernel {:store … :base-path "/app"}))
(def cid (embed/mint-conversation! k :flow/root init-args request))
(embed/shell-for k cid) ; → Hiccup nodes for `<body>`
(embed/head-tags k) ; → Hiccup nodes for `<head>`
(embed/dispatch! k cid event) ; programmatic event injection
(embed/halt! k) ; graceful shutdown
Component code never reaches into this namespace. Component authors
stay inside dev.zeko.stube.core (s/...), where state is implicit
and the active kernel is bound by the runtime around each dispatch.
Adapters (http.clj, halos/http.clj, server.clj) drive the
runtime through dev.zeko.stube.runtime directly — embed is the
host surface, not the adapter surface.
Embeddable runtime API for stube.
This is the namespace host applications reach for when they want to
drop stube into an existing Ring app, Integrant system, or test
harness. Every fn here is a thin facade over [[dev.zeko.stube.runtime]];
the indirection used to go through `requiring-resolve` for a load-order
concern that no longer applies, see ADR 0006.
Reading guide
-------------
A host typically uses three or four functions:
(def k (embed/make-kernel {:store … :base-path "/app"}))
(def cid (embed/mint-conversation! k :flow/root init-args request))
(embed/shell-for k cid) ; → Hiccup nodes for `<body>`
(embed/head-tags k) ; → Hiccup nodes for `<head>`
(embed/dispatch! k cid event) ; programmatic event injection
(embed/halt! k) ; graceful shutdown
Component code never reaches into this namespace. Component authors
stay inside [[dev.zeko.stube.core]] (`s/...`), where state is implicit
and the active kernel is bound by the runtime around each dispatch.
Adapters (`http.clj`, `halos/http.clj`, `server.clj`) drive the
runtime through [[dev.zeko.stube.runtime]] directly — `embed` is the
*host* surface, not the adapter surface.(dispatch! k cid event)Dispatch an event into live conversation cid in runtime k and
return the produced fragments.
Dispatch an event into live conversation `cid` in runtime `k` and return the produced fragments.
(halt! k)Close open SSE streams and clear runtime registries for k.
Close open SSE streams and clear runtime registries for `k`.
(head-tags k)Return Hiccup nodes for the assets required by shell-for. Host
pages should include these in <head>: optional stock CSS,
preserve.js, Datastar, and optional halos tooling.
Return Hiccup nodes for the assets required by [[shell-for]]. Host pages should include these in `<head>`: optional stock CSS, preserve.js, Datastar, and optional halos tooling.
(make-kernel)(make-kernel opts)Create an embeddable stube runtime instance. See
dev.zeko.stube.runtime/make-kernel for the supported option set.
Create an embeddable stube runtime instance. See [[dev.zeko.stube.runtime/make-kernel]] for the supported option set.
(mint-conversation! k root-id request)(mint-conversation! k root-id init-args request)Register a conversation in k and return its cid.
Register a conversation in `k` and return its cid.
(publish! k topic msg)Publish msg to every live instance subscribed to topic in
runtime kernel k. Use this from host code outside component
dispatch; component code can call dev.zeko.stube.core/publish!.
Publish `msg` to every live instance subscribed to `topic` in runtime kernel `k`. Use this from host code outside component dispatch; component code can call [[dev.zeko.stube.core/publish!]].
(replay-with k root-id events)Purely replay events against root-id using runtime k's render
configuration. Runtime state is not mutated.
Differs in shape from dev.zeko.stube.core/replay, which does not
take a kernel. Use this one when you want the replay to honour the
same base-path / context the kernel produces in
production; the bare core/replay is for unit-tests of components
whose render output doesn't depend on those bindings.
Purely replay `events` against `root-id` using runtime `k`'s render configuration. Runtime state is not mutated. Differs in shape from [[dev.zeko.stube.core/replay]], which does not take a kernel. Use this one when you want the replay to honour the same base-path / context the kernel produces in production; the bare `core/replay` is for unit-tests of components whose render output doesn't depend on those bindings.
(shell-for k cid)Return an embeddable Hiccup shell fragment for conversation cid.
Return an embeddable Hiccup shell fragment for conversation `cid`.
(shutting-down? k)True after halt! has begun draining k. HTTP adapters should
refuse new conversation mints (typically 503) while this is true.
True after [[halt!]] has begun draining `k`. HTTP adapters should refuse new conversation mints (typically 503) while this is true.
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 |