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

    Interface SemanticRelayProviderProps

    Props for <SemanticRelayProvider>. Mirrors the shape of RelayOptions from the underlying client, plus a disabled flag and a children slot. The provider owns the SemanticRelayClient instance and tears it down when roomId / userId / token change or when the component unmounts.

    interface SemanticRelayProviderProps {
        children: ReactNode;
        disabled?: boolean;
        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;
    }

    Hierarchy

    Index

    Properties

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

    Properties

    children: ReactNode
    disabled?: boolean

    When true, the provider does not connect. Useful for rooms where the relay isn't needed yet (e.g. while waiting for a token to come back from the backend) or when the consumer wants a kill switch.

    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 broadcast scope. The provider rebuilds its client whenever this changes so peers see the new session.

    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