@nostrify/nostrify 0.46.4

package/NKinds.test.ts

@@ -0,0 +1,42 @@
+import { assertEquals } from '@std/assert';
+
+import { NKinds } from './NKinds.ts';
+
+Deno.test('NKinds', () => {
+  assertEquals(NKinds.regular(1000), true);
+  assertEquals(NKinds.regular(10000), false);
+  assertEquals(NKinds.regular(0), false);
+  assertEquals(NKinds.regular(44), true);
+  assertEquals(NKinds.regular(45), false);
+  assertEquals(NKinds.regular(100000), false);
+
+  assertEquals(NKinds.replaceable(1000), false);
+  assertEquals(NKinds.replaceable(10000), true);
+  assertEquals(NKinds.replaceable(0), true);
+  assertEquals(NKinds.replaceable(3), true);
+  assertEquals(NKinds.replaceable(44), false);
+  assertEquals(NKinds.replaceable(45), false);
+  assertEquals(NKinds.replaceable(100000), false);
+
+  assertEquals(NKinds.ephemeral(1000), false);
+  assertEquals(NKinds.ephemeral(10000), false);
+  assertEquals(NKinds.ephemeral(0), false);
+  assertEquals(NKinds.ephemeral(3), false);
+  assertEquals(NKinds.ephemeral(44), false);
+  assertEquals(NKinds.ephemeral(45), false);
+  assertEquals(NKinds.ephemeral(20000), true);
+  assertEquals(NKinds.ephemeral(30000), false);
+  assertEquals(NKinds.ephemeral(40000), false);
+  assertEquals(NKinds.ephemeral(100000), false);
+
+  assertEquals(NKinds.addressable(1000), false);
+  assertEquals(NKinds.addressable(10000), false);
+  assertEquals(NKinds.addressable(0), false);
+  assertEquals(NKinds.addressable(3), false);
+  assertEquals(NKinds.addressable(44), false);
+  assertEquals(NKinds.addressable(45), false);
+  assertEquals(NKinds.addressable(20000), false);
+  assertEquals(NKinds.addressable(30000), true);
+  assertEquals(NKinds.addressable(40000), false);
+  assertEquals(NKinds.addressable(100000), false);
+});

package/NKinds.ts

@@ -0,0 +1,26 @@
+export class NKinds {
+  /** Events are **regular**, which means they're all expected to be stored by relays. */
+  static regular(kind: number): boolean {
+    return (1000 <= kind && kind < 10000) || [1, 2, 4, 5, 6, 7, 8, 16, 40, 41, 42, 43, 44].includes(kind);
+  }
+
+  /** Events are **replaceable**, which means that, for each combination of `pubkey` and `kind`, only the latest event is expected to (SHOULD) be stored by relays, older versions are expected to be discarded. */
+  static replaceable(kind: number): boolean {
+    return (10000 <= kind && kind < 20000) || [0, 3].includes(kind);
+  }
+
+  /** Events are **ephemeral**, which means they are not expected to be stored by relays. */
+  static ephemeral(kind: number): boolean {
+    return 20000 <= kind && kind < 30000;
+  }
+
+  /** Events are **addressable**, which means that, for each combination of `pubkey`, `kind` and the `d` tag, only the latest event is expected to be stored by relays, older versions are expected to be discarded. */
+  static addressable(kind: number): boolean {
+    return 30000 <= kind && kind < 40000;
+  }
+
+  /** @deprecated Use `NKinds.addressable()` instead. */
+  static parameterizedReplaceable(kind: number): boolean {
+    return NKinds.addressable(kind);
+  }
+}

package/NPool.test.ts

