applesauce-relay 0.12.0 → 1.0.1

package/README.md

@@ -1,3 +1,118 @@
 # Applesauce Relay
 
 `applesauce-relay` is a nostr relay communication framework built on top of [RxJS](https://rxjs.dev/)
+
+## Installation
+
+```bash
+npm install applesauce-relay
+```
+
+## Features
+
+- [x] NIP-01
+- [x] Relay pool and groups
+- [x] Fetch NIP-11 information before connecting
+- [x] NIP-11 `auth_required` limitation
+- [ ] NIP-11 `max_subscriptions` limitation
+- [x] Client negentropy sync
+- [x] Reconnection backoff logic
+- [x] republish event on reconnect and auth-required
+- [x] Resubscribe on reconnect and auth-required
+- [ ] NIP-45 COUNT
+
+## Examples
+
+Read the [documentation](https://hzrd149.github.io/applesauce/overview/relays.html) for more detailed explanation of all methods
+
+### Single Relay
+
+```typescript
+import { Relay } from "./relay";
+
+// Connect to a single relay
+const relay = new Relay("wss://relay.example.com");
+
+// Subscribe to events
+relay
+  .req({
+    kinds: [1],
+    limit: 10,
+  })
+  .subscribe((response) => {
+    if (response === "EOSE") {
+      console.log("End of stored events");
+    } else {
+      console.log("Received event:", response);
+    }
+  });
+
+// Publish an event
+const event = {
+  kind: 1,
+  content: "Hello Nostr!",
+  created_at: Math.floor(Date.now() / 1000),
+  tags: [],
+  // ... other required fields
+};
+
+relay.event(event).subscribe((response) => {
+  console.log(`Published:`, response.ok);
+});
+```
+
+### Relay Pool
+
+```typescript
+import { RelayPool } from "./pool";
+
+// Create a pool and connect to multiple relays
+const pool = new RelayPool();
+const relays = ["wss://relay1.example.com", "wss://relay2.example.com"];
+
+// Subscribe to events from multiple relays
+pool
+  .req(relays, {
+    kinds: [1],
+    limit: 10,
+  })
+  .subscribe((response) => {
+    if (response === "EOSE") {
+      console.log("End of stored events");
+    } else {
+      console.log("Received event:", response);
+    }
+  });
+
+// Publish to multiple relays
+pool.event(relays, event).subscribe((response) => {
+  console.log(`Published to ${response.from}:`, response.ok);
+});
+```
+
+### Relay Group
+
+```typescript
+import { RelayPool } from "./pool";
+
+const pool = new RelayPool();
+const relays = ["wss://relay1.example.com", "wss://relay2.example.com"];
+
+// Create a group (automatically deduplicates events)
+const group = pool.group(relays);
+
+// Subscribe to events
+group
+  .req({
+    kinds: [1],
+    limit: 10,
+  })
+  .subscribe((response) => {
+    console.log("Received:", response);
+  });
+
+// Publish to all relays in group
+group.event(event).subscribe((response) => {
+  console.log(`Published to ${response.from}:`, response.ok);
+});
+```

package/dist/__tests__/auth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/auth.test.js

@@ -0,0 +1,111 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { subscribeSpyTo } from "@hirez_io/observer-spy";
+import { WS } from "vitest-websocket-mock";
+import { Relay } from "../relay.js";
+let server;
+let relay;
+beforeEach(async () => {
+    server = new WS("wss://test", { jsonProtocol: true });
+    relay = new Relay("wss://test");
+    // Create a persistent subscription to keep the connection open
+    // @ts-expect-error
+    subscribeSpyTo(relay.socket);
+});
+afterEach(async () => {
+    server.close();
+    // Wait for server to close to prevent memory leaks
+    await WS.clean();
+});
+const mockEvent = {
+    kind: 1,
+    id: "00007641c9c3e65a71843933a44a18060c7c267a4f9169efa3735ece45c8f621",
+    pubkey: "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d",
+    created_at: 1743712795,
+    tags: [["nonce", "13835058055282167643", "16"]],
+    content: "This is just stupid: https://codestr.fiatjaf.com/",
+    sig: "5a57b5a12bba4b7cf0121077b1421cf4df402c5c221376c076204fc4f7519e28ce6508f26ddc132c406ccfe6e62cc6db857b96c788565cdca9674fe9a0710ac2",
+};
+describe("event", () => {
+    it("should wait for auth before sending EVENT if auth-required received", async () => {
+        // Create first event subscription
+        const spy1 = subscribeSpyTo(relay.event(mockEvent));
+        // Verify EVENT was sent
+        const firstEventMessage = await server.nextMessage;
+        expect(firstEventMessage).toEqual(["EVENT", mockEvent]);
+        // Send auth-required response
+        server.send(["OK", mockEvent.id, false, "auth-required: need to authenticate"]);
+        // Create second event subscription - this should not send EVENT yet
+        const spy2 = subscribeSpyTo(relay.event(mockEvent));
+        // Should not have received any messages
+        expect(server.messages.length).toBe(1);
+        // Send AUTH challenge
+        server.send(["AUTH", "challenge-string"]);
+        // Send auth event
+        const authEvent = { ...mockEvent, id: "auth-id" };
+        subscribeSpyTo(relay.auth(authEvent));
+        // Verify AUTH was sent
+        const authMessage = await server.nextMessage;
+        expect(authMessage).toEqual(["AUTH", authEvent]);
+        // Send successful auth response
+        server.send(["OK", authEvent.id, true, ""]);
+        // Now the second EVENT should be sent
+        const secondEventMessage = await server.nextMessage;
+        expect(secondEventMessage).toEqual(["EVENT", mockEvent]);
+        // Send OK response for second event
+        server.send(["OK", mockEvent.id, true, ""]);
+        expect(spy1.getLastValue()).toEqual({
+            ok: false,
+            message: "auth-required: need to authenticate",
+            from: "wss://test",
+        });
+        expect(spy2.getLastValue()).toEqual({ ok: true, message: "", from: "wss://test" });
+    });
+});
+describe("req", () => {
+    it("should wait for auth before sending REQ if auth-required received", async () => {
+        // Create first REQ subscription
+        const filters = [{ kinds: [1], limit: 10 }];
+        subscribeSpyTo(relay.req(filters, "sub1"), { expectErrors: true });
+        // Verify REQ was sent
+        const firstReqMessage = await server.nextMessage;
+        expect(firstReqMessage).toEqual(["REQ", "sub1", ...filters]);
+        // Send auth-required response
+        server.send(["CLOSED", "sub1", "auth-required: need to authenticate"]);
+        // Consume the client CLOSE message for sub1
+        await server.nextMessage;
+        // Create second REQ subscription - this should not send REQ yet
+        subscribeSpyTo(relay.req(filters, "sub2"), { expectErrors: true });
+        // Should not have received any messages
+        expect(server.messages).not.toContain(["REQ", "sub2", ...filters]);
+        // Send AUTH challenge
+        server.send(["AUTH", "challenge-string"]);
+        // Send auth event
+        const authEvent = { ...mockEvent, id: "auth-id" };
+        subscribeSpyTo(relay.auth(authEvent));
+        // Verify AUTH was sent
+        const authMessage = await server.nextMessage;
+        expect(authMessage).toEqual(["AUTH", authEvent]);
+        // Send successful auth response
+        server.send(["OK", authEvent.id, true, ""]);
+        // Now the second REQ should be sent
+        const secondReqMessage = await server.nextMessage;
+        expect(secondReqMessage).toEqual(["REQ", "sub2", ...filters]);
+        // Send some events for the second subscription
+        server.send(["EVENT", "sub2", mockEvent]);
+        server.send(["EOSE", "sub2"]);
+    });
+});
+describe("auth", () => {
+    it("should set authenticated state after successful AUTH challenge response", async () => {
+        // Send AUTH challenge
+        server.send(["AUTH", "challenge-string"]);
+        // Send auth event response
+        const authEvent = { ...mockEvent, id: "auth-id" };
+        subscribeSpyTo(relay.auth(authEvent));
+        // Verify AUTH was sent
+        await expect(server).toReceiveMessage(["AUTH", authEvent]);
+        // Send successful auth response
+        server.send(["OK", authEvent.id, true, ""]);
+        expect(relay.authenticated).toBe(true);
+    });
+});

package/dist/__tests__/group.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/group.test.js

@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { subscribeSpyTo } from "@hirez_io/observer-spy";
+import { WS } from "vitest-websocket-mock";
+import { Relay } from "../relay.js";
+import { RelayGroup } from "../group.js";
+import { of } from "rxjs";
+let mockRelay1;
+let mockRelay2;
+let relay1;
+let relay2;
+let group;
+let mockEvent;
+beforeEach(async () => {
+    // Create mock relays
+    mockRelay1 = new WS("wss://relay1.test", { jsonProtocol: true });
+    mockRelay2 = new WS("wss://relay2.test", { jsonProtocol: true });
+    // Mock empty information document
+    vi.spyOn(Relay, "fetchInformationDocument").mockImplementation(() => of(null));
+    // Create relays
+    relay1 = new Relay("wss://relay1.test");
+    relay2 = new Relay("wss://relay2.test");
+    // Create group
+    group = new RelayGroup([relay1, relay2]);
+    mockEvent = {
+        kind: 1,
+        id: "test-id",
+        pubkey: "test-pubkey",
+        created_at: 1234567890,
+        tags: [],
+        content: "test content",
+        sig: "test-sig",
+    };
+});
+afterEach(async () => {
+    mockRelay1.close();
+    mockRelay2.close();
+    await WS.clean();
+});
+describe("req", () => {
+    it("should make requests to multiple relays", async () => {
+        group.req([{ kinds: [1] }], "test-sub").subscribe();
+        await expect(mockRelay1).toReceiveMessage(["REQ", "test-sub", { kinds: [1] }]);
+        await expect(mockRelay2).toReceiveMessage(["REQ", "test-sub", { kinds: [1] }]);
+    });
+    it("should emit events from all relays", async () => {
+        const spy = subscribeSpyTo(group.req([{ kinds: [1] }], "test-sub"));
+        await expect(mockRelay1).toReceiveMessage(["REQ", "test-sub", { kinds: [1] }]);
+        await expect(mockRelay2).toReceiveMessage(["REQ", "test-sub", { kinds: [1] }]);
+        mockRelay1.send(["EVENT", "test-sub", { ...mockEvent, id: "1" }]);
+        mockRelay2.send(["EVENT", "test-sub", { ...mockEvent, id: "2" }]);
+        expect(spy.getValues()).toEqual([expect.objectContaining({ id: "1" }), expect.objectContaining({ id: "2" })]);
+    });
+    it("should only emit EOSE once all relays have emitted EOSE", async () => {
+        const spy = subscribeSpyTo(group.req([{ kinds: [1] }], "test-sub"));
+        mockRelay1.send(["EOSE", "test-sub"]);
+        expect(spy.getValues()).not.toContain("EOSE");
+        mockRelay2.send(["EOSE", "test-sub"]);
+        expect(spy.getValues()).toContain("EOSE");
+    });
+    it("should ignore relays that have an error", async () => {
+        const spy = subscribeSpyTo(group.req([{ kinds: [1] }], "test-sub"));
+        mockRelay1.error();
+        mockRelay2.send(["EVENT", "test-sub", mockEvent]);
+        mockRelay2.send(["EOSE", "test-sub"]);
+        expect(spy.getValues()).toEqual([expect.objectContaining(mockEvent), "EOSE"]);
+    });
+    it("should emit EOSE if all relays error", async () => {
+        const spy = subscribeSpyTo(group.req([{ kinds: [1] }], "test-sub"));
+        mockRelay1.error();
+        mockRelay2.error();
+        expect(spy.getValues()).toEqual(["EOSE"]);
+    });
+});
+describe("event", () => {
+    it("should send EVENT to all relays in the group", async () => {
+        group.event(mockEvent).subscribe();
+        await expect(mockRelay1).toReceiveMessage(["EVENT", mockEvent]);
+        await expect(mockRelay2).toReceiveMessage(["EVENT", mockEvent]);
+    });
+    it("should emit OK messages from all relays", async () => {
+        const spy = subscribeSpyTo(group.event(mockEvent));
+        mockRelay1.send(["OK", mockEvent.id, true, ""]);
+        mockRelay2.send(["OK", mockEvent.id, true, ""]);
+        expect(spy.getValues()).toEqual([
+            expect.objectContaining({ ok: true, from: "wss://relay1.test", message: "" }),
+            expect.objectContaining({ ok: true, from: "wss://relay2.test", message: "" }),
+        ]);
+    });
+    it("should complete when all relays have sent OK messages", async () => {
+        const spy = subscribeSpyTo(group.event(mockEvent));
+        mockRelay1.send(["OK", mockEvent.id, true, ""]);
+        expect(spy.receivedComplete()).toBe(false);
+        mockRelay2.send(["OK", mockEvent.id, true, ""]);
+        expect(spy.receivedComplete()).toBe(true);
+    });
+    it("should handle relay errors and still complete", async () => {
+        const spy = subscribeSpyTo(group.event(mockEvent));
+        mockRelay1.error();
+        mockRelay2.send(["OK", mockEvent.id, true, ""]);
+        expect(spy.getValues()).toEqual([
+            expect.objectContaining({ ok: false, from: "wss://relay1.test", message: "Unknown error" }),
+            expect.objectContaining({ ok: true, from: "wss://relay2.test", message: "" }),
+        ]);
+        expect(spy.receivedComplete()).toBe(true);
+    });
+});

package/dist/__tests__/pool.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/pool.test.js

@@ -0,0 +1,81 @@
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { subscribeSpyTo } from "@hirez_io/observer-spy";
+import { WS } from "vitest-websocket-mock";
+import { RelayPool } from "../pool.js";
+let pool;
+let mockServer1;
+let mockServer2;
+let mockEvent;
+beforeEach(async () => {
+    // Create mock WebSocket servers
+    mockServer1 = new WS("wss://relay1.example.com");
+    mockServer2 = new WS("wss://relay2.example.com");
+    pool = new RelayPool();
+    mockEvent = {
+        kind: 1,
+        id: "test-id",
+        pubkey: "test-pubkey",
+        created_at: 1743712795,
+        tags: [],
+        content: "test content",
+        sig: "test-sig",
+    };
+});
+afterEach(async () => {
+    mockServer1.close();
+    mockServer2.close();
+    // Clean up WebSocket mocks
+    await WS.clean();
+});
+test("creates new relay connections", () => {
+    const url = "wss://relay1.example.com";
+    const relay = pool.relay(url);
+    expect(relay).toBeDefined();
+    expect(pool.relays.get(url)).toBe(relay);
+});
+test("returns existing relay connection if already exists", () => {
+    const url = "wss://relay1.example.com";
+    const relay1 = pool.relay(url);
+    const relay2 = pool.relay(url);
+    expect(relay1).toBe(relay2);
+    expect(pool.relays.size).toBe(1);
+});
+test("creates relay group with multiple relays", () => {
+    const urls = ["wss://relay1.example.com", "wss://relay2.example.com"];
+    const group = pool.group(urls);
+    expect(group).toBeDefined();
+    expect(pool.groups.get(urls.sort().join(","))).toBe(group);
+});
+test("req method sends subscription to multiple relays", async () => {
+    const urls = ["wss://relay1.example.com", "wss://relay2.example.com"];
+    const filters = { kinds: [1] };
+    const spy = subscribeSpyTo(pool.req(urls, filters));
+    // Verify REQ was sent to both relays
+    const req1 = await mockServer1.nextMessage;
+    const req2 = await mockServer2.nextMessage;
+    // Both messages should be REQ messages with the same filter
+    expect(JSON.parse(req1)[0]).toBe("REQ");
+    expect(JSON.parse(req2)[0]).toBe("REQ");
+    expect(JSON.parse(req1)[2]).toEqual(filters);
+    expect(JSON.parse(req2)[2]).toEqual(filters);
+    // Send EVENT from first relay
+    mockServer1.send(JSON.stringify(["EVENT", JSON.parse(req1)[1], mockEvent]));
+    // Send EOSE from both relays
+    mockServer1.send(JSON.stringify(["EOSE", JSON.parse(req1)[1]]));
+    mockServer2.send(JSON.stringify(["EOSE", JSON.parse(req2)[1]]));
+    expect(spy.getValues()).toContainEqual(expect.objectContaining(mockEvent));
+});
+test("event method publishes to multiple relays", async () => {
+    const urls = ["wss://relay1.example.com", "wss://relay2.example.com"];
+    const spy = subscribeSpyTo(pool.event(urls, mockEvent));
+    // Verify EVENT was sent to both relays
+    const event1 = await mockServer1.nextMessage;
+    const event2 = await mockServer2.nextMessage;
+    expect(JSON.parse(event1)).toEqual(["EVENT", mockEvent]);
+    expect(JSON.parse(event2)).toEqual(["EVENT", mockEvent]);
+    // Send OK responses from both relays
+    mockServer1.send(JSON.stringify(["OK", mockEvent.id, true, ""]));
+    mockServer2.send(JSON.stringify(["OK", mockEvent.id, true, ""]));
+    expect(spy.getValues()).toContainEqual({ ok: true, from: "wss://relay1.example.com", message: "" });
+    expect(spy.getValues()).toContainEqual({ ok: true, from: "wss://relay2.example.com", message: "" });
+});

package/dist/__tests__/relay.test.d.ts

@@ -0,0 +1 @@
+export {};