dev.zeko.stube.http — dev.zeko/stube 0.3.0

Ring handlers that bridge HTTP to the kernel.

Five endpoints implement the client/server contract:

route	method	purpose
/<mount-path>	GET	mint a conversation, serve the shell HTML
/sse/:cid	GET	open the long-lived SSE stream for the conversation
/back/:cid	POST	restore the previous conversation snapshot
/upload/:cid/:iid	POST	parse multipart data and dispatch :upload-received
/event/:cid/:iid/:event	POST	dispatch one event; the iid and event live in the path, signals in the body

The shell page is a trivial HTML document. All real UI is delivered via SSE patches once the browser connects to /sse/:cid.

back-handler clj

(back-handler req)

(back-handler k {:keys [path-params] :as req})

POST /back/:cid — emit the [[:back]] effect. Mirrors event-handler but without an instance id or signals payload.

behaviors-js-handler clj

(behaviors-js-handler _req)

Serve the behaviors bridge loaded by the stock shell.

component-behavior-handler clj

(component-behavior-handler {:keys [path-params]})

Serve resources/stube_behaviors/<ns>/<name>.js for a behavior module lazy-imported by the behaviors bridge.

component-module-handler clj

(component-module-handler {:keys [path-params]})

Serve resources/stube_modules/<ns>/<name>.js for a JS module declared by a component's :modules vector.

component-style-handler clj

(component-style-handler {:keys [path-params]})

Serve resources/stube_styles/<ns>/<name>.css for a registered component. Path: /styles/<ns>/<name>.css.

event-handler clj

(event-handler req)

(event-handler k {:keys [path-params] :as req})

Dispatch one client event into the conversation. The instance id and event name are taken from the URL path; everything left in the request body / query is treated as the current Datastar signals.

preserve-js-handler clj

(preserve-js-handler _req)

Serve the preserved-subtree bridge loaded by the stock shell.

query-value clj

(query-value {:keys [query-string]} param-name)

Return the decoded value of query-param param-name from request, or nil if absent.

Works directly from Ring's :query-string without requiring params middleware. Useful in :init-args-fn callbacks passed to shell-handler to seed component state from the URL.

(shell-handler k :my/flow
  {:init-args-fn (fn [req]
                   {:page (parse-long (or (query-value req "page") "1"))})})

shell-handler clj

(shell-handler flow-id)

(shell-handler k flow-id)

(shell-handler k
               flow-id
               {:keys [init-args-fn] :or {init-args-fn (constantly {})}})

Build the GET handler for a mount path. Each request mints a fresh conversation pre-bound to flow-id; the cid is embedded in the shell so the browser's first SSE GET is to the right place.

When the server is started with :halos? true, every shell injects the halos overlay (initially inactive) and a data-stube-cid hook so the user can enable the overlay from a floating pill. Adding ?halos=1 on the URL is a shortcut that pre-enables the conv.

Optional opts map:

• :init-args-fn — (fn [request] init-args-map). Called on every GET to extract init-args from the request (e.g. query params) and pass them to mint-conversation!. Use this when the component's initial state should be seeded from the URL:

  (shell-handler k :my/component
    {:init-args-fn (fn [req] {:n (parse-long (query-value req "n"))})})
  

  Defaults to (constantly {}).

sse-handler clj

(sse-handler req)

(sse-handler k {:keys [path-params] :as req})

Open the long-lived SSE stream for a conversation.

Three startup paths:

1. Fresh shell visit — the cid was just minted by shell-handler, so a pending flow id is on the baton. We boot the flow.
2. Restored conversation — the cid exists in memory (loaded from the persistence store at startup, or carried over a hot reload), but no pending flow is pending. We re-render its current top frame so the freshly-attached browser sees the restored UI.
3. Unknown cid — the conversation is gone (ended, expired). The SSE channel just stays empty; the browser will see no patches.

Thereafter the kernel pushes whenever an event handler produces fragments.

ui-css-handler clj

(ui-css-handler _req)

Serve the opt-out stock stylesheet linked by the shell.

upload-handler clj

(upload-handler req)

(upload-handler k {:keys [path-params] :as req})

POST /upload/:cid/:iid — parse a multipart request and route it to the target instance as :upload-received.

Upload responses are written into a hidden iframe by s/upload-attrs; the visible page updates over the normal SSE stream.