onelobby 0.5.0 → 0.6.0

package/dist/nostr/limits.js

@@ -0,0 +1,36 @@
+/**
+ * Every Nostr limit and timer shared with the C# client. Pinned by `spec/vectors/nostr-limits.json` (test/nostr.test.ts);
+ * C# mirror: OneLobby.Direct/Nostr/NostrLimits.cs. Change a number in all three.
+ */
+// Reliable link (spec s.4)
+export const BATCH_MS = 30;
+export const RESEND_MS = 3000;
+export const MAX_RESENDS = 5;
+export const BEAT_MS = 10_000;
+export const SILENCE_MS = 30_000;
+export const MAX_HELD = 64;
+/** Outbound: queued texts plus unacknowledged frames, at most this many frames and bytes; excess texts are dropped. */
+export const MAX_OUT_FRAMES = 128;
+export const MAX_OUT_BYTES = 256 * 1024;
+export const MAX_FRAME_BYTES = 30_000; // under the 32 KiB content limit, room for the JSON envelope
+export const TICK_MS = 250;
+// Host bridge: new joiner token bucket (spec s.4)
+export const NEW_SESSION_BURST = 16;
+export const MAX_SESSION_BURST = 64;
+export const NEW_SESSION_REFILL_MS = 1_000;
+export const WAITING_MAX = 64;
+export const WAITING_STALE_MS = 5_000;
+// Joiner socket (spec s.4)
+export const OPEN_EVERY_MS = 2000;
+export const GIVE_UP_MS = 15_000;
+// Relay waits (spec s.6)
+/** `hostDirect`: how long to wait for a first relay before hosting by IP alone (the IP code shows first, the Nostr code takes over later). */
+export const HOST_FIRST_RELAY_MS = 3_000;
+/** `hostNostr` (no IP fallback): how long to wait for a first relay before `direct_unreachable`. */
+export const HOST_NOSTR_FIRST_RELAY_MS = 10_000;
+/** A joiner: how long to wait for a first relay before `connect_failed`. */
+export const JOINER_FIRST_RELAY_MS = 10_000;
+/** After the first relay: at most this long for the rest of the list; ends at once when every relay has answered. */
+export const RELAY_REST_WAIT_MS = 1500;
+export const RELAY_REST_POLL_MS = 50;
+//# sourceMappingURL=limits.js.map

