@feltdb/core 0.12.1 → 0.12.2

package/dist/create/server-source/crates/feltdb-client/src/lib.rs

@@ -0,0 +1,466 @@
+//! # 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.
+//!
+//! ```no_run
+//! use feltdb_client::{Client, Operation, Transaction};
+//! use serde_json::json;
+//!
+//! # async fn run() -> feltdb_client::Result<()> {
+//! 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?;
+//! # let _ = order;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! ## 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.
+
+mod application;
+mod authority;
+mod control;
+mod error;
+mod events;
+
+use std::{
+    sync::{Arc, RwLock},
+    time::Duration,
+};
+
+use serde::{de::DeserializeOwned, Serialize};
+use serde_json::Value;
+
+pub use application::{
+    AppCommit, AppTransaction, Application, ApplicationInfo, ReplayPage, StateVersion,
+};
+pub use authority::{
+    BoundedQuery, CasConflict, CasOutcome, CasRequest, CommitReceipt, Condition, Direction,
+    Operation, Precondition, QueryPage, Record, Revision, Transaction,
+};
+pub use control::{ApplicationRecord, Control, Health, Promotion, Tenant};
+pub use error::{ApiError, Error, Result};
+pub use events::{EventStream, ServerEvent};
+pub use feltdb;
+pub use feltdb::{
+    PreconditionFailure, ReadBasis, ReadCondition, ReadPredicate, ReadRecord, ReadSet,
+    TransactionStatus,
+};
+pub use reqwest::Method;
+
+/// The canonical application contract's wire types, from `feltdb::state_contract`.
+pub mod wire {
+    pub use feltdb::state_contract::{
+        AggregateDefinition, AggregateFunction, CanonicalQuery, QueryFilter, QueryOrder,
+        QueryReference, QueryResult, SortDirection, TransactionOperation, TransactionOperationKind,
+        TransactionPrecondition, TransactionResult,
+    };
+}
+
+/// The protocol version this client speaks; the server refuses one it does not.
+const PROTOCOL_VERSION: &str = "1";
+const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
+
+/// Which authority a request is addressed to, for servers that host several tenants.
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum AuthorityScope {
+    Tenant {
+        tenant_id: String,
+        environment_id: Option<String>,
+    },
+    Platform,
+}
+
+/// Configures a [`Client`].
+#[derive(Debug, Clone)]
+pub struct ClientBuilder {
+    url: String,
+    token: Option<String>,
+    scope: Option<AuthorityScope>,
+    timeout: Duration,
+    root_certificates: Vec<Vec<u8>>,
+}
+
+impl ClientBuilder {
+    /// Authenticate with a bearer token: an API key from `feltdb-server keys create`, or an
+    /// application session's access token.
+    pub fn token(mut self, token: impl Into<String>) -> Self {
+        let token = token.into();
+        self.token = (!token.is_empty()).then_some(token);
+        self
+    }
+
+    /// Bind every request to one tenant. A request the server resolves to another tenant is refused
+    /// with `AUTHORITY_SCOPE_MISMATCH` instead of being served.
+    pub fn tenant(mut self, tenant_id: impl Into<String>) -> Self {
+        self.scope = Some(AuthorityScope::Tenant {
+            tenant_id: tenant_id.into(),
+            environment_id: None,
+        });
+        self
+    }
+
+    /// Bind every request to one tenant and one of its environments.
+    pub fn tenant_environment(
+        mut self,
+        tenant_id: impl Into<String>,
+        environment_id: impl Into<String>,
+    ) -> Self {
+        self.scope = Some(AuthorityScope::Tenant {
+            tenant_id: tenant_id.into(),
+            environment_id: Some(environment_id.into()),
+        });
+        self
+    }
+
+    /// Address the platform authority rather than a tenant's.
+    pub fn platform(mut self) -> Self {
+        self.scope = Some(AuthorityScope::Platform);
+        self
+    }
+
+    /// How long one request may take before it is abandoned (30 seconds by default). Event streams
+    /// are exempt: they stay open until closed.
+    pub fn timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = timeout;
+        self
+    }
+
+    /// Trust a PEM certificate authority in addition to the bundled public roots, for a server
+    /// whose certificate a private CA issued. Certificate verification is never disabled. A PEM
+    /// that does not parse is refused by [`ClientBuilder::build`].
+    pub fn add_root_certificate_pem(mut self, pem: impl Into<Vec<u8>>) -> Self {
+        self.root_certificates.push(pem.into());
+        self
+    }
+
+    pub fn build(self) -> Result<Client> {
+        let url = self.url.trim_end_matches('/').to_owned();
+        let parsed = reqwest::Url::parse(&url)
+            .map_err(|error| Error::InvalidRequest(format!("server URL {url:?}: {error}")))?;
+        if !matches!(parsed.scheme(), "http" | "https") {
+            return Err(Error::InvalidRequest(format!(
+                "server URL {url:?} must be http or https"
+            )));
+        }
+        let mut http = reqwest::Client::builder();
+        for pem in &self.root_certificates {
+            // `Certificate::from_pem` accepts anything and adds nothing for input that holds no
+            // certificate; parse the bundle so a wrong file is refused here, not at a handshake.
+            let certificates = reqwest::Certificate::from_pem_bundle(pem)
+                .ok()
+                .filter(|certificates| !certificates.is_empty())
+                .ok_or_else(|| {
+                    Error::InvalidRequest("root certificate is not a PEM certificate".into())
+                })?;
+            for certificate in certificates {
+                http = http.add_root_certificate(certificate);
+            }
+        }
+        let http = http
+            .build()
+            .map_err(|source| Error::transport(source, false))?;
+        Ok(Client {
+            inner: Arc::new(Inner {
+                http,
+                url,
+                token: RwLock::new(self.token),
+                scope: self.scope,
+                timeout: self.timeout,
+            }),
+        })
+    }
+}
+
+struct Inner {
+    http: reqwest::Client,
+    url: String,
+    token: RwLock<Option<String>>,
+    scope: Option<AuthorityScope>,
+    timeout: Duration,
+}
+
+/// A connection to one FeltDB server. Cheap to clone; clones share the connection pool and token.
+#[derive(Clone)]
+pub struct Client {
+    inner: Arc<Inner>,
+}
+
+impl std::fmt::Debug for Client {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Client")
+            .field("url", &self.inner.url)
+            .field("scope", &self.inner.scope)
+            .finish_non_exhaustive()
+    }
+}
+
+impl Client {
+    /// Start configuring a client for the server at `url`, e.g. `http://127.0.0.1:7700`.
+    pub fn builder(url: impl Into<String>) -> ClientBuilder {
+        ClientBuilder {
+            url: url.into(),
+            token: None,
+            scope: None,
+            timeout: DEFAULT_TIMEOUT,
+            root_certificates: Vec::new(),
+        }
+    }
+
+    /// The server URL, without a trailing slash.
+    pub fn url(&self) -> &str {
+        &self.inner.url
+    }
+
+    /// Replace the bearer token (or clear it with an empty string) for this client and its clones.
+    pub fn set_token(&self, token: impl Into<String>) {
+        let token = token.into();
+        *self
+            .inner
+            .token
+            .write()
+            .unwrap_or_else(|poisoned| poisoned.into_inner()) =
+            (!token.is_empty()).then_some(token);
+    }
+
+    /// A handle on one application's canonical Service API, in its `production` environment
+    /// unless [`Application::environment`] says otherwise.
+    pub fn application(&self, application_id: impl Into<String>) -> Application {
+        Application::new(self.clone(), application_id.into())
+    }
+
+    /// Any server route, for what this client does not name. `path` starts with `/` and may carry
+    /// a query string. An empty success (`204`) is `Value::Null`.
+    pub async fn request<B: Serialize + ?Sized>(
+        &self,
+        method: Method,
+        path: &str,
+        body: Option<&B>,
+    ) -> Result<Value> {
+        self.send(method, path, body).await
+    }
+
+    /// [`Client::request`] with extra headers, e.g. a route's `if-version` precondition.
+    pub async fn request_with_headers<B: Serialize + ?Sized>(
+        &self,
+        method: Method,
+        path: &str,
+        headers: &[(&str, &str)],
+        body: Option<&B>,
+    ) -> Result<Value> {
+        self.send_with_headers(method, path, headers, body).await
+    }
+
+    async fn send_with_headers<T: DeserializeOwned, B: Serialize + ?Sized>(
+        &self,
+        method: Method,
+        path: &str,
+        headers: &[(&str, &str)],
+        body: Option<&B>,
+    ) -> Result<T> {
+        let mutating = !matches!(method, Method::GET | Method::HEAD | Method::OPTIONS);
+        let mut builder = self.builder_for(method, path).timeout(self.inner.timeout);
+        for (name, value) in headers {
+            builder = builder.header(*name, *value);
+        }
+        if let Some(body) = body {
+            builder = builder.json(body);
+        }
+        let response = self.respond(builder, mutating).await?;
+        decode(response, mutating).await
+    }
+
+    fn builder_for(&self, method: Method, path: &str) -> reqwest::RequestBuilder {
+        let mut builder = self
+            .inner
+            .http
+            .request(method, format!("{}{path}", self.inner.url))
+            .header("FeltDB-Protocol", PROTOCOL_VERSION);
+        if let Some(token) = self
+            .inner
+            .token
+            .read()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+            .as_deref()
+        {
+            builder = builder.bearer_auth(token);
+        }
+        match &self.inner.scope {
+            Some(AuthorityScope::Tenant {
+                tenant_id,
+                environment_id,
+            }) => {
+                builder = builder.header("FeltDB-Tenant-Id", tenant_id);
+                if let Some(environment_id) = environment_id {
+                    builder = builder.header("FeltDB-Environment-Id", environment_id);
+                }
+            }
+            Some(AuthorityScope::Platform) => {
+                builder = builder.header("FeltDB-Authority-Mode", "platform");
+            }
+            None => {}
+        }
+        builder
+    }
+
+    /// Send a request and return the raw response, mapping a refusal to [`Error::Api`].
+    async fn exchange<B: Serialize + ?Sized>(
+        &self,
+        method: Method,
+        path: &str,
+        body: Option<&B>,
+    ) -> Result<reqwest::Response> {
+        let mutating = !matches!(method, Method::GET | Method::HEAD | Method::OPTIONS);
+        let mut builder = self.builder_for(method, path).timeout(self.inner.timeout);
+        if let Some(body) = body {
+            builder = builder.json(body);
+        }
+        self.respond(builder, mutating).await
+    }
+
+    async fn respond(
+        &self,
+        builder: reqwest::RequestBuilder,
+        mutating: bool,
+    ) -> Result<reqwest::Response> {
+        let response = builder
+            .send()
+            .await
+            .map_err(|source| Error::transport(source, mutating))?;
+        if response.status().is_success() {
+            return Ok(response);
+        }
+        let status = response.status().as_u16();
+        let text = response
+            .text()
+            .await
+            .map_err(|source| Error::transport(source, mutating))?;
+        Err(Error::Api(Box::new(ApiError::from_body(status, &text))))
+    }
+
+    async fn send<T: DeserializeOwned, B: Serialize + ?Sized>(
+        &self,
+        method: Method,
+        path: &str,
+        body: Option<&B>,
+    ) -> Result<T> {
+        let mutating = !matches!(method, Method::GET | Method::HEAD | Method::OPTIONS);
+        let response = self.exchange(method, path, body).await?;
+        decode(response, mutating).await
+    }
+
+    async fn open_events(&self, path: &str, cursor: Option<&str>) -> Result<EventStream> {
+        let mut builder = self.builder_for(Method::GET, path);
+        if let Some(cursor) = cursor {
+            builder = builder.header("Last-Event-ID", cursor);
+        }
+        let response = builder
+            .send()
+            .await
+            .map_err(|source| Error::transport(source, false))?;
+        if !response.status().is_success() {
+            let status = response.status().as_u16();
+            let text = response
+                .text()
+                .await
+                .map_err(|source| Error::transport(source, false))?;
+            return Err(Error::Api(Box::new(ApiError::from_body(status, &text))));
+        }
+        Ok(EventStream::new(response, cursor.map(str::to_owned)))
+    }
+}
+
+async fn decode<T: DeserializeOwned>(response: reqwest::Response, mutating: bool) -> Result<T> {
+    let status = response.status().as_u16();
+    let bytes = response
+        .bytes()
+        .await
+        .map_err(|source| Error::transport(source, mutating))?;
+    let bytes: &[u8] = if bytes.is_empty() { b"null" } else { &bytes };
+    serde_json::from_slice(bytes).map_err(|source| Error::Decode { status, source })
+}
+
+/// 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.
+pub fn path_segment(value: &str) -> String {
+    encode(value)
+}
+
+fn encode(value: &str) -> String {
+    let mut out = String::with_capacity(value.len());
+    for byte in value.bytes() {
+        if byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b'~') {
+            out.push(byte as char);
+        } else {
+            out.push_str(&format!("%{byte:02X}"));
+        }
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn path_segments_are_encoded() {
+        assert_eq!(encode("o-1"), "o-1");
+        assert_eq!(encode("a/b c:é"), "a%2Fb%20c%3A%C3%A9");
+    }
+
+    #[test]
+    fn a_url_that_is_not_http_is_refused() {
+        assert!(matches!(
+            Client::builder("ftp://example.com").build(),
+            Err(Error::InvalidRequest(_))
+        ));
+        assert_eq!(
+            Client::builder("http://127.0.0.1:7700/")
+                .build()
+                .unwrap()
+                .url(),
+            "http://127.0.0.1:7700"
+        );
+    }
+}

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

