@irisrun/channel-rest 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,34 @@
+# @irisrun/channel-rest
+
+**Durable, replay-safe HTTP sessions.** The in-process REST channel over
+`node:http` that owns the two-identifier protocol — a stable `sessionId` plus a
+single-use `continuationToken` rotated every committed turn — so a session can be
+paused and resumed across processes and a stale or forged token is refused
+**loudly** (4xx), never a silent 200.
+
+## What it is
+
+`makeRestChannel` mints the `sessionId`, owns and issues the `continuationToken`,
+and streams a turn live over **SSE** *and* a hand-rolled, zero-dependency
+**WebSocket** (`ws://…/v1/ws`) — both records and model token deltas. Drop the
+`Accept: text/event-stream` header for one buffered JSON reply. A real
+external HTTP deploy is an env-gated smoke test.
+
+The two-identifier protocol itself — token rotation (only on a committed turn), the
+atomic single-use claim, and the loud refusal taxonomy — lives in
+**[`@irisrun/channel-core`](../channel-core/README.md)**, the shared channel **port**;
+this package is the HTTP/SSE/WS transport over it and passes the shared channel-port
+conformance suite (see the normative
+**[channel-port spec](../../docs/reference/channel-port-spec.md)**).
+
+## Use it
+
+```sh
+iris serve ./image --port 8787     # REST + SSE + WS; add --web for the chat UI
+```
+
+See **[docs/Channels](../../docs/channels.md)** for the wire protocol and
+**[@irisrun/client-sdk](../client-sdk/README.md)** for a typed client.
+
+---
+Part of [Iris](../../README.md) — own, portable, verifiable state.

package/dist/events.d.ts

@@ -1,20 +1,2 @@
-import type { Json, TurnOutcome } from "@irisrun/core";
-export type StreamEvent = {
-    type: "record";
-    record: Json;
-} | {
-    type: "delta";
-    text: string;
-} | {
-    type: "outcome";
-    sessionId: string;
-    status: TurnOutcome<Json>["status"];
-    output?: Json;
-    wait?: Json;
-    current?: number;
-    continuationToken?: string;
-} | {
-    type: "error";
-    message: string;
-};
-export declare function toOutcomeEvent<S extends Json>(sessionId: string, outcome: TurnOutcome<S>, token?: string): StreamEvent;
+export type { ChannelEvent as StreamEvent } from "@irisrun/channel-core";
+export { toOutcomeEvent } from "@irisrun/channel-core";

package/dist/events.js

@@ -1,18 +1 @@
-// Mirrors the buffered `turnResponse()` mapping, plus the rotated token. `token`
-// is omitted only when the channel did not (re)issue one.
-export function toOutcomeEvent(sessionId, outcome, token) {
-    const ev = {
-        type: "outcome",
-        sessionId,
-        status: outcome.status,
-    };
-    if (outcome.status === "finished" && outcome.output !== undefined)
-        ev.output = outcome.output;
-    if (outcome.status === "parked")
-        ev.wait = outcome.wait;
-    if (outcome.status === "contended")
-        ev.current = outcome.current;
-    if (token !== undefined)
-        ev.continuationToken = token;
-    return ev;
-}
+export { toOutcomeEvent } from "@irisrun/channel-core";

package/dist/server.js

@@ -1,4 +1,4 @@
-// makeRestChannel (ADR-0009, Spec 05 B3): an in-process node:http server speaking
+// makeRestChannel: an in-process node:http server speaking
 // the TWO-IDENTIFIER protocol. The channel MINTS the sessionId and OWNS/ISSUES the
 // continuationToken — the client presents it on the next call. Every turn ROTATES
 // the token; a missing/stale/malformed token is refused with a LOUD 4xx, never a
@@ -8,6 +8,7 @@ import { createServer } from "node:http";
 import { randomUUID } from "node:crypto";
 import { runTurnOn } from "@irisrun/host";
 import { toOutcomeEvent } from "./events.js";
+import { makeChannelSession } from "@irisrun/channel-core";
 import { wantsStream, openSse } from "./sse.js";
 import { writeHandshake, refuseUpgrade, makeWsFramer, encodeTextFrame, encodeCloseFrame, encodePongFrame, } from "./ws.js";
 const SESSION_MESSAGE = /^\/v1\/session\/([^/]+)\/message$/;
