@kyneta/sse-transport 1.1.0

package/src/client.ts

@@ -0,0 +1,30 @@
+// client — barrel export for @kyneta/sse-network-adapter/client.
+//
+// This is the client-side entry point. It exports everything needed
+// to create an SSE client adapter for browser connections.
+
+// ---------------------------------------------------------------------------
+// Client adapter + factory function
+// ---------------------------------------------------------------------------
+
+export {
+  createSseClient,
+  DEFAULT_FRAGMENT_THRESHOLD,
+  type DisconnectReason,
+  type SseClientLifecycleEvents,
+  type SseClientOptions,
+  type SseClientState,
+  SseClientTransport,
+} from "./client-transport.js"
+
+// ---------------------------------------------------------------------------
+// State machine
+// ---------------------------------------------------------------------------
+
+export { SseClientStateMachine } from "./client-state-machine.js"
+
+// ---------------------------------------------------------------------------
+// Shared types
+// ---------------------------------------------------------------------------
+
+export type { StateTransition, TransitionListener } from "./types.js"

package/src/connection.ts

@@ -0,0 +1,181 @@
+// connection — SseConnection for server-side peer connections.
+//
+// Wraps a TextReassembler + textCodec to provide send/receive for
+// ChannelMsg over a single SSE connection.
+//
+// Used by SseServerTransport to manage individual client connections.
+// The client adapter handles its own encoding/decoding inline since it
+// manages a single EventSource with reconnection logic.
+//
+// The sendFn receives pre-encoded text frame strings. Framework
+// integrations just wrap them in SSE syntax:
+//   Express: res.write(`data: ${textFrame}\n\n`)
+//   Hono:    stream.writeSSE({ data: textFrame })
+
+import type { Channel, ChannelMsg, PeerId } from "@kyneta/exchange"
+import {
+  encodeTextComplete,
+  fragmentTextPayload,
+  TextReassembler,
+  textCodec,
+} from "@kyneta/wire"
+
+/**
+ * Default fragment threshold in characters for outbound SSE messages.
+ * 60K chars provides a safety margin below typical infrastructure limits.
+ */
+export const DEFAULT_FRAGMENT_THRESHOLD = 60_000
+
+/**
+ * Configuration for creating an SseConnection.
+ */
+export 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.
+ */
+export class SseConnection {
+  readonly peerId: PeerId
+  readonly channelId: number
+
+  #channel: Channel | null = null
+  #sendFn: ((textFrame: string) => void) | null = null
+  #onDisconnect: (() => void) | null = null
+
+  // Fragmentation support
+  readonly #fragmentThreshold: 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) {
+    this.peerId = peerId
+    this.channelId = channelId
+    this.#fragmentThreshold =
+      config?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD
+    this.reassembler = new TextReassembler({
+      timeoutMs: 10_000,
+      onTimeout: (frameId: string) => {
+        console.warn(
+          `[SseConnection] Fragment batch timed out for peer ${peerId}: ${frameId}`,
+        )
+      },
+    })
+  }
+
+  // ==========================================================================
+  // INTERNAL API — for adapter use
+  // ==========================================================================
+
+  /**
+   * Set the channel reference.
+   * Called by the adapter when the channel is created.
+   * @internal
+   */
+  _setChannel(channel: Channel): void {
+    this.#channel = channel
+  }
+
+  // ==========================================================================
+  // PUBLIC API
+  // ==========================================================================
+
+  /**
+   * 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 {
+    this.#sendFn = sendFn
+  }
+
+  /**
+   * Set the function to call when this connection is disconnected.
+   */
+  setDisconnectHandler(handler: () => void): void {
+    this.#onDisconnect = handler
+  }
+
+  /**
+   * 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 {
+    if (!this.#sendFn) {
+      throw new Error(
+        `Cannot send message: send function not set for peer ${this.peerId}`,
+      )
+    }
+
+    // Encode to text wire format
+    const textFrame = encodeTextComplete(textCodec, msg)
+
+    // Fragment large payloads
+    if (
+      this.#fragmentThreshold > 0 &&
+      textFrame.length > this.#fragmentThreshold
+    ) {
+      const payload = JSON.stringify(textCodec.encode(msg))
+      const fragments = fragmentTextPayload(payload, this.#fragmentThreshold)
+      for (const fragment of fragments) {
+        this.#sendFn(fragment)
+      }
+    } else {
+      this.#sendFn(textFrame)
+    }
+  }
+
+  /**
+   * 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 {
+    if (!this.#channel) {
+      throw new Error(
+        `Cannot receive message: channel not set for peer ${this.peerId}`,
+      )
+    }
+    this.#channel.onReceive(msg)
+  }
+
+  /**
+   * Disconnect this connection.
+   */
+  disconnect(): void {
+    this.#onDisconnect?.()
+  }
+
+  /**
+   * Dispose of resources held by this connection.
+   * Must be called when the connection is closed to prevent timer leaks.
+   */
+  dispose(): void {
+    this.reassembler.dispose()
+  }
+}