package/dist/nostr/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/nostr/limits.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,2BAA2B;AAC3B,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,CAAC;AAC3B,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC;AAC9B,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAC7B,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC;AAC9B,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC;AACjC,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,CAAC;AAC3B,uHAAuH;AACvH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAClC,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,GAAG,IAAI,CAAC;AACxC,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,CAAC,6DAA6D;AACpG,MAAM,CAAC,MAAM,OAAO,GAAG,GAAG,CAAC;AAE3B,kDAAkD;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AACpC,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AACpC,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAC3C,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC;AAC9B,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAEtC,2BAA2B;AAC3B,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;AAClC,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC;AAEjC,yBAAyB;AACzB,8IAA8I;AAC9I,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AACzC,oGAAoG;AACpG,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAChD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAC5C,qHAAqH;AACrH,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AACvC,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC","sourcesContent":["/**\n * Every Nostr limit and timer shared with the C# client. Pinned by `spec/vectors/nostr-limits.json` (test/nostr.test.ts);\n * C# mirror: OneLobby.Direct/Nostr/NostrLimits.cs. Change a number in all three.\n */\n\n// Reliable link (spec s.4)\nexport const BATCH_MS = 30;\nexport const RESEND_MS = 3000;\nexport const MAX_RESENDS = 5;\nexport const BEAT_MS = 10_000;\nexport const SILENCE_MS = 30_000;\nexport const MAX_HELD = 64;\n/** Outbound: queued texts plus unacknowledged frames, at most this many frames and bytes; excess texts are dropped. */\nexport const MAX_OUT_FRAMES = 128;\nexport const MAX_OUT_BYTES = 256 * 1024;\nexport const MAX_FRAME_BYTES = 30_000; // under the 32 KiB content limit, room for the JSON envelope\nexport const TICK_MS = 250;\n\n// Host bridge: new joiner token bucket (spec s.4)\nexport const NEW_SESSION_BURST = 16;\nexport const MAX_SESSION_BURST = 64;\nexport const NEW_SESSION_REFILL_MS = 1_000;\nexport const WAITING_MAX = 64;\nexport const WAITING_STALE_MS = 5_000;\n\n// Joiner socket (spec s.4)\nexport const OPEN_EVERY_MS = 2000;\nexport const GIVE_UP_MS = 15_000;\n\n// Relay waits (spec s.6)\n/** `hostDirect`: how long to wait for a first relay before hosting by IP alone (the IP code shows first, the Nostr code takes over later). */\nexport const HOST_FIRST_RELAY_MS = 3_000;\n/** `hostNostr` (no IP fallback): how long to wait for a first relay before `direct_unreachable`. */\nexport const HOST_NOSTR_FIRST_RELAY_MS = 10_000;\n/** A joiner: how long to wait for a first relay before `connect_failed`. */\nexport const JOINER_FIRST_RELAY_MS = 10_000;\n/** After the first relay: at most this long for the rest of the list; ends at once when every relay has answered. */\nexport const RELAY_REST_WAIT_MS = 1500;\nexport const RELAY_REST_POLL_MS = 50;\n"]}

package/dist/nostr/link.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The frame layer of Nostr signaling (spec/nostr-signaling.md s.4): ordered, de-duplicated, acknowledged delivery of
+ * hub protocol texts between two pubkeys over lossy relays. One {@link ReliableLink} per peer; it knows nothing about
+ * relays, keys or encryption: the owner stamps and ships the frames it emits.
+ */
+import type { Clock } from "../clock.js";
+import { BATCH_MS, RESEND_MS, MAX_RESENDS, BEAT_MS, SILENCE_MS, MAX_HELD, MAX_OUT_FRAMES, MAX_OUT_BYTES, MAX_FRAME_BYTES } from "./limits.js";
+export type FrameType = "open" | "data" | "beat" | "close";
+/** The wire frame (JSON in the encrypted event content). */
+export interface Frame {
+    v: 1;
+    type: FrameType;
+    from: string;
+    to: string;
+    seq: number;
+    ack: number;
+    msgs?: string[];
+    reason?: string;
+}
+/** What a link emits; the owner adds v / from / to. */
+export type OutFrame = Pick<Frame, "type" | "seq" | "ack"> & {
+    msgs?: string[];
+    reason?: string;
+};
+export { BATCH_MS, RESEND_MS, MAX_RESENDS, BEAT_MS, SILENCE_MS, MAX_HELD, MAX_OUT_FRAMES, MAX_OUT_BYTES, MAX_FRAME_BYTES };
+export interface LinkOptions {
+    clock: Clock;
+    /** Ships a frame to the peer. */
+    send: (f: OutFrame) => void;
+    /** An in-order hub protocol text from the peer. */
+    deliver: (text: string) => void;
+    /** The peer sent `close`. */
+    onPeerClose: (reason: string) => void;
+    /** Gave up: five resends unanswered, or 30 s of silence (reason "timeout"). */
+    onDead: (reason: string) => void;
+}
+export declare class ReliableLink {
+    private readonly o;
+    private queue;
+    private queueBytes;
+    private unackedBytes;
+    private nextSeq;
+    private readonly unacked;
+    private rcvNext;
+    private readonly held;
+    private ackOwed;
+    private lastSent;
+    private lastHeard;
+    private cancelFlush;
+    private cancelTick;
+    private done;
+    constructor(o: LinkOptions);
+    get closed(): boolean;
+    /** Queues a hub text; sent within 30 ms, packed with its neighbours. */
+    send(text: string): void;
+    /** Any frame arrived from the peer (including `open`, which only proves it is alive). */
+    heard(): void;
+    /** `data`, `beat` and `close` frames from the peer. */
+    receive(f: Frame): void;
+    /** Sends what is queued, then `close` (once), and stops. */
+    close(reason?: string): void;
+    /** Stops the timers without telling the peer. */
+    stop(): void;
+    private scheduleFlush;
+    private flush;
+    private dropUnacked;
+    private emit;
+    private tick;
+    private die;
+}