@@ -0,0 +1,117 @@
+import { NostrEvent } from '@nostrify/types';
+import { assert, assertEquals } from '@std/assert';
+import { finalizeEvent, generateSecretKey } from 'nostr-tools';
+
+import { NPool } from './NPool.ts';
+import { NRelay1 } from './NRelay1.ts';
+
+import events from '../../fixtures/events.json' with { type: 'json' };
+import { TestRelayServer } from './test/TestRelayServer.ts';
+
+const event1s = events
+  .filter((e) => e.kind === 1)
+  .toSorted((_) => 0.5 - Math.random())
+  .slice(0, 10);
+
+Deno.test('NPool.query', async () => {
+  const controller = new AbortController();
+  const tid = setTimeout(() => controller.abort(), 5000);
+
+  await using server1 = new TestRelayServer();
+  await using server2 = new TestRelayServer();
+
+  for (const event of event1s) {
+    await server1.event(event);
+    await server2.event(event);
+  }
+
+  await using pool = new NPool({
+    open: (url) => new NRelay1(url),
+    reqRouter: (filters) =>
+      new Map([
+        [server1.url, filters],
+        [server2.url, filters],
+      ]),
+    eventRouter: () => [server1.url],
+  });
+
+  const events = await pool.query([{ kinds: [1], limit: 15 }]);
+
+  assertEquals(events.length, 10);
+  assert(events[0].created_at >= events[1].created_at);
+
+  clearTimeout(tid);
+});
+
+Deno.test('NPool.req', async () => {
+  const controller = new AbortController();
+  const tid = setTimeout(() => controller.abort(), 3000);
+
+  await using server1 = new TestRelayServer();
+  await using server2 = new TestRelayServer();
+
+  for (const event of event1s) {
+    await server1.event(event);
+    await server2.event(event);
+  }
+
+  const events: NostrEvent[] = [];
+
+  await using pool = new NPool({
+    open: (url) => new NRelay1(url),
+    reqRouter: (filters) =>
+      new Map([
+        [server1.url, filters],
+        [server2.url, filters],
+      ]),
+    eventRouter: () => [server1.url],
+  });
+
+  for await (const msg of pool.req([{ kinds: [1], limit: 3 }], { signal: controller.signal })) {
+    if (msg[0] === 'EVENT') {
+      events.push(msg[2]);
+    }
+
+    if (events.length === 3) break;
+  }
+
+  assertEquals(events.length, 3);
+
+  clearTimeout(tid);
+});
+
+Deno.test('NPool.event', async () => {
+  const controller = new AbortController();
+  const tid = setTimeout(() => controller.abort(), 5000);
+
+  await using server1 = new TestRelayServer();
+  await using server2 = new TestRelayServer();
+
+  for (const event of event1s) {
+    await server1.event(event);
+    await server2.event(event);
+  }
+
+  const event: NostrEvent = finalizeEvent({
+    kind: 1,
+    content: 'This is an automated test from Nostrify: https://gitlab.com/soapbox-pub/nostrify',
+    tags: [['unique', 'uniqueTag']],
+    created_at: Math.floor(Date.now() / 1000),
+  }, generateSecretKey());
+
+  await using pool = new NPool({
+    open: (url) => new NRelay1(url),
+    reqRouter: (filters) =>
+      new Map([
+        [server1.url, filters],
+        [server2.url, filters],
+      ]),
+    eventRouter: () => [server1.url],
+  });
+
+  await pool.event(event, { signal: controller.signal });
+
+  assertEquals((await pool.query([{ kinds: [1], '#unique': ['uniqueTag'] }], { signal: controller.signal })).length, 1);
+
+  clearTimeout(tid);
+});

package/NPool.ts

