applesauce-relay 4.0.0 → 4.2.0

package/README.md

@@ -10,16 +10,15 @@ npm install applesauce-relay
 
 ## Features
 
-- [x] NIP-01
+- [x] NIP-01 `REQ` and `EVENT` messages
 - [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
+- [x] NIP-45 COUNT
 
 ## Examples
 

package/dist/group.d.ts

@@ -1,9 +1,9 @@
 import { Filter, type NostrEvent } from "nostr-tools";
-import { Observable } from "rxjs";
+import { BehaviorSubject, MonoTypeOperatorFunction, Observable } from "rxjs";
 import { IAsyncEventStoreActions, IAsyncEventStoreRead, IEventStoreActions, IEventStoreRead } from "applesauce-core";
 import { NegentropySyncOptions, type ReconcileFunction } from "./negentropy.js";
-import { FilterInput, IGroup, IRelay, PublishOptions, PublishResponse, RequestOptions, SubscriptionOptions, SubscriptionResponse } from "./types.js";
 import { SyncDirection } from "./relay.js";
+import { CountResponse, FilterInput, IGroup, IGroupRelayInput, IRelay, PublishOptions, PublishResponse, RequestOptions, SubscriptionOptions, SubscriptionResponse } from "./types.js";
 /** Options for negentropy sync on a group of relays */
 export type GroupNegentropySyncOptions = NegentropySyncOptions & {
     /** Whether to sync in parallel (default true) */
@@ -20,25 +20,41 @@ export type GroupRequestOptions = RequestOptions & {
     eventStore?: IEventStoreActions | IAsyncEventStoreActions | null;
 };
 export declare class RelayGroup implements IGroup {
-    relays: IRelay[];
-    constructor(relays: IRelay[]);
-    /** Takes an array of observables and only emits EOSE when all observables have emitted EOSE */
-    protected mergeEOSE(requests: Observable<SubscriptionResponse>[], eventStore?: IEventStoreActions | IAsyncEventStoreActions | null): Observable<import("nostr-tools").Event | "EOSE">;
+    protected relays$: BehaviorSubject<IRelay[]> | Observable<IRelay[]>;
+    get relays(): IRelay[];
+    constructor(relays: IGroupRelayInput);
+    /** Whether this group is controlled by an upstream observable */
+    private get controlled();
+    /** Check if a relay is in the group */
+    has(relay: IRelay | string): boolean;
+    /** Add a relay to the group */
+    add(relay: IRelay): void;
+    /** Remove a relay from the group */
+    remove(relay: IRelay): void;
+    /** Internal logic for handling requests to multiple relays */
+    protected internalSubscription(project: (relay: IRelay) => Observable<SubscriptionResponse>, eventOperator?: MonoTypeOperatorFunction<NostrEvent>): Observable<SubscriptionResponse>;
+    /** Internal logic for handling publishes to multiple relays */
+    protected internalPublish(project: (relay: IRelay) => Observable<PublishResponse>): Observable<PublishResponse>;
     /**
      * Make a request to all relays
      * @note This does not deduplicate events
      */
-    req(filters: FilterInput, id?: string): Observable<SubscriptionResponse>;
+    req(filters: FilterInput, id?: string, opts?: {
+        /** Deduplicate events with an event store (default is a temporary instance of EventMemory), null will disable deduplication */
+        eventStore?: IEventStoreActions | IAsyncEventStoreActions | null;
+    }): Observable<SubscriptionResponse>;
     /** Send an event to all relays */
     event(event: NostrEvent): Observable<PublishResponse>;
     /** Negentropy sync events with the relays and an event store */
     negentropy(store: IEventStoreRead | IAsyncEventStoreRead | NostrEvent[], filter: Filter, reconcile: ReconcileFunction, opts?: GroupNegentropySyncOptions): Promise<boolean>;
     /** Publish an event to all relays with retries ( default 3 retries ) */
     publish(event: NostrEvent, opts?: PublishOptions): Promise<PublishResponse[]>;
-    /** Request events from all relays with retries ( default 3 retries ) */
+    /** Request events from all relays and complete on EOSE */
     request(filters: FilterInput, opts?: GroupRequestOptions): Observable<NostrEvent>;
     /** Open a subscription to all relays with retries ( default 3 retries ) */
     subscription(filters: FilterInput, opts?: GroupSubscriptionOptions): Observable<SubscriptionResponse>;
+    /** Count events on all relays in the group */
+    count(filters: Filter | Filter[], id?: string): Observable<Record<string, CountResponse>>;
     /** Negentropy sync events with the relays and an event store */
     sync(store: IEventStoreRead | IAsyncEventStoreRead | NostrEvent[], filter: Filter, direction?: SyncDirection): Observable<NostrEvent>;
 }

package/dist/group.js

@@ -1,45 +1,143 @@
 import { nanoid } from "nanoid";
-import { catchError, defer, EMPTY, endWith, identity, ignoreElements, merge, of, share, switchMap, } from "rxjs";
+import { BehaviorSubject, catchError, combineLatest, defaultIfEmpty, defer, endWith, filter, from, identity, ignoreElements, lastValueFrom, map, merge, of, scan, share, switchMap, take, takeWhile, toArray, } from "rxjs";
 import { EventMemory, filterDuplicateEvents, } from "applesauce-core";
 import { completeOnEose } from "./operators/complete-on-eose.js";
 import { onlyEvents } from "./operators/only-events.js";
+import { reverseSwitchMap } from "./operators/reverse-switch-map.js";
+/** Convert an error to a PublishResponse */
+function errorToPublishResponse(relay) {
+    return catchError((err) => of({ ok: false, from: relay.url, message: err?.message || "Unknown error" }));
+}
 export class RelayGroup {
-    relays;
+    relays$ = new BehaviorSubject([]);
+    get relays() {
+        if (this.relays$ instanceof BehaviorSubject)
+            return this.relays$.value;
+        throw new Error("This group was created with an observable, relays are not available");
+    }
     constructor(relays) {
-        this.relays = relays;
+        this.relays$ = Array.isArray(relays) ? new BehaviorSubject(relays) : relays;
+    }
+    /** Whether this group is controlled by an upstream observable */
+    get controlled() {
+        return this.relays$ instanceof BehaviorSubject === false;
+    }
+    /** Check if a relay is in the group */
+    has(relay) {
+        if (this.controlled)
+            throw new Error("This group was created with an observable, relays are not available");
+        if (typeof relay === "string")
+            return this.relays.some((r) => r.url === relay);
+        return this.relays.includes(relay);
+    }
+    /** Add a relay to the group */
+    add(relay) {
+        if (this.has(relay))
+            return;
+        this.relays$.next([...this.relays, relay]);
     }
-    /** Takes an array of observables and only emits EOSE when all observables have emitted EOSE */
-    mergeEOSE(requests, eventStore = new EventMemory()) {
-        // Create stream of events only
-        const events = merge(...requests).pipe(
-        // Ignore non event responses
+    /** Remove a relay from the group */
+    remove(relay) {
+        if (!this.has(relay))
+            return;
+        this.relays$.next(this.relays.filter((r) => r !== relay));
+    }
+    /** Internal logic for handling requests to multiple relays */
+    internalSubscription(project, eventOperator = identity) {
+        // Keep a cache of upstream observables for each relay
+        const upstream = new WeakMap();
+        // Subscribe to the group relays
+        const main = this.relays$.pipe(
+        // Every time they change switch to a new observable
+        // Using reverseSwitchMap to subscribe to the new relays before unsubscribing from the old ones
+        // This avoids sending duplicate REQ messages to the relays
+        reverseSwitchMap((relays) => {
+            const observables = [];
+            for (const relay of relays) {
+                // If an upstream observable exists for this relay, use it
+                if (upstream.has(relay)) {
+                    observables.push(upstream.get(relay));
+                    continue;
+                }
+                const observable = project(relay).pipe(
+                // Catch connection errors and return EOSE
+                catchError(() => of("EOSE")), 
+                // Map values into tuple of relay and value
+                map((value) => [relay, value]));
+                observables.push(observable);
+                upstream.set(relay, observable);
+            }
+            return merge(...observables);
+        }), 
+        // Only create one upstream subscription
+        share());
+        // Create an observable that only emits the events from the relays
+        const events = main.pipe(
+        // Pick the value from the tuple
+        map(([_, value]) => value), 
+        // Only return events
         onlyEvents(), 
-        // If an event store is provided, filter duplicate events
-        eventStore ? filterDuplicateEvents(eventStore) : identity);
-        // Create stream that emits EOSE when all relays have sent EOSE
-        const eose = merge(
-        // Create a new map of requests that only emits EOSE
-        ...requests.map((observable) => observable.pipe(completeOnEose(), ignoreElements()))).pipe(
+        // Add event operations
+        eventOperator);
+        // Create an observable that emits EOSE when all relays have sent EOSE
+        const eose = this.relays$.pipe(
+        // When the relays change, switch to a new observable
+        switchMap((relays) => 
+        // Subscribe to the events, and wait for EOSE from all relays
+        main.pipe(
+        // Only select EOSE messages
+        filter(([_, value]) => value === "EOSE"), 
+        // Track the relays that have sent EOSE
+        scan((received, [relay]) => [...received, relay], []), 
+        // Keep the observable open while there are relays that have not sent EOSE
+        takeWhile((received) => relays.some((r) => !received.includes(r))), 
+        // Ignore all values
+        ignoreElements(), 
         // When all relays have sent EOSE, emit EOSE
-        endWith("EOSE"));
-        return merge(events, eose);
+        endWith("EOSE"))));
+        return merge(events, eose).pipe(
+        // Ensure a single upstream
+        share());
+    }
+    /** Internal logic for handling publishes to multiple relays */
+    internalPublish(project) {
+        // Keep a cache of upstream observables for each relay
+        const upstream = new WeakMap();
+        // Subscribe to the group relays
+        return this.relays$.pipe(
+        // Take a snapshot of relays (no updates yet...)
+        take(1), 
+        // Every time they change switch to a new observable
+        switchMap((relays) => {
+            const observables = [];
+            for (const relay of relays) {
+                // If an upstream observable exists for this relay, use it
+                if (upstream.has(relay)) {
+                    observables.push(upstream.get(relay));
+                    continue;
+                }
+                // Create a new upstream observable for this relay
+                const observable = project(relay).pipe(
+                // Catch error and return as PublishResponse
+                errorToPublishResponse(relay));
+                observables.push(observable);
+                upstream.set(relay, observable);
+            }
+            return merge(...observables);
+        }), 
+        // Ensure a single upstream
+        share());
     }
     /**
      * Make a request to all relays
      * @note This does not deduplicate events
      */
-    req(filters, id = nanoid(8)) {
-        const requests = this.relays.map((relay) => relay.req(filters, id).pipe(
-        // Ignore connection errors
-        catchError(() => of("EOSE"))));
-        // Merge events and the single EOSE stream
-        return this.mergeEOSE(requests);
+    req(filters, id = nanoid(), opts) {
+        return this.internalSubscription((relay) => relay.req(filters, id), opts?.eventStore ? filterDuplicateEvents(opts?.eventStore) : identity);
     }
     /** Send an event to all relays */
     event(event) {
-        return merge(...this.relays.map((relay) => relay.event(event).pipe(
-        // Catch error and return as PublishResponse
-        catchError((err) => of({ ok: false, from: relay.url, message: err?.message || "Unknown error" })))));
+        return this.internalPublish((relay) => relay.event(event));
     }
     /** Negentropy sync events with the relays and an event store */
     async negentropy(store, filter, reconcile, opts) {
@@ -57,25 +155,29 @@ export class RelayGroup {
     }
     /** Publish an event to all relays with retries ( default 3 retries ) */
     publish(event, opts) {
-        return Promise.all(this.relays.map((relay) => relay.publish(event, opts).catch(
-        // Catch error and return as PublishResponse
-        (err) => ({ ok: false, from: relay.url, message: err?.message || "Unknown error" }))));
+        return lastValueFrom(this.internalPublish((relay) => from(relay.publish(event, opts))).pipe(toArray(), defaultIfEmpty([])));
     }
-    /** Request events from all relays with retries ( default 3 retries ) */
+    /** Request events from all relays and complete on EOSE */
     request(filters, opts) {
-        return merge(...this.relays.map((relay) => relay.request(filters, opts).pipe(
-        // Ignore individual connection errors
-        catchError(() => EMPTY)))).pipe(
+        return this.internalSubscription((relay) => relay.request(filters, opts).pipe(
+        // Simulate EOSE on completion
+        endWith("EOSE")), 
         // If an event store is provided, filter duplicate events
-        opts?.eventStore == null ? identity : filterDuplicateEvents(opts?.eventStore ?? new EventMemory()));
+        opts?.eventStore == null ? identity : filterDuplicateEvents(opts?.eventStore ?? new EventMemory())).pipe(
+        // Complete when all relays have sent EOSE
+        completeOnEose());
     }
     /** Open a subscription to all relays with retries ( default 3 retries ) */
     subscription(filters, opts) {
-        return this.mergeEOSE(this.relays.map((relay) => relay.subscription(filters, opts).pipe(
-        // Ignore individual connection errors
-        catchError(() => EMPTY))), 
-        // Pass event store so that duplicate events are removed
-        opts?.eventStore);
+        return this.internalSubscription((relay) => relay.subscription(filters, opts), 
+        // If an event store is provided, filter duplicate events
+        opts?.eventStore == null ? identity : filterDuplicateEvents(opts?.eventStore ?? new EventMemory()));
+    }
+    /** Count events on all relays in the group */
+    count(filters, id = nanoid()) {
+        return this.relays$.pipe(switchMap((relays) => combineLatest(Object.fromEntries(relays.map((relay) => [relay.url, relay.count(filters, id)])))), 
+        // Ensure a single upstream
+        share());
     }
     /** Negentropy sync events with the relays and an event store */
     sync(store, filter, direction) {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./group.js";
+export * from "./liveness.js";
 export * from "./pool.js";
 export * from "./relay.js";
 export * from "./types.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./group.js";
+export * from "./liveness.js";
 export * from "./pool.js";
 export * from "./relay.js";
 export * from "./types.js";

package/dist/liveness.d.ts

@@ -0,0 +1,123 @@
+import { Observable } from "rxjs";
+import { IPool } from "./types.js";
+/** Relay health states for liveness tracking */
+export type RelayHealthState = "online" | "offline" | "dead";
+/** State information for a relay's health tracking */
+export interface RelayState {
+    /** Current relay health state */
+    state: RelayHealthState;
+    /** Number of consecutive failures */
+    failureCount: number;
+    /** Timestamp of last failure */
+    lastFailureTime: number;
+    /** Timestamp of last success */
+    lastSuccessTime: number;
+    /** When the backoff period ends (timestamp) */
+    backoffUntil?: number;
+}
+/** Storage adapter interface for persisting relay liveness state */
+export interface LivenessStorage {
+    /**
+     * Get an item from storage
+     * @param key The storage key
+     * @returns The stored value or null if not found
+     */
+    getItem(key: string): Promise<any> | any;
+    /**
+     * Set an item in storage
+     * @param key The storage key
+     * @param value The value to store
+     */
+    setItem(key: string, value: any): Promise<void> | void;
+}
+/** Configuration options for RelayLiveness */
+export interface LivenessOptions {
+    /** Optional async storage adapter for persistence */
+    storage?: LivenessStorage;
+    /** Maximum failures before moving from offline to dead */
+    maxFailuresBeforeDead?: number;
+    /** Base delay for exponential backoff (ms) */
+    backoffBaseDelay?: number;
+    /** Maximum backoff delay (ms) */
+    backoffMaxDelay?: number;
+}
+/** Record and manage liveness reports for relays */
+export declare class RelayLiveness {
+    private log;
+    private readonly options;
+    private readonly states$;
+    /** Relays that have been seen this session. this should be used when checking dead relays for liveness */
+    readonly seen: Set<string>;
+    /** Storage adapter for persistence */
+    readonly storage?: LivenessStorage;
+    /** An observable of all relays that are online */
+    online$: Observable<string[]>;
+    /** An observable of all relays that are offline */
+    offline$: Observable<string[]>;
+    /** An observable of all relays that are dead */
+    dead$: Observable<string[]>;
+    /** An observable of all relays that are online or not in backoff */
+    healthy$: Observable<string[]>;
+    /** An observable of all relays that are dead or in backoff */
+    unhealthy$: Observable<string[]>;
+    /** Relays that are known to be online */
+    get online(): string[];
+    /** Relays that are known to be offline */
+    get offline(): string[];
+    /** Relays that are known to be dead */
+    get dead(): string[];
+    /** Relays that are online or not in backoff */
+    get healthy(): string[];
+    /** Relays that are dead or in backoff */
+    get unhealthy(): string[];
+    /**
+     * Create a new RelayLiveness instance
+     * @param options Configuration options for the liveness tracker
+     */
+    constructor(options?: LivenessOptions);
+    /** Load relay states from storage */
+    load(): Promise<void>;
+    /** Save all known relays and their states to storage */
+    save(): Promise<void>;
+    /** Filter relay list, removing dead relays and relays in backoff */
+    filter(relays: string[]): string[];
+    /** Subscribe to a relays state */
+    state(relay: string): Observable<RelayState | undefined>;
+    /** Revive a dead relay with the max backoff delay */
+    revive(relay: string): void;
+    /** Get current relay health state for a relay */
+    getState(relay: string): RelayState | undefined;
+    /** Check if a relay is currently in backoff period */
+    isInBackoff(relay: string): boolean;
+    /** Get remaining backoff time for a relay (in ms) */
+    getBackoffRemaining(relay: string): number;
+    /** Calculate backoff delay based on failure count */
+    private calculateBackoffDelay;
+    /**
+     * Record a successful connection
+     * @param relay The relay URL that succeeded
+     */
+    recordSuccess(relay: string): void;
+    /**
+     * Record a failed connection
+     * @param relay The relay URL that failed
+     */
+    recordFailure(relay: string): void;
+    /**
+     * Get all seen relays (for debugging/monitoring)
+     */
+    getSeenRelays(): string[];
+    /**
+     * Reset state for one or all relays
+     * @param relay Optional specific relay URL to reset, or reset all if not provided
+     */
+    reset(relay?: string): void;
+    private connections;
+    /** Connect to a {@link RelayPool} instance and track relay connections */
+    connectToPool(pool: IPool): void;
+    /** Disconnect from a {@link RelayPool} instance */
+    disconnectFromPool(pool: IPool): void;
+    private updateRelayState;
+    private saveKnownRelays;
+    private saveRelayState;
+}