applesauce-relay 4.0.0 → 4.2.0

package/dist/liveness.js

@@ -0,0 +1,327 @@
+import { logger } from "applesauce-core";
+import { BehaviorSubject, map } from "rxjs";
+/** Record and manage liveness reports for relays */
+export class RelayLiveness {
+    log = logger.extend("RelayLiveness");
+    options;
+    states$ = new BehaviorSubject({});
+    /** Relays that have been seen this session. this should be used when checking dead relays for liveness */
+    seen = new Set();
+    /** Storage adapter for persistence */
+    storage;
+    /** An observable of all relays that are online */
+    online$;
+    /** An observable of all relays that are offline */
+    offline$;
+    /** An observable of all relays that are dead */
+    dead$;
+    /** An observable of all relays that are online or not in backoff */
+    healthy$;
+    /** An observable of all relays that are dead or in backoff */
+    unhealthy$;
+    /** Relays that are known to be online */
+    get online() {
+        return Object.keys(this.states$.value).filter((relay) => this.states$.value[relay].state === "online");
+    }
+    /** Relays that are known to be offline */
+    get offline() {
+        return Object.keys(this.states$.value).filter((relay) => this.states$.value[relay].state === "offline");
+    }
+    /** Relays that are known to be dead */
+    get dead() {
+        return Object.keys(this.states$.value).filter((relay) => this.states$.value[relay].state === "dead");
+    }
+    /** Relays that are online or not in backoff */
+    get healthy() {
+        return Object.keys(this.states$.value).filter((relay) => {
+            const state = this.states$.value[relay];
+            return state.state === "online" || (state.state === "offline" && !this.isInBackoff(relay));
+        });
+    }
+    /** Relays that are dead or in backoff */
+    get unhealthy() {
+        return Object.keys(this.states$.value).filter((relay) => {
+            const state = this.states$.value[relay];
+            return state.state === "dead" || (state.state === "offline" && this.isInBackoff(relay));
+        });
+    }
+    /**
+     * Create a new RelayLiveness instance
+     * @param options Configuration options for the liveness tracker
+     */
+    constructor(options = {}) {
+        this.options = {
+            maxFailuresBeforeDead: options.maxFailuresBeforeDead ?? 5,
+            backoffBaseDelay: options.backoffBaseDelay ?? 30 * 1000, // 30 seconds
+            backoffMaxDelay: options.backoffMaxDelay ?? 5 * 60 * 1000, // 5 minutes
+        };
+        this.storage = options.storage;
+        // Create observable interfaces
+        this.online$ = this.states$.pipe(map((states) => Object.keys(states).filter((relay) => states[relay].state === "online")));
+        this.offline$ = this.states$.pipe(map((states) => Object.keys(states).filter((relay) => states[relay].state === "offline")));
+        this.dead$ = this.states$.pipe(map((states) => Object.keys(states).filter((relay) => states[relay].state === "dead")));
+        this.healthy$ = this.states$.pipe(map((states) => Object.keys(states).filter((relay) => {
+            const state = states[relay];
+            return state.state === "online" || (state.state === "offline" && !this.isInBackoff(relay));
+        })));
+        this.unhealthy$ = this.states$.pipe(map((states) => Object.keys(states).filter((relay) => {
+            const state = states[relay];
+            return state.state === "dead" || (state.state === "offline" && this.isInBackoff(relay));
+        })));
+    }
+    /** Load relay states from storage */
+    async load() {
+        if (!this.storage)
+            return;
+        const known = await this.storage.getItem("known");
+        if (!Array.isArray(known))
+            return;
+        this.log(`Loading states for ${known.length} known relays`);
+        const states = {};
+        for (const relay of known) {
+            try {
+                const state = await this.storage.getItem(relay);
+                if (state)
+                    states[relay] = state;
+            }
+            catch (error) {
+                // Ignore relay loading errors
+            }
+        }
+        this.states$.next(states);
+    }
+    /** Save all known relays and their states to storage */
+    async save() {
+        await this.saveKnownRelays();
+        await Promise.all(Object.entries(this.states$.value).map(([relay, state]) => this.saveRelayState(relay, state)));
+        this.log("Relay states saved to storage");
+    }
+    /** Filter relay list, removing dead relays and relays in backoff */
+    filter(relays) {
+        const results = [];
+        for (const relay of relays) {
+            // Track that this relay has been seen
+            this.seen.add(relay);
+            const state = this.getState(relay);
+            // Filter based on state and backoff
+            switch (state?.state) {
+                case undefined: // unknown state
+                case "online":
+                    results.push(relay);
+                    break;
+                case "offline":
+                    // Only include if not in backoff
+                    if (!this.isInBackoff(relay))
+                        results.push(relay);
+                    break;
+                case "dead":
+                default:
+                    // Don't include dead relays
+                    break;
+            }
+        }
+        return results;
+    }
+    /** Subscribe to a relays state */
+    state(relay) {
+        return this.states$.pipe(map((states) => states[relay]));
+    }
+    /** Revive a dead relay with the max backoff delay */
+    revive(relay) {
+        const state = this.getState(relay);
+        if (!state)
+            return;
+        this.updateRelayState(relay, {
+            state: "offline",
+            failureCount: 0,
+            lastFailureTime: 0,
+            lastSuccessTime: Date.now(),
+            backoffUntil: this.options.backoffMaxDelay,
+        });
+        this.log(`Relay ${relay} revived to offline state with max backoff delay`);
+    }
+    /** Get current relay health state for a relay */
+    getState(relay) {
+        return this.states$.value[relay];
+    }
+    /** Check if a relay is currently in backoff period */
+    isInBackoff(relay) {
+        const state = this.getState(relay);
+        if (!state?.backoffUntil)
+            return false;
+        return Date.now() < state.backoffUntil;
+    }
+    /** Get remaining backoff time for a relay (in ms) */
+    getBackoffRemaining(relay) {
+        const state = this.getState(relay);
+        if (!state?.backoffUntil)
+            return 0;
+        return Math.max(0, state.backoffUntil - Date.now());
+    }
+    /** Calculate backoff delay based on failure count */
+    calculateBackoffDelay(failureCount) {
+        const delay = this.options.backoffBaseDelay * Math.pow(2, failureCount - 1);
+        return Math.min(delay, this.options.backoffMaxDelay);
+    }
+    /**
+     * Record a successful connection
+     * @param relay The relay URL that succeeded
+     */
+    recordSuccess(relay) {
+        const now = Date.now();
+        const state = this.getState(relay);
+        // Don't update dead relays
+        if (state?.state === "dead") {
+            this.log(`Ignoring success for dead relay ${relay}`);
+            return;
+        }
+        // Record new relays
+        if (state === undefined) {
+            this.seen.add(relay);
+            this.saveKnownRelays();
+        }
+        // TODO: resetting the state back to online might be too aggressive?
+        const newState = {
+            state: "online",
+            failureCount: 0,
+            lastFailureTime: 0,
+            lastSuccessTime: now,
+        };
+        this.updateRelayState(relay, newState);
+        // Log transition if it's not the first time we've seen the relay
+        if (state && state.state !== newState.state)
+            this.log(`Relay ${relay} transitioned ${state?.state} -> online`);
+    }
+    /**
+     * Record a failed connection
+     * @param relay The relay URL that failed
+     */
+    recordFailure(relay) {
+        const state = this.getState(relay);
+        // Don't update dead relays
+        if (state?.state === "dead")
+            return;
+        // Ignore failures during backoff, this should help catch double reporting of failures
+        if (this.isInBackoff(relay))
+            return;
+        const now = Date.now();
+        const failureCount = (state?.failureCount || 0) + 1;
+        // Record new relays
+        if (state === undefined) {
+            this.seen.add(relay);
+            this.saveKnownRelays();
+        }
+        // Calculate backoff delay
+        const backoffDelay = this.calculateBackoffDelay(failureCount);
+        const newState = failureCount >= this.options.maxFailuresBeforeDead ? "dead" : "offline";
+        const relayState = {
+            state: newState,
+            failureCount,
+            lastFailureTime: now,
+            lastSuccessTime: state?.lastSuccessTime || 0,
+            backoffUntil: now + backoffDelay,
+        };
+        this.updateRelayState(relay, relayState);
+        // Log transition if it's not the first time we've seen the relay
+        if (newState !== state?.state)
+            this.log(`Relay ${relay} transitioned ${state?.state} -> ${newState}`);
+        // Set a timeout that will clear the backoff period
+        setTimeout(() => {
+            const state = this.getState(relay);
+            if (!state || state.backoffUntil === undefined)
+                return;
+            this.updateRelayState(relay, { ...state, backoffUntil: undefined });
+        }, backoffDelay);
+    }
+    /**
+     * Get all seen relays (for debugging/monitoring)
+     */
+    getSeenRelays() {
+        return Array.from(this.seen);
+    }
+    /**
+     * Reset state for one or all relays
+     * @param relay Optional specific relay URL to reset, or reset all if not provided
+     */
+    reset(relay) {
+        if (relay) {
+            const newStates = { ...this.states$.value };
+            delete newStates[relay];
+            this.states$.next(newStates);
+            this.seen.delete(relay);
+        }
+        else {
+            // Reset all relays
+            this.states$.next({});
+            this.seen.clear();
+        }
+    }
+    // The connected pools and cleanup methods
+    connections = new Map();
+    /** Connect to a {@link RelayPool} instance and track relay connections */
+    connectToPool(pool) {
+        // Relay cleanup methods
+        const relays = new Map();
+        // Listen for relays being added
+        const add = pool.add$.subscribe((relay) => {
+            // Record seen relays
+            this.seen.add(relay.url);
+            const open = relay.open$.subscribe(() => {
+                this.recordSuccess(relay.url);
+            });
+            const close = relay.close$.subscribe((event) => {
+                if (event.wasClean === false)
+                    this.recordFailure(relay.url);
+            });
+            // Register the cleanup method
+            relays.set(relay, () => {
+                open.unsubscribe();
+                close.unsubscribe();
+            });
+        });
+        // Listen for relays being removed
+        const remove = pool.remove$.subscribe((relay) => {
+            const cleanup = relays.get(relay);
+            if (cleanup)
+                cleanup();
+            relays.delete(relay);
+        });
+        // register the cleanup method
+        this.connections.set(pool, () => {
+            add.unsubscribe();
+            remove.unsubscribe();
+        });
+    }
+    /** Disconnect from a {@link RelayPool} instance */
+    disconnectFromPool(pool) {
+        const cleanup = this.connections.get(pool);
+        if (cleanup)
+            cleanup();
+        this.connections.delete(pool);
+    }
+    updateRelayState(relay, state) {
+        this.states$.next({ ...this.states$.value, [relay]: state });
+        // Auto-save to storage
+        this.saveRelayState(relay, state);
+    }
+    async saveKnownRelays() {
+        if (!this.storage)
+            return;
+        try {
+            await this.storage.setItem("known", Object.keys(this.states$.value));
+        }
+        catch (error) {
+            // Ignore storage errors
+        }
+    }
+    async saveRelayState(relay, state) {
+        if (!this.storage)
+            return;
+        try {
+            await this.storage.setItem(relay, state);
+        }
+        catch (error) {
+            // Ignore storage errors
+        }
+    }
+}