package/dist/nostr/link.js

@@ -0,0 +1,180 @@
+import { BATCH_MS, RESEND_MS, MAX_RESENDS, BEAT_MS, SILENCE_MS, MAX_HELD, MAX_OUT_FRAMES, MAX_OUT_BYTES, MAX_FRAME_BYTES, TICK_MS } from "./limits.js";
+export { BATCH_MS, RESEND_MS, MAX_RESENDS, BEAT_MS, SILENCE_MS, MAX_HELD, MAX_OUT_FRAMES, MAX_OUT_BYTES, MAX_FRAME_BYTES };
+const utf8 = new TextEncoder();
+const byteLen = (s) => utf8.encode(s).length;
+export class ReliableLink {
+    o;
+    queue = [];
+    queueBytes = 0;
+    unackedBytes = 0;
+    nextSeq = 1;
+    unacked = new Map();
+    rcvNext = 1; // next seq to deliver
+    held = new Map();
+    ackOwed = false;
+    lastSent;
+    lastHeard;
+    cancelFlush = null;
+    cancelTick = null;
+    done = false;
+    constructor(o) {
+        this.o = o;
+        this.lastSent = this.lastHeard = o.clock.now();
+        this.cancelTick = o.clock.setInterval(() => this.tick(), TICK_MS);
+    }
+    get closed() {
+        return this.done;
+    }
+    /** Queues a hub text; sent within 30 ms, packed with its neighbours. */
+    send(text) {
+        if (this.done)
+            return;
+        // relays refuse high publish rates: past the cap the text is dropped, the connection is not
+        const n = byteLen(text);
+        if (this.queue.length + this.unacked.size >= MAX_OUT_FRAMES || this.queueBytes + this.unackedBytes + n > MAX_OUT_BYTES)
+            return;
+        this.queue.push(text);
+        this.queueBytes += n;
+        this.scheduleFlush();
+    }
+    /** Any frame arrived from the peer (including `open`, which only proves it is alive). */
+    heard() {
+        this.lastHeard = this.o.clock.now();
+    }
+    /** `data`, `beat` and `close` frames from the peer. */
+    receive(f) {
+        if (this.done)
+            return;
+        this.heard();
+        if (f.type === "close") {
+            const reason = typeof f.reason === "string" ? f.reason : "";
+            this.stop();
+            this.o.onPeerClose(reason);
+            return;
+        }
+        if (f.type !== "data" && f.type !== "beat")
+            return;
+        if (Number.isInteger(f.ack))
+            for (const s of [...this.unacked.keys()])
+                if (s <= f.ack)
+                    this.dropUnacked(s);
+        if (f.type === "beat")
+            return;
+        const msgs = Array.isArray(f.msgs) ? f.msgs.filter((m) => typeof m === "string") : [];
+        if (!Number.isInteger(f.seq) || f.seq < 1)
+            return;
+        this.ackOwed = true;
+        if (f.seq === this.rcvNext) {
+            this.rcvNext++;
+            for (const m of msgs)
+                this.o.deliver(m);
+            for (let h = this.held.get(this.rcvNext); h && !this.done; h = this.held.get(this.rcvNext)) {
+                this.held.delete(this.rcvNext);
+                this.rcvNext++;
+                for (const m of h)
+                    this.o.deliver(m);
+            }
+        }
+        else if (f.seq > this.rcvNext && f.seq <= this.rcvNext + MAX_HELD)
+            this.held.set(f.seq, msgs);
+        // f.seq < rcvNext: a duplicate; the ack below tells the sender to stop resending
+        this.scheduleFlush();
+    }
+    /** Sends what is queued, then `close` (once), and stops. */
+    close(reason = "") {
+        if (this.done)
+            return;
+        this.flush();
+        this.o.send({ type: "close", seq: 0, ack: this.rcvNext - 1, ...(reason ? { reason } : {}) });
+        this.stop();
+    }
+    /** Stops the timers without telling the peer. */
+    stop() {
+        this.done = true;
+        this.cancelFlush?.();
+        this.cancelTick?.();
+        this.cancelFlush = this.cancelTick = null;
+        this.unacked.clear();
+        this.unackedBytes = 0;
+        this.held.clear();
+        this.queue = [];
+        this.queueBytes = 0;
+    }
+    scheduleFlush() {
+        if (this.cancelFlush || this.done)
+            return;
+        this.cancelFlush = this.o.clock.setTimeout(() => {
+            this.cancelFlush = null;
+            this.flush();
+        }, BATCH_MS);
+    }
+    flush() {
+        if (this.done)
+            return;
+        this.cancelFlush?.();
+        this.cancelFlush = null;
+        const now = this.o.clock.now();
+        if (this.queue.length === 0) {
+            if (this.ackOwed)
+                this.emit({ type: "beat", seq: 0, ack: this.rcvNext - 1 }, now);
+            return;
+        }
+        let batch = [];
+        let bytes = 0;
+        const ship = () => {
+            if (batch.length === 0)
+                return;
+            const frame = { type: "data", seq: this.nextSeq++, ack: this.rcvNext - 1, msgs: batch };
+            this.unacked.set(frame.seq, { bytes, frame, lastSent: now, resends: 0 });
+            this.unackedBytes += bytes;
+            this.emit(frame, now);
+            batch = [];
+            bytes = 0;
+        };
+        this.queueBytes = 0;
+        for (const m of this.queue.splice(0)) {
+            const n = byteLen(m);
+            if (batch.length > 0 && bytes + n > MAX_FRAME_BYTES)
+                ship();
+            batch.push(m);
+            bytes += n;
+        }
+        ship();
+    }
+    dropUnacked(seq) {
+        const p = this.unacked.get(seq);
+        if (!p)
+            return;
+        this.unackedBytes -= p.bytes;
+        this.unacked.delete(seq);
+    }
+    emit(f, now) {
+        this.lastSent = now;
+        this.ackOwed = false;
+        this.o.send(f);
+    }
+    tick() {
+        if (this.done)
+            return;
+        const now = this.o.clock.now();
+        if (now - this.lastHeard >= SILENCE_MS)
+            return this.die();
+        for (const p of this.unacked.values()) {
+            if (now - p.lastSent < RESEND_MS)
+                continue;
+            if (p.resends >= MAX_RESENDS)
+                return this.die();
+            p.resends++;
+            p.lastSent = now;
+            this.o.send({ ...p.frame, ack: this.rcvNext - 1 });
+            this.lastSent = now;
+        }
+        if (now - this.lastSent >= BEAT_MS)
+            this.emit({ type: "beat", seq: 0, ack: this.rcvNext - 1 }, now);
+    }
+    die() {
+        this.stop();
+        this.o.onDead("timeout");
+    }
+}
+//# sourceMappingURL=link.js.map

