Crate feltdb_client

Expand description

§feltdb-client

A native async Rust client for a FeltDB server (feltdb-server): the Rust counterpart of @feltdb/core’s server runtime. It owns no state: every read and write is a request to the authority, which alone decides what commits.

use feltdb_client::{Client, Operation, Transaction};
use serde_json::json;

let client = Client::builder("http://127.0.0.1:7700")
    .token(std::env::var("FELTDB_TOKEN").unwrap_or_default())
    .build()?;

// Several records, one atomic commit. The id makes a retry safe: resubmitting it after an
// uncertain outcome is recognized as a duplicate, never applied twice.
let receipt = client
    .commit(
        &Transaction::new("ship-o-1")
            .operation(Operation::put("orders", "o-1", json!({ "status": "shipped" })))
            .operation(Operation::create("audit", "a-1", json!({ "order": "o-1" }))),
    )
    .await?;
assert!(!receipt.duplicate);

let order = client.get("orders", "o-1").await?;

§Two surfaces, as on the server

The authority (Client): records, atomic transactions with preconditions and read-basis fences, compare-and-set, the bounded query, the committed revision and the event stream. This is the direct authority surface: the routes @feltdb/core uses without an applicationId.
An application (Application, from Client::application): the canonical /v1 Service API, scoped to one application and environment and authorized against its contract: contract discovery, canonical queries, transactions, read bases, events and replay.
The control plane (Control, from Client::control): tenants, applications, the draft → revision → promotion lifecycle of an application’s contract, and online backup; and the server’s Client::health.

Anything else the server exposes is reachable with Client::request.

§Outcomes

A refusal is an Error::Api carrying the server’s stable code and, for a refused transaction, the structured PreconditionFailure. A write that was sent but not answered is Error::is_outcome_unknown: resubmit the same transaction id to learn what happened.

§Wire types

Request and response documents that the server defines in feltdb are used directly, so the two sides cannot disagree about a field: ReadSet, ReadBasis, PreconditionFailure and the canonical query and transaction types in wire. feltdb itself is re-exported at the exact version this client is built against.

Re-exports§

pub use feltdb;

Modules§

wire: The canonical application contract’s wire types, from feltdb::state_contract.

Structs§

ApiError: A refusal from the server, as its JSON error body describes it.
AppCommit: What a canonical transaction committed.
AppTransaction: A canonical transaction: operations and preconditions the application contract validates and authorizes, committed atomically.
Application: One application environment on a FeltDB server. Cheap to clone.
ApplicationInfo: The active contract of an application environment, as discovery reports it.
ApplicationRecord: An application as the control plane records it. Which revision an environment runs is crate::Application::discover’s to answer.
BoundedQuery: The bounded authority query: a page of at most limit records in a total order, with an opaque cursor for the next page. It never reads more than it returns plus what its plan requires.
CasRequest: A conditional update of one record.
Client: A connection to one FeltDB server. Cheap to clone; clones share the connection pool and token.
ClientBuilder: Configures a Client.
CommitReceipt: What the authority committed.
Condition: One where condition of a BoundedQuery.
Control: The control-plane routes, from Client::control. Cheap to clone.
EventStream: A live event stream: a delivery adapter over committed history, not the history itself.
Health: The server’s own health report (GET /health): liveness, build identity and subsystem status.
Method: The Request Method (VERB)
Operation: One write inside a Transaction.
Precondition: A condition on a record the transaction need not write, evaluated inside the commit.
Promotion: Moves an environment to a revision: Control::promote.
QueryPage: One page of a BoundedQuery.
ReadBasis: A read set and what the authority held for it at one moment.
ReadCondition
ReadPredicate
ReadRecord
ReadSet: State a decision was read from: records by identity, and equality predicates over a collection (every record of collection whose fields equal these values, including records that do not exist yet).
Record: A stored record.
ReplayPage: One page of committed history.
Revision: The committed revision of the authority, and the identity of the store that counted it.
ServerEvent: One server-sent event.
StateVersion: The application’s committed state version: Application::state_version.
Tenant: A tenant on the server.
Transaction: Several writes committed as one durable record, or not at all.

Enums§

CasConflict: Which predicate refused a compare-and-set.
CasOutcome: How a compare-and-set ended. A lost race is a value, not an error.
Direction: Sort direction.
Error: Everything a request can end in other than success.
PreconditionFailure: Which predicate failed, and what the authority actually holds.
TransactionStatus

Functions§

path_segment: Percent-encode one path segment or query value, for paths passed to Client::request. Identifiers such as revision ids may contain / and :, which must not reach the path raw.

Type Aliases§

Result