@feltdb/core 0.12.1 → 0.12.2

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

@@ -0,0 +1,292 @@
+//! The control plane: server health, tenants, applications, the draft → revision → promotion
+//! lifecycle of an application's contract, and online backup.
+
+use feltdb::application::{
+    ApplicationDraft, ApplicationManifest, ApplicationRevision, ValidationReport,
+};
+use serde::Deserialize;
+use serde_json::{json, Value};
+
+use crate::{encode, Client, Method, Result};
+
+/// The server's own health report (`GET /health`): liveness, build identity and subsystem status.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+pub struct Health {
+    /// `healthy`, or the reason it is not.
+    pub status: String,
+    /// The server's package version.
+    pub version: String,
+    #[serde(default)]
+    pub git_commit: Option<String>,
+    #[serde(default)]
+    pub release_id: Option<String>,
+    #[serde(default)]
+    pub public_contract: Option<String>,
+    #[serde(default)]
+    pub capability_fingerprint: Option<String>,
+    #[serde(default)]
+    pub storage: Option<String>,
+    #[serde(default)]
+    pub membership: Option<String>,
+}
+
+/// A tenant on the server.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+pub struct Tenant {
+    pub id: String,
+    pub name: String,
+    #[serde(default)]
+    pub slug: Option<String>,
+}
+
+/// An application as the control plane records it. Which revision an environment runs is
+/// [`crate::Application::discover`]'s to answer.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+pub struct ApplicationRecord {
+    pub id: String,
+    pub tenant_id: String,
+    pub name: String,
+    #[serde(default)]
+    pub slug: Option<String>,
+    #[serde(default)]
+    pub status: Option<String>,
+}
+
+/// Moves an environment to a revision: [`Control::promote`].
+#[derive(Debug, Clone)]
+pub struct Promotion {
+    environment: String,
+    reason: String,
+    expected_current_revision: Option<String>,
+    approve_destructive_changes: bool,
+}
+
+impl Promotion {
+    pub fn new(environment: impl Into<String>) -> Self {
+        Self {
+            environment: environment.into(),
+            reason: String::new(),
+            expected_current_revision: None,
+            approve_destructive_changes: false,
+        }
+    }
+
+    /// Recorded in the environment's history.
+    pub fn reason(mut self, reason: impl Into<String>) -> Self {
+        self.reason = reason.into();
+        self
+    }
+
+    /// Promote only if the environment still runs `revision_id` (`None`: still runs nothing), so
+    /// two promotions racing from the same base cannot both win.
+    pub fn expect_current(mut self, revision_id: Option<String>) -> Self {
+        self.expected_current_revision = revision_id;
+        self
+    }
+
+    /// Allow a promotion whose schema change would drop data.
+    pub fn approve_destructive_changes(mut self) -> Self {
+        self.approve_destructive_changes = true;
+        self
+    }
+}
+
+/// The control-plane routes, from [`Client::control`]. Cheap to clone.
+#[derive(Debug, Clone)]
+pub struct Control {
+    client: Client,
+}
+
+impl Control {
+    fn application_path(application_id: &str, rest: &str) -> String {
+        format!("/api/applications/{}{rest}", encode(application_id))
+    }
+
+    fn draft_path(application_id: &str, draft_id: &str, rest: &str) -> String {
+        Self::application_path(
+            application_id,
+            &format!("/drafts/{}{rest}", encode(draft_id)),
+        )
+    }
+
+    /// The tenants this key can see.
+    pub async fn tenants(&self) -> Result<Vec<Tenant>> {
+        self.client
+            .send::<_, ()>(Method::GET, "/api/tenants", None)
+            .await
+    }
+
+    pub async fn create_tenant(&self, name: &str) -> Result<Tenant> {
+        self.client
+            .send(Method::POST, "/api/tenants", Some(&json!({ "name": name })))
+            .await
+    }
+
+    /// A tenant's applications that this key can see.
+    pub async fn applications(&self, tenant_id: &str) -> Result<Vec<ApplicationRecord>> {
+        let path = format!("/api/tenants/{}/applications", encode(tenant_id));
+        self.client.send::<_, ()>(Method::GET, &path, None).await
+    }
+
+    pub async fn create_application(
+        &self,
+        tenant_id: &str,
+        name: &str,
+    ) -> Result<ApplicationRecord> {
+        let path = format!("/api/tenants/{}/applications", encode(tenant_id));
+        self.client
+            .send(Method::POST, &path, Some(&json!({ "name": name })))
+            .await
+    }
+
+    pub async fn application(&self, application_id: &str) -> Result<ApplicationRecord> {
+        self.client
+            .send::<_, ()>(
+                Method::GET,
+                &Self::application_path(application_id, ""),
+                None,
+            )
+            .await
+    }
+
+    /// Start a draft of the application's contract from `base_revision_id`, or from an empty
+    /// manifest.
+    pub async fn create_draft(
+        &self,
+        application_id: &str,
+        base_revision_id: Option<&str>,
+    ) -> Result<ApplicationDraft> {
+        self.client
+            .send(
+                Method::POST,
+                &Self::application_path(application_id, "/drafts"),
+                Some(&json!({ "base_revision_id": base_revision_id })),
+            )
+            .await
+    }
+
+    pub async fn draft(&self, application_id: &str, draft_id: &str) -> Result<ApplicationDraft> {
+        self.client
+            .send::<_, ()>(
+                Method::GET,
+                &Self::draft_path(application_id, draft_id, ""),
+                None,
+            )
+            .await
+    }
+
+    /// Replace the draft's manifest, only if the draft is still at `version` (the
+    /// [`ApplicationDraft::version`] last read); a concurrent edit is refused, not overwritten.
+    pub async fn update_draft(
+        &self,
+        application_id: &str,
+        draft_id: &str,
+        version: u64,
+        manifest: &ApplicationManifest,
+    ) -> Result<ApplicationDraft> {
+        self.client
+            .send_with_headers(
+                Method::PUT,
+                &Self::draft_path(application_id, draft_id, ""),
+                &[("if-version", &version.to_string())],
+                Some(&json!({ "manifest": manifest })),
+            )
+            .await
+    }
+
+    /// Validate the draft without committing it. An invalid manifest is a report with
+    /// `valid: false` and its issues, not an error.
+    pub async fn validate_draft(
+        &self,
+        application_id: &str,
+        draft_id: &str,
+    ) -> Result<ValidationReport> {
+        self.client
+            .send(
+                Method::POST,
+                &Self::draft_path(application_id, draft_id, "/validate"),
+                Some(&json!({})),
+            )
+            .await
+    }
+
+    /// Commit the draft as an immutable revision. No environment runs it until it is promoted.
+    pub async fn commit_draft(
+        &self,
+        application_id: &str,
+        draft_id: &str,
+    ) -> Result<ApplicationRevision> {
+        self.client
+            .send(
+                Method::POST,
+                &Self::draft_path(application_id, draft_id, "/commit"),
+                Some(&json!({})),
+            )
+            .await
+    }
+
+    pub async fn revision(
+        &self,
+        application_id: &str,
+        revision_id: &str,
+    ) -> Result<ApplicationRevision> {
+        let path = Self::application_path(
+            application_id,
+            &format!("/revisions/{}", encode(revision_id)),
+        );
+        self.client.send::<_, ()>(Method::GET, &path, None).await
+    }
+
+    /// Make `revision_id` the revision an environment runs. Returns the server's promotion
+    /// record and readiness.
+    pub async fn promote(
+        &self,
+        application_id: &str,
+        revision_id: &str,
+        promotion: &Promotion,
+    ) -> Result<Value> {
+        let path = Self::application_path(
+            application_id,
+            &format!("/revisions/{}/promote", encode(revision_id)),
+        );
+        self.client
+            .send(
+                Method::POST,
+                &path,
+                Some(&json!({
+                    "environment": promotion.environment,
+                    "reason": promotion.reason,
+                    "expected_current_revision": promotion.expected_current_revision,
+                    "approve_destructive_changes": promotion.approve_destructive_changes,
+                })),
+            )
+            .await
+    }
+
+    /// An online backup: a consistent snapshot of the whole database written to `output`, a path
+    /// on the server's host. Returns the bundle's manifest. Requires `cluster:write`; verify the
+    /// bundle with `feltdb-server backup verify`.
+    pub async fn backup(&self, output: &str) -> Result<Value> {
+        self.client
+            .send(
+                Method::POST,
+                "/admin/backups",
+                Some(&json!({ "output": output })),
+            )
+            .await
+    }
+}
+
+impl Client {
+    /// The server's health report. Unauthenticated on the server.
+    pub async fn health(&self) -> Result<Health> {
+        self.send::<_, ()>(Method::GET, "/health", None).await
+    }
+
+    /// The control plane: tenants, applications, contract drafts, revisions, promotion, backup.
+    pub fn control(&self) -> Control {
+        Control {
+            client: self.clone(),
+        }
+    }
+}

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