package/dist/nostr/link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.js","sourceRoot":"","sources":["../../src/nostr/link.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The frame layer of Nostr signaling (spec/nostr-signaling.md s.4): ordered, de-duplicated, acknowledged delivery of\n * hub protocol texts between two pubkeys over lossy relays. One {@link ReliableLink} per peer; it knows nothing about\n * relays, keys or encryption: the owner stamps and ships the frames it emits.\n */\nimport type { Clock } from \"../clock.js\";\nimport { BATCH_MS, RESEND_MS, MAX_RESENDS, BEAT_MS, SILENCE_MS, MAX_HELD, MAX_OUT_FRAMES, MAX_OUT_BYTES, MAX_FRAME_BYTES, TICK_MS } from \"./limits.js\";\n\nexport type FrameType = \"open\" | \"data\" | \"beat\" | \"close\";\n\n/** The wire frame (JSON in the encrypted event content). */\nexport interface Frame {\n  v: 1;\n  type: FrameType;\n  from: string;\n  to: string;\n  seq: number;\n  ack: number;\n  msgs?: string[];\n  reason?: string;\n}\n\n/** What a link emits; the owner adds v / from / to. */\nexport type OutFrame = Pick<Frame, \"type\" | \"seq\" | \"ack\"> & { msgs?: string[]; reason?: string };\n\nexport { BATCH_MS, RESEND_MS, MAX_RESENDS, BEAT_MS, SILENCE_MS, MAX_HELD, MAX_OUT_FRAMES, MAX_OUT_BYTES, MAX_FRAME_BYTES };\n\nconst utf8 = new TextEncoder();\nconst byteLen = (s: string) => utf8.encode(s).length;\n\nexport interface LinkOptions {\n  clock: Clock;\n  /** Ships a frame to the peer. */\n  send: (f: OutFrame) => void;\n  /** An in-order hub protocol text from the peer. */\n  deliver: (text: string) => void;\n  /** The peer sent `close`. */\n  onPeerClose: (reason: string) => void;\n  /** Gave up: five resends unanswered, or 30 s of silence (reason \"timeout\"). */\n  onDead: (reason: string) => void;\n}\n\ninterface Pending {\n  bytes: number;\n  frame: OutFrame;\n  lastSent: number;\n  resends: number;\n}\n\nexport class ReliableLink {\n  private readonly o: LinkOptions;\n  private queue: string[] = [];\n  private queueBytes = 0;\n  private unackedBytes = 0;\n  private nextSeq = 1;\n  private readonly unacked = new Map<number, Pending>();\n  private rcvNext = 1; // next seq to deliver\n  private readonly held = new Map<number, string[]>();\n  private ackOwed = false;\n  private lastSent: number;\n  private lastHeard: number;\n  private cancelFlush: (() => void) | null = null;\n  private cancelTick: (() => void) | null = null;\n  private done = false;\n\n  constructor(o: LinkOptions) {\n    this.o = o;\n    this.lastSent = this.lastHeard = o.clock.now();\n    this.cancelTick = o.clock.setInterval(() => this.tick(), TICK_MS);\n  }\n\n  get closed(): boolean {\n    return this.done;\n  }\n\n  /** Queues a hub text; sent within 30 ms, packed with its neighbours. */\n  send(text: string): void {\n    if (this.done) return;\n    // relays refuse high publish rates: past the cap the text is dropped, the connection is not\n    const n = byteLen(text);\n    if (this.queue.length + this.unacked.size >= MAX_OUT_FRAMES || this.queueBytes + this.unackedBytes + n > MAX_OUT_BYTES) return;\n    this.queue.push(text);\n    this.queueBytes += n;\n    this.scheduleFlush();\n  }\n\n  /** Any frame arrived from the peer (including `open`, which only proves it is alive). */\n  heard(): void {\n    this.lastHeard = this.o.clock.now();\n  }\n\n  /** `data`, `beat` and `close` frames from the peer. */\n  receive(f: Frame): void {\n    if (this.done) return;\n    this.heard();\n    if (f.type === \"close\") {\n      const reason = typeof f.reason === \"string\" ? f.reason : \"\";\n      this.stop();\n      this.o.onPeerClose(reason);\n      return;\n    }\n    if (f.type !== \"data\" && f.type !== \"beat\") return;\n    if (Number.isInteger(f.ack)) for (const s of [...this.unacked.keys()]) if (s <= f.ack) this.dropUnacked(s);\n    if (f.type === \"beat\") return;\n    const msgs = Array.isArray(f.msgs) ? f.msgs.filter((m) => typeof m === \"string\") : [];\n    if (!Number.isInteger(f.seq) || f.seq < 1) return;\n    this.ackOwed = true;\n    if (f.seq === this.rcvNext) {\n      this.rcvNext++;\n      for (const m of msgs) this.o.deliver(m);\n      for (let h = this.held.get(this.rcvNext); h && !this.done; h = this.held.get(this.rcvNext)) {\n        this.held.delete(this.rcvNext);\n        this.rcvNext++;\n        for (const m of h) this.o.deliver(m);\n      }\n    } else if (f.seq > this.rcvNext && f.seq <= this.rcvNext + MAX_HELD) this.held.set(f.seq, msgs);\n    // f.seq < rcvNext: a duplicate; the ack below tells the sender to stop resending\n    this.scheduleFlush();\n  }\n\n  /** Sends what is queued, then `close` (once), and stops. */\n  close(reason = \"\"): void {\n    if (this.done) return;\n    this.flush();\n    this.o.send({ type: \"close\", seq: 0, ack: this.rcvNext - 1, ...(reason ? { reason } : {}) });\n    this.stop();\n  }\n\n  /** Stops the timers without telling the peer. */\n  stop(): void {\n    this.done = true;\n    this.cancelFlush?.();\n    this.cancelTick?.();\n    this.cancelFlush = this.cancelTick = null;\n    this.unacked.clear();\n    this.unackedBytes = 0;\n    this.held.clear();\n    this.queue = [];\n    this.queueBytes = 0;\n  }\n\n  private scheduleFlush(): void {\n    if (this.cancelFlush || this.done) return;\n    this.cancelFlush = this.o.clock.setTimeout(() => {\n      this.cancelFlush = null;\n      this.flush();\n    }, BATCH_MS);\n  }\n\n  private flush(): void {\n    if (this.done) return;\n    this.cancelFlush?.();\n    this.cancelFlush = null;\n    const now = this.o.clock.now();\n    if (this.queue.length === 0) {\n      if (this.ackOwed) this.emit({ type: \"beat\", seq: 0, ack: this.rcvNext - 1 }, now);\n      return;\n    }\n    let batch: string[] = [];\n    let bytes = 0;\n    const ship = () => {\n      if (batch.length === 0) return;\n      const frame: OutFrame = { type: \"data\", seq: this.nextSeq++, ack: this.rcvNext - 1, msgs: batch };\n      this.unacked.set(frame.seq, { bytes, frame, lastSent: now, resends: 0 });\n      this.unackedBytes += bytes;\n      this.emit(frame, now);\n      batch = [];\n      bytes = 0;\n    };\n    this.queueBytes = 0;\n    for (const m of this.queue.splice(0)) {\n      const n = byteLen(m);\n      if (batch.length > 0 && bytes + n > MAX_FRAME_BYTES) ship();\n      batch.push(m);\n      bytes += n;\n    }\n    ship();\n  }\n\n  private dropUnacked(seq: number): void {\n    const p = this.unacked.get(seq);\n    if (!p) return;\n    this.unackedBytes -= p.bytes;\n    this.unacked.delete(seq);\n  }\n\n  private emit(f: OutFrame, now: number): void {\n    this.lastSent = now;\n    this.ackOwed = false;\n    this.o.send(f);\n  }\n\n  private tick(): void {\n    if (this.done) return;\n    const now = this.o.clock.now();\n    if (now - this.lastHeard >= SILENCE_MS) return this.die();\n    for (const p of this.unacked.values()) {\n      if (now - p.lastSent < RESEND_MS) continue;\n      if (p.resends >= MAX_RESENDS) return this.die();\n      p.resends++;\n      p.lastSent = now;\n      this.o.send({ ...p.frame, ack: this.rcvNext - 1 });\n      this.lastSent = now;\n    }\n    if (now - this.lastSent >= BEAT_MS) this.emit({ type: \"beat\", seq: 0, ack: this.rcvNext - 1 }, now);\n  }\n\n  private die(): void {\n    this.stop();\n    this.o.onDead(\"timeout\");\n  }\n}\n"]}