@@ -0,0 +1,224 @@
+import { NostrEvent, NostrFilter, NostrRelayCLOSED, NostrRelayEOSE, NostrRelayEVENT, NRelay } from '@nostrify/types';
+import { getFilterLimit } from 'nostr-tools';
+
+import { CircularSet } from './utils/CircularSet';
+import { Machina } from './utils/Machina';
+import { NSet } from './NSet';
+
+export interface NPoolOpts<T extends NRelay> {
+  /** Creates an `NRelay` instance for the given URL. */
+  open(url: string): T;
+  /** Determines the relays to use for making `REQ`s to the given filters. To support the Outbox model, it should analyze the `authors` field of the filters. */
+  reqRouter(
+    filters: NostrFilter[],
+  ):
+    | ReadonlyMap<string, NostrFilter[]>
+    | Promise<ReadonlyMap<string, NostrFilter[]>>;
+  /** Determines the relays to use for publishing the given event. To support the Outbox model, it should analyze the `pubkey` field of the event. */
+  eventRouter(event: NostrEvent): string[] | Promise<string[]>;
+}
+
+/**
+ * The `NPool` class is a `NRelay` implementation for connecting to multiple relays.
+ *
+ * ```ts
+ * const pool = new NPool({
+ *   open: (url) => new NRelay1(url),
+ *   reqRouter: async (filters) => new Map([
+ *     ['wss://relay1.mostr.pub', filters],
+ *     ['wss://relay2.mostr.pub', filters],
+ *   ]),
+ *   eventRouter: async (event) => ['wss://relay1.mostr.pub', 'wss://relay2.mostr.pub'],
+ * });
+ *
+ * // Now you can use the pool like a regular relay.
+ * for await (const msg of pool.req([{ kinds: [1] }])) {
+ *   if (msg[0] === 'EVENT') console.log(msg[2]);
+ *   if (msg[0] === 'EOSE') break;
+ * }
+ * ```
+ *
+ * This class is designed with the Outbox model in mind.
+ * Instead of passing relay URLs into each method, you pass functions into the contructor that statically-analyze filters and events to determine which relays to use for requesting and publishing events.
+ * If a relay wasn't already connected, it will be opened automatically.
+ * Defining `open` will also let you use any relay implementation, such as `NRelay1`.
+ *
+ * Note that `pool.req` may stream duplicate events, while `pool.query` will correctly process replaceable events and deletions within the event set before returning them.
+ *
+ * `pool.req` will only emit an `EOSE` when all relays in its set have emitted an `EOSE`, and likewise for `CLOSED`.
+ */
+export class NPool<T extends NRelay = NRelay> implements NRelay {
+  private _relays = new Map<string, T>();
+
+  constructor(private opts: NPoolOpts<T>) {}
+
+  /** Get or create a relay instance for the given URL. */
+  public relay(url: string): T {
+    const relay = this._relays.get(url);
+
+    if (relay) {
+      return relay;
+    } else {
+      const relay = this.opts.open(url);
+      this._relays.set(url, relay);
+      return relay;
+    }
+  }
+
+  /** Returns a new pool instance that uses the given relays. Connections are shared with the original pool. */
+  public group(urls: string[]): NPool<T> {
+    return new NPool({
+      open: (url) => this.relay(url),
+      reqRouter: (filters) => new Map(urls.map((url) => [url, filters])),
+      eventRouter: () => urls,
+    });
+  }
+
+  public get relays(): ReadonlyMap<string, T> {
+    return this._relays;
+  }
+
+  /**
+   * Sends a `REQ` to relays based on the configured `reqRouter`.
+   *
+   * `EVENT` messages from the selected relays are yielded.
+   * `EOSE` and `CLOSE` messages are only yielded when all relays have emitted them.
+   *
+   * Deduplication of `EVENT` messages is attempted, so that each event is only yielded once.
+   * A circular set of 1000 is used to track seen event IDs, so it's possible that very
+   * long-running subscriptions (with over 1000 results) may yield duplicate events.
+   */
+  async *req(
+    filters: NostrFilter[],
+    opts?: { signal?: AbortSignal; relays?: string[] },
+  ): AsyncIterable<NostrRelayEVENT | NostrRelayEOSE | NostrRelayCLOSED> {
+    const controller = new AbortController();
+    const signal = opts?.signal ? AbortSignal.any([opts.signal, controller.signal]) : controller.signal;
+
+    const routes = opts?.relays
+      ? new Map(opts.relays.map((url) => [url, filters]))
+      : await this.opts.reqRouter(filters);
+
+    if (routes.size < 1) {
+      return;
+    }
+
+    const machina = new Machina<
+      NostrRelayEVENT | NostrRelayEOSE | NostrRelayCLOSED
+    >(signal);
+
+    const eoses = new Set<string>();
+    const closes = new Set<string>();
+    const events = new CircularSet<string>(1000);
+
+    for (const [url, filters] of routes.entries()) {
+      const relay = this.relay(url);
+      (async () => {
+        for await (const msg of relay.req(filters, { signal })) {
+          if (msg[0] === 'EOSE') {
+            eoses.add(url);
+            if (eoses.size === routes.size) {
+              machina.push(msg);
+            }
+          }
+          if (msg[0] === 'CLOSED') {
+            closes.add(url);
+            if (closes.size === routes.size) {
+              machina.push(msg);
+            }
+          }
+          if (msg[0] === 'EVENT') {
+            const [, , event] = msg;
+            if (!events.has(event.id)) {
+              events.add(event.id);
+              machina.push(msg);
+            }
+          }
+        }
+      })().catch(() => {});
+    }
+
+    try {
+      for await (const msg of machina) {
+        yield msg;
+      }
+    } finally {
+      controller.abort();
+    }
+  }
+
+  /**
+   * Events are sent to relays according to the `eventRouter`.
+   * Returns a fulfilled promise if ANY relay accepted the event,
+   * or a rejected promise if ALL relays rejected or failed to publish the event.
+   */
+  async event(
+    event: NostrEvent,
+    opts?: { signal?: AbortSignal; relays?: string[] },
+  ): Promise<void> {
+    const relayUrls = opts?.relays ?? await this.opts.eventRouter(event);
+
+    if (!relayUrls.length) {
+      return;
+    }
+
+    // @ts-ignore Promise.any exists for sure
+    await Promise.any(
+      relayUrls.map((url) => this.relay(url).event(event, opts)),
+    );
+  }
+
+  /**
+   * This method calls `.req` internally and then post-processes the results.
+   * Please read the definition of `.req`.
+   *
+   * - The strategy is to seek regular events quickly, and to wait to find the latest versions of replaceable events.
+   * - Filters for replaceable events will wait for all relays to `EOSE` (or `CLOSE`, or for the signal to be aborted) to ensure the latest event versions are retrieved.
+   * - Filters for regular events will stop as soon as the filters are fulfilled.
+   * - Events are deduplicated, sorted, and only the latest version of replaceable events is kept.
+   * - If the signal is aborted, this method will return partial results instead of throwing.
+   *
+   * To implement a custom strategy, call `.req` directly.
+   */
+  async query(
+    filters: NostrFilter[],
+    opts?: { signal?: AbortSignal; relays?: string[] },
+  ): Promise<NostrEvent[]> {
+    const map = new Map<string, NostrEvent>();
+    const events = new NSet(map);
+
+    const limit = filters.reduce(
+      (result, filter) => result + getFilterLimit(filter),
+      0,
+    );
+    if (limit === 0) return [];
+
+    try {
+      for await (const msg of this.req(filters, opts)) {
+        if (msg[0] === 'EOSE') break;
+        if (msg[0] === 'EVENT') events.add(msg[2]);
+        if (msg[0] === 'CLOSED') break;
+      }
+    } catch {
+      // Skip errors, return partial results.
+    }
+
+    // Don't sort results of search filters.
+    if (filters.some((filter) => typeof filter.search === 'string')) {
+      return [...map.values()];
+    } else {
+      return [...events];
+    }
+  }
+
+  /** Close all the relays in the pool. */
+  async close(): Promise<void> {
+    await Promise.all(
+      [...this._relays.values()].map((relay) => relay.close()),
+    );
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    await this.close();
+  }
+}