@@ -0,0 +1,4 @@
+Test-only TLS material for `tests/private_ca.rs`: a throwaway certificate authority
+(`private-ca.pem`) and a `localhost` / `127.0.0.1` server certificate it signed
+(`server.pem`, key `server-key.pem`). The CA's own key was discarded after signing.
+Nothing here protects anything; `tests/` is excluded from the published crate.

package/dist/create/server-source/crates/feltdb-client/tests/fixtures/private-ca.pem

@@ -0,0 +1,20 @@
+-----BEGIN CERTIFICATE-----
+MIIDQzCCAiugAwIBAgIUEo4ejwkWMTqDDfYQV4Y+0q94nQswDQYJKoZIhvcNAQEL
+BQAwKDEmMCQGA1UEAwwdZmVsdGRiLWNsaWVudCB0ZXN0IHByaXZhdGUgQ0EwIBcN
+MjYxMDIyMDQxMDI0WhgPMjEyNjA5MjgwNDEwMjRaMCgxJjAkBgNVBAMMHWZlbHRk
+Yi1jbGllbnQgdGVzdCBwcml2YXRlIENBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A
+MIIBCgKCAQEAmlEZ5GPlHa/RoaNGIPG10zIhIUfIzeNLoXtVlov+mYwxl587dlN1
+r9NVuDa03zxD4C/gFiJ3uhnx4D7XYZmv1KmGpMe9TkuwwTQdUzNAW77HR4zhZJ63
+gjJmR9vuFh3ZSZz/4Obo/q7sw9LlioeeBBGuHPSomlX6tJhxbE9RrccwXiJhogZq
+JesAVg1zE3+X8pc/yqxjGR/odCNLS0K0IZdryWAtCgA4jaEBbPZsSdijxVvE8Z7T
+4oT/ayLcDnBS7RZrEiLlXFnMd7NFxEeVH0Vst1tVJWmysNsZDv6X425KZV+oXK7q
+lSVjL1TnDqsffiATYGW2NaJh2mHoCFlztwIDAQABo2MwYTAdBgNVHQ4EFgQUPtQZ
+FXUMMOsq8/kYn4D00tqjhEMwHwYDVR0jBBgwFoAUPtQZFXUMMOsq8/kYn4D00tqj
+hEMwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8EBAMCAQYwDQYJKoZIhvcNAQEL
+BQADggEBAGVcmYj9eaptKeS9q97S0wWquC4nhhvTPY86lTcFCakaWd/ZfQOqZRkj
+6ayeYv3AyvN6YtGjc3DghiKjhAgvUcNg0py+zW2388bDBfVbLF6SDEuY2g/NKDSJ
+UN2L687WjX6ibGpoEUpl9uZ8cL/ifpAml6IUqVv4MoIX0yvYwOwDQR/dWp+FRLx1
+7Rf42Xq1ITEs+leLevzGEkADOL2HN5Iixk2IBWQnUqHXz5jacJGS/Lza59ZMOjYQ
+dUQlB0XCfkfvF52HZ8VLKkGM5WfCRn4zg9FdvTpRO9fUhFjspKXLxFDguI4rO+sX
+O4MKHOHuPrr4aOxmHdGbQhj/SfhBX0A=
+-----END CERTIFICATE-----

