@did-btcr2/aggregation 0.1.0

package/src/transport/http/sse-stream.ts

@@ -0,0 +1,121 @@
+/**
+ * Parsed Server-Sent Events record.
+ *
+ * Events without a `data` field are never yielded (per the SSE spec - only a
+ * blank line that follows at least one `data:` line dispatches an event).
+ */
+export interface SseEvent {
+  /** Optional event name (from `event:` field). Defaults to "message" if omitted. */
+  event?: string;
+  /** Accumulated data payload (multiple `data:` lines joined with `\n`). */
+  data: string;
+  /** Last-Event-ID value for reconnect resumption. */
+  id?: string;
+  /** Retry delay hint in milliseconds. */
+  retry?: number;
+}
+
+/**
+ * Parse an SSE stream into an async iterable of {@link SseEvent} records.
+ *
+ * The parser follows the HTML Living Standard ({@link https://html.spec.whatwg.org/multipage/server-sent-events.html})
+ * closely enough for our needs: LF and CRLF line terminators, multi-line
+ * `data` fields, `event` / `id` / `retry` fields, and `:`-prefixed comments.
+ * CR-only line terminators are not supported (every mainstream SSE
+ * implementation emits LF or CRLF).
+ *
+ * Pure, runtime-agnostic - works anywhere `ReadableStream<Uint8Array>` and
+ * `TextDecoder` exist (browsers and Node 22+).
+ *
+ * The caller owns stream lifecycle: cancellation should be effected via an
+ * `AbortController` on the producing `fetch`, which propagates as a read
+ * error and cleanly unwinds this generator's `finally`.
+ */
+export async function* parseSseStream(
+  readable: ReadableStream<Uint8Array>,
+): AsyncGenerator<SseEvent, void, void> {
+  const decoder = new TextDecoder('utf-8');
+  const reader  = readable.getReader();
+
+  let buffer  = '';
+  let pending: { event?: string; data?: string; id?: string; retry?: number } = {};
+
+  const dispatchPending = (): SseEvent | null => {
+    if(pending.data === undefined) {
+      pending = {};
+      return null;
+    }
+    const ev: SseEvent = { data: pending.data };
+    if(pending.event !== undefined) ev.event = pending.event;
+    if(pending.id    !== undefined) ev.id    = pending.id;
+    if(pending.retry !== undefined) ev.retry = pending.retry;
+    pending = {};
+    return ev;
+  };
+
+  const processLine = (line: string): void => {
+    if(line.startsWith(':')) return; // comment
+
+    const colon = line.indexOf(':');
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let   value = colon === -1 ? '' : line.slice(colon + 1);
+    if(value.startsWith(' ')) value = value.slice(1);
+
+    switch(field) {
+      case 'data':
+        pending.data = pending.data === undefined ? value : `${pending.data}\n${value}`;
+        break;
+      case 'event':
+        pending.event = value;
+        break;
+      case 'id':
+        // Per spec: ignore ids containing NUL.
+        if(!value.includes('\0')) pending.id = value;
+        break;
+      case 'retry': {
+        const n = Number(value);
+        if(Number.isInteger(n) && n >= 0) pending.retry = n;
+        break;
+      }
+      // Other fields (including unknown names) are ignored per the spec.
+    }
+  };
+
+  try {
+    for(;;) {
+      const { value, done } = await reader.read();
+      if(done) {
+        // Flush any bytes the decoder is still holding.
+        buffer += decoder.decode();
+        if(buffer.length > 0) {
+          const line = buffer.endsWith('\r') ? buffer.slice(0, -1) : buffer;
+          if(line.length > 0) processLine(line);
+          buffer = '';
+        }
+        const tail = dispatchPending();
+        if(tail) yield tail;
+        return;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+
+      // Drain as many complete lines as are available.
+      let lineEnd = buffer.indexOf('\n');
+      while(lineEnd !== -1) {
+        let line = buffer.slice(0, lineEnd);
+        if(line.endsWith('\r')) line = line.slice(0, -1);
+        buffer = buffer.slice(lineEnd + 1);
+
+        if(line.length === 0) {
+          const ev = dispatchPending();
+          if(ev) yield ev;
+        } else {
+          processLine(line);
+        }
+        lineEnd = buffer.indexOf('\n');
+      }
+    }
+  } finally {
+    try { reader.releaseLock(); } catch { /* already released */ }
+  }
+}

package/src/transport/http/sse-writer.ts

@@ -0,0 +1,23 @@
+/**
+ * Format an SSE event frame. Pairs with {@link parseSseStream}.
+ *
+ * Multi-line `data` is split across multiple `data:` lines per the SSE spec -
+ * each embedded `\n` becomes its own line, and the parser rejoins them.
+ *
+ * The returned string includes a trailing blank line (the dispatch marker).
+ */
+export function formatSseEvent(event: string, data: string, id?: string): string {
+  const lines: string[] = [];
+  if(id !== undefined) lines.push(`id: ${id}`);
+  lines.push(`event: ${event}`);
+  for(const part of data.split('\n')) lines.push(`data: ${part}`);
+  lines.push('');
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** SSE comment frame (server keepalive). Lines starting with `:` are ignored by compliant parsers. */
+export function formatSseComment(comment: string): string {
+  const safe = comment.replace(/\n/g, ' ');
+  return `: ${safe}\n\n`;
+}

package/src/transport/in-memory.ts

@@ -0,0 +1,178 @@
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import type { BaseMessage } from '../messages/base.js';
+import type { MessageHandler, Transport } from './transport.js';
+
+/** Internal registration for a single actor sharing an {@link InMemoryTransport}. */
+interface ActorEntry {
+  /** Compressed communication public key. The in-process bus does no encryption, so no secret is retained. */
+  publicKey: Uint8Array;
+  handlers: Map<string, MessageHandler>;
+}
+
+/**
+ * In-process message bus connecting one or more {@link InMemoryTransport}
+ * instances. Routes broadcasts to every registered actor and directed messages
+ * to the actor that owns the recipient DID, with no relay, server, or network.
+ *
+ * Each delivery does a JSON round-trip (Uint8Array preserved as `__bytes` hex)
+ * so handlers receive an isolated, serialization-faithful copy, exactly as a
+ * real transport would. The message `body` is merged to the top level to match
+ * the shape the {@link NostrTransport} dispatch produces.
+ *
+ * @class InMemoryBus
+ */
+export class InMemoryBus {
+  #transports: Set<InMemoryTransport> = new Set();
+
+  /** Attach a transport to this bus. Called by the transport's constructor. */
+  register(transport: InMemoryTransport): void {
+    this.#transports.add(transport);
+  }
+
+  /** Detach a transport from this bus. */
+  unregister(transport: InMemoryTransport): void {
+    this.#transports.delete(transport);
+  }
+
+  /**
+   * Deliver a message. With no `recipient` the message is broadcast to every
+   * actor on the bus; otherwise it is routed to the single transport that owns
+   * the recipient DID.
+   */
+  async deliver(message: BaseMessage, _sender: string, recipient?: string): Promise<void> {
+    const type = (message as { type?: string }).type;
+    if(!type) return;
+
+    // JSON round-trip to mimic transport serialization, preserving Uint8Array.
+    const replacer = (_k: string, v: unknown): unknown => v instanceof Uint8Array ? { __bytes: bytesToHex(v) } : v;
+    const reviver = (_k: string, v: unknown): unknown =>
+      v && typeof v === 'object' && '__bytes' in (v as Record<string, unknown>)
+        ? hexToBytes((v as { __bytes: string }).__bytes)
+        : v;
+    const raw = JSON.parse(JSON.stringify(message, replacer), reviver) as Record<string, unknown>;
+    const serialized = { ...raw, ...((raw.body as Record<string, unknown> | undefined) ?? {}) };
+
+    if(!recipient) {
+      for(const t of this.#transports) {
+        await t.dispatchBroadcast(type, serialized);
+      }
+      return;
+    }
+    for(const t of this.#transports) {
+      if(t.hasActor(recipient)) {
+        await t.dispatchDirected(recipient, type, serialized);
+        return;
+      }
+    }
+  }
+}
+
+/**
+ * In-process {@link Transport} that routes aggregation messages through an
+ * {@link InMemoryBus} instead of a relay or HTTP server. Supports multiple
+ * actors per instance, so a single transport can host both a service and its
+ * participants (e.g. a cohort-of-one via {@link AggregationRunner.solo}).
+ *
+ * Encryption is a no-op (in-process, same trust domain); `registerPeer` /
+ * `getPeerPk` keep a registry so the contract matches the wire transports.
+ *
+ * @class InMemoryTransport
+ * @implements {Transport}
+ */
+export class InMemoryTransport implements Transport {
+  name: string = 'in-memory';
+  readonly bus: InMemoryBus;
+
+  #actors: Map<string, ActorEntry> = new Map();
+  #peers: Map<string, Uint8Array> = new Map();
+
+  /** @param bus Shared bus. Pass the same bus to connect multiple transports. */
+  constructor(bus: InMemoryBus = new InMemoryBus()) {
+    this.bus = bus;
+    this.bus.register(this);
+  }
+
+  start(): void {
+    // No-op: there is no underlying connection to open.
+  }
+
+  registerActor(did: string, keys: SchnorrKeyPair): void {
+    // In-process delivery does no signing or encryption (same trust domain), so
+    // retain only the public key - the secret-bearing keypair is never stored in
+    // the transport registry (see ADR 038).
+    this.#actors.set(did, { publicKey: keys.publicKey.compressed, handlers: new Map() });
+  }
+
+  getActorPk(did: string): Uint8Array | undefined {
+    return this.#actors.get(did)?.publicKey;
+  }
+
+  /** True if `did` is registered on this transport. Used by the bus for routing. */
+  hasActor(did: string): boolean {
+    return this.#actors.has(did);
+  }
+
+  registerPeer(did: string, communicationPk: Uint8Array): void {
+    this.#peers.set(did, communicationPk);
+  }
+
+  getPeerPk(did: string): Uint8Array | undefined {
+    return this.#peers.get(did);
+  }
+
+  registerMessageHandler(actorDid: string, messageType: string, handler: MessageHandler): void {
+    const actor = this.#actors.get(actorDid);
+    if(actor) actor.handlers.set(messageType, handler);
+  }
+
+  unregisterMessageHandler(actorDid: string, messageType: string): void {
+    const actor = this.#actors.get(actorDid);
+    if(actor) actor.handlers.delete(messageType);
+  }
+
+  unregisterActor(did: string): void {
+    const actor = this.#actors.get(did);
+    if(!actor) return;
+    actor.handlers.clear();
+    this.#actors.delete(did);
+    this.#peers.delete(did);
+  }
+
+  async sendMessage(message: BaseMessage, sender: string, recipient?: string): Promise<void> {
+    await this.bus.deliver(message, sender, recipient);
+  }
+
+  publishRepeating(
+    message: BaseMessage,
+    sender: string,
+    intervalMs: number,
+    recipient?: string,
+  ): () => void {
+    let stopped = false;
+    void this.sendMessage(message, sender, recipient).catch(() => { /* in-process: no relay to reject */ });
+    const timer = setInterval(() => {
+      if(stopped) return;
+      void this.sendMessage(message, sender, recipient).catch(() => { /* ignore */ });
+    }, intervalMs);
+    return () => {
+      if(stopped) return;
+      stopped = true;
+      clearInterval(timer);
+    };
+  }
+
+  /** Deliver a broadcast message to every actor on this transport that handles `type`. */
+  async dispatchBroadcast(type: string, message: unknown): Promise<void> {
+    for(const actor of this.#actors.values()) {
+      const handler = actor.handlers.get(type);
+      if(handler) await handler(message);
+    }
+  }
+
+  /** Deliver a directed message to the recipient actor's handler for `type`. */
+  async dispatchDirected(recipientDid: string, type: string, message: unknown): Promise<void> {
+    const handler = this.#actors.get(recipientDid)?.handlers.get(type);
+    if(handler) await handler(message);
+  }
+}

package/src/transport/index.ts

@@ -0,0 +1,7 @@
+export * from './transport.js';
+export * from './error.js';
+export * from './factory.js';
+export * from './in-memory.js';
+export * from './nostr.js';
+export * from './didcomm.js';
+export * from './http/index.js';