package/NRelay1.test.ts

@@ -0,0 +1,174 @@
+import { NostrEvent } from '@nostrify/types';
+import { assert, assertEquals, assertRejects } from '@std/assert';
+import { finalizeEvent, generateSecretKey } from 'nostr-tools';
+import { WebsocketEvent } from 'websocket-ts';
+
+import { genEvent } from './test/mod.ts';
+import { TestRelayServer } from './test/TestRelayServer.ts';
+import { NRelay1 } from './NRelay1.ts';
+
+import events from '../../fixtures/events.json' with { type: 'json' };
+
+const event1s = events
+  .filter((e) => e.kind === 1)
+  .toSorted((_) => 0.5 - Math.random())
+  .slice(0, 10);
+
+Deno.test('NRelay1.query', async () => {
+  const controller = new AbortController();
+  const tid = setTimeout(() => controller.abort(), 3000);
+
+  await using server = new TestRelayServer();
+
+  for (const event of event1s) {
+    await server.event(event);
+  }
+
+  await using relay = new NRelay1(server.url);
+  const events = await relay.query([{ kinds: [1], limit: 3 }], { signal: controller.signal });
+
+  assertEquals(events.length, 3);
+  assert(events[0].created_at >= events[1].created_at);
+
+  clearTimeout(tid);
+});
+
+Deno.test('NRelay1.query mismatched filter', async () => {
+  await using server = new TestRelayServer({
+    handleMessage(socket, msg) {
+      if (msg[0] === 'REQ') {
+        const [, subId, ..._filters] = msg;
+        socket.send(JSON.stringify(['EVENT', subId, genEvent({ kind: 9001 })]));
+        socket.send(JSON.stringify(['EOSE', subId]));
+      }
+    },
+  });
+
+  await using relay = new NRelay1(server.url);
+  const events = await relay.query([{ kinds: [1] }]);
+
+  assertEquals(events, []);
+});
+
+Deno.test('NRelay1.req', async () => {
+  const controller = new AbortController();
+  const tid = setTimeout(() => controller.abort(), 3000);
+
+  await using server = new TestRelayServer();
+
+  for (const event of event1s) {
+    await server.event(event);
+  }
+
+  await using relay = new NRelay1(server.url);
+  const events: NostrEvent[] = [];
+
+  for await (const msg of relay.req([{ kinds: [1], limit: 3 }], { signal: controller.signal })) {
+    if (msg[0] === 'EVENT') {
+      events.push(msg[2]);
+      break;
+    }
+  }
+
+  assertEquals(events.length, 1);
+
+  clearTimeout(tid);
+});
+
+Deno.test('NRelay1.event', async () => {
+  await using server = new TestRelayServer();
+  await using relay = new NRelay1(server.url);
+
+  const event: NostrEvent = finalizeEvent({
+    kind: 1,
+    content: 'This is an automated test from Nostrify: https://gitlab.com/soapbox-pub/nostrify',
+    tags: [],
+    created_at: Math.floor(Date.now() / 1000),
+  }, generateSecretKey());
+
+  await relay.event(event);
+});
+
+Deno.test('NRelay1 backoff', async (t) => {
+  await using server = new TestRelayServer();
+  await using relay = new NRelay1(server.url);
+
+  await t.step('websocket opens', async () => {
+    await new Promise((resolve) => relay.socket.addEventListener(WebsocketEvent.open, resolve, { once: true }));
+    assertEquals(relay.socket.readyState, WebSocket.OPEN);
+  });
+
+  // Start a subscription so the relay will reconnect
+  (async () => {
+    try {
+      for await (const _msg of relay.req([{ kinds: [0] }])) {
+        // Do nothing
+      }
+    } catch {
+      //
+    }
+  })();
+
+  await t.step('websocket closes when server closes', async () => {
+    const waitForClose = new Promise((resolve) =>
+      relay.socket.addEventListener(WebsocketEvent.close, resolve, { once: true })
+    );
+    await server.close();
+    await waitForClose;
+    assertEquals(relay.socket.readyState, WebSocket.CLOSED);
+  });
+
+  await t.step('websocket reopens when server reopens', async () => {
+    server.open();
+    await new Promise((resolve) => relay.socket.addEventListener(WebsocketEvent.open, resolve, { once: true }));
+    assertEquals(relay.socket.readyState, WebSocket.OPEN);
+  });
+});
+
+Deno.test('NRelay1 idleTimeout', async (t) => {
+  await using server = new TestRelayServer();
+  await using relay = new NRelay1(server.url, { idleTimeout: 100 });
+
+  await t.step('websocket opens', async () => {
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    assertEquals(relay.socket.readyState, WebSocket.OPEN);
+  });
+
+  await t.step('websocket closes after idleTimeout', async () => {
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    assertEquals(relay.socket.readyState, WebSocket.CLOSED);
+    assertEquals(relay.socket.closedByUser, true);
+  });
+
+  await t.step('websocket wakes up during activity', async () => {
+    await relay.event(events[0]);
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    assertEquals(relay.socket.readyState, WebSocket.OPEN);
+  });
+});
+
+Deno.test('NRelay1.count rejects when the server sends CLOSED', async () => {
+  await using server = new TestRelayServer({
+    handleMessage(socket, msg) {
+      if (msg[0] === 'COUNT') {
+        server.send(socket, ['CLOSED', msg[1], 'unsupported: COUNT is not supported']);
+      }
+    },
+  });
+
+  await using relay = new NRelay1(server.url);
+
+  await assertRejects(() => relay.count([{ kinds: [1] }]));
+});
+
+Deno.test('NRelay1 closes when it receives a binary message', async () => {
+  await using server = new TestRelayServer({
+    handleMessage(socket) {
+      socket.send(new Uint8Array([0x00, 0x01, 0x02, 0x03]));
+    },
+  });
+
+  await using relay = new NRelay1(server.url);
+
+  await assertRejects(() => relay.query([{ kinds: [1] }]));
+});