@kyneta/sse-transport 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Duane Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,334 @@
+# @kyneta/sse-network-adapter
+
+SSE (Server-Sent Events) adapter for `@kyneta/exchange` — client, server, and Express integration. Provides real-time sync using SSE for server→client messages and HTTP POST for client→server messages, both encoded with the `@kyneta/wire` text protocol (JSON codec + text framing + text fragmentation).
+
+## Subpath Exports
+
+| Export | Entry point | Environment |
+|--------|-------------|-------------|
+| `@kyneta/sse-network-adapter/client` | `./dist/client.js` | Browser, Bun, Node.js |
+| `@kyneta/sse-network-adapter/server` | `./dist/server.js` | Bun, Node.js |
+| `@kyneta/sse-network-adapter/express` | `./dist/express.js` | Node.js (Express) |
+
+## Server Setup
+
+### Express (recommended)
+
+Use `createSseExpressRouter` for zero-boilerplate integration with Express:
+
+```/dev/null/express-server.ts#L1-20
+import { Exchange } from "@kyneta/exchange"
+import { SseServerAdapter } from "@kyneta/sse-network-adapter/server"
+import { createSseExpressRouter } from "@kyneta/sse-network-adapter/express"
+import express from "express"
+
+const app = express()
+
+const serverAdapter = new SseServerAdapter()
+
+const exchange = new Exchange({
+  identity: { peerId: "server", name: "server", type: "service" },
+  adapters: [() => serverAdapter],
+})
+
+app.use("/sse", createSseExpressRouter(serverAdapter, {
+  syncPath: "/sync",
+  eventsPath: "/events",
+  heartbeatInterval: 30000,
+}))
+
+app.listen(3000)
+```
+
+### Hono
+
+For Hono or other frameworks, use `parseTextPostBody` and `SseServerAdapter.registerConnection` directly:
+
+```/dev/null/hono-server.ts#L1-45
+import { SseServerAdapter } from "@kyneta/sse-network-adapter/server"
+import { parseTextPostBody } from "@kyneta/sse-network-adapter/express"
+import { Hono } from "hono"
+import { streamSSE } from "hono/streaming"
+
+const sseAdapter = new SseServerAdapter()
+
+const app = new Hono()
+
+app.get("/sse/events", async (c) => {
+  const peerId = c.req.query("peerId")
+  if (!peerId) return c.json({ error: "peerId required" }, 400)
+
+  return streamSSE(c, async (stream) => {
+    const connection = sseAdapter.registerConnection(peerId)
+
+    // sendFn receives pre-encoded text frame strings
+    connection.setSendFunction((textFrame) => {
+      stream.writeSSE({ data: textFrame })
+    })
+
+    stream.onAbort(() => {
+      sseAdapter.unregisterConnection(peerId)
+    })
+
+    await new Promise(() => {}) // keep alive
+  })
+})
+
+app.post("/sse/sync", async (c) => {
+  const peerId = c.req.header("x-peer-id")
+  if (!peerId) return c.json({ error: "x-peer-id required" }, 400)
+
+  const connection = sseAdapter.getConnection(peerId)
+  if (!connection) return c.json({ error: "Not connected" }, 404)
+
+  const body = await c.req.text()
+  const result = parseTextPostBody(connection.reassembler, body)
+
+  if (result.type === "messages") {
+    for (const msg of result.messages) {
+      connection.receive(msg)
+    }
+  }
+
+  return c.json(result.response.body, result.response.status)
+})
+```
+
+## Client Setup
+
+### Browser
+
+Use `createSseClient` for browser-to-server connections:
+
+```/dev/null/browser-client.ts#L1-13
+import { Exchange } from "@kyneta/exchange"
+import { createSseClient } from "@kyneta/sse-network-adapter/client"
+
+const exchange = new Exchange({
+  identity: { peerId: "browser-client", name: "Alice", type: "user" },
+  adapters: [createSseClient({
+    postUrl: "/sse/sync",
+    eventSourceUrl: (peerId) => `/sse/events?peerId=${peerId}`,
+    reconnect: { enabled: true },
+  })],
+})
+```
+
+## Connection Lifecycle
+
+The client adapter manages connection state through a validated state machine. Unlike the WebSocket adapter, SSE has no separate "ready" signal — the connection is usable as soon as `EventSource.onopen` fires.
+
+```/dev/null/state-machine.txt#L1-7
+disconnected → connecting → connected
+                   ↓            ↓
+              reconnecting ← ─ ─┘
+                   ↓
+              connecting (retry)
+                   ↓
+              disconnected (max retries)
+```
+
+| State | Description |
+|-------|-------------|
+| `disconnected` | No active connection. Optional `reason` field describes why. |
+| `connecting` | EventSource being created. Tracks `attempt` number. |
+| `connected` | EventSource open — protocol messages can flow. |
+| `reconnecting` | Connection lost, scheduling next attempt. Tracks `attempt` and `nextAttemptMs`. |
+
+### Connection Handshake
+
+1. Client creates `EventSource`, transitions to `connecting`
+2. `EventSource.onopen` fires, transitions to `connected`
+3. Client creates its channel, calls `establishChannel()`
+4. Synchronizer exchanges `establish-request` / `establish-response`
+
+### EventSource Reconnection
+
+On `EventSource.onerror`, the adapter **closes the EventSource immediately** and takes over reconnection via the state machine's backoff logic. This prevents the browser's built-in `EventSource` reconnection from running, giving full control over backoff timing and attempt counting.
+
+### Observing State
+
+```/dev/null/observe-state.ts#L1-18
+import { createSseClient } from "@kyneta/sse-network-adapter/client"
+
+const adapter = createSseClient({
+  postUrl: "/sse/sync",
+  eventSourceUrl: (peerId) => `/sse/events?peerId=${peerId}`,
+  lifecycle: {
+    onStateChange: ({ from, to }) => console.log(`${from.status} → ${to.status}`),
+    onDisconnect: (reason) => console.log("disconnected:", reason.type),
+    onReconnecting: (attempt, nextMs) => console.log(`retry #${attempt} in ${nextMs}ms`),
+    onReconnected: () => console.log("reconnected"),
+  },
+})
+
+// Or subscribe to transitions programmatically
+const unsub = adapter.subscribeToTransitions(({ from, to }) => {
+  console.log(`${from.status} → ${to.status}`)
+})
+
+await adapter.waitForStatus("connected", { timeoutMs: 5000 })
+```
+
+## Wire Format
+
+Both directions use the `@kyneta/wire` text pipeline — symmetric encoding with asymmetric transport:
+
+| Direction | Transport | Wire format |
+|-----------|-----------|-------------|
+| Client → Server | HTTP POST (`text/plain`) | Text frame (`["0c", <payload>]`) |
+| Server → Client | SSE `data:` event | Text frame (`["0c", <payload>]`) |
+
+### Text Frames
+
+Every message is wrapped in a text frame — a JSON array with a 2-character prefix:
+
+```/dev/null/text-frame-example.txt#L1-5
+Complete frame:  ["0c", {"type":"discover","docIds":["doc-1"]}]
+Fragment frame:  ["0f", "a1b2c3d4", 0, 3, 1500, "{\"type\":\"offer\"..."]
+```
+
+The `"0c"` prefix means "version 0, complete, no hash". Fragments use `"0f"` and carry `frameId`, `index`, `total`, `totalSize`, and a JSON substring chunk.
+
+### Why Text Instead of Binary?
+
+The old `@loro-extended/adapter-sse` used an asymmetric format: binary CBOR for POST, ad-hoc JSON for SSE. The new adapter uses uniform text encoding because:
+
+- Single code path for encode/decode on both client and server
+- Human-readable POST bodies and SSE events for debugging
+- No need for `express.raw()` with `application/octet-stream`
+- Text fragmentation works in both directions
+
+The ~33% bandwidth overhead of base64 for binary payloads (vs. native CBOR byte strings) is acceptable for SSE's use case (chat, presence, signaling). For bandwidth-sensitive workloads, use the WebSocket adapter.
+
+## Configuration
+
+### Client Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `postUrl` | — | POST URL. String or `(peerId) => string` function. |
+| `eventSourceUrl` | — | SSE URL. String or `(peerId) => string` function. |
+| `reconnect.enabled` | `true` | Enable automatic reconnection. |
+| `reconnect.maxAttempts` | `10` | Maximum reconnection attempts. |
+| `reconnect.baseDelay` | `1000` | Base delay in ms for exponential backoff. |
+| `reconnect.maxDelay` | `30000` | Maximum delay cap in ms. |
+| `postRetry.maxAttempts` | `3` | Maximum POST retry attempts. |
+| `postRetry.baseDelay` | `1000` | Base delay in ms for POST retry backoff. |
+| `postRetry.maxDelay` | `10000` | Maximum POST retry delay in ms. |
+| `fragmentThreshold` | `60000` | Character threshold for text fragmentation. |
+
+### Server Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `fragmentThreshold` | `60000` | Character threshold for text fragmentation. |
+
+### Express Router Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `syncPath` | `"/sync"` | Path for POST endpoint. |
+| `eventsPath` | `"/events"` | Path for SSE endpoint. |
+| `heartbeatInterval` | `30000` | Heartbeat interval in ms. |
+| `getPeerIdFromSyncRequest` | reads `x-peer-id` header | Custom peerId extraction for POST. |
+| `getPeerIdFromEventsRequest` | reads `peerId` query param | Custom peerId extraction for SSE. |
+
+### Heartbeat
+
+The Express router sends SSE comment heartbeats (`: heartbeat\n\n`) at the configured interval. SSE comments are silently ignored by `EventSource` clients. This keeps connections alive through proxies and load balancers that terminate idle connections.
+
+## Custom Framework Integration
+
+The `parseTextPostBody` function provides a framework-agnostic handler for POST requests:
+
+```/dev/null/custom-framework.ts#L1-13
+import { parseTextPostBody } from "@kyneta/sse-network-adapter/express"
+
+// In your framework's request handler
+const result = parseTextPostBody(connection.reassembler, bodyAsString)
+
+if (result.type === "messages") {
+  for (const msg of result.messages) {
+    connection.receive(msg)
+  }
+}
+
+// Send response
+response.status(result.response.status).json(result.response.body)
+```
+
+### Response Types
+
+| Result Type | HTTP Status | Meaning |
+|-------------|-------------|---------|
+| `messages` | 200 | Message(s) decoded successfully |
+| `pending` | 202 | Fragment received, waiting for more |
+| `error` | 400 | Decode or reassembly error |
+
+### The `sendFn` Pattern
+
+`SseConnection.send()` handles encoding and fragmentation internally. The injected `sendFn` receives pre-encoded text frame strings — the framework integration just wraps them in transport syntax:
+
+```/dev/null/sendfn-pattern.ts#L1-8
+// Express
+connection.setSendFunction((textFrame) => {
+  res.write(`data: ${textFrame}\n\n`)
+})
+
+// Hono
+connection.setSendFunction((textFrame) => {
+  stream.writeSSE({ data: textFrame })
+})
+```
+
+## Architecture
+
+```/dev/null/architecture.txt#L1-17
+┌──────────────────────────────────────────────────────────┐
+│                        Client                            │
+│  ┌──────────────────┐        ┌───────────────────┐       │
+│  │ SseClientAdapter │        │ EventSource       │       │
+│  │ (text POST)      │───────▶│ (text receive)    │       │
+│  └──────────────────┘        └───────────────────┘       │
+└──────────────────────────────────────────────────────────┘
+         │                             ▲
+         │ HTTP POST                   │ SSE
+         │ (text wire frame)           │ (text wire frame)
+         ▼                             │
+┌──────────────────────────────────────────────────────────┐
+│                        Server                            │
+│  ┌──────────────────┐        ┌───────────────────┐       │
+│  │ Express Router   │        │ SSE Writer        │       │
+│  │ (parseTextPost)  │───────▶│ (sendFn)          │       │
+│  └──────────────────┘        └───────────────────┘       │
+│           │                             ▲                │
+│           ▼                             │                │
+│  ┌───────────────────────────────────────────────────┐   │
+│  │          SseServerAdapter                         │   │
+│  │  ┌────────────────────────────────────────────┐   │   │
+│  │  │ SseConnection (per peer)                   │   │   │
+│  │  │ - TextReassembler (handles fragmented POST)│   │   │
+│  │  │ - textCodec encoding (handles outbound SSE)│   │   │
+│  │  │ - Channel reference                        │   │   │
+│  │  └────────────────────────────────────────────┘   │   │
+│  └───────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Peer Dependencies
+
+```/dev/null/package.json#L1-4
+{
+  "peerDependencies": {
+    "@kyneta/exchange": ">=0.0.1",
+    "@kyneta/wire": ">=0.0.1"
+  }
+}
+```
+
+Express is an optional peer dependency — only needed if using `@kyneta/sse-network-adapter/express`.
+
+## License
+
+MIT

