Applesauce
    Preparing search index...

    Class PrimalCache

    Extended relay interface for primal caching server

    https://github.com/PrimalHQ/primal-server/blob/main/src/app_ext.jl

    Hierarchy

    • Relay
      • PrimalCache
    Index
    constructor
    _nip11 _ready$ attempts$ authenticated$ authenticatedAs$ authenticatedPubkeys$ authentication$ authenticationResponse$ authentications$ authLog challenge$ close$ closing$ connected$ countTimeout destroy$ enablePing error$ eventTimeout icon$ information$ internalSubscriptions keepAlive lastMessageAt$ limitations$ log message$ name$ notice$ noticeLimit notices$ onUnresponsive? open$ pingFrequency pingTimeout publishRetry publishTimeout ready$ reconnectSubscription reconnectTimer reqs$ requestReconnect router socket status$ subscriptionReconnect supported$ url watchTower
    authenticated authenticatedAs authenticatedPubkeys authentication authenticationResponse authentications challenge connected information lastMessageAt notices ready reqs
    [RELAY_REQ_LIFECYCLE] advancedFeed advancedSearch auth authenticate authenticatedFor$ authRetryOperator authSatisfied$ broadcastEvents broadcastReply buildAuthContext cacheRequest checkFilterlist close count customConnectionRetryOperator customRepeatOperator customRetryOperator customSuspendableTimeoutOperator event explore exploreGlobalMostZapped4h exploreGlobalTrending24h exploreLegendCounts feedDirective feedDirective2 getAdvancedFeeds getDefaultRelays getFilterlist getInformation getLimitations getMediaMetadata getNotifications getNotificationsSeen getRecommendedUsers getSuggestedUsers getSupported isAuthenticated missingPubkeysFor multiplex negentropy noteMentions noteMentionsCount publish relays reportNote reportUser req request resetState satisfiedPubkeysFor scored scoredUsers scoredUsers24h search send setNotificationsSeen startReconnectTimer subscription sync timelineRequest trendingHashtags trendingHashtags4h trendingHashtags7d trendingImages trendingImages4h trustedUsers userProfileScoredContent userProfileScoredMediaThumbnails userSearch waitForReady afterOpen completeAnd completeOr createReconnectTimer defaultComplete fetchInformationDocument

    Protected_nip11

    _nip11: RelayInformation | null

    Protected_ready$

    _ready$: BehaviorSubject<boolean>

    Internal subject that tracks the ready state of the relay

    attempts$: BehaviorSubject<number>

    How many times the relay has tried to reconnect

    authenticated$: Observable<boolean>

    Boolean authentication state (true if at least one pubkey is authenticated)

    authenticatedAs$: Observable<string | null>

    The pubkey of the most recently authenticated user, or null if not authenticated

    use authenticatedPubkeys$ instead

    authenticatedPubkeys$: Observable<string[]>

    The pubkeys that are currently authenticated on the connection, ordered oldest to most recent

    authentication$: BehaviorSubject<KnownEvent<22242> | null>

    The last authentication event sent to the relay

    use authentications$ instead

    authenticationResponse$: BehaviorSubject<PublishResponse | null>

    The response to the last AUTH message sent to the relay

    use authentications$ instead

    authentications$: BehaviorSubject<Record<string, RelayAuthState>>

    All AUTH attempts on this connection keyed by pubkey (NIP-42 supports multiple authenticated users per connection)

    authLog: Debugger

    D-13/D-20: the relay's NIP-42 lines, re-derived in the constructor as Relay:auth:<url>.

    challenge$: BehaviorSubject<string | null>

    The authentication challenge string from the relay

    close$: Subject<CloseEvent>

    An observable that emits when underlying websocket is closed

    closing$: Subject<void>

    An observable that emits when underlying websocket is closing due to unsubscribe or complete

    connected$: BehaviorSubject<boolean>

    Whether the relay is connected

    countTimeout: number

    Whole logical COUNT request timeout (default 10s)

    destroy$: ReplaySubject<void>

    Fires when the relay is closed. Used to cancel the watchTower's keepAlive reset timer. A ReplaySubject so a reset timer armed after close() is torn down immediately.

    enablePing: boolean

    Enable/disable ping functionality (default false)

    error$: BehaviorSubject<Error | null>

    The last connection error

    eventTimeout: number

    How long to wait for an OK message from the relay (default 10s)

    icon$: Observable<string | undefined>

    An observable that emits the icon URL for the relay, or the favicon.ico URL for the relay

    information$: Observable<RelayInformation | null>

    An observable that emits the NIP-11 information document for the relay

    internalSubscriptions: Subscription

    Long-lived state-watcher subscriptions created in the constructor (open/close/auth)

    keepAlive: number

    How long to keep the connection alive after nothing is subscribed (default 30s)

    lastMessageAt$: Observable<number>
    limitations$: Observable<Partial<Limitations> | null | undefined>

    An observable that emits the limitations for the relay

    log: Debugger
    message$: Observable<any>

    A passive observable of all messages from the relay

    Subscribing to this will not connect to the relay

    name$: Observable<string>

    An observable that emits the NIP-11 name of the relay, or its URL until the information document loads

    notice$: Observable<string>

    A passive observable of NOTICE messages from the relay

    Subscribing to this will not connect to the relay

    noticeLimit: number

    The constructor-configured maximum number of retained notices

    notices$: BehaviorSubject<string[]>

    The retained notices from the current relay connection, ordered oldest to newest

    onUnresponsive?: (
        info: {
            attempts: number;
            lastMessageAt: number;
            now: number;
            url: string;
        },
    ) => "reconnect"
    | "close"
    | "ignore"

    Policy hook for unresponsive connections

    open$: Subject<Event>

    An observable that emits when underlying websocket is opened

    pingFrequency: number

    How often to send pings in milliseconds (default 29000)

    pingTimeout: number

    How long to wait for EOSE response in milliseconds (default 20000)

    publishRetry: RetryConfig

    Default retry config for publish() method

    publishTimeout: number

    How long to wait for a publish to complete (default 30s)

    ready$: Observable<boolean>

    Whether the relay is ready for subscriptions or event publishing. setting this to false will cause all .req and .event observables to hang until the relay is ready

    reconnectSubscription: Subscription | null

    The currently armed reconnect timer subscription, if any

    reconnectTimer: (
        error: Error | CloseEvent,
        attempts: number,
    ) => Observable<number>

    A method that returns an Observable that emits when the relay should reconnect

    reqs$: ReqsSubject

    Tracks active req() operations by subscription ID

    requestReconnect: RetryConfig

    Default retry config for request() connection errors

    router: SocketRouter

    Routes subscription and OK replies to their listeners by id

    socket: WebSocketSubject<any>
    status$: Observable<RelayStatus>

    Observable of relay status (connection, authentication, and ready state)

    subscriptionReconnect: RetryConfig

    Default retry config for subscription() connection errors

    supported$: Observable<number[] | null>

    An array of supported NIPs from the NIP-11 information document

    url: string
    watchTower: Observable<never>

    An internal observable that is responsible for watching all messages and updating state, subscribing to it will trigger a connection to the relay

    • get authenticated(): boolean

      Returns boolean

    • get authenticatedAs(): string | null

      Returns string | null

      use authenticatedPubkeys instead

    • get authenticatedPubkeys(): string[]

      Returns string[]

    • get authentication(): KnownEvent<22242> | null

      Returns KnownEvent<22242> | null

      use authentications instead

    • get authenticationResponse(): PublishResponse | null

      Returns PublishResponse | null

      use authentications instead

    • get authentications(): Record<string, RelayAuthState>

      Returns Record<string, RelayAuthState>

    • get challenge(): string | null

      Returns string | null

    • get connected(): boolean

      Returns boolean

    • get information(): RelayInformation | null

      Returns RelayInformation | null

    • get lastMessageAt(): number

      Returns number

    • get notices(): string[]

      Returns string[]

    • get ready(): boolean

      Returns boolean

    • get reqs(): Record<string, Filter[]>

      Returns Record<string, Filter[]>

    • Compose fresh raw REQ attempts while retaining lifecycle messages for high-level consumers.

      Parameters

      • filters: FilterInput
      • Optionalopts: RelaySubscriptionOptions
      • Optionalgate: AuthPhaseGate

      Returns Observable<RelayReqMessage>

    • Advanced feed

      Parameters

      • params: {
            feed_type: string;
            limit?: number;
            offset?: number;
            since?: number;
            until?: number;
        }

      Returns Promise<NostrEvent[]>

    • Advanced search

      Parameters

      • params: {
            limit?: number;
            offset?: number;
            query: string;
            since?: number;
            sort?: "popular" | "trending" | "latest";
            until?: number;
        }

      Returns Promise<NostrEvent[]>

    • Send an AUTH message. Can be called multiple times with events from different pubkeys to authenticate multiple users

      Parameters

      Returns Promise<PublishResponse>

    • Authenticate with bounded challenge acquisition, signing, freshness checks, and one raw AUTH verdict.

      Parameters

      • signer: AuthSigner
      • Optionalopts: RelayAuthenticateOptions

      Returns Promise<PublishResponse>

    • An observable that emits whether a specific pubkey (or all of an array of pubkeys) is authenticated

      Parameters

      • pubkeys: string | string[]

      Returns Observable<boolean>

    • Returns the shared authRetry operator configured from an operation's auth options. AuthRequiredError triggers an auth phase, and the three terminal auth errors are what it gives up with.

      Type Parameters

      • T extends unknown = unknown

      Parameters

      • describeRequest: () => RelayAuthWireRequest
      • opts: RelayAuthOptions | undefined
      • gate: AuthPhaseGate
      • isProgress: ProgressPredicate<T>
      • Optionalcounter: { consecutive: number }

      Returns MonoTypeOperatorFunction<T>

    • Convert an auth requirement into an observable of whether it is satisfied

      Parameters

      • requirement: AuthRequirement

      Returns Observable<boolean>

    • Assemble the RelayAuthContext passed to a caller's onAuthRequired handler (RAUTH-01)

      Parameters

      • request: RelayAuthWireRequest
      • requirement: AuthRequirement
      • reason: string

      Returns RelayAuthContext

    • Make a "cache" request to the caching server

      Type Parameters

      Parameters

      • request:
            | ["explore_legend_counts", { pubkey: string }]
            | [
                "explore",
                {
                    apply_humaness_check?: boolean;
                    created_after?: number;
                    gm_mode?: boolean;
                    group_by_pubkey?: boolean;
                    include_top_zaps?: boolean;
                    limit?: number;
                    offset?: number;
                    pubkeys?: string[];
                    since?: number;
                    timeframe: "popular"
                    | "trending"
                    | "recent";
                    until?: number;
                    user_pubkey?: string;
                },
            ]
            | ["explore_global_trending_24h", { limit?: number }]
            | ["explore_global_mostzapped_4h", { limit?: number }]
            | [
                "scored",
                {
                    apply_humaness_check?: boolean;
                    created_after?: number;
                    gm_mode?: boolean;
                    group_by_pubkey?: boolean;
                    include_top_zaps?: boolean;
                    limit?: number;
                    offset?: number;
                    pubkeys?: string[];
                    since?: number;
                    timeframe: "popular"
                    | "trending"
                    | "recent";
                    until?: number;
                    user_pubkey?: string;
                },
            ]
            | ["scored_users", { limit?: number }]
            | ["scored_users_24h", { limit?: number }]
            | ["get_default_relays", {}]
            | ["get_recommended_users", { limit?: number }]
            | ["get_suggested_users", { limit?: number }]
            | [
                "user_profile_scored_content",
                {
                    created_after?: number;
                    limit?: number;
                    offset?: number;
                    pubkey: string;
                    since?: number;
                    until?: number;
                },
            ]
            | [
                "user_profile_scored_media_thumbnails",
                {
                    created_after?: number;
                    limit?: number;
                    offset?: number;
                    pubkey: string;
                    since?: number;
                    until?: number;
                },
            ]
            | [
                "search",
                {
                    limit?: number;
                    offset?: number;
                    query: string;
                    since?: number;
                    until?: number;
                },
            ]
            | [
                "advanced_search",
                {
                    limit?: number;
                    offset?: number;
                    query: string;
                    since?: number;
                    sort?: "popular"
                    | "trending"
                    | "latest";
                    until?: number;
                },
            ]
            | [
                "advanced_feed",
                {
                    feed_type: string;
                    limit?: number;
                    offset?: number;
                    since?: number;
                    until?: number;
                },
            ]
            | ["relays", {}]
            | [
                "get_notifications",
                {
                    limit?: number;
                    offset?: number;
                    pubkey: string;
                    since?: number;
                    until?: number;
                },
            ]
            | ["set_notifications_seen", { pubkey: string; until: number }]
            | ["get_notifications_seen", { pubkey: string }]
            | ["user_search", { limit?: number; query: string }]
            | [
                "feed_directive",
                {
                    feed_type: string;
                    limit?: number;
                    offset?: number;
                    pubkey: string;
                    since?: number;
                    until?: number;
                },
            ]
            | [
                "feed_directive_2",
                {
                    feed_type: string;
                    limit?: number;
                    offset?: number;
                    pubkey: string;
                    since?: number;
                    until?: number;
                },
            ]
            | ["get_advanced_feeds", {}]
            | ["trending_hashtags", { limit?: number }]
            | ["trending_hashtags_4h", { limit?: number }]
            | ["trending_hashtags_7d", { limit?: number }]
            | ["trending_images", { limit?: number }]
            | ["trending_images_4h", { limit?: number }]
            | ["report_user", { pubkey: string; reason: string }]
            | ["report_note", { event_id: string; reason: string }]
            | ["get_filterlist", {}]
            | ["check_filterlist", { pubkeys: string[] }]
            | ["broadcast_reply", { event: NostrEvent }]
            | ["broadcast_events", { events: NostrEvent[]; relays: string[] }]
            | ["trusted_users", { extended_response?: boolean; limit?: number }]
            | [
                "note_mentions",
                {
                    event_id?: string;
                    identifier?: string;
                    limit?: number;
                    offset?: number;
                    pubkey?: string;
                    user_pubkey?: string;
                },
            ]
            | ["note_mentions_count", { event_id: string }]
            | ["get_media_metadata", { urls: string[] }]

      Returns Observable<R["event"]>

    • Force close the connection and tear down all internal subscriptions and timers.

      Returns void

      This is a terminal operation; the relay should be discarded after calling it.

    • Creates a one-shot NIP-45 COUNT request that emits a single response

      Parameters

      • filters: Filter | Filter[]
      • Optionalid: string
      • Optionalopts: RelayCountOptions

      Returns Observable<RelayCountResponse>

    • Internal operator for retrying connection failures without retrying relay CLOSED errors

      Type Parameters

      • T extends unknown = unknown

      Parameters

      • times: number | boolean | RetryConfig | undefined
      • Optionalbase: RetryConfig

      Returns MonoTypeOperatorFunction<T>

    • Internal operator for creating the repeat() operator, optionally gated by a condition

      Type Parameters

      • T extends unknown = unknown

      Parameters

      • times: number | boolean | RepeatConfig | undefined
      • Optionalcondition: () => boolean

      Returns MonoTypeOperatorFunction<T>

    • Classifier-supplied retry policy shared by the high-level publish and COUNT families. Each caller supplies a positive allow-list; all other failures are re-thrown immediately. The call-scoped auth counter persists across transient resubscriptions, enforcing the additive 1 + authRetries + retries EVENT-write bound.

      Type Parameters

      • T extends unknown = unknown

      Parameters

      • times: number | boolean | RetryConfig | undefined
      • Optionalbase: RetryConfig
      • Optionalclassifier: (error: unknown) => boolean

      Returns MonoTypeOperatorFunction<T>

    • Internal operator for creating a suspendable timeout() operator whose countdown does not advance while gate is in an auth phase (D-15) — used by publish() so publishTimeout gets its full budget for the real work once the auth phase closes, rather than racing authTimeout. Preserves the same false/true/number semantics the prior bare-timeout helper had. Do NOT "simplify" this back to a bare rxjs timeout(), which cannot pause. firstWhen is required (CR-01/WR-01) — the sole caller states what counts as progress for its own stream shape; there is no permissive default.

      Type Parameters

      • T extends unknown = unknown

      Parameters

      • timeout: number | boolean | undefined
      • defaultTimeout: number
      • gate: AuthPhaseGate
      • firstWhen: ProgressPredicate<T>

      Returns MonoTypeOperatorFunction<T>

    • Send one EVENT frame and observe its matching OK response.

      Parameters

      Returns Observable<PublishResponse>

    • Explore content with various filters

      Parameters

      • params: {
            apply_humaness_check?: boolean;
            created_after?: number;
            gm_mode?: boolean;
            group_by_pubkey?: boolean;
            include_top_zaps?: boolean;
            limit?: number;
            offset?: number;
            pubkeys?: string[];
            since?: number;
            timeframe: "popular" | "trending" | "recent";
            until?: number;
            user_pubkey?: string;
        }

      Returns Promise<NostrEvent[]>

    • Feed directive

      Parameters

      • params: {
            feed_type: string;
            limit?: number;
            offset?: number;
            pubkey: string;
            since?: number;
            until?: number;
        }

      Returns Promise<NostrEvent[]>

    • Feed directive v2

      Parameters

      • params: {
            feed_type: string;
            limit?: number;
            offset?: number;
            pubkey: string;
            since?: number;
            until?: number;
        }

      Returns Promise<NostrEvent[]>

    • An async method that returns the NIP-11 information document for the relay

      Returns Promise<RelayInformation | null>

    • An async method that returns the NIP-11 limitations for the relay

      Returns Promise<Partial<Limitations> | null | undefined>

    • Get notifications

      Parameters

      • params: {
            limit?: number;
            offset?: number;
            pubkey: string;
            since?: number;
            until?: number;
        }

      Returns Promise<NostrEvent[]>

    • An async method that returns the supported NIPs for the relay

      Returns Promise<number[] | null>

    • Whether a specific pubkey (or all of an array of pubkeys) is authenticated on the connection

      Parameters

      • pubkeys: string | string[]

      Returns boolean

    • Compute the pubkeys not yet authenticated for an AuthRequirement, for RelayAuthContext.missingPubkeys. true returns null (any authenticated user satisfies it, so no specific pubkeys are "missing"). A single pubkey returns an empty array when already authenticated, a one-element array otherwise. An array returns only the entries isAuthenticated reports false for.

      Parameters

      • requirement: AuthRequirement

      Returns string[] | null

    • Type Parameters

      • T

      Parameters

      • open: () => any
      • close: () => any
      • filter: (message: any) => boolean

      Returns Observable<T>

    • Negentropy sync event ids with the relay and an event store

      Parameters

      • store: NegentropyReadStore
      • filter: Filter
      • Optionalopts: NegentropyOptions

      Returns Observable<NegentropyRound>

    • Get note mentions

      Parameters

      • params: {
            event_id?: string;
            identifier?: string;
            limit?: number;
            offset?: number;
            pubkey?: string;
            user_pubkey?: string;
        }

      Returns Promise<NostrEvent[]>

    • Publishes an event to the relay and retries when relay errors or responds with auth-required ( default 3 retries )

      Parameters

      Returns Promise<PublishResponse>

    • Create a REQ observable that emits OPEN, EVENT, EOSE, and CLOSED messages.

      resubscribe only repeats after the relay sends a clean CLOSED message for this REQ. reconnect only retries connection errors and does not retry relay CLOSED errors.

      Parameters

      • filters: FilterInput
      • Optionalopts: RelayReqOptions

      Returns Observable<RelayReqMessage>

    • Makes a single request that retries connection errors and completes on EOSE

      Parameters

      • filters: FilterInput
      • Optionalopts: RelayRequestOptions

      Returns Observable<NostrEvent>

    • Returns void

    • D-08: compute the pubkeys that currently satisfy an AuthRequirement — the join key an operation track hangs its "now waiting for …" line off. true is satisfied by any authenticated pubkey, so the whole current set is returned wholesale. A string or array requirement returns only the required pubkeys that are already authenticated.

      Parameters

      • requirement: AuthRequirement

      Returns string[]

    • Get scored content

      Parameters

      • params: {
            apply_humaness_check?: boolean;
            created_after?: number;
            gm_mode?: boolean;
            group_by_pubkey?: boolean;
            include_top_zaps?: boolean;
            limit?: number;
            offset?: number;
            pubkeys?: string[];
            since?: number;
            timeframe: "popular" | "trending" | "recent";
            until?: number;
            user_pubkey?: string;
        }

      Returns Promise<NostrEvent[]>

    • Search content

      Parameters

      • params: {
            limit?: number;
            offset?: number;
            query: string;
            since?: number;
            until?: number;
        }

      Returns Promise<NostrEvent[]>

    • Send a message to the relay

      Parameters

      • message: any

      Returns void

    • Set ready = false and start the reconnect timer

      Parameters

      • error: Error | CloseEvent

      Returns void

    • Creates a persistent REQ that retries connection errors (default 3 retries)

      Parameters

      • filters: FilterInput
      • Optionalopts: RelaySubscriptionOptions

      Returns Observable<RelaySubscriptionResponse>

    • Negentropy sync events with the relay and an event store

      Parameters

      • store: NegentropySyncStore
      • filters: Filter
      • Optionaldirection: SyncDirection
      • Optionalopts: RelaySyncOptions

      Returns Observable<SyncMessage>

    • Makes a cache request and returns a timeline of events

      Type Parameters

      • R extends RequestAndResponse<any, any, any>

      Parameters

      • method: R["req"][0]
      • args: R["req"][1]

      Returns Promise<R["event"][]>

    • Get trusted users

      Parameters

      • limit: number = 500
      • extendedResponse: boolean = true

      Returns Promise<NostrEvent[]>

    • Get user profile scored content

      Parameters

      • params: {
            created_after?: number;
            limit?: number;
            offset?: number;
            pubkey: string;
            since?: number;
            until?: number;
        }

      Returns Promise<NostrEvent[]>

    • Get user profile scored media thumbnails

      Parameters

      • params: {
            created_after?: number;
            limit?: number;
            offset?: number;
            pubkey: string;
            since?: number;
            until?: number;
        }

      Returns Promise<NostrEvent[]>

    • Wait for the relay to be ready to accept connections

      Type Parameters

      • T extends unknown = unknown

      Parameters

      Returns Observable<T>

    • A complete condition that waits for the subscription to open

      Parameters

      • condition: RelayRequestCompleteOperator

      Returns RelayRequestCompleteOperator

    • An AND complete condition, that completes when all conditions are truthy

      Parameters

      • ...conditions: RelayRequestCompleteOperator[]

      Returns RelayRequestCompleteOperator

    • An OR complete condition, that completes when either condition is truthy

      Parameters

      • ...conditions: RelayRequestCompleteOperator[]

      Returns RelayRequestCompleteOperator

    • Static method to create a reconnection method for each relay

      Parameters

      • _relay: string

      Returns (_error?: Error | CloseEvent, tries?: number) => Observable<0>

    • A default complete condition that waits for the subscription to open and then completes after a timeout

      Parameters

      • timeout: number
      • OptionalafterOpen: number

      Returns RelayRequestCompleteOperator

    • Fetches the NIP-11 information document for a relay

      Parameters

      • url: string

      Returns Promise<RelayInformation | null>

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Accessors
    Methods
    [RELAY_REQ_LIFECYCLE]advancedFeedadvancedSearchauthauthenticateauthenticatedFor$authRetryOperatorauthSatisfied$broadcastEventsbroadcastReplybuildAuthContextcacheRequestcheckFilterlistclosecountcustomConnectionRetryOperatorcustomRepeatOperatorcustomRetryOperatorcustomSuspendableTimeoutOperatoreventexploreexploreGlobalMostZapped4hexploreGlobalTrending24hexploreLegendCountsfeedDirectivefeedDirective2getAdvancedFeedsgetDefaultRelaysgetFilterlistgetInformationgetLimitationsgetMediaMetadatagetNotificationsgetNotificationsSeengetRecommendedUsersgetSuggestedUsersgetSupportedisAuthenticatedmissingPubkeysFormultiplexnegentropynoteMentionsnoteMentionsCountpublishrelaysreportNotereportUserreqrequestresetStatesatisfiedPubkeysForscoredscoredUsersscoredUsers24hsearchsendsetNotificationsSeenstartReconnectTimersubscriptionsynctimelineRequesttrendingHashtagstrendingHashtags4htrendingHashtags7dtrendingImagestrendingImages4htrustedUsersuserProfileScoredContentuserProfileScoredMediaThumbnailsuserSearchwaitForReadyafterOpencompleteAndcompleteOrcreateReconnectTimerdefaultCompletefetchInformationDocument