@kyneta/sse-transport 1.1.0

package/dist/server-transport-BrMRLsmp.d.ts

@@ -0,0 +1,180 @@
+import { PeerId, Channel, ChannelMsg, Transport, GeneratedChannel } from '@kyneta/exchange';
+import { TextReassembler } from '@kyneta/wire';
+
+/**
+ * Default fragment threshold in characters for outbound SSE messages.
+ * 60K chars provides a safety margin below typical infrastructure limits.
+ */
+declare const DEFAULT_FRAGMENT_THRESHOLD = 60000;
+/**
+ * Configuration for creating an SseConnection.
+ */
+interface SseConnectionConfig {
+    /**
+     * Fragment threshold in characters. Messages larger than this are fragmented.
+     * Set to 0 to disable fragmentation.
+     * Default: 60000 (60K chars)
+     */
+    fragmentThreshold?: number;
+}
+/**
+ * Represents a single SSE connection to a peer (server-side).
+ *
+ * Manages encoding, framing, fragmentation, and reassembly for one
+ * connected client. Created by `SseServerTransport.registerConnection()`.
+ *
+ * The connection uses the text codec for transport — this is the natural
+ * choice for SSE's text-only protocol.
+ */
+declare class SseConnection {
+    #private;
+    readonly peerId: PeerId;
+    readonly channelId: number;
+    /**
+     * Text reassembler for handling fragmented POST bodies.
+     * Each connection has its own reassembler to track in-flight fragment batches.
+     */
+    readonly reassembler: TextReassembler;
+    constructor(peerId: PeerId, channelId: number, config?: SseConnectionConfig);
+    /**
+     * Set the channel reference.
+     * Called by the adapter when the channel is created.
+     * @internal
+     */
+    _setChannel(channel: Channel): void;
+    /**
+     * Set the function to call when sending messages to this peer.
+     *
+     * The function receives a fully encoded text frame string.
+     * The framework integration just wraps it in SSE syntax:
+     * - Express: `res.write(\`data: \${textFrame}\\n\\n\`)`
+     * - Hono: `stream.writeSSE({ data: textFrame })`
+     *
+     * @param sendFn Function that writes a text frame string to the SSE stream
+     */
+    setSendFunction(sendFn: (textFrame: string) => void): void;
+    /**
+     * Set the function to call when this connection is disconnected.
+     */
+    setDisconnectHandler(handler: () => void): void;
+    /**
+     * Send a ChannelMsg to the peer through the SSE stream.
+     *
+     * Encodes via textCodec → text frame → fragment if needed → sendFn().
+     * Encoding and fragmentation are the connection's concern — the
+     * framework integration only needs to write strings.
+     */
+    send(msg: ChannelMsg): void;
+    /**
+     * Receive a message from the peer and route it to the channel.
+     *
+     * Called by the framework integration after parsing a POST body
+     * through `parseTextPostBody`.
+     */
+    receive(msg: ChannelMsg): void;
+    /**
+     * Disconnect this connection.
+     */
+    disconnect(): void;
+    /**
+     * Dispose of resources held by this connection.
+     * Must be called when the connection is closed to prevent timer leaks.
+     */
+    dispose(): void;
+}
+
+/**
+ * Options for the SSE server adapter.
+ */
+interface SseServerTransportOptions {
+    /**
+     * Fragment threshold in characters. Messages larger than this are fragmented
+     * into multiple SSE events.
+     * Set to 0 to disable fragmentation.
+     * Default: 60000 (60K chars)
+     */
+    fragmentThreshold?: number;
+}
+/**
+ * SSE server network adapter.
+ *
+ * Framework-agnostic — works with any HTTP framework through the
+ * `SseConnection.setSendFunction()` callback. Use `registerConnection()`
+ * to integrate with your framework's SSE endpoint handler.
+ *
+ * Each client connection is tracked as an `SseConnection` keyed by peer ID.
+ * The adapter creates a channel per connection and routes outbound messages
+ * through the connection's send method (which encodes to text wire format
+ * and calls the injected sendFn).
+ *
+ * The connection handshake:
+ * 1. Client opens EventSource (GET /events)
+ * 2. Server calls `registerConnection(peerId)` → creates channel
+ * 3. Client's EventSource.onopen fires → client sends establish-request (POST)
+ * 4. Server receives establish-request → Synchronizer responds with establish-response (SSE)
+ *
+ * The server does NOT call `establishChannel()` — it waits for the client's
+ * establish-request, which arrives via POST after the EventSource is open.
+ */
+declare class SseServerTransport extends Transport<PeerId> {
+    #private;
+    constructor(options?: SseServerTransportOptions);
+    protected generate(peerId: PeerId): GeneratedChannel;
+    onStart(): Promise<void>;
+    onStop(): Promise<void>;
+    /**
+     * Register a new peer connection.
+     *
+     * Call this from your framework's SSE endpoint handler when a client
+     * connects via EventSource. Returns an `SseConnection` that you wire
+     * up with `setSendFunction()` and `setDisconnectHandler()`.
+     *
+     * @param peerId The unique identifier for the peer (from query param or header)
+     * @returns An SseConnection object for managing the connection
+     *
+     * @example Express
+     * ```typescript
+     * const connection = serverAdapter.registerConnection(peerId)
+     * connection.setSendFunction((textFrame) => {
+     *   res.write(`data: ${textFrame}\n\n`)
+     * })
+     * ```
+     *
+     * @example Hono
+     * ```typescript
+     * const connection = serverAdapter.registerConnection(peerId)
+     * connection.setSendFunction((textFrame) => {
+     *   stream.writeSSE({ data: textFrame })
+     * })
+     * ```
+     */
+    registerConnection(peerId?: PeerId): SseConnection;
+    /**
+     * Unregister a peer connection.
+     *
+     * Removes the channel, disposes the connection's reassembler,
+     * and cleans up tracking state. Called automatically when the
+     * client disconnects (via req.on("close")) or manually.
+     *
+     * @param peerId The unique identifier for the peer
+     */
+    unregisterConnection(peerId: PeerId): void;
+    /**
+     * Get an active connection by peer ID.
+     */
+    getConnection(peerId: PeerId): SseConnection | undefined;
+    /**
+     * Get all active connections.
+     */
+    getAllConnections(): SseConnection[];
+    /**
+     * Check if a peer is connected.
+     */
+    isConnected(peerId: PeerId): boolean;
+    /**
+     * Get the number of connected peers.
+     */
+    get connectionCount(): number;
+}
+
+export { DEFAULT_FRAGMENT_THRESHOLD as D, SseConnection as S, type SseConnectionConfig as a, SseServerTransport as b, type SseServerTransportOptions as c };

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+export { D as DEFAULT_FRAGMENT_THRESHOLD, S as SseConnection, a as SseConnectionConfig, b as SseServerTransport, c as SseServerTransportOptions } from './server-transport-BrMRLsmp.js';
+export { D as DisconnectReason, S as SseConnectionHandle, a as SseConnectionResult } from './types-BTgljZGe.js';
+import '@kyneta/exchange';
+import '@kyneta/wire';

