Interface QwpBrowserIngressOptions

Default timeout for waitForAck() and QwpSender.flushAndWait(): how long a wait may go without the ACK watermark advancing. Defaults to 15 seconds. Capped at 2,147,483,647ms (the host timer ceiling); a larger value throws a RangeError.

Authenticates every WebSocket upgrade with a credential carried in its subprotocol offer instead of a session cookie. This is how a web application served from another origin, which QuestDB lists in qwp.browser.allowed.origins, connects. Pass a fixed credential, or a QwpBrowserAuthProvider the client calls before every connect, reconnect, and failover attempt, for example to supply a refreshed OIDC access token. Under a client's cluster it authenticates both sides, and a provider is called before every connection attempt of either side.

QuestDB accepts the credential only from a listed origin: a page served from QuestDB's own origin must be listed too, or keep using sessionBootstrap. It creates no session for the credential and ignores cookies on the upgrade. Use wss:: the credential travels in the opening HTTP request. Cannot be combined with sessionBootstrap.

Soft threshold for estimated buffered column bytes. Zero disables the byte trigger. Defaults to zero and is clamped below a connected server's batch cap; exact encoded frames remain subject to the protocol batch limit.

Not capped at the host timer ceiling: compared against elapsed time only.

Maximum time close() spends publishing queued rows and waiting for the server ACK watermark. Zero or a negative value skips the ACK wait, but RAM-backed frames still have up to 5 seconds to reach the socket before close() reports a timeout; if the session can no longer send them at all, close() rejects with its failure. Defaults to 5 seconds. Capped at 2,147,483,647ms (the host timer ceiling); a larger value throws a RangeError.

Maximum time allowed for a graceful WebSocket close. Defaults to 15s. Capped at 2,147,483,647ms (the host timer ceiling); a larger value throws a RangeError.

Bounded reconnect-listener inbox. Oldest pending events are dropped when full. Defaults to 64, matching the Java client.

Node TCP/TLS connection deadline, or the complete opening deadline in a browser. Defaults to 15s. Capped at 2,147,483,647ms (the host timer ceiling); a larger value throws a RangeError.

Durable-ACK keepalive interval. While committed table transactions await durable upload, Node transports send WebSocket PING frames and browser transports send table-less QWP poll frames. Takes effect only with requestDurableAck: true, where it defaults to 200ms; otherwise it is ignored, as in the Java and Rust clients. Zero disables the keepalive but still tracks durable progress. Capped at 2,147,483,647ms (the host timer ceiling); a larger value throws a RangeError.

Bounded typed/legacy error inbox. Oldest pending errors are dropped when full. Defaults to 256, matching the Java client.

Additional endpoints attempted in order when the preferred endpoint fails.

Gorilla-compresses TIMESTAMP and TIMESTAMP_NANOS columns; a column whose deltas the encoding cannot represent is sent raw. Defaults to true. UDP senders always disable it.

Startup policy when no server is reachable; the typed spelling of the initial_connect_retry configuration-string key.

• "off" makes one pass over the endpoints and fails fast.
• "sync" retries on the caller for up to reconnect.reconnectMaxDurationMs, then fails with QwpReconnectExhaustedError.
• "async" returns at once and connects in the background, retrying until close(). Rows published meanwhile wait in the replay queue -- memory, or the Node store-and-forward journal. An authentication or capability rejection that every endpoint would repeat ends the session if it comes before the first successful connection.

Defaults to "off", or to "sync" when reconnectMaxDurationMs, reconnectInitialBackoffMs or reconnectMaxBackoffMs is set. "sync" and "async" require reconnection, so they cannot be combined with reconnect: false.

Optional local ingress frame cap. Browsers cannot read WebSocket upgrade headers, so browser applications should set this to the server's configured QWP cap. When the server also advertises a cap, the smaller value wins. Table batches are split at row boundaries automatically; an individual row that cannot fit is rejected with QwpBatchTooLargeError before it is sent.

Maximum UTF-8 byte length of table and column names. Defaults to 127.

Maximum time a memory replay append waits for ACK-driven trimming after reaching memoryReplayMaxBytes. Defaults to 30 seconds.

Target cap for the built-in memory-only replay queue. Each queued frame counts its payload plus 1 KiB for the bookkeeping it keeps in memory, so the cap bounds the memory a backlog of small frames takes as well; the default holds about 127,000 one-row frames. Defaults to 128 MiB. A transaction-closing logical batch may temporarily exceed this target by up to one target-sized batch, because the server cannot ACK its deferred prefix before receiving that batch. A browser durable-ACK poll is admitted above it too, since only the durable progress it asks for can trim frames awaiting durability. This applies in browsers and non-persistent Node sessions; a Node store-and-forward journal is bounded by its own maxBytes instead.

Server rejections and terminal session failures. A waitForAck() that times out is reported only to its caller.

Monotonic send/accept/durability notifications. Callback errors are ignored.

Java-parity typed server-rejection and data-loss notifications. When omitted, the default handler logs retriable errors at warn and terminal errors or abandoned data at error.

Reconnection and at-least-once replay policy. Reconnection is enabled by default for factory-created sessions; set false to keep one fixed connection. Browser and non-persistent Node replay is memory-only. When initialConnectMode is not set, the first connect is a single attempt unless reconnectMaxDurationMs, reconnectInitialBackoffMs or reconnectMaxBackoffMs is set, as in the Java client; it then retries for up to reconnectMaxDurationMs (5 minutes by default). An onEvent observer alone does not make it retry. Once connected, the session retries every outage until close() or a terminal error.

An ACK lost during disconnect can cause a frame to be replayed after the server accepted it; configure server-side deduplication when duplicates are not acceptable.

Maximum time a send may remain queued by the WebSocket. Defaults to 15s. Capped at 2,147,483,647ms (the host timer ceiling); a larger value throws a RangeError.

Authenticates over REST before every WebSocket connection attempt so the browser can attach QuestDB's HttpOnly session cookies to the upgrade. Without a url, it targets /exec beside the endpoint being connected. Cannot be combined with auth.

Connection-scoped symbol dictionary deltas are the default; full opts out, so every frame carries its own dictionaries. UDP senders always use full.

Keep auto-flushed rows in an open server-side transaction. An explicit flush() closes the transaction. QWP transactions are atomic per table, rather than across every table in a multi-table flush.

Test or framework hook; defaults to the browser's global WebSocket. Under a client's cluster it is shared, and either side may override it.