package/src/express-router.ts

@@ -0,0 +1,231 @@
+// express-router — Express integration for @kyneta/sse-network-adapter.
+//
+// Creates Express routes that integrate with SseServerTransport:
+// - GET endpoint for clients to establish SSE connections
+// - POST endpoint for clients to send text wire frame messages
+//
+// The POST endpoint accepts text/plain bodies containing text wire frames.
+// The GET endpoint sends text wire frames as SSE data events.
+//
+// Design: Imperative Shell — delegates parsing to parseTextPostBody()
+// (functional core) and message delivery to SseConnection.
+
+import type { PeerId } from "@kyneta/exchange"
+import type { Request, Response, Router } from "express"
+import express from "express"
+import type { SseServerTransport } from "./server-transport.js"
+import { parseTextPostBody } from "./sse-handler.js"
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface SseExpressRouterOptions {
+  /**
+   * Path for the sync endpoint where clients POST messages.
+   * @default "/sync"
+   */
+  syncPath?: string
+
+  /**
+   * Path for the events endpoint where clients connect via SSE.
+   * @default "/events"
+   */
+  eventsPath?: string
+
+  /**
+   * Interval in milliseconds for sending heartbeat comments to keep connections alive.
+   * @default 30000 (30 seconds)
+   */
+  heartbeatInterval?: number
+
+  /**
+   * Custom function to extract peerId from the sync request.
+   * By default, reads from the "x-peer-id" header.
+   */
+  getPeerIdFromSyncRequest?: (req: Request) => PeerId | undefined
+
+  /**
+   * Custom function to extract peerId from the events request.
+   * By default, reads from the "peerId" query parameter.
+   */
+  getPeerIdFromEventsRequest?: (req: Request) => PeerId | undefined
+}
+
+// ---------------------------------------------------------------------------
+// createSseExpressRouter
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an Express router for SSE server adapter.
+ *
+ * This factory function creates Express routes that integrate with the
+ * SseServerTransport. It handles:
+ * - POST endpoint for clients to send text wire frame messages to the server
+ * - GET endpoint for clients to establish SSE connections
+ * - Heartbeat mechanism to detect stale connections
+ *
+ * ## Wire Format
+ *
+ * The POST endpoint accepts text/plain bodies containing text wire frames
+ * (JSON arrays with "0c"/"0f" prefix). The SSE endpoint sends text wire
+ * frames as `data:` events. Both directions use the same encoding.
+ *
+ * @param adapter The SseServerTransport instance
+ * @param options Configuration options for the router
+ * @returns An Express Router ready to be mounted
+ *
+ * @example
+ * ```typescript
+ * import { SseServerTransport } from "@kyneta/sse-network-adapter/server"
+ * import { createSseExpressRouter } from "@kyneta/sse-network-adapter/express"
+ * import { Exchange } from "@kyneta/exchange"
+ *
+ * const serverAdapter = new SseServerTransport()
+ * const exchange = new Exchange({
+ *   identity: { peerId: "server", name: "server", type: "service" },
+ *   transports: [() => serverAdapter],
+ * })
+ *
+ * app.use("/sse", createSseExpressRouter(serverAdapter, {
+ *   syncPath: "/sync",
+ *   eventsPath: "/events",
+ *   heartbeatInterval: 30000,
+ * }))
+ * ```
+ */
+export function createSseExpressRouter(
+  adapter: SseServerTransport,
+  options: SseExpressRouterOptions = {},
+): Router {
+  const {
+    syncPath = "/sync",
+    eventsPath = "/events",
+    heartbeatInterval = 30000,
+    getPeerIdFromSyncRequest = req => req.headers["x-peer-id"] as PeerId,
+    getPeerIdFromEventsRequest = req => req.query.peerId as PeerId,
+  } = options
+
+  const router = express.Router()
+  const heartbeats = new Map<PeerId, NodeJS.Timeout>()
+
+  // ---------------------------------------------------------------------------
+  // POST /sync — clients send text wire frame messages TO the server
+  // ---------------------------------------------------------------------------
+
+  router.post(
+    syncPath,
+    express.text({ type: "text/plain", limit: "1mb" }),
+    (req: Request, res: Response) => {
+      // Extract peerId from request
+      const peerId = getPeerIdFromSyncRequest(req)
+
+      if (!peerId) {
+        res.status(400).json({ error: "Missing peer ID" })
+        return
+      }
+
+      // Get connection for this peer
+      const connection = adapter.getConnection(peerId)
+
+      if (!connection) {
+        res.status(404).json({ error: "Peer not connected" })
+        return
+      }
+
+      // Ensure we have text data
+      if (typeof req.body !== "string") {
+        res.status(400).json({ error: "Expected text body" })
+        return
+      }
+
+      // Functional core: parse body through reassembler
+      const result = parseTextPostBody(connection.reassembler, req.body)
+
+      // Imperative shell: execute side effects based on result
+      if (result.type === "messages") {
+        for (const msg of result.messages) {
+          connection.receive(msg)
+        }
+      }
+      // "pending" type means fragment received, waiting for more — no action needed
+      // "error" type is logged implicitly by the response status
+
+      res.status(result.response.status).json(result.response.body)
+    },
+  )
+
+  // ---------------------------------------------------------------------------
+  // GET /events — clients connect and listen for events FROM the server
+  // ---------------------------------------------------------------------------
+
+  router.get(eventsPath, (req: Request, res: Response) => {
+    const peerId = getPeerIdFromEventsRequest(req)
+    if (!peerId) {
+      res.status(400).end("peerId is required")
+      return
+    }
+
+    // Set headers for SSE
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+    })
+    res.flushHeaders()
+    // Send initial comment to ensure headers are flushed and connection is established
+    res.write(": ok\n\n")
+
+    // Register connection with adapter
+    const connection = adapter.registerConnection(peerId)
+
+    // Set up send function to write pre-encoded text frames to SSE stream.
+    // The connection's send() method handles encoding and fragmentation —
+    // the sendFn just wraps the text frame in SSE data syntax.
+    connection.setSendFunction((textFrame: string) => {
+      res.write(`data: ${textFrame}\n\n`)
+      // Flush the response buffer to ensure immediate delivery
+      // Note: 'flush' is added by compression middleware or some environments
+      if (typeof (res as any).flush === "function") {
+        ;(res as any).flush()
+      }
+    })
+
+    // Set up disconnect handler
+    connection.setDisconnectHandler(() => {
+      const hb = heartbeats.get(peerId)
+      if (hb) {
+        clearInterval(hb)
+        heartbeats.delete(peerId)
+      }
+      res.end()
+    })
+
+    // Setup heartbeat to detect stale connections
+    const hb = setInterval(() => {
+      try {
+        // Send a heartbeat comment (SSE comments are ignored by EventSource clients)
+        res.write(": heartbeat\n\n")
+      } catch (_err) {
+        // If we can't write to the response, the connection is dead
+        adapter.unregisterConnection(peerId)
+        clearInterval(hb)
+        heartbeats.delete(peerId)
+      }
+    }, heartbeatInterval)
+
+    heartbeats.set(peerId, hb)
+
+    // Handle client disconnect
+    req.on("close", () => {
+      adapter.unregisterConnection(peerId)
+      const existingHb = heartbeats.get(peerId)
+      if (existingHb) {
+        clearInterval(existingHb)
+        heartbeats.delete(peerId)
+      }
+    })
+  })
+
+  return router
+}

