Class RedisRelayBackend

Redis implementation of IRelayBackend. Every operation is one of the relay* Lua scripts; this class only passes arguments and decodes results.

Keys of a namespace live under {prefix}::relay:{<namespace>}:

The empty segment after the prefix keeps the relay out of the queues' keyspace: every queue key (jobs included) is {prefix}:{queue}:... with a non-empty queue name, so no queue (not even one named "relay") nor any of its jobs can ever collide with a relay key.
Every key ends with a fixed word that is not a queue key suffix, never with a node id or topic, so tools that discover queues by key suffix (*:*:id, *:*:meta) never mistake relay keys for queues.
The namespace is a hash tag, so on Redis Cluster each namespace is one slot (the unit of scale) whatever the prefix.

Key	Type	Content
`:layout`	hash	`layout` version
`:nodes`	sorted set	node → lease deadline
`:started`	sorted set	node → registration time
`:{id}:node`	hash	`info`, `hb`, `backlog`, `dropped`; expires with the lease
`:{id}:inbox`	stream	the node's messages; expires with the lease
`:subs`	sorted set	subscription index (see `includes/relayIndex.lua`)
`:cleanup`	sorted set	removed nodes whose subscriptions are being pruned
`:retained`	sorted set	topic → expiry
`:{topic}:ret`	hash	retained message (`m`, `ts`, `d`)
`:mid`	string	message id counter (starts at the server time in µs)

Every key expires on its own when the namespace has no live node (and no retained message), so nothing is left behind even if no node sweeps it. {prefix}::relay:namespaces (sorted set: namespace → in use until) lists the namespaces in use, and expires on its own as well.

Each node's inbox is a stream, read with a blocking XREAD on a dedicated connection. Entries published while that connection is reconnecting are read once it's back.

Hierarchy

EventEmitter
- RedisRelayBackend

Implements

IRelayBackend

Index

Constructors

constructor

new RedisRelayBackend(
opts: RelayBackendOptions<ConnectionOptions>,
): RedisRelayBackend
Parameters
- opts: RelayBackendOptions<ConnectionOptions>
Returns RedisRelayBackend
Overrides EventEmitter.constructor
- Defined in classes/redis-relay-backend.ts:97

Properties

`Readonly` `Experimental`initialInboxCursor

initialInboxCursor: "0-0" = '0-0'

Position from which a freshly registered node reads its inbox.

`Readonly` `Experimental`namespace

namespace: string

Methods

close

close(): Promise<void>
Experimental
Closes the backend's connections it owns.

Returns Promise<void>
Implementation of IRelayBackend.close
- Defined in classes/redis-relay-backend.ts:142

deleteRetained

deleteRetained(topic: string): Promise<boolean>
Experimental
Deletes the retained message of a topic.
Parameters
- topic: string
Returns Promise<boolean>
false if the topic had no retained message.
Implementation of IRelayBackend.deleteRetained
- Defined in classes/redis-relay-backend.ts:234

getCounts

getCounts(): Promise<RelayCounts>
Experimental
Read-only getters, for dashboards. Lists are paginated like the queue getters: start and end are inclusive positions (from 0), and an end of -1 means "to the end". Orders are stable: nodes by registration, subscriptions and patterns by value (bytewise), retained messages by expiry.

Returns Promise<RelayCounts>
Implementation of IRelayBackend.getCounts
- Defined in classes/redis-relay-backend.ts:322

getNamespaces

getNamespaces(): Promise<string[]>
Experimental
Namespaces of the datastore (or Redis prefix) with live nodes or retained messages, sorted by name.

Returns Promise<string[]>
Implementation of IRelayBackend.getNamespaces
- Defined in classes/redis-relay-backend.ts:390

getNodeConnections

getNodeConnections(nodeId: string): Promise<RelayNodeConnection[]>
Experimental
The inbox connection of a node, as the datastore sees it (from CLIENT LIST or pg_stat_activity): where it connects from, and for how long. Empty when the node isn't connected. Lists every client connection of the datastore, so use it on demand rather than polling it.
Parameters
- nodeId: string
Returns Promise<RelayNodeConnection[]>
Implementation of IRelayBackend.getNodeConnections
- Defined in classes/redis-relay-backend.ts:418

getNodes

getNodes(start: number, end: number): Promise<RelayNodeState[]>
Experimental
Parameters
- start: number
- end: number
Returns Promise<RelayNodeState[]>
Implementation of IRelayBackend.getNodes
- Defined in classes/redis-relay-backend.ts:327

getPatterns

getPatterns(start: number, end: number): Promise<RelayPatternState[]>
Experimental
Parameters
- start: number
- end: number
Returns Promise<RelayPatternState[]>
Implementation of IRelayBackend.getPatterns
- Defined in classes/redis-relay-backend.ts:371

getRetained

getRetained(start: number, end: number): Promise<RelayRetainedState[]>
Experimental
Parameters
- start: number
- end: number
Returns Promise<RelayRetainedState[]>
Implementation of IRelayBackend.getRetained
- Defined in classes/redis-relay-backend.ts:379

getSubscriptions

getSubscriptions(
    filter: RelaySubscriptionFilter,
    start: number,
    end: number,
): Promise<RelaySubscriptionState[]>
Experimental
All subscriptions, or those of a node or a pattern.
Parameters
- filter: RelaySubscriptionFilter
- start: number
- end: number
Returns Promise<RelaySubscriptionState[]>
Implementation of IRelayBackend.getSubscriptions
- Defined in classes/redis-relay-backend.ts:352

heartbeat