@@ -41,58 +42,60 @@ function turnResponse(sessionId, token, outcome) {
     return base;
 }
 export function makeRestChannel(opts) {
-    const mintSessionId = opts.mintSessionId ?? (() => randomUUID());
-    const mintToken = opts.mintToken ?? (() => randomUUID());
-    // The channel OWNS the current continuationToken per session (in-process here;
-    // a real deploy would persist it). It rotates on every committed turn.
-    const tokens = new Map();
-    // Sessions with a turn in flight — enforces the token's SINGLE-USE invariant
-    // under concurrency (the token rotates only after the turn commits, so without
-    // this a second concurrent request presenting the same valid token would slip
-    // past the check before rotation; ADR-0009 advertises single-use, so we honor it).
-    const inFlight = new Set();
-    // Rotate the continuationToken ONLY on a COMMITTED turn (single-use). A
-    // `contended` turn journaled nothing — the lease was held elsewhere — so the
-    // prior token stays valid and the client retries it (no rotation). A START turn
-    // (priorToken === null) always issues a fresh token. Used by all three paths
-    // (buffered/SSE/WS) so token discipline is identical across them.
-    const issueToken = (sessionId, outcome, priorToken) => {
-        if (priorToken !== null && outcome.status === "contended")
-            return priorToken;
-        const token = mintToken();
-        tokens.set(sessionId, token);
-        return token;
+    // The two-identifier protocol (mint sessionId, own/rotate a single-use token, atomic
+    // single-use, committed-only rotation) lives in the shared channel-core port — the
+    // SAME driver channel-mcp uses. This REST transport maps refusals to HTTP status and
+    // adds the SSE/WS framing. `runTurn` builds the per-request journal-timeline tap.
+    const session = makeChannelSession({
+        runTurn: async (sessionId, body, emit) => {
+            const inputs = await opts.makeTurnInputs(sessionId, body, emit);
+            // onRecord is the per-REQUEST journal-timeline tap (only on a streaming request).
+            // It rides RunTurnOnOptions, NOT TurnInputs (per-session-static).
+            const onRecord = emit
+                ? (r) => emit({ type: "record", record: r })
+                : undefined;
+            return runTurnOn(opts.adapter, {
+                sessionId,
+                ...inputs,
+                ...(onRecord ? { onRecord } : {}),
+            });
+        },
+        mintSessionId: opts.mintSessionId ?? (() => randomUUID()),
+        mintToken: opts.mintToken ?? (() => randomUUID()),
+    });
+    // Map a channel-core refusal to its LOUD HTTP status (preserving the prior messages).
+    const REFUSAL_STATUS = {
+        "unknown-session": 404,
+        "missing-token": 400,
+        "stale-token": 409,
+        "in-flight": 409,
     };
-    const runTurn = async (sessionId, body, emit) => {
-        const inputs = await opts.makeTurnInputs(sessionId, body, emit);
-        // onRecord is the per-REQUEST journal-timeline tap (only on a streaming
-        // request). It rides RunTurnOnOptions, NOT TurnInputs (per-session-static).
-        const onRecord = emit
-            ? (r) => emit({ type: "record", record: r })
-            : undefined;
-        return runTurnOn(opts.adapter, {
-            sessionId,
-            ...inputs,
-            ...(onRecord ? { onRecord } : {}),
-        });
+    const refusalMessage = (reason, sessionId) => {
+        switch (reason) {
+            case "unknown-session":
+                return `unknown session '${sessionId}'`;
+            case "missing-token":
+                return "missing continuationToken";
+            case "stale-token":
+                return "stale or invalid continuationToken";
+            case "in-flight":
+                return "a turn is already in flight for this session";
+        }
     };
-    // Drive one turn into an SSE stream: records + deltas, then a terminal outcome
-    // carrying the rotated token. Validation (loud 4xx) already ran in the handler
+    // Drive a session op into an SSE stream: records + deltas, then a terminal outcome
+    // carrying the rotated token. Any loud refusal (4xx) already ran in the handler
     // BEFORE this opens the stream, so a refusal is never a half-open SSE.
-    const streamTurn = async (res, sessionId, body, priorToken) => {
+    const runSse = async (res, produce) => {
         const sse = openSse(res);
         const emit = (ev) => sse.emit(ev);
-        let outcome;
         try {
-            outcome = await runTurn(sessionId, body, emit);
+            const r = await produce(emit);
+            emit(toOutcomeEvent(r.sessionId, r.outcome, r.token));
         }
         catch (err) {
             // The turn threw AFTER the stream opened — surface it in-band, loudly.
             emit({ type: "error", message: err instanceof Error ? err.message : String(err) });
-            sse.end();
-            return;
         }
-        emit(toOutcomeEvent(sessionId, outcome, issueToken(sessionId, outcome, priorToken)));
         sse.end();
     };
     const handler = async (req, res) => {
@@ -115,61 +118,54 @@ export function makeRestChannel(opts) {
         const body = parsed.body;
         // --- start: MINT a session + the first continuationToken --------------
         if (url === "/v1/session") {
-            const sessionId = mintSessionId();
             if (stream) {
-                await streamTurn(res, sessionId, body, null); // START → always issues a fresh token
+                await runSse(res, async (emit) => {
+                    const r = await session.start(body, emit); // START → always issues a fresh token
+                    return { sessionId: r.sessionId, token: r.token, outcome: r.outcome };
+                });
                 return;
             }
-            const outcome = await runTurn(sessionId, body);
-            const token = issueToken(sessionId, outcome, null);
-            send(res, 200, turnResponse(sessionId, token, outcome));
+            const r = await session.start(body);
+            send(res, 200, turnResponse(r.sessionId, r.token, r.outcome));
             return;
         }
         // --- continue: REQUIRE the matching token, then ROTATE it -------------
         const m = SESSION_MESSAGE.exec(url);
         if (m) {
             const sessionId = decodeURIComponent(m[1]);
-            if (!tokens.has(sessionId)) {
-                send(res, 404, { error: `unknown session '${sessionId}'` });
-                return;
-            }
             const headerToken = req.headers["x-continuation-token"];
             const presented = typeof body.continuationToken === "string"
                 ? body.continuationToken
                 : typeof headerToken === "string"
                     ? headerToken
                     : null;
-            if (presented === null || presented === "") {
-                send(res, 400, { error: "missing continuationToken" });
-                return;
-            }
-            if (presented !== tokens.get(sessionId)) {
-                send(res, 409, { error: "stale or invalid continuationToken" });
-                return;
-            }
-            // The token check above and this in-flight claim run in ONE event-loop
-            // callback with no interleaving, so a SECOND concurrent request presenting
-            // the same valid token is refused HERE — before the token rotates — instead
-            // of slipping past the check. The flag also keeps the token usable across a
-            // failed turn: we rotate ONLY on success, in the finally we just release.
-            if (inFlight.has(sessionId)) {
-                send(res, 409, { error: "a turn is already in flight for this session" });
-                return;
-            }
-            inFlight.add(sessionId);
-            try {
-                if (stream) {
-                    await streamTurn(res, sessionId, body, presented); // CONTINUE → rotate only if committed
+            if (stream) {
+                // Validate the token AND peek in-flight BEFORE opening the stream — these
+                // checks plus the advance() claim run with no `await` between, so the
+                // single-use claim stays atomic and a refusal is never a half-open SSE.
+                const refusal = session.validateContinue(sessionId, presented);
+                if (refusal) {
+                    send(res, REFUSAL_STATUS[refusal], { error: refusalMessage(refusal, sessionId) });
+                    return;
                 }
-                else {
-                    const outcome = await runTurn(sessionId, body);
-                    const next = issueToken(sessionId, outcome, presented);
-                    send(res, 200, turnResponse(sessionId, next, outcome));
+                if (session.inFlight(sessionId)) {
+                    send(res, 409, { error: "a turn is already in flight for this session" });
+                    return;
                 }
+                await runSse(res, async (emit) => {
+                    const r = await session.advance(sessionId, body, emit); // rotate only if committed
+                    if (!r.ok)
+                        throw new Error("a turn is already in flight for this session");
+                    return { sessionId, token: r.token, outcome: r.outcome };
+                });
+                return;
             }
-            finally {
-                inFlight.delete(sessionId);
+            const r = await session.continueTurn(sessionId, presented, body);
+            if (!r.ok) {
+                send(res, REFUSAL_STATUS[r.reason], { error: refusalMessage(r.reason, sessionId) });
+                return;
             }
+            send(res, 200, turnResponse(sessionId, r.token, r.outcome));
             return;
         }
         send(res, 404, { error: `no route for ${url}` });
@@ -209,30 +205,37 @@ export function makeRestChannel(opts) {
                     sendEvent({ type: "error", message: "present no continuationToken to start a session" });
                     return;
                 }
-                sessionId = mintSessionId();
+                // Bind the session to the connection SYNCHRONOUSLY (before the first turn
+                // runs) so a second frame on this connection sees the bound session.
+                sessionId = session.newSessionId();
             }
             else if (presented !== null) {
-                if (presented !== tokens.get(sessionId)) {
+                // The held connection authorizes continuation; a presented token (if any) is
+                // validated against the current one (read fresh, never cached).
+                if (presented !== session.currentToken(sessionId)) {
                     sendEvent({ type: "error", message: "stale or invalid continuationToken" });
                     return;
                 }
             }
-            if (inFlight.has(sessionId)) {
+            // in-flight peek then advance() claim run with no `await` between → atomic
+            // single-use even across two frames interleaving at their awaits.
+            if (session.inFlight(sessionId)) {
                 sendEvent({ type: "error", message: "a turn is already in flight for this session" });
                 return;
             }
-            const priorToken = tokens.get(sessionId) ?? null; // null on this connection's START turn
-            inFlight.add(sessionId);
             try {
-                const outcome = await runTurn(sessionId, body, sendEvent);
-                sendEvent(toOutcomeEvent(sessionId, outcome, issueToken(sessionId, outcome, priorToken)));
+                // advance on a freshly-minted (unregistered) session runs as a START (prior
+                // token null → mints); on a bound session it rotates per the committed rule.
+                const r = await session.advance(sessionId, body, sendEvent);
+                if (!r.ok) {
+                    sendEvent({ type: "error", message: "a turn is already in flight for this session" });
+                    return;
+                }
+                sendEvent(toOutcomeEvent(sessionId, r.outcome, r.token));
             }
             catch (err) {
                 sendEvent({ type: "error", message: err instanceof Error ? err.message : String(err) });
             }
-            finally {
-                inFlight.delete(sessionId);
-            }
         };
         const feed = makeWsFramer({
             onText: (t) => {
@@ -273,7 +276,7 @@ export function makeRestChannel(opts) {
                 res.end();
         });
     });
-    // WebSocket upgrade (ADR-0008 capability gate): a host that does not advertise
+    // WebSocket upgrade (capability gate): a host that does not advertise
     // `websockets` is refused LOUDLY (426, no 101) — never silently downgraded.
     server.on("upgrade", (req, socket, head) => {
         if (opts.adapter.capabilities.websockets !== true) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@irisrun/channel-rest",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
-  "description": "Iris in-process REST channel (ADR-0009) over node:http — the two-identifier protocol: the channel MINTS sessionId and OWNS/ISSUES the continuationToken; every turn rotates the token, and a missing/stale/malformed token is refused with a loud 4xx (never a silent 200). A real external HTTP deploy is a manual smoke.",
+  "description": "Durable, replay-safe HTTP sessions — the in-process REST channel over node:http with live SSE + hand-rolled zero-dep WebSocket streaming. Owns the two-identifier protocol: the channel MINTS the sessionId and OWNS/ISSUES a single-use continuationToken, rotated every committed turn, so a missing/stale/malformed token is refused with a loud 4xx (never a silent 200). A real external HTTP deploy is a manual smoke.",
   "exports": {
     ".": {
       "iris-src": "./src/index.ts",
@@ -11,8 +11,9 @@
     }
   },
   "dependencies": {
-    "@irisrun/core": "^0.1.0",
-    "@irisrun/host": "^0.1.0"
+    "@irisrun/core": "^0.2.0",
+    "@irisrun/channel-core": "^0.2.0",
+    "@irisrun/host": "^0.2.0"
   },
   "license": "MIT",
   "engines": {