package/src/express.ts

@@ -0,0 +1,29 @@
+// express — barrel export for @kyneta/sse-network-adapter/express.
+//
+// This is the Express integration entry point. It exports everything
+// needed to integrate SseServerTransport with Express.
+
+// ---------------------------------------------------------------------------
+// Express router factory
+// ---------------------------------------------------------------------------
+
+export {
+  createSseExpressRouter,
+  type SseExpressRouterOptions,
+} from "./express-router.js"
+
+// ---------------------------------------------------------------------------
+// Server adapter (re-exported for convenience)
+// ---------------------------------------------------------------------------
+
+export { SseServerTransport } from "./server-transport.js"
+
+// ---------------------------------------------------------------------------
+// Handler (for custom framework integration)
+// ---------------------------------------------------------------------------
+
+export {
+  parseTextPostBody,
+  type SsePostResponse,
+  type SsePostResult,
+} from "./sse-handler.js"

package/src/server-transport.ts

@@ -0,0 +1,229 @@
+// server-adapter — SSE server adapter for @kyneta/exchange.
+//
+// Manages SSE connections from clients, encoding/decoding via the
+// kyneta text wire format. Framework-agnostic — works with any HTTP
+// framework through the SseConnection's setSendFunction() callback.
+//
+// Usage with Express:
+//   import { SseServerTransport } from "@kyneta/sse-network-adapter/server"
+//   import { createSseExpressRouter } from "@kyneta/sse-network-adapter/express"
+//
+//   const serverAdapter = new SseServerTransport()
+//   app.use("/sse", createSseExpressRouter(serverAdapter))
+//
+// Usage with Hono:
+//   import { SseServerTransport } from "@kyneta/sse-network-adapter/server"
+//   import { parseTextPostBody } from "@kyneta/sse-network-adapter/express"
+//
+//   const serverAdapter = new SseServerTransport()
+//   // Wire up GET /events and POST /sync manually using
+//   // serverAdapter.registerConnection() and parseTextPostBody()
+
+import type { ChannelMsg, GeneratedChannel, PeerId } from "@kyneta/exchange"
+import { Transport } from "@kyneta/exchange"
+import {
+  DEFAULT_FRAGMENT_THRESHOLD,
+  SseConnection,
+  type SseConnectionConfig,
+} from "./connection.js"
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for the SSE server adapter.
+ */
+export 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
+}
+
+// ---------------------------------------------------------------------------
+// Peer ID generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a random peer ID for connections that don't provide one.
+ */
+function generatePeerId(): PeerId {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+  let result = "sse-"
+  for (let i = 0; i < 12; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length))
+  }
+  return result
+}
+
+// ---------------------------------------------------------------------------
+// SseServerTransport
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ */
+export class SseServerTransport extends Transport<PeerId> {
+  #connections = new Map<PeerId, SseConnection>()
+  readonly #fragmentThreshold: number
+
+  constructor(options?: SseServerTransportOptions) {
+    super({ transportType: "sse-server" })
+    this.#fragmentThreshold =
+      options?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD
+  }
+
+  // ==========================================================================
+  // Adapter abstract method implementations
+  // ==========================================================================
+
+  protected generate(peerId: PeerId): GeneratedChannel {
+    return {
+      transportType: this.transportType,
+      send: (msg: ChannelMsg) => {
+        const connection = this.#connections.get(peerId)
+        if (connection) {
+          connection.send(msg)
+        }
+      },
+      stop: () => {
+        this.unregisterConnection(peerId)
+      },
+    }
+  }
+
+  async onStart(): Promise<void> {
+    // Server adapter starts passively — connections arrive via registerConnection()
+  }
+
+  async onStop(): Promise<void> {
+    // Disconnect all active connections
+    for (const connection of this.#connections.values()) {
+      connection.disconnect()
+    }
+    this.#connections.clear()
+  }
+
+  // ==========================================================================
+  // Connection management
+  // ==========================================================================
+
+  /**
+   * 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 {
+    const resolvedPeerId = peerId ?? generatePeerId()
+
+    // Check for existing connection and clean it up
+    const existingConnection = this.#connections.get(resolvedPeerId)
+    if (existingConnection) {
+      existingConnection.dispose()
+      this.unregisterConnection(resolvedPeerId)
+    }
+
+    // Create channel for this peer
+    const channel = this.addChannel(resolvedPeerId)
+
+    // Create connection object with fragmentation config
+    const connection = new SseConnection(resolvedPeerId, channel.channelId, {
+      fragmentThreshold: this.#fragmentThreshold,
+    })
+    connection._setChannel(channel)
+
+    // Store connection
+    this.#connections.set(resolvedPeerId, connection)
+
+    return connection
+  }
+
+  /**
+   * 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 {
+    const connection = this.#connections.get(peerId)
+    if (connection) {
+      connection.dispose()
+      this.removeChannel(connection.channelId)
+      this.#connections.delete(peerId)
+    }
+  }
+
+  /**
+   * Get an active connection by peer ID.
+   */
+  getConnection(peerId: PeerId): SseConnection | undefined {
+    return this.#connections.get(peerId)
+  }
+
+  /**
+   * Get all active connections.
+   */
+  getAllConnections(): SseConnection[] {
+    return Array.from(this.#connections.values())
+  }
+
+  /**
+   * Check if a peer is connected.
+   */
+  isConnected(peerId: PeerId): boolean {
+    return this.#connections.has(peerId)
+  }
+
+  /**
+   * Get the number of connected peers.
+   */
+  get connectionCount(): number {
+    return this.#connections.size
+  }
+}