dev.zeko.stube.http — dev.zeko/stube 0.0.2

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
/conv/:cid/sse	GET	open the long-lived SSE stream for the conversation
/conv/:cid/back	POST	restore the previous conversation snapshot
/stube/upload/:cid/:iid	POST	parse multipart data and dispatch :upload-received
/conv/: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 /conv/:cid/sse.

back-handler clj

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

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

event-handler clj

(event-handler {: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.

shell-handler clj

(shell-handler flow-id)

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.

sse-handler clj

(sse-handler {: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 {:keys [path-params] :as req})

POST /stube/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.