Struct Reader 

pub struct Reader { /* private fields */ }

Per-connection reader. Owns the WebSocket transport and the connection-scoped symbol dictionary.

Implementations

impl Reader

pub fn from_conf<T: AsRef<str>>(conf: T) -> Result<Self>

Open a new connection from a connect string.

pub fn from_env() -> Result<Self>

Open a new connection from the config string stored in the QDB_CLIENT_CONF environment variable. Format matches Reader::from_conf.

pub fn from_config(cfg: &ReaderConfig) -> Result<Self>

Walk cfg.addrs via the per-client host-health tracker, opening the highest-priority unattempted endpoint and eagerly consuming the SERVER_INFO frame. Accepts the first endpoint whose role matches cfg.target. Returns:

• RoleMismatch if every endpoint connected but none advertised a matching role (last-seen role surfaced in the message).
• AuthError if at least one endpoint 401/403’d and every other endpoint failed too (per-endpoint accumulation lets the message name every endpoint that rejected credentials).
• SocketError if every endpoint failed at the transport layer (refused / timed out / TLS error / etc.).
• whatever the last attempt returned otherwise.

The initial connect deliberately does not apply the egress failover backoff schedule — it walks every address once and reports back. Mid-query failover (via Cursor::next_batch) is what uses failover_backoff_* to space retries.

The tracker is constructed fresh here, so every host starts at Unknown state and the priority-based pick degenerates to the user-supplied addr= order. From this Reader onward, the tracker accumulates classifications across Executes per the failover.md §2 priority lattice.

pub fn current_addr(&self) -> &Endpoint

The endpoint this connection is currently bound to. Borrowed from the configured address list, so the borrow lives as long as &self. Stable across connect-string reorderings, unlike the (deliberately not exposed) underlying address-list index.

pub fn bytes_received(&self) -> u64

Total wire bytes (frame header + payload) read off the transport since this connection was opened. Useful for benchmarking the effective throughput a query produces.

pub fn transport_torn_down(&self) -> bool

true when the underlying transport has been torn down (mid-stream cursor abandonment, fatal socket error, role-mismatch failover that couldn’t find a replacement). Pool return paths should treat such a reader as must-close.

pub fn credit_granted_total(&self) -> u64

Total bytes granted to the server via CREDIT (0x15) frames since this connection was opened. Useful for verifying that flow-control replenishment behaves as expected — in particular, that Cursor::cancel() doesn’t continue topping up the server’s budget while draining frames it’s about to discard.

pub fn read_ns(&self) -> u64

Diagnostic accumulator (nanoseconds): time spent in transport.read_frame(). Saturates at u64::MAX (~584 years). Reset to zero by Reader::reset_timing.

pub fn decode_ns(&self) -> u64

Diagnostic accumulator (nanoseconds): time spent in decode_frame(). Saturates at u64::MAX. Reset to zero by Reader::reset_timing.

pub fn reset_timing(&self)

Reset both read_ns and decode_ns accumulators to zero.

pub fn stats(&self) -> &Arc<ReaderStats>

Borrow the shared diagnostic counters. The FFI clones this at qwp_reader_from_conf time so its stat getters can read the counters without touching the UnsafeCell<Reader> that holds this Reader — eliminating the aliasing question of “what happens when a stat getter synthesises a &Reader while a laundered &mut Reader is in flight.”

pub fn server_info(&self) -> Option<&ServerInfo>

SERVER_INFO (0x18) captured at connect time. None only while a reconnect is in flight; the single QWP version always supplies it.

pub fn server_version(&self) -> Result<u8>

Negotiated QWP version this connection is using. Returns SocketError when the Reader is poisoned after a failed mid-query failover.

pub fn symbol_dict(&self) -> &SymbolDict

Connection-scoped symbol dictionary.

pub fn prepare<S: Into<String>>(&mut self, sql: S) -> ReaderQuery<'_>

Begin building a parametrised query. The returned ReaderQuery exclusively borrows the reader; only one in-flight cursor at a time. Append binds in placeholder order, then call .execute().

pub fn execute<S: Into<String>>(&mut self, sql: S) -> Result<Cursor<'_>>

Execute a SQL statement with no binds and return a streaming cursor. Convenience for self.prepare(sql).execute().