package/dist/create/server-source/crates/feltdb-client/tests/fixtures/server-key.pem

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC2iuw6lydSsT61
+7poW0kIYR5CU4O5q9UC25z5EZxprIZzwMH+9nmmvjxJIkuIS9D+abxJxsKcTubvS
+1R33kI+aR9h3WpYECC4/8NatMbHts2MRrVbb7U/AfddQG6WJLPuC+8+CdssxTprM
+ZL6aGGYRzd3EVCVqX+1MvQiWn9l9W4laW7jLQJwPeAfzHvy96d9BG/ZpIn3O5ue1
+m0nxX2x1T7DNkp5JSqM7oxIwNcumImg1l3qUpKPDrTBE/L2CqitqLVoE3GxWIsiY
+OtSwkwEM/Va69T/kX5G6Ii0O78ehRKi05WEU1ZxMDpE30psCnxCYoh2sIW5uQakk
+rmjnRKQfAgMBAAECggEASv1ZPFyaJ+tukrjZjmSECItlxvN8nm3wTvNCbkFY5gfh
++/5Ai/pG+nsxDKViwFycwGm+zvu+N2lG0r8AV5KIm93F/Io3NKLTtSrQVkgjCz51
+hW6LTz/3UmGgEWW6JFdZX57oyXTZ1oCvMSZ18sHxNIE5CI107XVI/AxwOcijRU6g
+rrIxAhszZ46NddnvGWvLuOmIJeOdc75xzGUUAGrBtT+IMfqCn+7gliLxNm1DEImG
+Lse+KJau/4YPtSM/tA7ra2AEGYTBTDwiQePZdfSHweez6W/58qqXK6+nM101lrXt
+kZmpgCyngsgHN/Ywyxr7y0MEHexWgqHYtRQRu1lIuQKBgQD8JdrT9n0hM4sTe3sk
+Ndek2oU7Wnv3zprhrdXujLnJQ9J+rkEJ25lmG/6uSts7zXtmEcj8Jip7KxKBnfue
+7MhipX76KW8JHGpp/CshRNUj8EFNf5NaUj4axzLe++xAQlGSl6DbcGmY8gMElqUV
+1i/7dTJESAzYZ48qweXpw4L0IwKBgQC5VNfrXFXP+Q0EjVNMiHZJJr7iit0SLtof
+2QSwpH1z9F2Q48J1zA0HozoDowlJiDkZ47NKVK6ODQblu9j+pKcEPeSDCxrTgMr5
+JKROsrkynnJKA0EUNFLCPrNzDZSaGBYpM9ufSdxNmal6RzGthAd8wsPJmQUchovl
+IvHQNL0h1QKBgQCqRmIFW+JaZnVX3b5l0JpksFDiqRMoYHRFTOA4bP4VhWCDvecb
+4hkwVF1jlBeCxhu77Oy+IoPzkz23HFnMk/gqbbpW814RWAggtHLnz5Tj5R4kWK/I
+gduAt96JqLR9HIv7o7u0FLCq4VvaYGTxXygd9qHQbJuIFD8hT7mUaDxp4wKBgC4r
+w+r/wuUgD60tpC3x5T4OKAn6PF8WSwMaJr/3CsYDf/fjtgNwxWI8uOxFBsBJ7qfT
+gUwoUqBTAH/lT4cI8A7veGlpL9K3SFnPVhvBDMBelux3aRQmgOOhiUVFgdrt2z+C
+itlhJkAy4vTynZ6zwMXFI8+qjopvvpRkI0gSi3fNAoGAcgb/jgNxiGfAhcXpAJJd
+6R+T+eY7JRJn1G166reOMqKGmUaByeb97luaBamQlMa02RuBSvELCbqkSg4AUCLr
+YjYkLk7w5bzcFPjIasHV95dQCEhxPaiKJxALqxs3/N7Fqa+QSyqRAkt0VfxiO82e
+osfGdpvRH+ZrjMsVdSOUHO8=
+-----END PRIVATE KEY-----