@@ -0,0 +1,227 @@
+use std::fmt;
+
+use feltdb::PreconditionFailure;
+use serde_json::Value;
+
+/// Everything a request can end in other than success.
+///
+/// Match on the variant and on [`ApiError::code`], never on message text. The enum is
+/// `#[non_exhaustive]`, so keep a catch-all arm.
+#[derive(Debug)]
+#[non_exhaustive]
+pub enum Error {
+    /// The server answered and refused the request.
+    Api(Box<ApiError>),
+    /// The request did not complete: connection refused, reset, timed out, or the response could
+    /// not be read.
+    ///
+    /// For a write, [`Error::is_outcome_unknown`] says whether the server may still have applied it.
+    /// A transaction with an identity is safe to resubmit with the same id: the authority
+    /// recognizes the retry as a duplicate instead of applying it twice.
+    Transport {
+        outcome_unknown: bool,
+        source: reqwest::Error,
+    },
+    /// The server answered successfully with a body this client could not decode.
+    Decode {
+        status: u16,
+        source: serde_json::Error,
+    },
+    /// Refused before anything was sent: the request is not one the server could accept.
+    InvalidRequest(String),
+    /// An event stream ended with a reported authority error.
+    Stream(String),
+}
+
+/// A refusal from the server, as its JSON error body describes it.
+#[derive(Debug, Clone)]
+pub struct ApiError {
+    /// The HTTP status.
+    pub status: u16,
+    /// The stable machine-readable code, e.g. `PRECONDITION_FAILED`, `VERSION_CONFLICT`,
+    /// `IDEMPOTENCY_CONFLICT`, `FORBIDDEN`, `NOT_FOUND`.
+    pub code: String,
+    /// Human-readable detail. Not a contract: do not branch on it.
+    pub message: String,
+    /// The server's request id, when it reported one. Quote it when reporting a problem.
+    pub request_id: Option<String>,
+    /// Which predicate failed and what the authority holds, when a transaction was refused for a
+    /// failed precondition or fence. Nothing was written.
+    pub failure: Option<PreconditionFailure>,
+    /// The complete error body, for fields this type does not name.
+    pub body: Value,
+}
+
+impl Error {
+    /// The stable error code, when the server reported one.
+    pub fn code(&self) -> Option<&str> {
+        match self {
+            Self::Api(error) => Some(&error.code),
+            _ => None,
+        }
+    }
+
+    /// The HTTP status, when the server answered.
+    pub fn status(&self) -> Option<u16> {
+        match self {
+            Self::Api(error) => Some(error.status),
+            Self::Decode { status, .. } => Some(*status),
+            _ => None,
+        }
+    }
+
+    /// True when a write may or may not have been applied: it was sent, and no answer arrived.
+    /// Reconcile by resubmitting a transaction with the same id, or by reading the state back.
+    pub fn is_outcome_unknown(&self) -> bool {
+        matches!(
+            self,
+            Self::Transport {
+                outcome_unknown: true,
+                ..
+            }
+        )
+    }
+
+    /// The structured precondition failure of a refused transaction.
+    pub fn precondition_failure(&self) -> Option<&PreconditionFailure> {
+        match self {
+            Self::Api(error) => error.failure.as_ref(),
+            _ => None,
+        }
+    }
+
+    /// True for a refusal caused by state: a failed precondition or fence, a version, epoch or
+    /// lease conflict, a record already present. Retry against fresh state, not unchanged.
+    pub fn is_conflict(&self) -> bool {
+        match self {
+            Self::Api(error) => error.status == 409 || error.failure.is_some(),
+            _ => false,
+        }
+    }
+
+    pub(crate) fn transport(source: reqwest::Error, mutating: bool) -> Self {
+        // A connection that was never established carried no request, so nothing can have been
+        // applied. Every other failure of a write leaves its outcome open.
+        let outcome_unknown = mutating && !source.is_connect() && !source.is_builder();
+        Self::Transport {
+            outcome_unknown,
+            source,
+        }
+    }
+}
+
+impl ApiError {
+    pub(crate) fn from_body(status: u16, text: &str) -> Self {
+        let body = serde_json::from_str::<Value>(text)
+            .ok()
+            .filter(Value::is_object)
+            .unwrap_or_else(|| serde_json::json!({ "message": text }));
+        let field = |name: &str| body.get(name).and_then(Value::as_str).map(str::to_owned);
+        let code = field("code")
+            .or_else(|| field("error"))
+            .unwrap_or_else(|| fallback_code(status).to_owned());
+        let message = field("message")
+            .or_else(|| field("error"))
+            .unwrap_or_else(|| format!("FeltDB request failed with HTTP {status}"));
+        let failure = body
+            .get("failure")
+            .cloned()
+            .and_then(|value| serde_json::from_value(value).ok());
+        Self {
+            status,
+            code,
+            message,
+            request_id: field("request_id"),
+            failure,
+            body,
+        }
+    }
+}
+
+fn fallback_code(status: u16) -> &'static str {
+    match status {
+        401 => "UNAUTHORIZED",
+        403 => "FORBIDDEN",
+        404 => "NOT_FOUND",
+        409 => "CONFLICT",
+        _ if status >= 500 => "EXECUTION_FAILED",
+        _ => "INVALID_REQUEST",
+    }
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Api(error) => write!(f, "{error}"),
+            Self::Transport {
+                outcome_unknown: true,
+                source,
+            } => write!(f, "request outcome unknown: {source}"),
+            Self::Transport { source, .. } => write!(f, "request failed: {source}"),
+            Self::Decode { status, source } => {
+                write!(f, "could not decode an HTTP {status} response: {source}")
+            }
+            Self::InvalidRequest(message) => write!(f, "invalid request: {message}"),
+            Self::Stream(message) => write!(f, "event stream ended: {message}"),
+        }
+    }
+}
+
+impl fmt::Display for ApiError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{} (HTTP {}): {}", self.code, self.status, self.message)?;
+        if let Some(request_id) = &self.request_id {
+            write!(f, " [{request_id}]")?;
+        }
+        Ok(())
+    }
+}
+
+impl std::error::Error for Error {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Transport { source, .. } => Some(source),
+            Self::Decode { source, .. } => Some(source),
+            _ => None,
+        }
+    }
+}
+
+impl std::error::Error for ApiError {}
+
+pub type Result<T, E = Error> = std::result::Result<T, E>;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_refused_transaction_carries_its_structured_failure() {
+        let error = ApiError::from_body(
+            409,
+            r#"{"committed":false,"code":"PRECONDITION_FAILED","error":"PRECONDITION_FAILED","message":"Conflict",
+                "failure":{"predicate":"version","collection":"orders","key":"orders:o-1","expected":1,"actual":2},
+                "request_id":"req_1"}"#,
+        );
+        assert_eq!(error.code, "PRECONDITION_FAILED");
+        assert_eq!(error.request_id.as_deref(), Some("req_1"));
+        assert_eq!(
+            error.failure,
+            Some(PreconditionFailure::Version {
+                collection: "orders".into(),
+                key: "orders:o-1".into(),
+                expected: 1,
+                actual: 2
+            })
+        );
+        assert!(Error::Api(Box::new(error)).is_conflict());
+    }
+
+    #[test]
+    fn a_body_that_is_not_json_still_yields_a_code() {
+        let error = ApiError::from_body(502, "bad gateway");
+        assert_eq!(error.code, "EXECUTION_FAILED");
+        assert_eq!(error.message, "bad gateway");
+        assert!(error.failure.is_none());
+    }
+}

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

