applesauce-relay 0.0.0-next-20260116173453 → 0.0.0-next-20260120162357

package/README.md

@@ -22,7 +22,7 @@ npm install applesauce-relay
 
 ## Examples
 
-Read the [documentation](https://hzrd149.github.io/applesauce/overview/relays.html) for more detailed explanation of all methods
+Read the [documentation](https://applesauce.build/overview/relays.html) for more detailed explanation of all methods
 
 ### Single Relay
 

package/dist/group.d.ts

@@ -3,7 +3,7 @@ import type { Filter, NostrEvent } from "applesauce-core/helpers";
 import { BehaviorSubject, MonoTypeOperatorFunction, Observable } from "rxjs";
 import { NegentropySyncOptions, type ReconcileFunction } from "./negentropy.js";
 import { SyncDirection } from "./relay.js";
-import { CountResponse, FilterInput, IGroup, IGroupRelayInput, IRelay, NegentropyReadStore, NegentropySyncStore, PublishOptions, PublishResponse, RequestOptions, SubscriptionOptions, SubscriptionResponse } from "./types.js";
+import { CountResponse, FilterInput, IGroup, IGroupRelayInput, IRelay, NegentropyReadStore, NegentropySyncStore, PublishOptions, PublishResponse, RelayStatus, 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) */
@@ -21,6 +21,8 @@ export type GroupRequestOptions = RequestOptions & {
 };
 export declare class RelayGroup implements IGroup {
     protected relays$: BehaviorSubject<IRelay[]> | Observable<IRelay[]>;
+    /** Observable of relay status for all relays in the group */
+    status$: Observable<Record<string, RelayStatus>>;
     get relays(): IRelay[];
     constructor(relays: IGroupRelayInput);
     /** Whether this group is controlled by an upstream observable */

package/dist/group.js

@@ -1,7 +1,7 @@
 import { EventMemory } from "applesauce-core/event-store";
 import { filterDuplicateEvents } from "applesauce-core/observable";
 import { nanoid } from "nanoid";
-import { BehaviorSubject, catchError, combineLatest, defaultIfEmpty, defer, endWith, filter, from, identity, ignoreElements, lastValueFrom, map, merge, of, scan, share, switchMap, take, takeWhile, toArray, } from "rxjs";
+import { BehaviorSubject, catchError, combineLatest, defaultIfEmpty, defer, endWith, filter, from, identity, ignoreElements, lastValueFrom, map, merge, of, scan, share, shareReplay, startWith, switchMap, take, takeWhile, toArray, } from "rxjs";
 import { completeOnEose } from "./operators/complete-on-eose.js";
 import { onlyEvents } from "./operators/only-events.js";
 import { reverseSwitchMap } from "./operators/reverse-switch-map.js";
@@ -11,6 +11,8 @@ function errorToPublishResponse(relay) {
 }
 export class RelayGroup {
     relays$ = new BehaviorSubject([]);
+    /** Observable of relay status for all relays in the group */
+    status$;
     get relays() {
         if (this.relays$ instanceof BehaviorSubject)
             return this.relays$.value;
@@ -18,6 +20,23 @@ export class RelayGroup {
     }
     constructor(relays) {
         this.relays$ = Array.isArray(relays) ? new BehaviorSubject(relays) : relays;
+        // Initialize status$ observable
+        this.status$ = this.relays$.pipe(switchMap((relays) => {
+            // If no relays, return empty record
+            if (relays.length === 0)
+                return of({});
+            // Merge all relay status streams
+            return merge(...relays.map((relay) => relay.status$)).pipe(
+            // Accumulate into a Record
+            scan((acc, status) => ({
+                ...acc,
+                [status.url]: status,
+            }), {}), 
+            // Start with initial empty state
+            startWith({}));
+        }), 
+        // Share the subscription
+        shareReplay(1));
     }
     /** Whether this group is controlled by an upstream observable */
     get controlled() {

package/dist/pool.d.ts

@@ -5,11 +5,13 @@ 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 { CountResponse, FilterInput, IPool, IPoolRelayInput, IRelay, NegentropyReadStore, NegentropySyncStore, PublishResponse, SubscriptionResponse } from "./types.js";
+import type { CountResponse, FilterInput, IPool, IPoolRelayInput, IRelay, NegentropyReadStore, NegentropySyncStore, PublishResponse, RelayStatus, SubscriptionResponse } from "./types.js";
 export declare class RelayPool implements IPool {
     options?: RelayOptions | undefined;
     relays$: BehaviorSubject<Map<string, Relay>>;
     get relays(): Map<string, Relay>;
+    /** Observable of relay status for all relays in the pool */
+    status$: Observable<Record<string, RelayStatus>>;
     /** Whether to ignore relays that are ready=false */
     ignoreOffline: boolean;
     /** A signal when a relay is added */

package/dist/pool.js

@@ -1,7 +1,7 @@
 import { isFilterEqual } from "applesauce-core/helpers/filter";
 import { createFilterMap } from "applesauce-core/helpers/relay-selection";
 import { normalizeURL } from "applesauce-core/helpers/url";
-import { BehaviorSubject, distinctUntilChanged, isObservable, map, of, Subject } from "rxjs";
+import { BehaviorSubject, distinctUntilChanged, isObservable, map, merge, of, scan, shareReplay, startWith, Subject, switchMap, } from "rxjs";
 import { RelayGroup } from "./group.js";
 import { Relay } from "./relay.js";
 export class RelayPool {
@@ -10,6 +10,8 @@ export class RelayPool {
     get relays() {
         return this.relays$.value;
     }
+    /** Observable of relay status for all relays in the pool */
+    status$;
     /** Whether to ignore relays that are ready=false */
     ignoreOffline = true;
     /** A signal when a relay is added */
@@ -18,6 +20,19 @@ export class RelayPool {
     remove$ = new Subject();
     constructor(options) {
         this.options = options;
+        // Initialize status$ observable
+        this.status$ = this.relays$.pipe(
+        // Convert Map to array of relays
+        map((relayMap) => Array.from(relayMap.values())), 
+        // Use same pattern as RelayGroup
+        switchMap((relays) => {
+            if (relays.length === 0)
+                return of({});
+            return merge(...relays.map((relay) => relay.status$)).pipe(scan((acc, status) => ({
+                ...acc,
+                [status.url]: status,
+            }), {}), startWith({}));
+        }), shareReplay(1));
     }
     /** Get or create a new relay connection */
     relay(url) {

package/dist/relay.d.ts

@@ -1,10 +1,10 @@
 import { logger } from "applesauce-core";
-import { NostrEvent } from "applesauce-core/helpers/event";
+import { KnownEvent, NostrEvent } from "applesauce-core/helpers/event";
 import { Filter } from "applesauce-core/helpers/filter";
 import { BehaviorSubject, MonoTypeOperatorFunction, Observable, RepeatConfig, RetryConfig, Subject } from "rxjs";
 import { WebSocketSubject, WebSocketSubjectConfig } from "rxjs/webSocket";
 import { type NegentropySyncOptions, type ReconcileFunction } from "./negentropy.js";
-import { AuthSigner, CountResponse, FilterInput, IRelay, NegentropyReadStore, NegentropySyncStore, PublishOptions, PublishResponse, RelayInformation, RequestOptions, SubscriptionOptions, SubscriptionResponse } from "./types.js";
+import { AuthSigner, CountResponse, FilterInput, IRelay, NegentropyReadStore, NegentropySyncStore, PublishOptions, PublishResponse, RelayInformation, RelayStatus, RequestOptions, SubscriptionOptions, SubscriptionResponse } from "./types.js";
 /** Flags for the negentropy sync type */
 export declare enum SyncDirection {
     RECEIVE = 1,
@@ -31,6 +31,13 @@ export type RelayOptions = {
     pingFrequency?: number;
     /** How long to wait for EOSE response in milliseconds (default 20000) */
     pingTimeout?: number;
+    /** Policy for handling unresponsive connections (default: reconnect) */
+    onUnresponsive?: (info: {
+        url: string;
+        lastMessageAt: number;
+        now: number;
+        attempts: number;
+    }) => "reconnect" | "close" | "ignore";
     /** Default retry config for subscription() method */
     subscriptionRetry?: RetryConfig;
     /** Default retry config for request() method */
@@ -56,6 +63,10 @@ export declare class Relay implements IRelay {
     challenge$: BehaviorSubject<string | null>;
     /** Boolean authentication state (will be false if auth failed) */
     authenticated$: Observable<boolean>;
+    /** The pubkey of the authenticated user, or null if not authenticated */
+    authenticatedAs$: Observable<string | null>;
+    /** The authentication event sent to the relay */
+    authentication$: BehaviorSubject<KnownEvent<22242> | null>;
     /** The response to the last AUTH message sent to the relay */
     authenticationResponse$: BehaviorSubject<PublishResponse | null>;
     /** The notices from the relay */
@@ -74,6 +85,11 @@ export declare class Relay implements IRelay {
     notice$: Observable<string>;
     /** Timestamp of the last message received from the relay */
     private lastMessageReceivedAt;
+    /** Observable of the timestamp when last message was received */
+    private _lastMessageAt$;
+    lastMessageAt$: Observable<number>;
+    /** Observable of relay status (connection, authentication, and ready state) */
+    status$: Observable<RelayStatus>;
     /** An observable that emits the NIP-11 information document for the relay */
     information$: Observable<RelayInformation | null>;
     protected _nip11: RelayInformation | null;
@@ -89,13 +105,19 @@ export declare class Relay implements IRelay {
     close$: Subject<CloseEvent>;
     /** An observable that emits when underlying websocket is closing due to unsubscription */
     closing$: Subject<void>;
+    /** Tracks active req() operations by subscription ID */
+    reqs$: BehaviorSubject<Record<string, Filter[]>>;
     get ready(): boolean;
     get connected(): boolean;
     get challenge(): string | null;
     get notices(): string[];
     get authenticated(): boolean;
+    get authentication(): KnownEvent<22242> | null;
+    get authenticatedAs(): string | null;
     get authenticationResponse(): PublishResponse | null;
     get information(): RelayInformation | null;
+    get lastMessageAt(): number;
+    get reqs(): Record<string, Filter[]>;
     /** If an EOSE message is not seen in this time, emit one locally (default 10s)  */
     eoseTimeout: number;
     /** How long to wait for an OK message from the relay (default 10s) */
@@ -116,6 +138,8 @@ export declare class Relay implements IRelay {
     protected requestReconnect: RetryConfig;
     /** Default retry config for publish() method */
     protected publishRetry: RetryConfig;
+    /** Policy hook for unresponsive connections */
+    protected onUnresponsive?: RelayOptions["onUnresponsive"];
     protected receivedAuthRequiredForReq: BehaviorSubject<boolean>;
     protected receivedAuthRequiredForEvent: BehaviorSubject<boolean>;
     authRequiredForRead$: Observable<boolean>;

package/dist/relay.js

@@ -47,6 +47,10 @@ export class Relay {
     challenge$ = new BehaviorSubject(null);
     /** Boolean authentication state (will be false if auth failed) */
     authenticated$;
+    /** The pubkey of the authenticated user, or null if not authenticated */
+    authenticatedAs$;
+    /** The authentication event sent to the relay */
+    authentication$ = new BehaviorSubject(null);
     /** The response to the last AUTH message sent to the relay */
     authenticationResponse$ = new BehaviorSubject(null);
     /** The notices from the relay */
@@ -65,6 +69,11 @@ export class Relay {
     notice$;
     /** Timestamp of the last message received from the relay */
     lastMessageReceivedAt = 0;
+    /** Observable of the timestamp when last message was received */
+    _lastMessageAt$ = new BehaviorSubject(0);
+    lastMessageAt$ = this._lastMessageAt$.asObservable();
+    /** Observable of relay status (connection, authentication, and ready state) */
+    status$;
     /** An observable that emits the NIP-11 information document for the relay */
     information$;
     _nip11 = null;
@@ -80,6 +89,8 @@ export class Relay {
     close$ = new Subject();
     /** An observable that emits when underlying websocket is closing due to unsubscription */
     closing$ = new Subject();
+    /** Tracks active req() operations by subscription ID */
+    reqs$ = new BehaviorSubject({});
     // sync state
     get ready() {
         return this._ready$.value;
@@ -96,12 +107,24 @@ export class Relay {
     get authenticated() {
         return this.authenticationResponse?.ok === true;
     }
+    get authentication() {
+        return this.authentication$.value;
+    }
+    get authenticatedAs() {
+        return this.authenticated ? (this.authentication?.pubkey ?? null) : null;
+    }
     get authenticationResponse() {
         return this.authenticationResponse$.value;
     }
     get information() {
         return this._nip11;
     }
+    get lastMessageAt() {
+        return this._lastMessageAt$.value;
+    }
+    get reqs() {
+        return this.reqs$.value;
+    }
     /** If an EOSE message is not seen in this time, emit one locally (default 10s)  */
     eoseTimeout = 10_000;
     /** How long to wait for an OK message from the relay (default 10s) */
@@ -122,6 +145,8 @@ export class Relay {
     requestReconnect;
     /** Default retry config for publish() method */
     publishRetry;
+    /** Policy hook for unresponsive connections */
+    onUnresponsive;
     // Subjects that track if an "auth-required" message has been received for REQ or EVENT
     receivedAuthRequiredForReq = new BehaviorSubject(false);
     receivedAuthRequiredForEvent = new BehaviorSubject(false);
@@ -134,6 +159,8 @@ export class Relay {
             this.challenge$.next(null);
         if (this.authenticationResponse$.value)
             this.authenticationResponse$.next(null);
+        if (this.authentication$.value !== null)
+            this.authentication$.next(null);
         if (this.notices$.value.length > 0)
             this.notices$.next([]);
         if (this.receivedAuthRequiredForReq.value)
@@ -161,12 +188,16 @@ export class Relay {
             this.pingFrequency = opts.pingFrequency;
         if (opts?.pingTimeout !== undefined)
             this.pingTimeout = opts.pingTimeout;
+        if (opts?.onUnresponsive !== undefined)
+            this.onUnresponsive = opts.onUnresponsive;
         // Set retry configs
         this.subscriptionReconnect = { ...DEFAULT_RETRY_CONFIG, ...(opts?.subscriptionRetry ?? {}) };
         this.requestReconnect = { ...DEFAULT_RETRY_CONFIG, ...(opts?.requestRetry ?? {}) };
         this.publishRetry = { ...DEFAULT_RETRY_CONFIG, ...(opts?.publishRetry ?? {}) };
         // Create an observable that tracks boolean authentication state
         this.authenticated$ = this.authenticationResponse$.pipe(map((response) => response?.ok === true));
+        // Create an observable that returns the pubkey when authenticated, or null otherwise
+        this.authenticatedAs$ = combineLatest([this.authenticated$, this.authentication$]).pipe(map(([authenticated, authEvent]) => (authenticated && authEvent ? authEvent.pubkey : null)));
         /** Use the static method to create a new reconnect method for this relay */
         this.reconnectTimer = Relay.createReconnectTimer(url);
         // Subscribe to open and close events
@@ -225,6 +256,16 @@ export class Relay {
         this.authRequiredForPublish$
             .pipe(filter((r) => r === true), take(1))
             .subscribe(() => this.log("Auth required for EVENT"));
+        // Create status$ observable by combining state observables
+        this.status$ = combineLatest({
+            url: of(this.url),
+            connected: this.connected$,
+            authenticated: this.authenticated$,
+            authenticatedAs: this.authenticatedAs$,
+            ready: this._ready$,
+            authRequiredForRead: this.authRequiredForRead$,
+            authRequiredForPublish: this.authRequiredForPublish$,
+        }).pipe(shareReplay(1));
         // Update the notices state
         const listenForNotice = this.socket.pipe(
         // listen for NOTICE messages
@@ -249,7 +290,9 @@ export class Relay {
         const allMessagesSubject = new Subject();
         const listenForAllMessages = this.socket.pipe(tap((message) => {
             // Update the last message received at timestamp
-            this.lastMessageReceivedAt = Date.now();
+            const now = Date.now();
+            this.lastMessageReceivedAt = now;
+            this._lastMessageAt$.next(now);
             // Pass to the message subject
             allMessagesSubject.next(message);
         }));
@@ -274,20 +317,46 @@ export class Relay {
                 // Skip ping if we have received a message in the last pingFrequency milliseconds
                 if (Date.now() - this.lastMessageReceivedAt < this.pingFrequency)
                     return NEVER;
-                // Send a ping request
-                this.send(["REQ", "ping:" + nanoid(), PING_FILTER]);
-                // Wait for the EOSE response
+                // Generate unique ping ID for correlation
+                const pingId = "ping:" + nanoid();
+                this.send(["REQ", pingId, PING_FILTER]);
+                // Wait for the EOSE or CLOSED response for this specific ping
                 return this.message$.pipe(
-                // Complete after first message received
+                // Wait specifically for response to OUR ping
+                filter((m) => Array.isArray(m) && (m[0] === "EOSE" || m[0] === "CLOSED") && m[1] === pingId), 
+                // Complete after first matching message received
                 take(1), 
                 // Add timeout to detect unresponsive connections
                 timeout({
                     first: this.pingTimeout,
                     with: () => {
-                        console.warn(`Relay connection has become unresponsive: ${this.url}`);
+                        // Determine action via policy hook (default: reconnect)
+                        const now = Date.now();
+                        const action = this.onUnresponsive?.({
+                            url: this.url,
+                            lastMessageAt: this.lastMessageReceivedAt,
+                            now,
+                            attempts: this.attempts$.value,
+                        }) ?? "reconnect";
+                        const err = new Error(`Relay ping timeout after ${this.pingTimeout}ms`);
+                        if (action === "reconnect") {
+                            this.log("Relay connection has become unresponsive, triggering reconnect");
+                            this.startReconnectTimer(err);
+                        }
+                        else if (action === "close") {
+                            this.log("Relay connection has become unresponsive, closing connection");
+                            this.error$.next(err);
+                            this.socket.complete();
+                        }
+                        else {
+                            // "ignore" - log but don't take action
+                            this.log("Relay connection has become unresponsive (ignoring per policy)");
+                        }
                         return NEVER;
                     },
-                }));
+                }), 
+                // Close the ping subscription when done
+                finalize(() => this.send(["CLOSE", pingId])));
             }));
         }), 
         // Catch errors to prevent breaking the watchTower
@@ -379,9 +448,18 @@ export class Relay {
         // Create an observable that controls sending the filters and closing the REQ
         const control = input.pipe(
         // Send the filters when they change
-        tap((filters) => this.socket.next(["REQ", id, ...filters])), 
+        tap((filters) => {
+            this.socket.next(["REQ", id, ...filters]);
+            // Add to tracking when REQ is sent
+            this.reqs$.next({ ...this.reqs$.value, [id]: filters });
+        }), 
         // Send the CLOSE message when unsubscribed or input completes
-        finalize(() => this.socket.next(["CLOSE", id])), 
+        finalize(() => {
+            this.socket.next(["CLOSE", id]);
+            // Remove from tracking when REQ closes
+            const { [id]: _, ...rest } = this.reqs$.value;
+            this.reqs$.next(rest);
+        }), 
         // Once filters have been sent, switch to listening for messages
         switchMap(() => messages));
         // Start the watch tower with the observables
@@ -481,6 +559,8 @@ export class Relay {
     }
     /** send and AUTH message */
     auth(event) {
+        // Save the authentication event
+        this.authentication$.next(event);
         return lastValueFrom(this.event(event, "AUTH").pipe(
         // update authenticated
         tap((result) => this.authenticationResponse$.next(result))));

package/dist/types.d.ts

@@ -16,6 +16,23 @@ export type PublishResponse = {
 export type CountResponse = {
     count: number;
 };
+/** Status information for a single relay */
+export interface RelayStatus {
+    /** Relay URL */
+    url: string;
+    /** WebSocket connection state (true = socket is open) */
+    connected: boolean;
+    /** Authentication state (true = successfully authenticated) */
+    authenticated: boolean;
+    /** The pubkey of the authenticated user, or null if not authenticated */
+    authenticatedAs: string | null;
+    /** Application-layer ready state (true = safe to use) */
+    ready: boolean;
+    /** Whether authentication is required for read operations (REQ/COUNT) */
+    authRequiredForRead: boolean;
+    /** Whether authentication is required for publish operations (EVENT) */
+    authRequiredForPublish: boolean;
+}
 export type MultiplexWebSocket<T = any> = Pick<WebSocketSubject<T>, "multiplex">;
 /** Options for the publish method on the pool and relay */
 export type PublishOptions = {
@@ -66,6 +83,7 @@ export interface IRelay extends MultiplexWebSocket {
     message$: Observable<any>;
     notice$: Observable<string>;
     connected$: Observable<boolean>;
+    ready$: Observable<boolean>;
     challenge$: Observable<string | null>;
     authenticated$: Observable<boolean>;
     notices$: Observable<string[]>;
@@ -73,10 +91,14 @@ export interface IRelay extends MultiplexWebSocket {
     close$: Observable<CloseEvent>;
     closing$: Observable<void>;
     error$: Observable<Error | null>;
+    lastMessageAt$: Observable<number>;
+    status$: Observable<RelayStatus>;
     readonly connected: boolean;
+    readonly ready: boolean;
     readonly authenticated: boolean;
     readonly challenge: string | null;
     readonly notices: string[];
+    readonly lastMessageAt: number;
     /** Force close the connection */
     close(): void;
     /** Send a REQ message */
@@ -108,6 +130,8 @@ export interface IRelay extends MultiplexWebSocket {
 }
 export type IGroupRelayInput = IRelay[] | Observable<IRelay[]>;
 export interface IGroup {
+    /** Observable of relay status for all relays in the group */
+    status$: Observable<Record<string, RelayStatus>>;
     /** Send a REQ message */
     req(filters: Parameters<IRelay["req"]>[0], id?: string): Observable<SubscriptionResponse>;
     /** Send an EVENT message */
@@ -138,6 +162,8 @@ export interface IPoolSignals {
 }
 export type IPoolRelayInput = string[] | Observable<string[]>;
 export interface IPool extends IPoolSignals {
+    /** Observable of relay status for all relays in the pool */
+    status$: Observable<Record<string, RelayStatus>>;
     /** Get or create a relay */
     relay(url: string): IRelay;
     /** Create a relay group */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "applesauce-relay",
-  "version": "0.0.0-next-20260116173453",
+  "version": "0.0.0-next-20260120162357",
   "description": "nostr relay communication framework built on rxjs",
   "type": "module",
   "main": "dist/index.js",
@@ -57,7 +57,7 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.7.1",
-    "applesauce-core": "0.0.0-next-20260116173453",
+    "applesauce-core": "0.0.0-next-20260120162357",
     "nanoid": "^5.0.9",
     "nostr-tools": "~2.19",
     "rxjs": "^7.8.1"