package/dist/create/server-source/crates/feltdb-client/tests/fixtures/server.pem

@@ -0,0 +1,20 @@
+-----BEGIN CERTIFICATE-----
+MIIDSjCCAjKgAwIBAgIUDb0J9OVXZhIyb2u5+uUAyWlfosowDQYJKoZIhvcNAQEL
+BQAwKDEmMCQGA1UEAwwdZmVsdGRiLWNsaWVudCB0ZXN0IHByaXZhdGUgQ0EwIBcN
+MjYxMDIyMDQxMDI0WhgPMjEyNjA5MjgwNDEwMjRaMBQxEjAQBgNVBAMMCWxvY2Fs
+aG9zdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALaK7DqXJ1KxPrXu
+mhbSQhhHkJTg7mr1QLbnPkRnGmshnPAwf72eaa+PEkiS4hL0P5pvEnGwpxO5u9LV
+HfeQj5pH2HdalgQILj/w1q0xse2zYxGtVtvtT8B911AbpYks+4L7z4J2yzFOmsxk
+vpoYZhHN3cRUJWpf7Uy9CJaf2X1biVpbuMtAnA94B/Me/L3p30Eb9mkifc7m57Wb
+SfFfbHVPsM2SnklKozujEjA1y6YiaDWXepSko8OtMET8vYKqK2otWgTcbFYiyJg6
+1LCTAQz9Vrr1P+RfkboiLQ7vx6FEqLTlYRTVnEwOkTfSmwKfEJiiHawhbm5BqSSu
+aOdEpB8CAwEAAaN+MHwwGgYDVR0RBBMwEYIJbG9jYWxob3N0hwR/AAABMAkGA1Ud
+EwQCMAAwEwYDVR0lBAwwCgYIKwYBBQUHAwEwHQYDVR0OBBYEFO2Q1I+MS8BrlT0h
+qeQ1EjHgbS27MB8GA1UdIwQYMBaAFD7UGRV1DDDrKvP5GJ+A9NLao4RDMA0GCSqG
+SIb3DQEBCwUAA4IBAQA+GaxqRADunwafJpff5XzpDISMJnxgN7N43iGYV0zy59r9
+R2YaWs3Q5Q1Us5geh2t9tuAEF67dh+FEqRbsxtiGob8CN5s6lqX6Vqhd3wEI9ay/
+RbHvIjT3yY7yXzwhpCJVVKXO9x+6+UZnD0Iu5MRXNN+8msmSAAHstJ8Y/ldKOpDA
+L/PA+8BmEdDZlaP8m9a+vAlV7zXhLiFz/xjWSWcW/vgt+AZ1SDeMqUh46KRYqrhE
+HYsVuUdu6VRlnnJkc0v8BSb9qfwAxVIsMor9SUizm4eg95m+VEIAQEOt9UjEz5a0
+uxLAOzN5gczgQ9jJFRnC07f5Nrs4tkOzzoBDqC6y
+-----END CERTIFICATE-----

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

