Hiyve Components - v1.0.0
    Preparing search index...

    Interface RelayOptions

    interface RelayOptions {
        getToken?: () => string | Promise<string>;
        maxSeenMessages?: number;
        onConnectionChange?: (state: RelayConnectionState) => void;
        onDebug?: (msg: string, ...args: unknown[]) => void;
        onError?: (err: Error) => void;
        pruneCount?: number;
        reconnect?: boolean;
        reconnectBaseDelayMs?: number;
        reconnectMaxDelayMs?: number;
        retryDelaysMs?: readonly number[];
        roomId: string;
        serverCertificateHashes?: RelayCertHash[];
        token: string;
        transport?: RelayTransportPolicy;
        url: string;
        userId: string;
        wsBufferedAmountHighWater?: number;
    }
    Index

    Properties

    getToken? maxSeenMessages? onConnectionChange? onDebug? onError? pruneCount? reconnect? reconnectBaseDelayMs? reconnectMaxDelayMs? retryDelaysMs? roomId serverCertificateHashes? token transport? url userId wsBufferedAmountHighWater?

    Properties

    getToken?: () => string | Promise<string>

    Supply a fresh token before each reconnect attempt.

    Tokens expire, and a connection lost for long enough comes back to a token the relay will reject. Without this, a reconnect that fails authentication stops — there is nothing useful to retry. With it, the client asks for a new token each time and keeps going.

    maxSeenMessages?: number

    Maximum dedupe entries per topic before pruning kicks in. Default 200.

    onConnectionChange?: (state: RelayConnectionState) => void

    Notification when the connection state changes.

    onDebug?: (msg: string, ...args: unknown[]) => void

    Optional debug hook — pairs nicely with createDebugLogger('hiyve:semantic-relay').

    onError?: (err: Error) => void

    Connection-level error callback.

    pruneCount?: number

    Number of dedupe entries to drop when the cache is pruned. Default 50.

    reconnect?: boolean

    Keep the connection alive for the life of the room. Default true.

    A relay connection can be lost long after it was established — a VPN or tunnel dropping, a Wi-Fi handover, a laptop waking, the relay restarting. With this on, the client re-establishes it on its own with an escalating backoff, and also keeps trying when the very first connect never succeeded, so a room joined on a network that blocks the relay recovers the moment that network changes. Retries fire immediately on online and on the tab becoming visible rather than waiting out the backoff.

    Media and messaging carried over other transports are unaffected either way; this governs only the relay connection.

    Set false to connect once and stop.

    reconnectBaseDelayMs?: number

    First reconnect delay (ms), doubling to reconnectMaxDelayMs. Default 1000.

    reconnectMaxDelayMs?: number

    Ceiling for the reconnect delay (ms). Default 30000.

    retryDelaysMs?: readonly number[]

    Override the connect-retry policy. Defaults to three attempts with 200ms / 800ms / 2000ms backoff. Auth failures (401/403 from the handshake) are not retried regardless of this setting. In 'auto' transport mode the ladder applies to the WebSocket fallback attempts; WebTransport gets a single attempt before falling through (a WebTransport connect failure is almost always environmental — blocked UDP — and retrying it only delays a transport that will work).

    roomId: string

    Room identifier — relay-side scope for broadcasts.

    serverCertificateHashes?: RelayCertHash[]

    Cert hashes for the browser WebTransport serverCertificateHashes option. Only needed when the relay serves a self-signed certificate (e.g. localhost development). Deployed relays serve a CA-trusted certificate, which passes ordinary browser validation — leave this unset (an empty array is treated as "no pinning").

    token: string

    HMAC-SHA256 JWT minted by the app backend.

    transport?: RelayTransportPolicy

    Transport selection policy. Default 'auto'.

    url: string

    WebTransport URL — must use the https:// scheme (HTTP/3). The relay adds query parameters for room and token, so callers should pass the raw base path, e.g. https://semantic.hiyve.tv:4443/relay.

    userId: string

    Identifier the consumer treats as authoritative. Duplicated into every published envelope so subscribers can attribute messages without waiting for a peer-presence stream from the server. Should match the JWT's userId claim — the SDK does not enforce this, but mismatches lead to confusing attribution.

    wsBufferedAmountHighWater?: number

    Congestion threshold (bytes) for the WebSocket fallback: while the socket's bufferedAmount exceeds this, outbound messages coalesce latest-wins per topic. Default 16 KB. Ignored on WebTransport.

    Settings

    Member Visibility

    On This Page

    Properties