Client API Reference
Complete reference for NerveClient, NerveConfig, SchemaId, and SdkMetrics.
NerveClient Methods
| Method | Signature | Description |
|---|---|---|
| connect | async fn connect(config: NerveConfig) -> NerveResult<Self> | TLS 1.3 handshake probe + spawn background worker |
| send_raw | fn send_raw(schema: SchemaId, payload: &[u8]) -> NerveResult<()> | Non-blocking send (~50 ns). Spills to disk if queue full. |
| send_priority | fn send_priority(schema, payload, priority) -> NerveResult<()> | Explicit priority: Critical bypasses batching. |
| send | fn send<T: FlatBufferSerializable>(data: &T) -> NerveResult<()> | Typed convenience: auto-extracts schema ID and serializes. |
| set_command_handler | fn set_command_handler(handler: impl CommandHandler) | Register bidirectional command handler. |
| queue_depth | fn queue_depth() -> usize | In-memory channel depth (excludes spill). |
| spill_depth | fn spill_depth() -> u64 | Messages persisted on disk. |
| metrics | fn metrics() -> &Arc<SdkMetrics> | Access atomic counters. |
| is_connected | fn is_connected() -> bool | False after shutdown or worker exit. |
| shutdown | async fn shutdown(self, timeout: Duration) -> NerveResult<usize> | Drain remaining. Returns unflushed count (0 = fully flushed). |
NerveConfig
See Transport Layer for the full config table, TLS options, and workload tuning guide.
SchemaId
Content-addressed 32-bit identifier: first 4 bytes of SHA-256 of the schema content.
| Constructor | Description |
|---|---|
| SchemaId::new(u32) | From a known numeric ID |
| SchemaId::from_bytes(&[u8]) | Hash arbitrary bytes and truncate to 4 bytes |
| SchemaId::from_file(&Path) | Read file, hash contents |
Display format: zero-padded lowercase hex (e.g. "00000002"). Birthday collision: ~65,536 schemas before meaningful probability.
SdkMetrics
Seven atomic u64 counters, accessible from any thread. Use metrics().snapshot() to export all as (name, value) pairs for Prometheus or StatsD.
| Counter | Incremented when |
|---|---|
| messages_sent | send_raw succeeds (queued or spilled) |
| messages_dropped | Channel disconnected (worker dead) |
| messages_spilled | Channel full → spilled to disk |
| bytes_sent | Compressed bytes written to QUIC |
| batch_flushes | Each batch written to a QUIC stream |
| reconnect_count | Worker reconnect attempt |
| circuit_opens | Circuit breaker enters Open state |
Error Types
| Error | When | Recovery |
|---|---|---|
| QueueFull | Channel and spill both at capacity | Rare — increase queue_capacity or max_disk_bytes |
| Disconnected | Background worker terminated | Create a new NerveClient |
| HandshakeTimeout | TLS handshake exceeded deadline | Check network, increase connect_timeout_ms |
| TlsValidation | Certificate verification failed | Check ca_cert_path or use insecure() for dev |
| ConnectionRefused | Server unreachable | Check endpoint, firewall, server status |
| StreamClosed | QUIC stream reset | Auto-reconnects (no user action needed) |
Authentication
Two authentication modes:
- Static API Key: Configured in
AuthConfig.api_key. Sent as an auth frame after each QUIC handshake. - Token Provider: Implement
TokenProvidertrait for rotating JWT, HMAC, or HSM-backed auth. Register viaQuicConnector::with_auth().
Auth frame wire format:
Text
[magic: u16 LE = 0xA077][token_len: u16][token: bytes][device_id_len: u16][device_id: bytes]Questions?
Reach out for help with integration, deployment, or custom domain codecs.