@@ -0,0 +1,146 @@
+use serde::de::DeserializeOwned;
+
+use crate::error::{Error, Result};
+
+/// One server-sent event.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ServerEvent {
+    /// The opaque cursor after this event. Pass it back to resume from here.
+    pub id: Option<String>,
+    /// The event name; `state.committed` for a committed change.
+    pub event: String,
+    /// The event payload, a JSON document for `state.committed`.
+    pub data: String,
+}
+
+impl ServerEvent {
+    /// Decode the payload.
+    pub fn json<T: DeserializeOwned>(&self) -> Result<T> {
+        serde_json::from_str(&self.data).map_err(|source| Error::Decode {
+            status: 200,
+            source,
+        })
+    }
+}
+
+/// A live event stream: a delivery adapter over committed history, not the history itself.
+///
+/// It does not reconnect on its own. When it ends or fails, open a new one from
+/// [`EventStream::last_event_id`] and nothing committed in between is skipped. For a complete,
+/// bounded read of history use the application's event replay instead.
+pub struct EventStream {
+    response: reqwest::Response,
+    buffer: Vec<u8>,
+    last_event_id: Option<String>,
+    finished: bool,
+}
+
+impl EventStream {
+    pub(crate) fn new(response: reqwest::Response, resumed_from: Option<String>) -> Self {
+        Self {
+            response,
+            buffer: Vec::new(),
+            last_event_id: resumed_from,
+            finished: false,
+        }
+    }
+
+    /// The cursor of the last event delivered (or the one this stream resumed from).
+    pub fn last_event_id(&self) -> Option<&str> {
+        self.last_event_id.as_deref()
+    }
+
+    /// The next event; `None` when the server closed the stream.
+    ///
+    /// An `authority.error` event from the server ends the stream with [`Error::Stream`].
+    pub async fn next(&mut self) -> Option<Result<ServerEvent>> {
+        loop {
+            if self.finished {
+                return None;
+            }
+            while let Some(frame) = take_frame(&mut self.buffer) {
+                let Some(event) = parse_frame(&frame) else {
+                    continue;
+                };
+                if event.event == "authority.error" {
+                    self.finished = true;
+                    return Some(Err(Error::Stream(event.data)));
+                }
+                if event.id.is_some() {
+                    self.last_event_id.clone_from(&event.id);
+                }
+                return Some(Ok(event));
+            }
+            match self.response.chunk().await {
+                // Bytes, not text: a chunk can end inside a multi-byte character, and only a
+                // complete frame is decoded. Carriage returns are dropped so CRLF framing parses
+                // as LF; JSON payloads escape theirs.
+                Ok(Some(bytes)) => self
+                    .buffer
+                    .extend(bytes.iter().copied().filter(|byte| *byte != b'\r')),
+                Ok(None) => {
+                    self.finished = true;
+                    return None;
+                }
+                Err(source) => {
+                    self.finished = true;
+                    return Some(Err(Error::transport(source, false)));
+                }
+            }
+        }
+    }
+}
+
+fn take_frame(buffer: &mut Vec<u8>) -> Option<String> {
+    let end = buffer.windows(2).position(|pair| pair == b"\n\n")?;
+    let frame = String::from_utf8_lossy(&buffer[..end]).into_owned();
+    buffer.drain(..end + 2);
+    Some(frame)
+}
+
+/// Parse one SSE frame. Comments (keep-alives) and frames without data are skipped.
+fn parse_frame(frame: &str) -> Option<ServerEvent> {
+    let mut id = None;
+    let mut event = None;
+    let mut data: Vec<&str> = Vec::new();
+    for line in frame.split('\n') {
+        if line.starts_with(':') {
+            continue;
+        }
+        let (field, value) = line.split_once(':').unwrap_or((line, ""));
+        let value = value.strip_prefix(' ').unwrap_or(value);
+        match field {
+            "id" => id = Some(value.to_owned()),
+            "event" => event = Some(value.to_owned()),
+            "data" => data.push(value),
+            _ => {}
+        }
+    }
+    if data.is_empty() {
+        return None;
+    }
+    Some(ServerEvent {
+        id,
+        event: event.unwrap_or_else(|| "message".to_owned()),
+        data: data.join("\n"),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn frames_are_split_and_parsed() {
+        let mut buffer =
+            b": keep-alive\n\nid: c-2\nevent: state.committed\ndata: {\"a\":\ndata: 1}\n\nid: partial"
+                .to_vec();
+        assert_eq!(parse_frame(&take_frame(&mut buffer).unwrap()), None);
+        let event = parse_frame(&take_frame(&mut buffer).unwrap()).unwrap();
+        assert_eq!(event.id.as_deref(), Some("c-2"));
+        assert_eq!(event.event, "state.committed");
+        assert_eq!(event.data, "{\"a\":\n1}");
+        assert_eq!(take_frame(&mut buffer), None);
+        assert_eq!(buffer, b"id: partial");
+    }
+}