# Rust network client

The `ratdb-server` crate exports a synchronous client under `ratdb_server::client`. An authenticated connection owns a single navigation context. A borrowed den lets the compiler enforce that other code cannot navigate the same connection away from that den while it is in use.

```rust
use ratdb_server::client::Client;
use serde_json::json;
use std::net::SocketAddr;

fn store_car(address: SocketAddr, password: String) -> Result<(), Box<dyn std::error::Error>> {
    let mut session = Client::connect(address, "admin", password)?;
    let mut cars = session.warren("garage")?.den("cars")?;
    cars.put("car:001", json!({"make": "Ford"}))?;
    cars.update("car:001", json!({"year": 2021}))?;
    let matches = cars.find("make", json!("Ford"), 20)?;
    for car in matches.documents {
        println!("{}", car["id"]);
    }
    Ok(())
}
```

Use `insert` for a new ID and `get` for an optional document. `page(limit, after, filter)` returns documents, an examination count and a continuation ID. Continue until `next_after` is `None`, reusing the same filter and namespace. Consecutive pages see the current database contents. Dropping the session closes its socket.

`Error::Server` provides the server's error code and message. After an I/O error, reconnect, select the namespace and reconcile the result of any write with an uncertain outcome. The client accepts only loopback socket addresses. Forward remote servers using the SSH tunnel described in SERVER.md.

The TCP integration test runs with `cargo test -p ratdb-server client_facade`.

The Rust client enforces a five-minute deadline for each complete response frame. It checks frame length before allocating the body and closes the connection after a partial write or invalid reply envelope. Applications embedding the server can set complete authentication and command frame deadlines with `Server::with_frame_timeouts`; the defaults are 30 and 300 seconds.
`Den::get_versioned` and `Client::transaction` support [conditional atomic server writes](SERVER_TRANSACTIONS.md) in the development checkout. A generation_conflict leaves the connection available for a fresh read.