@kyneta/sse-transport 1.6.0 → 1.7.0

package/src/__tests__/connection.test.ts

@@ -2,20 +2,8 @@
 
 import { SYNC_AUTHORITATIVE } from "@kyneta/schema"
 import type { ChannelMsg } from "@kyneta/transport"
-import type { WireInterestMsg } from "@kyneta/wire"
-import {
-  applyInboundAliasing,
-  applyOutboundAliasing,
-  complete,
-  decodeTextFrame,
-  decodeTextWireMessage,
-  emptyAliasState,
-  encodeTextFrame,
-  encodeTextWireMessage,
-  fragmentTextPayload,
-  MessageType,
-  TEXT_WIRE_VERSION,
-} from "@kyneta/wire"
+import { Pipeline } from "@kyneta/transport"
+import { complete, encodeBinaryFrame, WIRE_VERSION } from "@kyneta/wire"
 import { describe, expect, it, vi } from "vitest"
 import { SseConnection } from "../connection.js"
 
@@ -39,12 +27,16 @@ function createMockChannel() {
 }
 
 /**
- * Encode a ChannelMsg into a text frame string via the alias-aware pipeline.
+ * Encode a ChannelMsg into binary frame bytes via Pipeline<"binary">.
+ * This simulates what the client sends over POST.
  */
