@feltdb/core 0.12.1 → 0.13.0

package/dist/create/server-source/crates/feltdb/tests/production_readiness_contract.rs

@@ -1020,19 +1020,25 @@ fn retention_cost_grows_with_the_window_and_inflates_the_log() {
 
     // Compare the best of repeated independent runs. The workspace executes
     // other crash/soak processes concurrently, so a single wall-clock sample
-    // can measure scheduler delay rather than retention work. Taking the
-    // minimum preserves the envelope claim while filtering that one-sided
-    // noise; every sample still performs the complete durable workload.
-    fn sample(run_once: impl Fn() -> (std::time::Duration, u64)) -> (std::time::Duration, u64) {
-        (0..3)
-            .map(|_| run_once())
-            .min_by_key(|(elapsed, _)| *elapsed)
-            .unwrap()
+    // can measure scheduler delay rather than retention work. The minimum
+    // filters that one-sided noise, but only if every configuration is sampled
+    // across the same stretch of time: sampling them one after another lets a
+    // busy sibling inflate one configuration's every sample and not another's.
+    // So each round runs all three, and each keeps its own best. Every sample
+    // still performs the complete durable workload.
+    let mut none = (std::time::Duration::MAX, 0u64);
+    let mut small = (std::time::Duration::MAX, 0u64);
+    let mut large = std::time::Duration::MAX;
+    for _ in 0..9 {
+        let sample = run(None);
+        if sample.0 < none.0 { none = sample; }
+        let sample = run(Some(5));
+        if sample.0 < small.0 { small = sample; }
+        large = large.min(run(Some(50)).0);
     }
-
-    let (none_time, none_bytes) = sample(|| run(None));
-    let (small_time, small_bytes) = sample(|| run(Some(5)));
-    let (large_time, _) = sample(|| run(Some(50)));
+    let (none_time, none_bytes) = none;
+    let (small_time, small_bytes) = small;
+    let large_time = large;
 
     assert!(
         large_time > small_time,

package/dist/create/server-source/crates/feltdb/tests/workload_envelope_contract.rs

@@ -215,14 +215,26 @@ fn a_barrier_per_write_costs_more_than_none() {
     let directory = TempDir::new().unwrap();
     let workload = WORKLOADS[0];
 
-    let flushed = run(directory.path(), workload, DurabilityMode::Flushed);
+    // A stall can only invert this ordering by inflating the cheap, flushed
+    // run, so take the best of several of those against one synced run. The
+    // minimum is the cost of the mode with scheduler contention taken out;
+    // repeating the slow synced run would only add load to sibling timing
+    // tests in this concurrently-run binary.
     let synced = run(directory.path(), workload, DurabilityMode::Synced);
+    let flushed = run(directory.path(), workload, DurabilityMode::Flushed);
+    let mut best_flushed = flushed.elapsed;
+    for sample in 0..4 {
+        // A fresh log per sample: a reused path would append to its history.
+        let sample_directory = directory.path().join(format!("flushed-{sample}"));
+        std::fs::create_dir_all(&sample_directory).unwrap();
+        let repeat = run(&sample_directory, workload, DurabilityMode::Flushed);
+        best_flushed = best_flushed.min(repeat.elapsed);
+    }
 
     assert!(
-        synced.elapsed > flushed.elapsed,
-        "a barrier per write must cost something: synced {:?} vs flushed {:?}",
-        synced.elapsed,
-        flushed.elapsed
+        synced.elapsed > best_flushed,
+        "a barrier per write must cost something: synced {:?} vs flushed {best_flushed:?}",
+        synced.elapsed
     );
 
     // Durability is the only thing that changed. The database is identical.

package/dist/create/server-source/crates/feltdb-client/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "feltdb-client"
+version.workspace = true
+edition.workspace = true
+# The oldest toolchain CI builds and tests this workspace with (.github/workflows/ci.yml).
+rust-version = "1.96"
+description = "Native async Rust client for a FeltDB server: records, atomic and idempotent transactions, compare-and-set, bounded queries, read-basis fences, events, and the canonical application API"
+license = "MIT"
+repository = "https://github.com/rkendel1/flow_db"
+readme = "README.md"
+keywords = ["database", "client", "transactions", "feltdb", "http"]
+categories = ["database", "api-bindings", "asynchronous"]
+exclude = ["tests/", "target/"]
+
+[dependencies]
+# The wire types are the server's own: the request and response documents are defined once, in
+# `feltdb`, and both sides serialize the same structs. Exact, because the modules they come from are
+# not yet covered by `feltdb`'s compatibility policy; the workspace releases both at one version.
+feltdb = { version = "=0.2.2", path = "../feltdb" }
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+uuid = { version = "1.6", features = ["v4"] }
+
+[dev-dependencies]
+serde_json = "1"
+tokio = { version = "1", features = ["io-util", "macros", "net", "rt-multi-thread"] }
+# A TLS server for the private-CA test; the same rustls reqwest uses.
+tokio-rustls = { version = "0.26", default-features = false, features = ["ring", "tls12"] }

package/dist/create/server-source/crates/feltdb-client/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FeltDB Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/create/server-source/crates/feltdb-client/README.md

@@ -0,0 +1,70 @@
+# feltdb-client
+
+A native async Rust client for a [FeltDB](https://github.com/rkendel1/flow_db) server: the Rust
+counterpart of `@feltdb/core`'s server runtime. It holds no state of its own; the server is the
+authority for every read and write.
+
+```toml
+[dependencies]
+feltdb-client = "0.2"
+serde_json = "1"
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+```
+
+```rust
+use feltdb_client::{Client, Operation, Precondition, Transaction};
+use serde_json::json;
+
+#[tokio::main]
+async fn main() -> feltdb_client::Result<()> {
+    let client = Client::builder("http://127.0.0.1:7700")
+        .token(std::env::var("FELTDB_TOKEN").unwrap_or_default())
+        .build()?;
+
+    // One atomic commit. The id makes a retry after an uncertain outcome safe.
+    let tx = Transaction::new("ship-o-1")
+        .operation(Operation::put("orders", "o-1", json!({ "status": "shipped" })).expect_version(1))
+        .operation(Operation::create("audit", "a-1", json!({ "order": "o-1" })))
+        .precondition(Precondition::absent("locks", "o-1"));
+    match client.commit(&tx).await {
+        Ok(receipt) => println!("committed at revision {}", receipt.commit_revision),
+        Err(error) if error.is_conflict() => println!("lost a race: {:?}", error.precondition_failure()),
+        Err(error) if error.is_outcome_unknown() => { /* resubmit `tx` unchanged */ }
+        Err(error) => return Err(error),
+    }
+    Ok(())
+}
+```
+
+## What it covers
+
+| Server surface | Client |
+| --- | --- |
+| Records: `GET/POST /collections/…`, `PATCH`, `DELETE` | `get`, `list`, `create`, `update`, `delete` |
+| Atomic, idempotent transactions with preconditions and fences: `POST /transactions` | `commit` with `Transaction`, `Operation`, `Precondition` |
+| Read bases: `POST /transactions/read-basis` | `read_basis`, then `Transaction::fence` |
+| Compare-and-set: `POST /collections/{c}/{id}/cas` | `compare_and_set` → `CasOutcome` |
+| Bounded query: `POST /query` | `query` with `BoundedQuery` |
+| Committed revision: `GET /revision` | `revision` |
+| Live events: `GET /events` (SSE) | `events` → `EventStream` |
+| Canonical application API under `/v1` | `client.application(id)`: `discover`, `query`, `commit` (per-operation `if_version` via `update_if_version`/`delete_if_version`), `read_basis`, `events`, `replay`, `provenance`, `sign_in`/`sign_up`/`session`/`sign_out` |
+| Committed state version: `GET /v1/state/version` | `application.state_version()` |
+| Control plane: `/api/tenants`, `/api/applications/…` drafts, revisions, promotion; `POST /admin/backups` | `client.control()`: `create_tenant`, `create_application`, `create_draft`, `update_draft`, `validate_draft`, `commit_draft`, `revision`, `promote`, `backup` |
+| Health: `GET /health` | `health` |
+| Capability discovery | `capabilities` |
+| Anything else | `request(Method, path, body)` |
+
+Errors carry the server's stable `code`, its `request_id`, and for a refused transaction the
+structured `PreconditionFailure`. The canonical query and transaction documents are `feltdb`'s
+own types (re-exported under `feltdb_client::wire`), so the client and server serialize the same
+structs.
+
+A server behind a private CA is trusted with
+`Client::builder(url).add_root_certificate_pem(pem)`, in addition to the bundled public roots; verification is never
+disabled.
+
+The event stream does not reconnect by itself; reopen it from `EventStream::last_event_id()`.
+For an embedded store in your own process, use the [`feltdb`](https://crates.io/crates/feltdb)
+crate instead; to run the server, `cargo install feltdb-server`.
+
+License: MIT.