package/dist/negentropy.js

@@ -1,5 +1,5 @@
 import { logger } from "applesauce-core";
-import { map, share, firstValueFrom } from "rxjs";
+import { map, share, firstValueFrom, race, Observable } from "rxjs";
 import { nanoid } from "nanoid";
 import { Negentropy, NegentropyStorageVector } from "./lib/negentropy.js";
 const log = logger.extend("negentropy");
@@ -52,16 +52,49 @@ export async function negentropySync(storage, socket, filter, reconcile, opts) {
             throw new Error(msg[2]);
         return msg[2];
     }), share());
+    // Check if already aborted before starting sync
+    if (opts?.signal?.aborted)
+        return false;
+    // Create an observable that emits when abort signal is triggered
+    const abortSignal$ = new Observable((observer) => {
+        if (opts?.signal?.aborted) {
+            observer.next("abort");
+            observer.complete();
+            return;
+        }
+        const onAbort = () => {
+            observer.next("abort");
+            observer.complete();
+        };
+        opts?.signal?.addEventListener("abort", onAbort);
+        return () => opts?.signal?.removeEventListener("abort", onAbort);
+    });
     // keep an additional subscription open while waiting for async operations
-    const sub = incoming.subscribe((m) => log(m));
+    const sub = incoming.subscribe({
+        next: (m) => log(m),
+        error: () => { }, // Ignore errors here, they'll be caught by firstValueFrom
+    });
     try {
         while (msg && opts?.signal?.aborted !== true) {
-            const received = await firstValueFrom(incoming);
-            if (opts?.signal?.aborted)
-                return false;
-            const [newMsg, have, need] = await ne.reconcile(received);
-            await reconcile(have, need);
-            msg = newMsg;
+            // Race between incoming message and abort signal
+            try {
+                const received = await firstValueFrom(race(incoming.pipe(map((m) => ({ type: "message", data: m }))), abortSignal$.pipe(map(() => ({ type: "abort" })))));
+                if (received.type === "abort" || opts?.signal?.aborted) {
+                    sub.unsubscribe();
+                    return false;
+                }
+                const [newMsg, have, need] = await ne.reconcile(received.data);
+                await reconcile(have, need);
+                msg = newMsg;
+            }
+            catch (err) {
+                // Check if aborted during reconcile or message processing
+                if (opts?.signal?.aborted) {
+                    sub.unsubscribe();
+                    return false;
+                }
+                throw err;
+            }
         }
     }
     catch (err) {

package/dist/operators/index.d.ts

@@ -1,5 +1,7 @@
 export * from "./complete-on-eose.js";
+export * from "./liveness.js";
 export * from "./mark-from-relay.js";
 export * from "./only-events.js";
+export * from "./reverse-switch-map.js";
 export * from "./store-events.js";
 export * from "./to-event-store.js";

package/dist/operators/index.js

@@ -1,5 +1,7 @@
 export * from "./complete-on-eose.js";
+export * from "./liveness.js";
 export * from "./mark-from-relay.js";
 export * from "./only-events.js";
+export * from "./reverse-switch-map.js";
 export * from "./store-events.js";
 export * from "./to-event-store.js";

package/dist/operators/liveness.d.ts

@@ -0,0 +1,17 @@
+import { MonoTypeOperatorFunction, Observable } from "rxjs";
+type ILivenessTracker = {
+    unhealthy$: Observable<string[]>;
+    seen?: Set<string>;
+};
+/** Filters out unhealthy relays from an array of pointers */
+export declare function ignoreUnhealthyRelaysOnPointers<T extends {
+    relays?: string[];
+}, Tracker extends ILivenessTracker>(liveness: Tracker): MonoTypeOperatorFunction<T[]>;
+/** Filters out unhealthy relays from the inboxes and outboxes */
+export declare function ignoreUnhealthyMailboxes<T extends {
+    inboxes?: string[];
+    outboxes?: string[];
+}, Tracker extends ILivenessTracker>(liveness: Tracker): MonoTypeOperatorFunction<T>;
+/** Filters out unhealthy relays from an array of relays */
+export declare function ignoreUnhealthyRelays<Tracker extends ILivenessTracker>(liveness: Tracker): MonoTypeOperatorFunction<string[]>;
+export {};

package/dist/operators/liveness.js

@@ -0,0 +1,47 @@
+import { combineLatestWith, map } from "rxjs";
+function filterRelays(relays, unhealthy, liveness) {
+    return (relays &&
+        relays.filter((relay) => {
+            // Notify the liveness tracker that we've seen this relay
+            liveness.seen?.add(relay);
+            // Exclude unhealthy relays
+            return !unhealthy.includes(relay);
+        }));
+}
+/** Filters out unhealthy relays from an array of pointers */
+export function ignoreUnhealthyRelaysOnPointers(liveness) {
+    return (source) => source.pipe(
+    // Combine with the liveness observable
+    combineLatestWith(liveness.unhealthy$), 
+    // Filters out unhealthy relays from the pointers
+    map(([pointers, unhealthy]) => pointers.map((pointer) => {
+        if (!pointer.relays)
+            return pointer;
+        // Exclude unhealthy relays
+        return { ...pointer, relays: filterRelays(pointer.relays, unhealthy, liveness) };
+    })));
+}
+/** Filters out unhealthy relays from the inboxes and outboxes */
+export function ignoreUnhealthyMailboxes(liveness) {
+    return (source) => source.pipe(
+    // Combine with the liveness observable
+    combineLatestWith(liveness.unhealthy$), 
+    // Filters out unhealthy relays from the inboxes and outboxes
+    map(([mailboxes, unhealthy]) => {
+        if (!mailboxes.inboxes && !mailboxes.outboxes)
+            return mailboxes;
+        return {
+            ...mailboxes,
+            inboxes: filterRelays(mailboxes.inboxes, unhealthy, liveness),
+            outboxes: filterRelays(mailboxes.outboxes, unhealthy, liveness),
+        };
+    }));
+}
+/** Filters out unhealthy relays from an array of relays */
+export function ignoreUnhealthyRelays(liveness) {
+    return (source) => source.pipe(
+    // Combine with the liveness observable
+    combineLatestWith(liveness.unhealthy$), 
+    // Filters out unhealthy relays from the array
+    map(([relays, unhealthy]) => filterRelays(relays, unhealthy, liveness)));
+}

package/dist/operators/reverse-switch-map.d.ts

@@ -0,0 +1,9 @@
+import { OperatorFunction, ObservableInput, ObservedValueOf } from "rxjs";
+/**
+ * Like switchMap, but subscribes to the new observable before unsubscribing from the old one.
+ * This prevents gaps in subscription coverage.
+ *
+ * @param project A function that, when applied to an item emitted by the source Observable,
+ * returns an Observable.
+ */
+export declare function reverseSwitchMap<T, O extends ObservableInput<any>>(project: (value: T, index: number) => O): OperatorFunction<T, ObservedValueOf<O>>;

package/dist/operators/reverse-switch-map.js

@@ -0,0 +1,46 @@
+import { from } from "rxjs";
+import { createOperatorSubscriber } from "rxjs/internal/operators/OperatorSubscriber";
+import { operate } from "rxjs/internal/util/lift";
+/**
+ * Like switchMap, but subscribes to the new observable before unsubscribing from the old one.
+ * This prevents gaps in subscription coverage.
+ *
+ * @param project A function that, when applied to an item emitted by the source Observable,
+ * returns an Observable.
+ */
+export function reverseSwitchMap(project) {
+    return operate((source, subscriber) => {
+        let innerSubscriber = null;
+        let index = 0;
+        // Whether or not the source subscription has completed
+        let isComplete = false;
+        // We only complete the result if the source is complete AND we don't have an active inner subscription.
+        // This is called both when the source completes and when the inners complete.
+        const checkComplete = () => {
+            if (isComplete && !innerSubscriber)
+                subscriber.complete();
+        };
+        source.subscribe(createOperatorSubscriber(subscriber, (value) => {
+            const outerIndex = index++;
+            const oldSubscriber = innerSubscriber;
+            // Create the new inner subscription FIRST
+            // Immediately assign the new subscriber because observables can emit and complete synchronously
+            const self = (innerSubscriber = createOperatorSubscriber(subscriber, (innerValue) => subscriber.next(innerValue), () => {
+                // The inner has completed. Null out the inner subscriber to
+                // free up memory and to signal that we have no inner subscription
+                // currently. Only do this if this is still the active inner subscriber.
+                if (innerSubscriber === self || innerSubscriber === null) {
+                    innerSubscriber = null;
+                    checkComplete();
+                }
+            }));
+            // Subscribe to the new observable FIRST
+            from(project(value, outerIndex)).subscribe(innerSubscriber);
+            // THEN unsubscribe from the previous inner subscription
+            oldSubscriber?.unsubscribe();
+        }, () => {
+            isComplete = true;
+            checkComplete();
+        }));
+    });
+}

package/dist/pool.d.ts

@@ -1,42 +1,44 @@
 import type { IAsyncEventStoreRead, IEventStoreRead } from "applesauce-core";
+import { FilterMap, OutboxMap } from "applesauce-core/helpers";
 import { Filter, type NostrEvent } from "nostr-tools";
 import { BehaviorSubject, Observable, Subject } from "rxjs";
 import { RelayGroup } from "./group.js";
 import type { NegentropySyncOptions, ReconcileFunction } from "./negentropy.js";
 import { Relay, SyncDirection, type RelayOptions } from "./relay.js";
-import type { FilterInput, IPool, IRelay, PublishResponse, SubscriptionResponse } from "./types.js";
+import type { CountResponse, FilterInput, IPool, IPoolRelayInput, IRelay, PublishResponse, SubscriptionResponse } from "./types.js";
 export declare class RelayPool implements IPool {
     options?: RelayOptions | undefined;
-    groups$: BehaviorSubject<Map<string, RelayGroup>>;
-    get groups(): Map<string, RelayGroup>;
     relays$: BehaviorSubject<Map<string, Relay>>;
     get relays(): Map<string, Relay>;
     /** A signal when a relay is added */
     add$: Subject<IRelay>;
     /** A signal when a relay is removed */
     remove$: Subject<IRelay>;
-    /** An array of relays to never connect to */
-    blacklist: Set<string>;
     constructor(options?: RelayOptions | undefined);
-    protected filterBlacklist(urls: string[]): string[];
     /** Get or create a new relay connection */
     relay(url: string): Relay;
     /** Create a group of relays */
-    group(relays: string[]): RelayGroup;
+    group(relays: IPoolRelayInput): RelayGroup;
     /** Removes a relay from the pool and defaults to closing the connection */
     remove(relay: string | IRelay, close?: boolean): void;
     /** Make a REQ to multiple relays that does not deduplicate events */
-    req(relays: string[], filters: FilterInput, id?: string): Observable<SubscriptionResponse>;
+    req(relays: IPoolRelayInput, filters: FilterInput, id?: string): Observable<SubscriptionResponse>;
     /** Send an EVENT message to multiple relays */
-    event(relays: string[], event: NostrEvent): Observable<PublishResponse>;
+    event(relays: IPoolRelayInput, event: NostrEvent): Observable<PublishResponse>;
     /** Negentropy sync event ids with the relays and an event store */
-    negentropy(relays: string[], store: IEventStoreRead | IAsyncEventStoreRead | NostrEvent[], filter: Filter, reconcile: ReconcileFunction, opts?: NegentropySyncOptions): Promise<boolean>;
+    negentropy(relays: IPoolRelayInput, store: IEventStoreRead | IAsyncEventStoreRead | NostrEvent[], filter: Filter, reconcile: ReconcileFunction, opts?: NegentropySyncOptions): Promise<boolean>;
     /** Publish an event to multiple relays */
-    publish(relays: string[], event: Parameters<RelayGroup["publish"]>[0], opts?: Parameters<RelayGroup["publish"]>[1]): Promise<PublishResponse[]>;
+    publish(relays: IPoolRelayInput, event: Parameters<RelayGroup["publish"]>[0], opts?: Parameters<RelayGroup["publish"]>[1]): Promise<PublishResponse[]>;
     /** Request events from multiple relays */
-    request(relays: string[], filters: Parameters<RelayGroup["request"]>[0], opts?: Parameters<RelayGroup["request"]>[1]): Observable<NostrEvent>;
+    request(relays: IPoolRelayInput, filters: FilterInput, opts?: Parameters<RelayGroup["request"]>[1]): Observable<NostrEvent>;
     /** Open a subscription to multiple relays */
-    subscription(relays: string[], filters: Parameters<RelayGroup["subscription"]>[0], options?: Parameters<RelayGroup["subscription"]>[1]): Observable<SubscriptionResponse>;
+    subscription(relays: IPoolRelayInput, filters: FilterInput, options?: Parameters<RelayGroup["subscription"]>[1]): Observable<SubscriptionResponse>;
+    /** Open a subscription for a map of relays and filters */
+    subscriptionMap(relays: FilterMap | Observable<FilterMap>, options?: Parameters<RelayGroup["subscription"]>[1]): Observable<SubscriptionResponse>;
+    /** Open a subscription for an {@link OutboxMap} and filter */
+    outboxSubscription(outboxes: OutboxMap | Observable<OutboxMap>, filter: Omit<Filter, "authors">, options?: Parameters<RelayGroup["subscription"]>[1]): Observable<SubscriptionResponse>;
+    /** Count events on multiple relays */
+    count(relays: IPoolRelayInput, filters: Filter | Filter[], id?: string): Observable<Record<string, CountResponse>>;
     /** Negentropy sync events with the relays and an event store */
-    sync(relays: string[], store: IEventStoreRead | IAsyncEventStoreRead | NostrEvent[], filter: Filter, direction?: SyncDirection): Observable<NostrEvent>;
+    sync(relays: IPoolRelayInput, store: IEventStoreRead | IAsyncEventStoreRead | NostrEvent[], filter: Filter, direction?: SyncDirection): Observable<NostrEvent>;
 }