@kyneta/sse-transport 1.1.0

package/src/server.ts

@@ -0,0 +1,33 @@
+// server — barrel export for @kyneta/sse-network-adapter/server.
+//
+// This is the server-side entry point. It exports everything needed
+// to create an SSE server adapter with any framework.
+
+// ---------------------------------------------------------------------------
+// Server adapter
+// ---------------------------------------------------------------------------
+
+export {
+  SseServerTransport,
+  type SseServerTransportOptions,
+} from "./server-transport.js"
+
+// ---------------------------------------------------------------------------
+// Connection
+// ---------------------------------------------------------------------------
+
+export {
+  DEFAULT_FRAGMENT_THRESHOLD,
+  SseConnection,
+  type SseConnectionConfig,
+} from "./connection.js"
+
+// ---------------------------------------------------------------------------
+// Shared types
+// ---------------------------------------------------------------------------
+
+export type {
+  DisconnectReason,
+  SseConnectionHandle,
+  SseConnectionResult,
+} from "./types.js"

package/src/sse-handler.ts

@@ -0,0 +1,116 @@
+// sse-handler — framework-agnostic SSE POST handler (Functional Core).
+//
+// This module provides pure functions for handling text POST requests
+// in SSE adapters. Framework-specific adapters (Express, Hono, etc.)
+// use these functions and handle the HTTP-specific concerns.
+//
+// Design: Functional Core / Imperative Shell
+// - This module parses and decodes, returning a result describing what to do
+// - Framework adapters execute side effects (delivering messages, sending responses)
+//
+// The POST body is a text wire frame string (JSON array with "0c"/"0f" prefix).
+// Decoding is two-step:
+//   1. TextReassembler.receive(body) → Frame<string>
+//   2. JSON.parse(frame.content.payload) → textCodec.decode(parsed) → ChannelMsg[]
+
+import type { ChannelMsg } from "@kyneta/exchange"
+import { type TextReassembler, textCodec } from "@kyneta/wire"
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+/**
+ * Response to send back to the client after processing a POST.
+ */
+export interface SsePostResponse {
+  status: 200 | 202 | 400
+  body: { ok: true } | { pending: true } | { error: string }
+}
+
+/**
+ * Result of parsing a text POST body.
+ *
+ * Discriminated union describing what happened:
+ * - "messages": Complete message(s) decoded, ready to deliver
+ * - "pending": Fragment received, waiting for more
+ * - "error": Decode/reassembly error
+ */
+export type SsePostResult =
+  | { type: "messages"; messages: ChannelMsg[]; response: SsePostResponse }
+  | { type: "pending"; response: SsePostResponse }
+  | { type: "error"; response: SsePostResponse }
+
+// ---------------------------------------------------------------------------
+// parseTextPostBody
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a text POST body through the reassembler.
+ *
+ * This is the functional core of POST handling. It:
+ * 1. Passes the body through the reassembler (handles fragmentation)
+ * 2. If complete, decodes the text frame payload to ChannelMsg(s)
+ * 3. Returns a result describing what happened
+ *
+ * The caller (framework adapter) executes side effects based on the result.
+ *
+ * @param reassembler - The connection's text fragment reassembler
+ * @param body - Text wire frame string (JSON array with "0c"/"0f" prefix)
+ * @returns Result describing what to do
+ *
+ * @example
+ * ```typescript
+ * // In Express router (imperative shell)
+ * const result = parseTextPostBody(connection.reassembler, req.body)
+ *
+ * if (result.type === "messages") {
+ *   for (const msg of result.messages) {
+ *     connection.receive(msg)
+ *   }
+ * }
+ *
+ * res.status(result.response.status).json(result.response.body)
+ * ```
+ */
+export function parseTextPostBody(
+  reassembler: TextReassembler,
+  body: string,
+): SsePostResult {
+  const result = reassembler.receive(body)
+
+  if (result.status === "complete") {
+    try {
+      // Two-step decode:
+      // 1. Frame<string> → extract payload string
+      // 2. JSON.parse → textCodec.decode → ChannelMsg[]
+      const parsed = JSON.parse(result.frame.content.payload)
+      const messages = textCodec.decode(parsed)
+      return {
+        type: "messages",
+        messages,
+        response: { status: 200, body: { ok: true } },
+      }
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : "decode_failed"
+      return {
+        type: "error",
+        response: { status: 400, body: { error: errorMessage } },
+      }
+    }
+  } else if (result.status === "pending") {
+    return {
+      type: "pending",
+      response: { status: 202, body: { pending: true } },
+    }
+  } else {
+    // result.status === "error"
+    return {
+      type: "error",
+      response: {
+        status: 400,
+        body: { error: result.error.type },
+      },
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,108 @@
+// types — SSE-specific types for @kyneta/sse-network-adapter.
+//
+// SSE has a simpler lifecycle than WebSocket — no "ready" state because
+// there's no transport-level handshake. The connection is usable as soon
+// as EventSource.onopen fires.
+//
+// DisconnectReason is SSE-specific: no "closed" variant (SSE doesn't have
+// close codes) and no "not-started" variant (no "ready" gate).
+
+import type { PeerId } from "@kyneta/exchange"
+
+// Re-export specialized transition types from generic state machine
+export type { StateTransition, TransitionListener } from "@kyneta/exchange"
+
+// ---------------------------------------------------------------------------
+// Disconnect reason
+// ---------------------------------------------------------------------------
+
+/**
+ * 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
+ */
+export type DisconnectReason =
+  | { type: "intentional" }
+  | { type: "error"; error: Error }
+  | { type: "max-retries-exceeded"; attempts: number }
+
+// ---------------------------------------------------------------------------
+// Connection state (for client adapter observability)
+// ---------------------------------------------------------------------------
+
+/**
+ * All possible states of the SSE client.
+ *
+ * State machine transitions (4 states, no "ready"):
+ * ```
+ * disconnected → connecting → connected
+ *                    ↓            ↓
+ *               reconnecting ← ─ ─┘
+ *                    ↓
+ *               connecting (retry)
+ *                    ↓
+ *               disconnected (max retries)
+ * ```
+ */
+export type SseClientState =
+  | { status: "disconnected"; reason?: DisconnectReason }
+  | { status: "connecting"; attempt: number }
+  | { status: "connected" }
+  | { status: "reconnecting"; attempt: number; nextAttemptMs: number }
+
+/**
+ * A state transition event for SSE client states.
+ * Specialized from the generic `StateTransition<S>`.
+ */
+export type { StateTransition as SseClientStateTransition } from "@kyneta/exchange"
+
+// ---------------------------------------------------------------------------
+// Connection handle — used by server adapter
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle for an active SSE connection (server-side).
+ */
+export 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.
+ */
+export interface SseConnectionResult {
+  /** The connection handle for managing this peer. */
+  connection: SseConnectionHandle
+}
+
+// ---------------------------------------------------------------------------
+// Client options
+// ---------------------------------------------------------------------------
+
+/**
+ * Lifecycle event callbacks for the SSE client.
+ */
+export 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
+}