@@ -0,0 +1,95 @@
+//! A server whose certificate a private CA issued: refused by default, served once that CA is
+//! trusted. The fixtures are a test CA and a `localhost`/`127.0.0.1` certificate it signed.
+
+use std::sync::Arc;
+
+use feltdb_client::{Client, Error, Method};
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio_rustls::rustls::pki_types::{pem::PemObject, CertificateDer, PrivateKeyDer};
+use tokio_rustls::rustls::ServerConfig;
+
+const PRIVATE_CA: &str = include_str!("fixtures/private-ca.pem");
+const SERVER_CERTIFICATE: &str = include_str!("fixtures/server.pem");
+const SERVER_KEY: &str = include_str!("fixtures/server-key.pem");
+
+/// An HTTPS server that answers every request with `{"ok":true}`.
+async fn private_ca_server() -> u16 {
+    let certificates = CertificateDer::pem_slice_iter(SERVER_CERTIFICATE.as_bytes())
+        .collect::<Result<Vec<_>, _>>()
+        .unwrap();
+    let key = PrivateKeyDer::from_pem_slice(SERVER_KEY.as_bytes()).unwrap();
+    let config = ServerConfig::builder()
+        .with_no_client_auth()
+        .with_single_cert(certificates, key)
+        .unwrap();
+    let acceptor = tokio_rustls::TlsAcceptor::from(Arc::new(config));
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let port = listener.local_addr().unwrap().port();
+    tokio::spawn(async move {
+        while let Ok((stream, _)) = listener.accept().await {
+            let acceptor = acceptor.clone();
+            tokio::spawn(async move {
+                // A client that does not trust the CA aborts the handshake.
+                let Ok(mut stream) = acceptor.accept(stream).await else {
+                    return;
+                };
+                let mut request = Vec::new();
+                let mut chunk = [0_u8; 1024];
+                while !request.windows(4).any(|window| window == b"\r\n\r\n") {
+                    match stream.read(&mut chunk).await {
+                        Ok(0) | Err(_) => return,
+                        Ok(read) => request.extend_from_slice(&chunk[..read]),
+                    }
+                }
+                let body = br#"{"ok":true}"#;
+                let head = format!(
+                    "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n",
+                    body.len()
+                );
+                let _ = stream.write_all(head.as_bytes()).await;
+                let _ = stream.write_all(body).await;
+                let _ = stream.shutdown().await;
+            });
+        }
+    });
+    port
+}
+
+#[tokio::test]
+async fn a_private_ca_is_refused_until_it_is_trusted() {
+    let port = private_ca_server().await;
+    for host in ["localhost", "127.0.0.1"] {
+        let url = format!("https://{host}:{port}");
+
+        let untrusting = Client::builder(&url).build().unwrap();
+        let refused = untrusting
+            .request::<()>(Method::GET, "/health", None)
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(refused, Error::Transport { .. }),
+            "{host}: an unknown issuer fails the handshake: {refused:?}"
+        );
+
+        let trusting = Client::builder(&url)
+            .add_root_certificate_pem(PRIVATE_CA)
+            .build()
+            .unwrap();
+        let answer = trusting
+            .request::<()>(Method::GET, "/health", None)
+            .await
+            .unwrap();
+        assert_eq!(answer, serde_json::json!({ "ok": true }), "{host}");
+    }
+}
+
+#[test]
+fn a_root_certificate_that_is_not_pem_is_refused() {
+    let built = Client::builder("https://localhost:1")
+        .add_root_certificate_pem("not a certificate")
+        .build();
+    assert!(
+        matches!(built, Err(Error::InvalidRequest(ref message)) if message.contains("root certificate")),
+        "{built:?}"
+    );
+}

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