heartbeat(nodeId: string, leaseMs: number): Promise<boolean>
Experimental
Renews a node's lease.
Parameters
- nodeId: string
- leaseMs: number
Returns Promise<boolean>
false when the node is not registered or its lease expired, even if it was not swept. The caller must register again and restore its subscriptions.
Implementation of IRelayBackend.heartbeat
- Defined in classes/redis-relay-backend.ts:177

interruptInbox

interruptInbox(): void
Experimental
Makes a blocked readInbox return (or fail) promptly, and later reads stop waiting. Used on close, so an interrupt that lands while a read is still starting is not lost.

Returns void
Implementation of IRelayBackend.interruptInbox
- Defined in classes/redis-relay-backend.ts:457

publish

publish(
    topic: string,
    data: string,
    opts: RelayPublishOptions,
): Promise<RelayPublishResult>
Experimental
Parameters
- topic: string
- data: string
- opts: RelayPublishOptions
Returns Promise<RelayPublishResult>
Implementation of IRelayBackend.publish
- Defined in classes/redis-relay-backend.ts:212

readInbox

readInbox(
    nodeId: string,
    cursor: string,
    opts: { blockMs: number; count: number },
): Promise<RelayInboxBatch>
Experimental
Returns the next entries of a node's inbox, waiting up to blockMs when there are none (0: return immediately).
Parameters
- nodeId: string
- cursor: string
- opts: { blockMs: number; count: number }
Returns Promise<RelayInboxBatch>
Implementation of IRelayBackend.readInbox
- Defined in classes/redis-relay-backend.ts:243

registerNode

registerNode(
    nodeId: string,
    leaseMs: number,
    info?: RelayNodeInfo,
    inboxMaxLength?: number,
): Promise<void>
Experimental
Registers (or refreshes) a node, its liveness lease and its info.
Parameters
- nodeId: string
- leaseMs: number
- info: RelayNodeInfo = {}
- inboxMaxLength: number = ...
Returns Promise<void>
Implementation of IRelayBackend.registerNode
- Defined in classes/redis-relay-backend.ts:153

removeEndpoint

removeEndpoint(nodeId: string, endpointId: string): Promise<number>
Experimental
Parameters
- nodeId: string
- endpointId: string
Returns Promise<number>
the number of subscriptions removed.
Implementation of IRelayBackend.removeEndpoint
- Defined in classes/redis-relay-backend.ts:208

subscribe(
    nodeId: string,
    endpointId: string,
    pattern: string,
): Promise<RelaySubscribeResult>
Experimental
Parameters
- nodeId: string
- endpointId: string
- pattern: string
Returns Promise<RelaySubscribeResult>
Implementation of IRelayBackend.subscribe
- Defined in classes/redis-relay-backend.ts:193

sweep

sweep(limit: number): Promise<string[]>
Experimental
Removes up to limit nodes whose lease expired, with their subscriptions and inboxes.
Parameters
- limit: number
Returns Promise<string[]>
the ids of the removed nodes.
Implementation of IRelayBackend.sweep
- Defined in classes/redis-relay-backend.ts:189

trimInbox

trimInbox(nodeId: string, cursor: string, maxLength: number): Promise<number>
Experimental
Removes the entries of a node's inbox that were already consumed (up to cursor, as returned by readInbox) and the oldest entries beyond maxLength.
Parameters
- nodeId: string
- cursor: string
- maxLength: number
Returns Promise<number>
the number of entries left: the messages the node hasn't read yet (its backlog).
Implementation of IRelayBackend.trimInbox
- Defined in classes/redis-relay-backend.ts:314

unregisterNode

unregisterNode(nodeId: string): Promise<boolean>
Experimental
Removes a node with its subscriptions and inbox.
Parameters
- nodeId: string
Returns Promise<boolean>
Implementation of IRelayBackend.unregisterNode
- Defined in classes/redis-relay-backend.ts:185

waitUntilReady

waitUntilReady(): Promise<void>
Experimental
Returns Promise<void>
Implementation of IRelayBackend.waitUntilReady
- Defined in classes/redis-relay-backend.ts:125

Class RedisRelayBackend

Hierarchy

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns RedisRelayBackend

Properties

Readonly ExperimentalinitialInboxCursor

Readonly Experimentalnamespace

Methods

close

Returns Promise<void>

deleteRetained

Parameters

Returns Promise<boolean>

getCounts

Returns Promise<RelayCounts>

getNamespaces

Returns Promise<string[]>

getNodeConnections

Parameters

Returns Promise<RelayNodeConnection[]>

getNodes

Parameters

Returns Promise<RelayNodeState[]>

getPatterns

Parameters

Returns Promise<RelayPatternState[]>

getRetained

Parameters

Returns Promise<RelayRetainedState[]>

getSubscriptions

Parameters

Returns Promise<RelaySubscriptionState[]>

heartbeat

Parameters

Returns Promise<boolean>

interruptInbox

Returns void

publish

Parameters

Returns Promise<RelayPublishResult>

readInbox

Parameters

Returns Promise<RelayInboxBatch>

registerNode

Parameters

Returns Promise<void>

removeEndpoint

Parameters

Returns Promise<number>

subscribe

Parameters

Returns Promise<RelaySubscribeResult>

sweep

Parameters

Returns Promise<string[]>

trimInbox

Parameters

Returns Promise<number>

unregisterNode

Parameters

Returns Promise<boolean>

waitUntilReady

Returns Promise<void>

Settings

On This Page

`Readonly` `Experimental`initialInboxCursor

`Readonly` `Experimental`namespace