package/dist/nostr/relays.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Nostr events and the relay pool (spec/nostr-signaling.md s.3 and s.6). Anonymous: every connection uses a throw-away
+ * key and carries encrypted frames only.
+ */
+import type { Clock } from "../clock.js";
+import type { SocketLike } from "../transport.js";
+export declare const NOSTR_KIND = 25050;
+export interface NostrEvent {
+    id: string;
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: string[][];
+    content: string;
+    sig: string;
+}
+/** NIP-01 event id: SHA-256 of `[0, pubkey, created_at, kind, tags, content]` serialised without whitespace. */
+export declare function eventId(pubkey: string, createdAt: number, kind: number, tags: string[][], content: string): Promise<string>;
+/** A signed kind-25050 event (BIP340 Schnorr over the id). */
+export declare function makeEvent(secret: Uint8Array, topic: string, content: string, createdAt: number): Promise<NostrEvent>;
+/** The WebSocket constructor to a relay; the browser's, or Node 22+'s global one. Tests pass their own. */
+export type RelayConnect = (url: string) => SocketLike;
+export declare const defaultRelayConnect: RelayConnect;
+export interface RelayPoolOptions {
+    urls: readonly string[];
+    topic: string;
+    connect: RelayConnect;
+    clock: Clock;
+    /** Unix ms. */
+    wall: () => number;
+    onEvent: (ev: NostrEvent) => void;
+    /** Called when the number of connected relays changes. */
+    onChange?: () => void;
+}
+/** Every relay at once, each reconnected with backoff (1 s doubling to 30 s); events deduped by id. */
+export declare class RelayPool {
+    private readonly o;
+    private readonly relays;
+    private readonly seen;
+    private readonly sub;
+    private closed;
+    private waiters;
+    constructor(o: RelayPoolOptions);
+    get total(): number;
+    /** Relays connected right now (and not skipped). */
+    get connected(): number;
+    /** Every relay has either connected, failed a connect, or been skipped: waiting longer for the rest is pointless. */
+    get settled(): boolean;
+    start(): void;
+    /** Resolves true once one relay is connected, false after `timeoutMs` (or when closed). */
+    whenUp(timeoutMs: number): Promise<boolean>;
+    publish(ev: NostrEvent): void;
+    close(): void;
+    private changed;
+    private trySend;
+    private dial;
+    private drop;
+    private retryLater;
+    private skip;
+    private onMessage;
+}
+/** Default public relays (probed 2026-10-26, docs/design/no-server-fallback.md): all accept and echo ephemeral kind 25050. */
+export declare const DEFAULT_NOSTR_RELAYS: readonly string[];
+/** Public STUN servers for Nostr joiners (spec s.5). */
+export declare const DEFAULT_NOSTR_STUN: readonly string[];
+export interface RelayCheck {
+    url: string;
+    ok: boolean;
+    ms: number;
+    error?: string;
+}
+/**
+ * Probes each relay: connect, subscribe, publish one kind-25050 event to itself under a random topic with a random
+ * key, and see it echoed. Anonymous (nothing about the player is sent). Use it to pick `hosting.nostrRelays`.
+ */
+export declare function checkNostrRelays(urls: readonly string[], timeoutMs?: number, opts?: {
+    connect?: RelayConnect;
+    clock?: Clock;
+}): Promise<RelayCheck[]>;