@@ -2,6 +2,17 @@
 name = "feltdb-server"
 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 = "The FeltDB server: the managed FeltDB authority over HTTP (scoped state, transactions, CAS, history, principals, events), installed as the `feltdb-server` binary"
+license = "MIT"
+repository = "https://github.com/rkendel1/flow_db"
+readme = "README.md"
+keywords = ["database", "server", "transactions", "durable", "feltdb"]
+categories = ["database-implementations", "web-programming::http-server"]
+# The integration tests and benches read repository fixtures by path and cannot run from a
+# packaged copy, so they stay in the repository.
+exclude = ["tests/", "benches/", "target/"]
 
 [dependencies]
 axum = { version = "0.8", features = ["json", "tokio"] }
@@ -10,7 +21,10 @@ argon2 = "0.5"
 password-hash = "0.5"
 base64 = "0.22"
 hmac = "0.12"
-feltdb = { path = "../feltdb" }
+# Exact: the server uses `unstable-internals`, which carries no semver promise, so a release of
+# this crate is built against the one `feltdb` release it was tested with. The workspace shares one
+# version, so this moves with every release (a mismatch fails to resolve, it cannot drift silently).
+feltdb = { version = "=0.2.1", path = "../feltdb", features = ["unstable-internals"] }
 futures-core = "0.3"
 rand = "0.8"
 ring = "0.17"
@@ -24,6 +38,11 @@ tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 uuid = { version = "1.6", features = ["v4"] }
 
+[dev-dependencies]
+# The Rust client is tested against this server's real binary (tests/rust_client.rs). A path-only
+# dev-dependency is dropped from the published package.
+feltdb-client = { path = "../feltdb-client" }
+
 [[bench]]
 name = "query_shape_observer"
 harness = false