Struct LanceClient 

pub struct LanceClient { /* private fields */ }

LANCE protocol client for communicating with LANCE servers

Provides methods for ingesting data, managing topics, and consuming records.

Implementations

impl LanceClient

pub async fn connect(config: ClientConfig) -> Result<Self, ClientError>

Connect to LANCE server, automatically using TLS if configured

The address in the config can be either an IP:port or hostname:port. DNS resolution is performed automatically for hostnames.

pub async fn connect_tls( config: ClientConfig, tls_config: TlsClientConfig, ) -> Result<Self, ClientError>

Connect to LANCE server with TLS encryption

Arguments

• config - Client configuration with server address (IP:port or hostname:port)
• tls_config - TLS configuration including certificates

Example

use lnc_client::{ClientConfig, TlsClientConfig, LanceClient};

let config = ClientConfig::new("lance.example.com:1992");
let tls = TlsClientConfig::new()
    .with_ca_cert("/path/to/ca.pem");

let client = LanceClient::connect_tls(config, tls).await?;

pub async fn connect_to(addr: &str) -> Result<Self, ClientError>

Connect to a LANCE server using an address string

The address can be either an IP:port (e.g., “127.0.0.1:1992”) or a hostname:port (e.g., “lance.example.com:1992”).

pub async fn connect_tls_to( addr: &str, tls_config: TlsClientConfig, ) -> Result<Self, ClientError>

Connect to LANCE server with TLS using address string

The address can be either an IP:port (e.g., “127.0.0.1:1992”) or a hostname:port (e.g., “lance.example.com:1992”).

pub async fn send_ingest( &mut self, payload: Bytes, record_count: u32, ) -> Result<u64, ClientError>

Sends an ingest frame to the default topic (ID 0) while preserving the Architecture §22 write-buffering guarantees.

Arguments

• payload - Record batch encoded using the zero-copy LWP format.
• record_count - Logical record total encoded in the frame header.

Returns

• Result<u64> - Server-assigned batch identifier for the frame.

Errors

Propagates ClientError::Timeout when the write exceeds the configured deadline or any framing/connection error surfaced by Tokio.

pub async fn send_ingest_to_topic( &mut self, topic_id: u32, payload: Bytes, record_count: u32, _auth_config: Option<&AuthConfig>, ) -> Result<u64, ClientError>

Sends an ingest frame to a specific topic while attaching metadata required by Architecture §22’s deferred flush/ack scheme.

Arguments

• topic_id - Destination topic identifier.
• payload - Zero-copy encoded batch.
• record_count - Logical records contained in payload.
• _auth_config - Optional future hook for per-request auth context.

Returns

• Result<u64> - Batch identifier allocated by the client monotonic counter and echoed back by the server.

pub async fn send_ingest_sync( &mut self, payload: Bytes, record_count: u32, ) -> Result<u64, ClientError>

Sends an ingest request to the default topic and waits for the corresponding acknowledgment, mirroring Architecture §22.3 sync gates.

Arguments

• payload - Ingest batch to transmit.
• record_count - Logical record total for metrics validation.

Returns

• Result<u64> - The acked batch identifier if the server confirms the write succeeded.

pub async fn send_ingest_to_topic_sync( &mut self, topic_id: u32, payload: Bytes, record_count: u32, auth_config: Option<&AuthConfig>, ) -> Result<u64, ClientError>

Sends an ingest request to a topic and blocks for server acknowledgment so callers can enforce durability or backpressure decisions inline.

Arguments

• topic_id - Destination topic.
• payload - Zero-copy loaner buffer to transmit.
• record_count - Logical records contained in the batch.
• auth_config - Optional per-request authentication context.

Returns

• Result<u64> - The acked batch identifier, ensuring sequencing with downstream consumers.

pub async fn recv_ack(&mut self) -> Result<u64, ClientError>

Receives the next acknowledgment frame and translates server feedback (ack, backpressure, or error) into structured ClientError variants.

Returns

• Result<u64> - Acked batch identifier if the server confirmed success.

Errors

Surfaces ClientError::ServerBackpressure or ClientError::InvalidResponse when the frame type deviates from the Architecture §22 control flow expectations.

pub async fn send_keepalive(&mut self) -> Result<(), ClientError>

Sends a keepalive frame so long-lived clients satisfy Architecture §9.4 drain/force-exit requirements and keep connection state fresh.