-function encodeToTextFrame(msg: ChannelMsg): string {
-  const { wire } = applyOutboundAliasing(emptyAliasState(), msg)
-  const payload = JSON.stringify(encodeTextWireMessage(wire))
-  return encodeTextFrame(complete(TEXT_WIRE_VERSION, payload))
+function encodeToBinaryFrame(msg: ChannelMsg): Uint8Array<ArrayBuffer> {
+  const pipeline = new Pipeline({ send: "binary" })
+  const results = pipeline.send(msg)
+  pipeline.dispose()
+  const r = results[0]
+  if (!r || !r.ok) throw new Error("Failed to encode message via pipeline")
+  return r.value
 }
 
 const presentMsg: ChannelMsg = {
@@ -80,41 +72,16 @@ describe("SseConnection — send", () => {
 
     expect(sent).toHaveLength(1)
 
+    // Verify the sent text frame can be decoded back via Pipeline<"text">
+    const recvPipeline = new Pipeline({ send: "text" })
     const sentFrame = sent.at(0)
     if (!sentFrame) throw new Error("expected sent frame")
-    const frame = decodeTextFrame(sentFrame)
-    expect(frame.content.kind).toBe("complete")
-    const parsed = JSON.parse(frame.content.payload)
-    const wire = decodeTextWireMessage(parsed)
-    const decoded = applyInboundAliasing(emptyAliasState(), wire)
-    expect(decoded.error).toBeUndefined()
-    expect(decoded.msg).toEqual(presentMsg)
-  })
-
-  it("sends messages with short field names (alias-form wire format)", () => {
-    const conn = createConnection()
-    const sent: string[] = []
-    conn.setSendFunction(textFrame => sent.push(textFrame))
-    conn._setChannel(createMockChannel() as any)
-
-    conn.send(presentMsg)
-
-    const sentFrame = sent.at(0)
-    if (!sentFrame) throw new Error("expected sent frame")
-    const frame = decodeTextFrame(sentFrame)
-    const payload = JSON.parse(frame.content.payload) as Record<string, unknown>
-
-    // The alias-aware pipeline uses compact integer discriminators and
-    // short field names, not the long-name human-readable format.
-    expect(payload.t).toBe(MessageType.Present)
-    expect(payload.docs).toBeInstanceOf(Array)
-    const doc = (payload.docs as Array<Record<string, unknown>>)[0]
-    if (!doc) throw new Error("expected doc entry")
-    expect(doc.d).toBe("doc-1")
-    expect(doc.sh).toBe("test-hash")
-    // No long-name fields from the old textCodec format
-    expect(doc.docId).toBeUndefined()
-    expect(doc.schemaHash).toBeUndefined()
+    const results = recvPipeline.receive(sentFrame)
+    recvPipeline.dispose()
+    expect(results).toHaveLength(1)
+    const r = results[0]
+    if (!r || !r.ok) throw new Error("expected successful decode")
+    expect(r.value).toEqual(presentMsg)
   })
 
   it("throws if sendFn not set", () => {
@@ -141,7 +108,6 @@ describe("SseConnection — fragmentation", () => {
     conn.send(presentMsg)
 
     expect(sent).toHaveLength(1)
-    expect(sent[0]).toContain('"1c"')
   })
 
   it("fragments into multiple sendFn calls when above threshold", () => {
@@ -153,9 +119,6 @@ describe("SseConnection — fragmentation", () => {
     conn.send(presentMsg)
 
     expect(sent.length).toBeGreaterThan(1)
-    for (const frame of sent) {
-      expect(frame).toContain('"1f"')
-    }
   })
 
   it("does not fragment when threshold is 0 (disabled)", () => {
@@ -200,11 +163,11 @@ describe("SseConnection — receive", () => {
 // ---------------------------------------------------------------------------
 
 describe("SseConnection — handlePostBody", () => {
-  it("decodes a complete frame to messages", () => {
+  it("decodes a complete binary frame to messages", () => {
     const conn = createConnection()
 
-    const textFrame = encodeToTextFrame(presentMsg)
-    const result = conn.handlePostBody(textFrame)
+    const frameBytes = encodeToBinaryFrame(presentMsg)
+    const result = conn.handlePostBody(frameBytes)
 
     expect(result.type).toBe("messages")
     if (result.type !== "messages") throw new Error("expected messages")
@@ -213,109 +176,67 @@ describe("SseConnection — handlePostBody", () => {
     expect(result.response).toEqual({ status: 200, body: { ok: true } })
   })
 
-  it("skips messages with alias resolution errors, continues processing", () => {
-    const conn = createConnection()
-
-    // An interest with an unresolved dx alias will fail alias resolution.
-    // The connection should skip it (not throw, not break) and return
-    // an empty messages array with a 200 (no fatal error).
-    const unresolvedInterest: WireInterestMsg = {
-      t: MessageType.Interest,
-      dx: 999,
-    }
-    const payload = JSON.stringify(encodeTextWireMessage(unresolvedInterest))
-    const textFrame = encodeTextFrame(complete(TEXT_WIRE_VERSION, payload))
-
-    const result = conn.handlePostBody(textFrame)
-
-    expect(result.type).toBe("messages")
-    if (result.type !== "messages") throw new Error("expected messages")
-    expect(result.messages).toHaveLength(0)
-    expect(result.response).toEqual({ status: 200, body: { ok: true } })
-  })
-
-  it("reassembles fragmented payloads", () => {
-    const conn = createConnection()
-
-    const { wire } = applyOutboundAliasing(emptyAliasState(), presentMsg)
-    const payload = JSON.stringify(encodeTextWireMessage(wire))
-    const fragments = fragmentTextPayload(payload, 50, 42)
-
-    expect(fragments.length).toBeGreaterThan(1)
-
-    for (let i = 0; i < fragments.length - 1; i++) {
-      const fragment = fragments.at(i)
-      if (fragment === undefined) throw new Error(`missing fragment ${i}`)
-      const result = conn.handlePostBody(fragment)
-      expect(result.type).toBe("pending")
-      if (result.type === "pending") {
-        expect(result.response).toEqual({
-          status: 202,
-          body: { pending: true },
-        })
-      }
-    }
-
-    const lastFragment = fragments.at(fragments.length - 1)
-    if (lastFragment === undefined) throw new Error("missing last fragment")
-    const finalResult = conn.handlePostBody(lastFragment)
-
-    expect(finalResult.type).toBe("messages")
-    if (finalResult.type !== "messages") throw new Error("expected messages")
-    expect(finalResult.messages).toHaveLength(1)
-    expect(finalResult.messages[0]).toEqual(presentMsg)
-  })
-
   it("resolves docId aliases across messages", () => {
     const conn = createConnection()
 
-    const { wire: presentWire } = applyOutboundAliasing(
-      emptyAliasState(),
-      presentMsg,
-    )
-    const presentPayload = JSON.stringify(encodeTextWireMessage(presentWire))
-    const presentFrame = encodeTextFrame(
-      complete(TEXT_WIRE_VERSION, presentPayload),
-    )
-
-    const presentResult = conn.handlePostBody(presentFrame)
+    // First message: present (establishes alias bindings)
+    const presentBytes = encodeToBinaryFrame(presentMsg)
+    const presentResult = conn.handlePostBody(presentBytes)
     expect(presentResult.type).toBe("messages")
     if (presentResult.type !== "messages") throw new Error("expected messages")
     expect(presentResult.messages[0]).toEqual(presentMsg)
 
-    const docAlias = (presentWire as { docs: Array<{ a?: number }> }).docs[0]?.a
-    if (docAlias === undefined) throw new Error("expected doc alias assignment")
-
-    const interestWire: WireInterestMsg = {
-      t: MessageType.Interest,
-      dx: docAlias,
+    // Second message: interest using the alias established by present.
+    // To build this, we use the same pipeline so its alias table is in sync.
+    const sendPipeline = new Pipeline({ send: "binary" })
+    // Send the present first to establish alias bindings in the send pipeline
+    sendPipeline.send(presentMsg)
+    // Now send an interest for the first doc
+    const interestMsg: ChannelMsg = {
+      type: "interest",
+      docId: "doc-1",
     }
-    const interestPayload = JSON.stringify(encodeTextWireMessage(interestWire))
-    const interestFrame = encodeTextFrame(
-      complete(TEXT_WIRE_VERSION, interestPayload),
-    )
+    const interestResults = sendPipeline.send(interestMsg)
+    sendPipeline.dispose()
+    const interestFrame = interestResults[0]
+    if (!interestFrame || !interestFrame.ok)
+      throw new Error("expected interest frame")
 
-    const interestResult = conn.handlePostBody(interestFrame)
+    const interestResult = conn.handlePostBody(interestFrame.value)
     expect(interestResult.type).toBe("messages")
     if (interestResult.type !== "messages") throw new Error("expected messages")
     expect(interestResult.messages).toHaveLength(1)
 
-    const interestMsg = interestResult.messages[0]
-    if (!interestMsg) throw new Error("expected interest message")
-    expect(interestMsg.type).toBe("interest")
-    if (interestMsg.type !== "interest") throw new Error("expected interest")
-    expect(interestMsg.docId).toBe("doc-1")
+    const decoded = interestResult.messages[0]
+    if (!decoded) throw new Error("expected interest message")
+    expect(decoded.type).toBe("interest")
+    if (decoded.type !== "interest") throw new Error("expected interest")
+    expect(decoded.docId).toBe("doc-1")
   })
 
-  it("returns error on malformed JSON input", () => {
+  it("returns error on malformed binary input", () => {
     const conn = createConnection()
 
-    const result = conn.handlePostBody("not json")
+    // Garbage bytes that aren't a valid binary frame
+    const garbage = new Uint8Array([0xff, 0xff, 0xff, 0xff])
+    const result = conn.handlePostBody(garbage)
 
     expect(result.type).toBe("error")
-    if (result.type === "error") {
-      expect(result.response.status).toBe(400)
-    }
+    expect(result.response.status).toBe(400)
+    conn.dispose()
+  })
+
+  it("returns error (not pending) on malformed CBOR payload", () => {
+    const conn = new SseConnection("peer-err", 1)
+    // Construct a structurally valid binary frame wrapping garbage CBOR.
+    // The frame parser accepts it (valid header), but CBOR decode fails.
+    const garbageCbor = new Uint8Array([0xff, 0xfe, 0xfd, 0xfc])
+    const frame = encodeBinaryFrame(complete(WIRE_VERSION, garbageCbor))
+
+    const result = conn.handlePostBody(frame)
+    expect(result.type).toBe("error")
+    expect(result.response.status).toBe(400)
+    conn.dispose()
   })
 })
 

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

@@ -0,0 +1,205 @@
+// sse-asymmetric — tests for asymmetric text/binary Pipeline encoding.
+//
+// Verifies the key SSE invariant: server sends text, client sends binary,
+// and a single AliasState covers both encoding directions because the
+// alias transformer operates on WireMessage shape, not encoded bytes.
+
+import { SYNC_AUTHORITATIVE } from "@kyneta/schema"
+import type {
+  ChannelMsg,
+  EstablishMsg,
+  InterestMsg,
+  PresentMsg,
+} from "@kyneta/transport"
+import { Pipeline } from "@kyneta/transport"
+import type { Result, WireError } from "@kyneta/wire"
+import { describe, expect, it } from "vitest"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function unwrapAll<T>(results: readonly Result<T, WireError>[]): T[] {
+  const out: T[] = []
+  for (const r of results) {
+    if (!r.ok) throw new Error(`Unexpected error: ${JSON.stringify(r.error)}`)
+    out.push(r.value)
+  }
+  return out
+}
+
+function recoverAll(
+  pipeline: Pipeline<any, any>,
+  frames: readonly unknown[],
+): ChannelMsg[] {
+  const msgs: ChannelMsg[] = []
+  for (const frame of frames) {
+    for (const r of pipeline.receive(frame as any)) {
+      if (!r.ok) throw new Error(`receive error: ${JSON.stringify(r.error)}`)
+      msgs.push(r.value)
+    }
+  }
+  return msgs
+}
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const serverEstablish: EstablishMsg = {
+  type: "establish",
+  identity: { peerId: "server", name: "Server", type: "service" },
+  features: { alias: true },
+}
+
+const clientEstablish: EstablishMsg = {
+  type: "establish",
+  identity: { peerId: "client", name: "Client", type: "user" },
+  features: { alias: true },
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("SSE asymmetric encoding", () => {
+  it("server text → client binary receive", () => {
+    // Server sends text, receives binary
+    const server = new Pipeline<"text", "binary">({
+      send: "text",
+      receive: "binary",
+    })
+    // Client sends binary, receives text
+    const client = new Pipeline<"binary", "text">({
+      send: "binary",
+      receive: "text",
+    })
+
+    try {
+      const serverOut = unwrapAll(server.send(serverEstablish))
+      const recovered = recoverAll(client, serverOut)
+
+      expect(recovered).toHaveLength(1)
+      expect(recovered[0]).toEqual(serverEstablish)
+    } finally {
+      server.dispose()
+      client.dispose()
+    }
+  })
+
+  it("client binary → server binary receive", () => {
+    const server = new Pipeline<"text", "binary">({
+      send: "text",
+      receive: "binary",
+    })
+    const client = new Pipeline<"binary", "text">({
+      send: "binary",
+      receive: "text",
+    })
+
+    try {
+      const clientOut = unwrapAll(client.send(clientEstablish))
+      const recovered = recoverAll(server, clientOut)
+
+      expect(recovered).toHaveLength(1)
+      expect(recovered[0]).toEqual(clientEstablish)
+    } finally {
+      server.dispose()
+      client.dispose()
+    }
+  })
+
+  it("alias state shared across encoding asymmetry", () => {
+    const server = new Pipeline<"text", "binary">({
+      send: "text",
+      receive: "binary",
+    })
+    const client = new Pipeline<"binary", "text">({
+      send: "binary",
+      receive: "text",
+    })
+
+    try {
+      // Step 1: Server sends establish with alias:true → client receives
+      const serverEstFrames = unwrapAll(server.send(serverEstablish))
+      const clientGotEst = recoverAll(client, serverEstFrames)
+      expect(clientGotEst).toHaveLength(1)
+      expect(clientGotEst[0]).toEqual(serverEstablish)
+
+      // Step 2: Client sends establish with alias:true → server receives
+      const clientEstFrames = unwrapAll(client.send(clientEstablish))
+      const serverGotEst = recoverAll(server, clientEstFrames)
+      expect(serverGotEst).toHaveLength(1)
+      expect(serverGotEst[0]).toEqual(clientEstablish)
+
+      // Both pipelines now have mutualAlias enabled.
+
+      // Step 3: Server sends present with alias info (text) → client receives
+      const presentMsg: PresentMsg = {
+        type: "present",
+        docs: [
+          {
+            docId: "doc-1",
+            schemaHash: "h-1",
+            replicaType: ["plain", 1, 0],
+            syncProtocol: SYNC_AUTHORITATIVE,
+          },
+        ],
+      }
+
+      const presentFrames = unwrapAll(server.send(presentMsg))
+      const clientGotPresent = recoverAll(client, presentFrames)
+      expect(clientGotPresent).toHaveLength(1)
+      const gotPresent = clientGotPresent[0]
+      if (gotPresent === undefined) throw new Error("unreachable")
+      expect(gotPresent.type).toBe("present")
+      if (gotPresent.type !== "present") throw new Error("unreachable")
+      expect(gotPresent.docs).toHaveLength(1)
+      expect(gotPresent.docs[0]?.docId).toBe("doc-1")
+
+      // Step 4: Client sends its own present for doc-1 (binary) → server receives.
+      // This assigns an outbound alias in the client's alias table.
+      const clientPresent: PresentMsg = {
+        type: "present",
+        docs: [
+          {
+            docId: "doc-1",
+            schemaHash: "h-1",
+            replicaType: ["plain", 1, 0],
+            syncProtocol: SYNC_AUTHORITATIVE,
+          },
+        ],
+      }
+
+      const clientPresentFrames = unwrapAll(client.send(clientPresent))
+      const serverGotPresent = recoverAll(server, clientPresentFrames)
+      expect(serverGotPresent).toHaveLength(1)
+      const gotClientPresent = serverGotPresent[0]
+      if (gotClientPresent === undefined) throw new Error("unreachable")
+      expect(gotClientPresent.type).toBe("present")
+      if (gotClientPresent.type !== "present") throw new Error("unreachable")
+      expect(gotClientPresent.docs[0]?.docId).toBe("doc-1")
+
+      // Step 5: Client sends interest using the alias (dx instead of doc) → server receives
+      // The client's outbound alias table now has doc-1 (from step 4),
+      // and mutualAlias is true, so the interest will use dx.
+      const interestMsg: InterestMsg = {
+        type: "interest",
+        docId: "doc-1",
+        version: "v1",
+      }
+
+      const interestFrames = unwrapAll(client.send(interestMsg))
+      const serverGotInterest = recoverAll(server, interestFrames)
+      expect(serverGotInterest).toHaveLength(1)
+      const gotInterest = serverGotInterest[0]
+      if (gotInterest === undefined) throw new Error("unreachable")
+      expect(gotInterest.type).toBe("interest")
+      if (gotInterest.type !== "interest") throw new Error("unreachable")
+      expect(gotInterest.docId).toBe("doc-1")
+    } finally {
+      server.dispose()
+      client.dispose()
+    }
+  })
+})

package/src/client-program.ts

@@ -9,7 +9,7 @@
 
 import type { Program } from "@kyneta/machine"
 import type { ReconnectOptions } from "@kyneta/transport"
-import { computeBackoffDelay, DEFAULT_RECONNECT } from "@kyneta/transport"
+import { DEFAULT_RECONNECT, shouldReconnect } from "@kyneta/transport"
 
 import type { DisconnectReason, SseClientState } from "./types.js"
 
@@ -44,8 +44,8 @@ export type SseClientEffect =
 export interface SseClientProgramOptions {
   url: string
   reconnect?: Partial<ReconnectOptions>
-  /** Inject jitter source for deterministic testing. Default: () => Math.random() * 1000 */
-  jitterFn?: () => number
+  /** Source of `[0, 1)` random values for jitter. Default: `Math.random` */
+  randomFn?: () => number
 }
 
 /**
@@ -58,7 +58,7 @@ export interface SseClientProgramOptions {
 export function createSseClientProgram(
   options: SseClientProgramOptions,
 ): Program<SseClientMsg, SseClientState, SseClientEffect> {
-  const { url, jitterFn = () => Math.random() * 1000 } = options
+  const { url, randomFn = Math.random } = options
   const reconnect: ReconnectOptions = {
     ...DEFAULT_RECONNECT,
     ...options.reconnect,
@@ -67,44 +67,31 @@ export function createSseClientProgram(
   /**
    * Attempt to transition into reconnecting, or give up and disconnect.
    *
-   * Pure — computes the next state and effects from the current attempt
-   * count and reconnect configuration. Returns a tuple suitable for
-   * spreading into an `update` return.
+   * Wraps the pure `shouldReconnect` decision and builds the SSE-specific
+   * state/effect tuple. Returns a tuple suitable for spreading into an
+   * `update` return.
    */
   function tryReconnect(
     currentAttempt: number,
     reason: DisconnectReason,
     ...extraEffects: SseClientEffect[]
   ): [SseClientState, ...SseClientEffect[]] {
-    if (!reconnect.enabled) {
-      return [{ status: "disconnected", reason }, ...extraEffects]
+    const d = shouldReconnect(reconnect, currentAttempt, randomFn)
+    if (!d.reconnect) {
+      const finalReason: DisconnectReason =
+        d.cause === "max-attempts-exceeded"
+          ? { type: "max-retries-exceeded", attempts: d.attempts }
+          : reason
+      return [{ status: "disconnected", reason: finalReason }, ...extraEffects]
     }
-
-    if (currentAttempt >= reconnect.maxAttempts) {
-      return [
-        {
-          status: "disconnected",
-          reason: { type: "max-retries-exceeded", attempts: currentAttempt },
-        },
-        ...extraEffects,
-      ]
-    }
-
-    const delay = computeBackoffDelay(
-      currentAttempt + 1,
-      reconnect.baseDelay,
-      reconnect.maxDelay,
-      jitterFn(),
-    )
-
     return [
       {
         status: "reconnecting",
-        attempt: currentAttempt + 1,
-        nextAttemptMs: delay,
+        attempt: d.attempt,
+        nextAttemptMs: d.delayMs,
       },
       ...extraEffects,
-      { type: "start-reconnect-timer", delayMs: delay },
+      { type: "start-reconnect-timer", delayMs: d.delayMs },
     ]
   }