package/dist/chunk-7D4SUZUM.js

@@ -0,0 +1,38 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+export {
+  __require,
+  __commonJS,
+  __toESM
+};
+//# sourceMappingURL=chunk-7D4SUZUM.js.map

package/dist/chunk-7D4SUZUM.js.map

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

package/dist/chunk-TR4Y3HFB.js

@@ -0,0 +1,255 @@
+// src/connection.ts
+import {
+  encodeTextComplete,
+  fragmentTextPayload,
+  TextReassembler,
+  textCodec
+} from "@kyneta/wire";
+var DEFAULT_FRAGMENT_THRESHOLD = 6e4;
+var SseConnection = class {
+  peerId;
+  channelId;
+  #channel = null;
+  #sendFn = null;
+  #onDisconnect = null;
+  // Fragmentation support
+  #fragmentThreshold;
+  /**
+   * Text reassembler for handling fragmented POST bodies.
+   * Each connection has its own reassembler to track in-flight fragment batches.
+   */
+  reassembler;
+  constructor(peerId, channelId, config) {
+    this.peerId = peerId;
+    this.channelId = channelId;
+    this.#fragmentThreshold = config?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD;
+    this.reassembler = new TextReassembler({
+      timeoutMs: 1e4,
+      onTimeout: (frameId) => {
+        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) {
+    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) {
+    this.#sendFn = sendFn;
+  }
+  /**
+   * Set the function to call when this connection is disconnected.
+   */
+  setDisconnectHandler(handler) {
+    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) {
+    if (!this.#sendFn) {
+      throw new Error(
+        `Cannot send message: send function not set for peer ${this.peerId}`
+      );
+    }
+    const textFrame = encodeTextComplete(textCodec, msg);
+    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) {
+    if (!this.#channel) {
+      throw new Error(
+        `Cannot receive message: channel not set for peer ${this.peerId}`
+      );
+    }
+    this.#channel.onReceive(msg);
+  }
+  /**
+   * Disconnect this connection.
+   */
+  disconnect() {
+    this.#onDisconnect?.();
+  }
+  /**
+   * Dispose of resources held by this connection.
+   * Must be called when the connection is closed to prevent timer leaks.
+   */
+  dispose() {
+    this.reassembler.dispose();
+  }
+};
+
+// src/server-transport.ts
+import { Transport } from "@kyneta/exchange";
+function generatePeerId() {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "sse-";
+  for (let i = 0; i < 12; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+var SseServerTransport = class extends Transport {
+  #connections = /* @__PURE__ */ new Map();
+  #fragmentThreshold;
+  constructor(options) {
+    super({ transportType: "sse-server" });
+    this.#fragmentThreshold = options?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD;
+  }
+  // ==========================================================================
+  // Adapter abstract method implementations
+  // ==========================================================================
+  generate(peerId) {
+    return {
+      transportType: this.transportType,
+      send: (msg) => {
+        const connection = this.#connections.get(peerId);
+        if (connection) {
+          connection.send(msg);
+        }
+      },
+      stop: () => {
+        this.unregisterConnection(peerId);
+      }
+    };
+  }
+  async onStart() {
+  }
+  async onStop() {
+    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) {
+    const resolvedPeerId = peerId ?? generatePeerId();
+    const existingConnection = this.#connections.get(resolvedPeerId);
+    if (existingConnection) {
+      existingConnection.dispose();
+      this.unregisterConnection(resolvedPeerId);
+    }
+    const channel = this.addChannel(resolvedPeerId);
+    const connection = new SseConnection(resolvedPeerId, channel.channelId, {
+      fragmentThreshold: this.#fragmentThreshold
+    });
+    connection._setChannel(channel);
+    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) {
+    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) {
+    return this.#connections.get(peerId);
+  }
+  /**
+   * Get all active connections.
+   */
+  getAllConnections() {
+    return Array.from(this.#connections.values());
+  }
+  /**
+   * Check if a peer is connected.
+   */
+  isConnected(peerId) {
+    return this.#connections.has(peerId);
+  }
+  /**
+   * Get the number of connected peers.
+   */
+  get connectionCount() {
+    return this.#connections.size;
+  }
+};
+
+export {
+  DEFAULT_FRAGMENT_THRESHOLD,
+  SseConnection,
+  SseServerTransport
+};
+//# sourceMappingURL=chunk-TR4Y3HFB.js.map