package/dist/server.js

@@ -0,0 +1,12 @@
+import {
+  DEFAULT_FRAGMENT_THRESHOLD,
+  SseConnection,
+  SseServerTransport
+} from "./chunk-TR4Y3HFB.js";
+import "./chunk-7D4SUZUM.js";
+export {
+  DEFAULT_FRAGMENT_THRESHOLD,
+  SseConnection,
+  SseServerTransport
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types-BTgljZGe.d.ts

@@ -0,0 +1,83 @@
+import { PeerId } from '@kyneta/exchange';
+
+/**
+ * Discriminated union describing why an SSE connection was lost.
+ *
+ * Unlike WebSocket's DisconnectReason, SSE does not have:
+ * - `{ type: "closed"; code; reason }` — SSE has no close codes
+ * - `{ type: "not-started" }` — SSE has no "ready" gate
+ */
+type DisconnectReason = {
+    type: "intentional";
+} | {
+    type: "error";
+    error: Error;
+} | {
+    type: "max-retries-exceeded";
+    attempts: number;
+};
+/**
+ * All possible states of the SSE client.
+ *
+ * State machine transitions (4 states, no "ready"):
+ * ```
+ * disconnected → connecting → connected
+ *                    ↓            ↓
+ *               reconnecting ← ─ ─┘
+ *                    ↓
+ *               connecting (retry)
+ *                    ↓
+ *               disconnected (max retries)
+ * ```
+ */
+type SseClientState = {
+    status: "disconnected";
+    reason?: DisconnectReason;
+} | {
+    status: "connecting";
+    attempt: number;
+} | {
+    status: "connected";
+} | {
+    status: "reconnecting";
+    attempt: number;
+    nextAttemptMs: number;
+};
+
+/**
+ * Handle for an active SSE connection (server-side).
+ */
+interface SseConnectionHandle {
+    /** The peer ID for this connection. */
+    readonly peerId: PeerId;
+    /** The channel ID for this connection. */
+    readonly channelId: number;
+    /** Disconnect this connection. */
+    disconnect(): void;
+}
+/**
+ * Result of registering an SSE connection on the server.
+ */
+interface SseConnectionResult {
+    /** The connection handle for managing this peer. */
+    connection: SseConnectionHandle;
+}
+/**
+ * Lifecycle event callbacks for the SSE client.
+ */
+interface SseClientLifecycleEvents {
+    /** Called on every state transition (delivered async via microtask). */
+    onStateChange?: (transition: {
+        from: SseClientState;
+        to: SseClientState;
+        timestamp: number;
+    }) => void;
+    /** Called when the connection is lost. */
+    onDisconnect?: (reason: DisconnectReason) => void;
+    /** Called when a reconnection attempt is scheduled. */
+    onReconnecting?: (attempt: number, nextAttemptMs: number) => void;
+    /** Called when reconnection succeeds after a previous connection. */
+    onReconnected?: () => void;
+}
+
+export type { DisconnectReason as D, SseConnectionHandle as S, SseConnectionResult as a, SseClientLifecycleEvents as b, SseClientState as c };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@kyneta/sse-transport",
+  "version": "1.1.0",
+  "description": "SSE (Server-Sent Events) network adapter for @kyneta/exchange — client, server, and Express integration",
+  "author": "Duane Johnson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/halecraft/kyneta",
+    "directory": "packages/exchange/network-adapters/sse"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "import": "./dist/express.js"
+    },
+    "./src/*": "./src/*"
+  },
+  "peerDependencies": {
+    "@kyneta/exchange": "^1.1.0",
+    "@kyneta/wire": "^1.1.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.23",
+    "@types/node": "^22",
+    "express": "^4.21.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^4.0.17",
+    "@kyneta/exchange": "^1.1.0",
+    "@kyneta/schema": "^1.1.0",
+    "@kyneta/wire": "^1.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "verify logic",
+    "verify": "verify"
+  }
+}

