@kyneta/sse-transport 1.1.0

package/src/__tests__/connection.test.ts

@@ -0,0 +1,184 @@
+// SseConnection tests.
+//
+// Tests the core behavioral contracts:
+// 1. send() encodes a ChannelMsg to a decodable text frame and calls sendFn
+// 2. send() fragments large messages into multiple sendFn calls
+// 3. receive() routes messages to the channel's onReceive
+// 4. Guard: send() throws if sendFn not set
+// 5. Guard: receive() throws if channel not set
+
+import type { ChannelMsg } from "@kyneta/exchange"
+import { decodeTextFrame, textCodec } from "@kyneta/wire"
+import { describe, expect, it, vi } from "vitest"
+import { SseConnection } from "../connection.js"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createConnection(config?: { fragmentThreshold?: number }) {
+  const conn = new SseConnection("test-peer", 1, config)
+  return conn
+}
+
+function createMockChannel() {
+  return {
+    channelId: 1,
+    onReceive: vi.fn(),
+    send: vi.fn(),
+    type: "connected" as const,
+    transportType: "sse-server",
+  }
+}
+
+const presentMsg: ChannelMsg = {
+  type: "present",
+  docs: [
+    {
+      docId: "doc-1",
+      replicaType: ["plain", 1, 0] as const,
+      mergeStrategy: "sequential" as const,
+    },
+    {
+      docId: "doc-2",
+      replicaType: ["plain", 1, 0] as const,
+      mergeStrategy: "sequential" as const,
+    },
+  ],
+}
+
+const establishMsg: ChannelMsg = {
+  type: "establish-request",
+  identity: { peerId: "peer-1", name: "Peer 1", type: "user" },
+}
+
+// ---------------------------------------------------------------------------
+// send() — encoding round-trip
+// ---------------------------------------------------------------------------
+
+describe("SseConnection — send", () => {
+  it("encodes a ChannelMsg to a valid text frame and calls sendFn", () => {
+    const conn = createConnection()
+    const sent: string[] = []
+    conn.setSendFunction(textFrame => sent.push(textFrame))
+    conn._setChannel(createMockChannel() as any)
+
+    conn.send(presentMsg)
+
+    expect(sent).toHaveLength(1)
+
+    // The sent string should be a valid text frame that round-trips
+    const frame = decodeTextFrame(sent[0]!)
+    expect(frame.content.kind).toBe("complete")
+    const parsed = JSON.parse(frame.content.payload)
+    const decoded = textCodec.decode(parsed)
+    expect(decoded).toHaveLength(1)
+    expect(decoded[0]).toEqual(presentMsg)
+  })
+
+  it("round-trips establish-request with identity", () => {
+    const conn = createConnection()
+    const sent: string[] = []
+    conn.setSendFunction(textFrame => sent.push(textFrame))
+    conn._setChannel(createMockChannel() as any)
+
+    conn.send(establishMsg)
+
+    const frame = decodeTextFrame(sent[0]!)
+    const decoded = textCodec.decode(JSON.parse(frame.content.payload))
+    expect(decoded[0]).toEqual(establishMsg)
+  })
+
+  it("throws if sendFn not set", () => {
+    const conn = createConnection()
+    conn._setChannel(createMockChannel() as any)
+
+    expect(() => conn.send(presentMsg)).toThrow(
+      "Cannot send message: send function not set",
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// send() — fragmentation
+// ---------------------------------------------------------------------------
+
+describe("SseConnection — fragmentation", () => {
+  it("sends a single text frame when below threshold", () => {
+    const conn = createConnection({ fragmentThreshold: 100_000 })
+    const sent: string[] = []
+    conn.setSendFunction(textFrame => sent.push(textFrame))
+    conn._setChannel(createMockChannel() as any)
+
+    conn.send(presentMsg)
+
+    // Small message → single call
+    expect(sent).toHaveLength(1)
+    // Should be a complete frame (starts with ["0c",...])
+    expect(sent[0]).toContain('"0c"')
+  })
+
+  it("fragments into multiple sendFn calls when above threshold", () => {
+    // Use a very low threshold to force fragmentation on a normal message
+    const conn = createConnection({ fragmentThreshold: 20 })
+    const sent: string[] = []
+    conn.setSendFunction(textFrame => sent.push(textFrame))
+    conn._setChannel(createMockChannel() as any)
+
+    conn.send(presentMsg)
+
+    // Should produce multiple fragments
+    expect(sent.length).toBeGreaterThan(1)
+    // Each fragment should be a fragment frame (contains "0f" prefix)
+    for (const frame of sent) {
+      expect(frame).toContain('"0f"')
+    }
+  })
+
+  it("does not fragment when threshold is 0 (disabled)", () => {
+    const conn = createConnection({ fragmentThreshold: 0 })
+    const sent: string[] = []
+    conn.setSendFunction(textFrame => sent.push(textFrame))
+    conn._setChannel(createMockChannel() as any)
+
+    conn.send(presentMsg)
+
+    expect(sent).toHaveLength(1)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// receive() — delivery
+// ---------------------------------------------------------------------------
+
+describe("SseConnection — receive", () => {
+  it("delivers a ChannelMsg to the channel onReceive", () => {
+    const conn = createConnection()
+    const channel = createMockChannel()
+    conn._setChannel(channel as any)
+
+    conn.receive(presentMsg)
+
+    expect(channel.onReceive).toHaveBeenCalledTimes(1)
+    expect(channel.onReceive).toHaveBeenCalledWith(presentMsg)
+  })
+
+  it("throws if channel not set", () => {
+    const conn = createConnection()
+
+    expect(() => conn.receive(presentMsg)).toThrow(
+      "Cannot receive message: channel not set",
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// dispose
+// ---------------------------------------------------------------------------
+
+describe("SseConnection — dispose", () => {
+  it("can be called without error", () => {
+    const conn = createConnection()
+    expect(() => conn.dispose()).not.toThrow()
+  })
+})

package/src/__tests__/sse-handler.test.ts

@@ -0,0 +1,145 @@
+// parseTextPostBody tests.
+//
+// Tests the framework-agnostic POST handler (functional core):
+// 1. Complete text frame body → returns decoded ChannelMsg[]
+// 2. Fragment text frame body → returns pending, then complete on final fragment
+// 3. Malformed body → returns error
+
+import type { ChannelMsg } from "@kyneta/exchange"
+import {
+  encodeTextComplete,
+  fragmentTextPayload,
+  TextReassembler,
+  textCodec,
+} from "@kyneta/wire"
+import { describe, expect, it } from "vitest"
+import { parseTextPostBody } from "../sse-handler.js"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const presentMsg: ChannelMsg = {
+  type: "present",
+  docs: [
+    {
+      docId: "doc-1",
+      replicaType: ["plain", 1, 0] as const,
+      mergeStrategy: "sequential" as const,
+    },
+    {
+      docId: "doc-2",
+      replicaType: ["plain", 1, 0] as const,
+      mergeStrategy: "sequential" as const,
+    },
+  ],
+}
+
+const interestMsg: ChannelMsg = {
+  type: "interest",
+  docId: "doc-1",
+  version: "v1",
+  reciprocate: true,
+}
+
+function encodeAsTextFrame(msg: ChannelMsg): string {
+  return encodeTextComplete(textCodec, msg)
+}
+
+// ---------------------------------------------------------------------------
+// Complete frame
+// ---------------------------------------------------------------------------
+
+describe("parseTextPostBody — complete frame", () => {
+  it("decodes a present message from a complete text frame", () => {
+    const reassembler = new TextReassembler()
+    const body = encodeAsTextFrame(presentMsg)
+
+    const result = parseTextPostBody(reassembler, body)
+
+    expect(result.type).toBe("messages")
+    if (result.type !== "messages") throw new Error("unreachable")
+    expect(result.messages).toHaveLength(1)
+    expect(result.messages[0]).toEqual(presentMsg)
+    expect(result.response).toEqual({ status: 200, body: { ok: true } })
+
+    reassembler.dispose()
+  })
+
+  it("decodes an interest message with all fields", () => {
+    const reassembler = new TextReassembler()
+    const body = encodeAsTextFrame(interestMsg)
+
+    const result = parseTextPostBody(reassembler, body)
+
+    expect(result.type).toBe("messages")
+    if (result.type !== "messages") throw new Error("unreachable")
+    expect(result.messages[0]).toEqual(interestMsg)
+
+    reassembler.dispose()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Fragment frames
+// ---------------------------------------------------------------------------
+
+describe("parseTextPostBody — fragments", () => {
+  it("returns pending for intermediate fragments, then complete on the last", () => {
+    const reassembler = new TextReassembler()
+
+    // Encode the message payload and fragment it into small chunks
+    const payload = JSON.stringify(textCodec.encode(presentMsg))
+    const fragments = fragmentTextPayload(payload, 20) // very small chunks
+
+    expect(fragments.length).toBeGreaterThan(1)
+
+    // All but the last fragment should return pending
+    for (let i = 0; i < fragments.length - 1; i++) {
+      const result = parseTextPostBody(reassembler, fragments[i]!)
+      expect(result.type).toBe("pending")
+      expect(result.response).toEqual({ status: 202, body: { pending: true } })
+    }
+
+    // The last fragment should complete and return messages
+    const finalResult = parseTextPostBody(
+      reassembler,
+      fragments[fragments.length - 1]!,
+    )
+    expect(finalResult.type).toBe("messages")
+    if (finalResult.type !== "messages") throw new Error("unreachable")
+    expect(finalResult.messages).toHaveLength(1)
+    expect(finalResult.messages[0]).toEqual(presentMsg)
+    expect(finalResult.response).toEqual({ status: 200, body: { ok: true } })
+
+    reassembler.dispose()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Malformed body
+// ---------------------------------------------------------------------------
+
+describe("parseTextPostBody — errors", () => {
+  it("returns error for invalid JSON", () => {
+    const reassembler = new TextReassembler()
+
+    const result = parseTextPostBody(reassembler, "not valid json at all")
+
+    expect(result.type).toBe("error")
+    expect(result.response.status).toBe(400)
+
+    reassembler.dispose()
+  })
+
+  it("returns error for valid JSON that is not a text frame", () => {
+    const reassembler = new TextReassembler()
+
+    const result = parseTextPostBody(reassembler, '{"type":"present"}')
+
+    expect(result.type).toBe("error")
+    expect(result.response.status).toBe(400)
+
+    reassembler.dispose()
+  })
+})

package/src/client-state-machine.ts

@@ -0,0 +1,69 @@
+// client-state-machine — SSE client state machine.
+//
+// Thin wrapper around the generic ClientStateMachine<S> from @kyneta/exchange,
+// providing the SSE-specific 4-state transition map and an isConnected() helper.
+//
+// States: disconnected → connecting → connected
+//                            ↓            ↓
+//                       reconnecting ← ─ ─┘
+//                            ↓
+//                       connecting (retry)
+//                            ↓
+//                       disconnected (max retries)
+
+import { ClientStateMachine } from "@kyneta/exchange"
+import type { SseClientState } from "./types.js"
+
+// ---------------------------------------------------------------------------
+// SSE transition map
+// ---------------------------------------------------------------------------
+
+const SSE_VALID_TRANSITIONS: Record<string, string[]> = {
+  disconnected: ["connecting"],
+  connecting: ["connected", "disconnected", "reconnecting"],
+  connected: ["disconnected", "reconnecting"],
+  reconnecting: ["connecting", "disconnected"],
+}
+
+// ---------------------------------------------------------------------------
+// SseClientStateMachine
+// ---------------------------------------------------------------------------
+
+/**
+ * Observable state machine for SSE client connection lifecycle.
+ *
+ * Extends the generic `ClientStateMachine<SseClientState>` with
+ * an SSE-specific convenience helper. Unlike the WebSocket state machine,
+ * SSE has no `"ready"` state — the connection is usable as soon as
+ * `EventSource.onopen` fires.
+ *
+ * Usage:
+ * ```typescript
+ * const sm = new SseClientStateMachine()
+ *
+ * sm.subscribeToTransitions(({ from, to }) => {
+ *   console.log(`${from.status} → ${to.status}`)
+ * })
+ *
+ * sm.transition({ status: "connecting", attempt: 1 })
+ * sm.transition({ status: "connected" })
+ *
+ * // Transitions are delivered asynchronously via microtask
+ * // Listener will see: disconnected → connecting, connecting → connected
+ * ```
+ */
+export class SseClientStateMachine extends ClientStateMachine<SseClientState> {
+  constructor() {
+    super({
+      initialState: { status: "disconnected" },
+      validTransitions: SSE_VALID_TRANSITIONS,
+    })
+  }
+
+  /**
+   * Check if the client is connected (EventSource open, channel established).
+   */
+  isConnected(): boolean {
+    return this.getStatus() === "connected"
+  }
+}