Returns

• Result<()> - Ok when the frame is flushed before the configured write timeout expires.

pub async fn recv_keepalive(&mut self) -> Result<(), ClientError>

Waits for a keepalive response, guaranteeing the control-plane path is still healthy per Architecture §9.4 monitoring requirements.

Returns

• Result<()> - Ok when the server replies with FrameType::Keepalive.

Errors

Returns ClientError::InvalidResponse when any other frame type arrives, signaling connection drift.

pub async fn ping(&mut self) -> Result<Duration, ClientError>

Ping the server and measure round-trip latency

pub async fn create_topic( &mut self, name: &str, ) -> Result<TopicInfo, ClientError>

Create a new topic with the given name

pub async fn ensure_topic( &mut self, name: &str, max_attempts: usize, base_backoff_ms: u64, ) -> Result<TopicInfo, ClientError>

Ensure a topic exists and return its metadata.

This helper encapsulates common create/list convergence retry behavior so application callers (bench/chaos) can stay simple.

pub async fn ensure_topic_default( &mut self, name: &str, ) -> Result<TopicInfo, ClientError>

Ensure topic with standard retry profile suitable for benchmark/chaos tools.

pub async fn list_topics(&mut self) -> Result<Vec<TopicInfo>, ClientError>

List all topics on the server

pub async fn get_topic( &mut self, topic_id: u32, ) -> Result<TopicInfo, ClientError>

Get information about a specific topic

pub async fn delete_topic(&mut self, topic_id: u32) -> Result<(), ClientError>

Delete a topic by its ID

pub async fn set_retention( &mut self, topic_id: u32, max_age_secs: u64, max_bytes: u64, ) -> Result<(), ClientError>

Sets the retention policy for an existing topic, mirroring the configuration model documented in Architecture §12.7.

Arguments

• topic_id - Topic identifier
• max_age_secs - Maximum age in seconds (0 = no limit)
• max_bytes - Maximum size in bytes (0 = no limit)

pub async fn create_topic_with_retention( &mut self, name: &str, max_age_secs: u64, max_bytes: u64, ) -> Result<TopicInfo, ClientError>

Create a topic with retention policy in a single operation

Arguments

• name - Topic name
• max_age_secs - Maximum age in seconds (0 = no limit)
• max_bytes - Maximum size in bytes (0 = no limit)

pub async fn get_cluster_status(&mut self) -> Result<ClusterStatus, ClientError>

Get cluster status and health information

pub async fn fetch( &mut self, topic_id: u32, start_offset: u64, max_bytes: u32, ) -> Result<FetchResult, ClientError>

Fetch data from a topic starting at the given offset Returns (data, next_offset, record_count)

pub async fn subscribe( &mut self, topic_id: u32, start_offset: u64, max_batch_bytes: u32, consumer_id: u64, ) -> Result<SubscribeResult, ClientError>

Subscribes to a topic for streaming consumption, honoring the consumer coordination model described in Architecture §20.

Arguments

• topic_id - Topic to follow.
• start_offset - First logical offset to deliver.
• max_batch_bytes - Maximum payload size per delivery window.
• consumer_id - Stable consumer identifier for server-side tracking.

Returns

• Result<SubscribeResult> - Contains the confirmed consumer_id and start offset granted by the server.

Errors

Surfaces timeouts, protocol violations, or server error frames (e.g., ControlCommand::ErrorResponse).

pub async fn unsubscribe( &mut self, topic_id: u32, consumer_id: u64, ) -> Result<(), ClientError>

Unsubscribes a consumer from a topic, ensuring server resources are reclaimed per Architecture §20’s consumer lifecycle.

Arguments

• topic_id - Topic to leave.
• consumer_id - Consumer identifier provided during subscribe.

Returns

• Result<()> - Ok when the server acknowledges the unsubscribe.

Errors

Propagates ClientError::ServerError if the server rejects the request or ClientError::InvalidResponse if a non-ack frame arrives.

pub async fn commit_offset( &mut self, topic_id: u32, consumer_id: u64, offset: u64, ) -> Result<CommitResult, ClientError>

Commit consumer offset for checkpointing

pub fn config(&self) -> &ClientConfig

Get a reference to the client configuration

pub async fn close(self) -> Result<(), ClientError>

Close the client connection

Trait Implementations

impl Debug for LanceClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.