package/src/__tests__/client-state-machine.test.ts

@@ -0,0 +1,201 @@
+// SseClientStateMachine tests.
+//
+// Tests only SSE-specific concerns: the 4-state transition map, the
+// isConnected() helper, and a full lifecycle. Generic state machine
+// mechanics (async delivery, waitForState, batching, etc.) are tested
+// in packages/exchange/src/__tests__/client-state-machine.test.ts.
+
+import { describe, expect, it } from "vitest"
+import { SseClientStateMachine } from "../client-state-machine.js"
+
+// ---------------------------------------------------------------------------
+// Initial state
+// ---------------------------------------------------------------------------
+
+describe("SseClientStateMachine — initial state", () => {
+  it("starts in disconnected state", () => {
+    const sm = new SseClientStateMachine()
+    expect(sm.getState()).toEqual({ status: "disconnected" })
+    expect(sm.getStatus()).toBe("disconnected")
+  })
+
+  it("isConnected() returns false initially", () => {
+    const sm = new SseClientStateMachine()
+    expect(sm.isConnected()).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Valid transitions
+// ---------------------------------------------------------------------------
+
+describe("SseClientStateMachine — valid transitions", () => {
+  it("disconnected → connecting", () => {
+    const sm = new SseClientStateMachine()
+    sm.transition({ status: "connecting", attempt: 1 })
+    expect(sm.getStatus()).toBe("connecting")
+  })
+
+  it("connecting → connected", () => {
+    const sm = new SseClientStateMachine()
+    sm.transition({ status: "connecting", attempt: 1 })
+    sm.transition({ status: "connected" })
+    expect(sm.getStatus()).toBe("connected")
+    expect(sm.isConnected()).toBe(true)
+  })
+
+  it("connecting → disconnected", () => {
+    const sm = new SseClientStateMachine()
+    sm.transition({ status: "connecting", attempt: 1 })
+    sm.transition({
+      status: "disconnected",
+      reason: { type: "error", error: new Error("fail") },
+    })
+    expect(sm.getStatus()).toBe("disconnected")
+  })
+
+  it("connecting → reconnecting", () => {
+    const sm = new SseClientStateMachine()
+    sm.transition({ status: "connecting", attempt: 1 })
+    sm.transition({ status: "reconnecting", attempt: 1, nextAttemptMs: 1000 })
+    expect(sm.getStatus()).toBe("reconnecting")
+  })
+
+  it("connected → disconnected", () => {
+    const sm = new SseClientStateMachine()
+    sm.transition({ status: "connecting", attempt: 1 })
+    sm.transition({ status: "connected" })
+    sm.transition({ status: "disconnected", reason: { type: "intentional" } })
+    expect(sm.getStatus()).toBe("disconnected")
+  })
+
+  it("connected → reconnecting", () => {
+    const sm = new SseClientStateMachine()
+    sm.transition({ status: "connecting", attempt: 1 })
+    sm.transition({ status: "connected" })
+    sm.transition({ status: "reconnecting", attempt: 1, nextAttemptMs: 2000 })
+    expect(sm.getStatus()).toBe("reconnecting")
+  })
+
+  it("reconnecting → connecting", () => {
+    const sm = new SseClientStateMachine()
+    sm.transition({ status: "connecting", attempt: 1 })
+    sm.transition({ status: "reconnecting", attempt: 1, nextAttemptMs: 1000 })
+    sm.transition({ status: "connecting", attempt: 2 })
+    expect(sm.getStatus()).toBe("connecting")
+    expect((sm.getState() as { attempt: number }).attempt).toBe(2)
+  })
+
+  it("reconnecting → disconnected", () => {
+    const sm = new SseClientStateMachine()
+    sm.transition({ status: "connecting", attempt: 1 })
+    sm.transition({ status: "reconnecting", attempt: 1, nextAttemptMs: 1000 })
+    sm.transition({
+      status: "disconnected",
+      reason: { type: "max-retries-exceeded", attempts: 10 },
+    })
+    expect(sm.getStatus()).toBe("disconnected")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Invalid transitions
+// ---------------------------------------------------------------------------
+
+describe("SseClientStateMachine — invalid transitions", () => {
+  it("rejects disconnected → connected (must go through connecting)", () => {
+    const sm = new SseClientStateMachine()
+    expect(() => sm.transition({ status: "connected" })).toThrow(
+      "Invalid state transition: disconnected -> connected",
+    )
+  })
+
+  it("rejects disconnected → reconnecting", () => {
+    const sm = new SseClientStateMachine()
+    expect(() =>
+      sm.transition({
+        status: "reconnecting",
+        attempt: 1,
+        nextAttemptMs: 1000,
+      }),
+    ).toThrow("Invalid state transition: disconnected -> reconnecting")
+  })
+
+  it("rejects connected → connecting (must go through reconnecting)", () => {
+    const sm = new SseClientStateMachine()
+    sm.transition({ status: "connecting", attempt: 1 })
+    sm.transition({ status: "connected" })
+    expect(() => sm.transition({ status: "connecting", attempt: 2 })).toThrow(
+      "Invalid state transition: connected -> connecting",
+    )
+  })
+
+  // SSE has no "ready" state — verify it's not in the transition map
+  it("rejects transition to ready (SSE has no ready state)", () => {
+    const sm = new SseClientStateMachine()
+    sm.transition({ status: "connecting", attempt: 1 })
+    sm.transition({ status: "connected" })
+    expect(() => sm.transition({ status: "ready" } as any)).toThrow(
+      "Invalid state transition: connected -> ready",
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// isConnected
+// ---------------------------------------------------------------------------
+
+describe("SseClientStateMachine — isConnected", () => {
+  it("returns false for disconnected", () => {
+    const sm = new SseClientStateMachine()
+    expect(sm.isConnected()).toBe(false)
+  })
+
+  it("returns false for connecting", () => {
+    const sm = new SseClientStateMachine()
+    sm.transition({ status: "connecting", attempt: 1 })
+    expect(sm.isConnected()).toBe(false)
+  })
+
+  it("returns true for connected", () => {
+    const sm = new SseClientStateMachine()
+    sm.transition({ status: "connecting", attempt: 1 })
+    sm.transition({ status: "connected" })
+    expect(sm.isConnected()).toBe(true)
+  })
+
+  it("returns false for reconnecting", () => {
+    const sm = new SseClientStateMachine()
+    sm.transition({ status: "connecting", attempt: 1 })
+    sm.transition({ status: "reconnecting", attempt: 1, nextAttemptMs: 1000 })
+    expect(sm.isConnected()).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Full lifecycle
+// ---------------------------------------------------------------------------
+
+describe("SseClientStateMachine — full lifecycle", () => {
+  it("disconnected → connecting → connected → reconnecting → connecting → connected → disconnected", () => {
+    const sm = new SseClientStateMachine()
+
+    sm.transition({ status: "connecting", attempt: 1 })
+    sm.transition({ status: "connected" })
+    expect(sm.isConnected()).toBe(true)
+
+    // Connection lost
+    sm.transition({ status: "reconnecting", attempt: 1, nextAttemptMs: 1000 })
+    expect(sm.isConnected()).toBe(false)
+
+    // Retry
+    sm.transition({ status: "connecting", attempt: 2 })
+    sm.transition({ status: "connected" })
+    expect(sm.isConnected()).toBe(true)
+
+    // Intentional disconnect
+    sm.transition({ status: "disconnected", reason: { type: "intentional" } })
+    expect(sm.getStatus()).toBe("disconnected")
+    expect(sm.isConnected()).toBe(false)
+  })
+})