@feltdb/core 0.12.1 → 0.13.0

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

@@ -0,0 +1,679 @@
+//! The direct authority surface: records, transactions, compare-and-set, the bounded query, the
+//! committed revision and the event stream.
+
+use feltdb::{ReadBasis, ReadSet, SemanticQueryClause, TransactionStatus};
+use serde::{ser::SerializeMap, Deserialize, Serialize, Serializer};
+use serde_json::{Map, Value};
+
+use crate::{encode, Client, Error, EventStream, Method, Result};
+
+/// A stored record.
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+pub struct Record {
+    /// The record id within its collection.
+    pub id: String,
+    /// The storage key, `collection:id`.
+    pub key: String,
+    /// The document, including its `id` and, after a fenced write, its `__version`.
+    pub value: Value,
+}
+
+/// The committed revision of the authority, and the identity of the store that counted it.
+///
+/// Two revisions are comparable only when their scopes are equal: behind a load balancer or after
+/// a failover the URL stays the same while the store, and so the counter, changes.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+pub struct Revision {
+    pub revision: u64,
+    pub scope: String,
+}
+
+/// One write inside a [`Transaction`].
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Operation {
+    collection: String,
+    id: String,
+    /// `None` deletes the record.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    value: Option<Value>,
+    #[serde(skip_serializing_if = "std::ops::Not::not")]
+    require_absent: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    expected_version: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    expected_epoch: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    expected_lease_id: Option<String>,
+}
+
+impl Operation {
+    fn new(collection: impl Into<String>, id: impl Into<String>, value: Option<Value>) -> Self {
+        Self {
+            collection: collection.into(),
+            id: id.into(),
+            value,
+            require_absent: false,
+            expected_version: None,
+            expected_epoch: None,
+            expected_lease_id: None,
+        }
+    }
+
+    /// Write `value` (a JSON object) as the record, whether or not it exists.
+    pub fn put(collection: impl Into<String>, id: impl Into<String>, value: Value) -> Self {
+        Self::new(collection, id, Some(value))
+    }
+
+    /// Create the record; the whole transaction is refused if it already exists. The authority
+    /// assigns the created document `__version` 1.
+    pub fn create(collection: impl Into<String>, id: impl Into<String>, value: Value) -> Self {
+        Self {
+            require_absent: true,
+            ..Self::new(collection, id, Some(value))
+        }
+    }
+
+    /// Delete the record.
+    pub fn delete(collection: impl Into<String>, id: impl Into<String>) -> Self {
+        Self::new(collection, id, None)
+    }
+
+    /// Commit only if the record's `__version` is still `version`.
+    pub fn expect_version(mut self, version: u64) -> Self {
+        self.expected_version = Some(version);
+        self
+    }
+
+    /// Commit only if the record's authority epoch is still `epoch`.
+    pub fn expect_epoch(mut self, epoch: u64) -> Self {
+        self.expected_epoch = Some(epoch);
+        self
+    }
+
+    /// Commit only while `lease_id` is an unexpired lease on the record.
+    pub fn expect_lease(mut self, lease_id: impl Into<String>) -> Self {
+        self.expected_lease_id = Some(lease_id.into());
+        self
+    }
+}
+
+/// A condition on a record the transaction need not write, evaluated inside the commit.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Precondition {
+    collection: String,
+    id: String,
+    #[serde(skip_serializing_if = "std::ops::Not::not")]
+    require_absent: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    expected_version: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    expected_epoch: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    expected_lease_id: Option<String>,
+}
+
+impl Precondition {
+    fn new(collection: impl Into<String>, id: impl Into<String>) -> Self {
+        Self {
+            collection: collection.into(),
+            id: id.into(),
+            require_absent: false,
+            expected_version: None,
+            expected_epoch: None,
+            expected_lease_id: None,
+        }
+    }
+
+    /// The record must not exist.
+    pub fn absent(collection: impl Into<String>, id: impl Into<String>) -> Self {
+        Self {
+            require_absent: true,
+            ..Self::new(collection, id)
+        }
+    }
+
+    /// The record's `__version` must be `version`.
+    pub fn version(collection: impl Into<String>, id: impl Into<String>, version: u64) -> Self {
+        Self {
+            expected_version: Some(version),
+            ..Self::new(collection, id)
+        }
+    }
+
+    /// The record's authority epoch must be `epoch`.
+    pub fn epoch(collection: impl Into<String>, id: impl Into<String>, epoch: u64) -> Self {
+        Self {
+            expected_epoch: Some(epoch),
+            ..Self::new(collection, id)
+        }
+    }
+
+    /// `lease_id` must be an unexpired lease on the record.
+    pub fn lease(
+        collection: impl Into<String>,
+        id: impl Into<String>,
+        lease_id: impl Into<String>,
+    ) -> Self {
+        Self {
+            expected_lease_id: Some(lease_id.into()),
+            ..Self::new(collection, id)
+        }
+    }
+}
+
+/// Several writes committed as one durable record, or not at all.
+///
+/// The id is the transaction's identity. Resubmitting the same transaction with the same id after
+/// an uncertain outcome returns the original commit with `duplicate: true`; the same id with
+/// different content is refused with `IDEMPOTENCY_CONFLICT`.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Transaction {
+    transaction_id: String,
+    operations: Vec<Operation>,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    preconditions: Vec<Precondition>,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    fences: Vec<ReadBasis>,
+}
+
+impl Transaction {
+    /// A transaction with this identity.
+    pub fn new(transaction_id: impl Into<String>) -> Self {
+        Self {
+            transaction_id: transaction_id.into(),
+            operations: Vec::new(),
+            preconditions: Vec::new(),
+            fences: Vec::new(),
+        }
+    }
+
+    /// A transaction with a fresh random identity. Keep [`Transaction::id`] if you may need to
+    /// resubmit it.
+    pub fn generated() -> Self {
+        Self::new(format!("tx-{}", uuid::Uuid::new_v4()))
+    }
+
+    pub fn id(&self) -> &str {
+        &self.transaction_id
+    }
+
+    pub fn operation(mut self, operation: Operation) -> Self {
+        self.operations.push(operation);
+        self
+    }
+
+    pub fn precondition(mut self, precondition: Precondition) -> Self {
+        self.preconditions.push(precondition);
+        self
+    }
+
+    /// Commit only if the state `basis` covers is unchanged since [`Client::read_basis`] captured it.
+    pub fn fence(mut self, basis: ReadBasis) -> Self {
+        self.fences.push(basis);
+        self
+    }
+
+    fn validate(&self) -> Result<()> {
+        if self.transaction_id.trim().is_empty() {
+            return Err(Error::InvalidRequest("a transaction id is required".into()));
+        }
+        if self.operations.is_empty() {
+            return Err(Error::InvalidRequest(
+                "a transaction requires at least one operation".into(),
+            ));
+        }
+        for operation in &self.operations {
+            if operation
+                .value
+                .as_ref()
+                .is_some_and(|value| !value.is_object())
+            {
+                return Err(Error::InvalidRequest(format!(
+                    "the value written to {}/{} must be a JSON object",
+                    operation.collection, operation.id
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+/// What the authority committed.
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CommitReceipt {
+    pub transaction_id: String,
+    pub base_revision: u64,
+    pub commit_revision: u64,
+    pub status: TransactionStatus,
+    /// True when this id had already committed: nothing was applied again.
+    pub duplicate: bool,
+    pub operations: usize,
+    pub state_before: u64,
+    pub state_after: u64,
+    pub revision_id: String,
+    #[serde(default)]
+    pub operation_ids: Vec<String>,
+}
+
+/// A conditional update of one record.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CasRequest {
+    expected_version: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    expected_epoch: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    expected_lease_id: Option<String>,
+    #[serde(skip_serializing_if = "std::ops::Not::not")]
+    reject_if_diverged: bool,
+    value: Value,
+}
+
+impl CasRequest {
+    /// Replace the record with `value` if its `__version` is `expected_version`. A record that has
+    /// never been through a fenced write is version 1.
+    pub fn new(expected_version: u64, value: Value) -> Self {
+        Self {
+            expected_version,
+            expected_epoch: None,
+            expected_lease_id: None,
+            reject_if_diverged: false,
+            value,
+        }
+    }
+
+    pub fn expect_epoch(mut self, epoch: u64) -> Self {
+        self.expected_epoch = Some(epoch);
+        self
+    }
+
+    pub fn expect_lease(mut self, lease_id: impl Into<String>) -> Self {
+        self.expected_lease_id = Some(lease_id.into());
+        self
+    }
+
+    /// Also refuse when the record has diverged across replicas.
+    pub fn reject_if_diverged(mut self) -> Self {
+        self.reject_if_diverged = true;
+        self
+    }
+}
+
+/// Which predicate refused a compare-and-set.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
+pub enum CasConflict {
+    #[serde(rename = "VERSION_CONFLICT")]
+    Version,
+    #[serde(rename = "AUTHORITY_CONFLICT")]
+    Authority,
+    #[serde(rename = "LEASE_CONFLICT")]
+    Lease,
+    #[serde(rename = "REPLICATION_CONFLICT")]
+    Replication,
+}
+
+/// How a compare-and-set ended. A lost race is a value, not an error.
+#[derive(Debug, Clone, PartialEq)]
+pub enum CasOutcome {
+    Updated {
+        current_version: u64,
+        current_epoch: u64,
+        /// The document as committed.
+        item: Value,
+    },
+    /// Nothing was written; this is what the authority holds.
+    Conflict {
+        conflict: CasConflict,
+        current_version: u64,
+        current_epoch: u64,
+    },
+    NotFound,
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct CasBody {
+    updated: bool,
+    #[serde(default)]
+    code: Option<String>,
+    #[serde(default)]
+    current_version: u64,
+    #[serde(default)]
+    current_epoch: u64,
+    #[serde(default)]
+    item: Value,
+}
+
+/// A comparison operator of the bounded query.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Operator {
+    Eq,
+    Neq,
+    Lt,
+    Lte,
+    Gt,
+    Gte,
+}
+
+/// One `where` condition of a [`BoundedQuery`].
+#[derive(Debug, Clone, PartialEq)]
+pub struct Condition {
+    field: String,
+    operator: Operator,
+    value: Value,
+}
+
+impl Serialize for Condition {
+    fn serialize<S: Serializer>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error> {
+        let operator = match self.operator {
+            Operator::Eq => "eq",
+            Operator::Neq => "neq",
+            Operator::Lt => "lt",
+            Operator::Lte => "lte",
+            Operator::Gt => "gt",
+            Operator::Gte => "gte",
+        };
+        let mut map = serializer.serialize_map(Some(2))?;
+        map.serialize_entry("field", &self.field)?;
+        map.serialize_entry(operator, &self.value)?;
+        map.end()
+    }
+}
+
+/// Sort direction.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum Direction {
+    Asc,
+    Desc,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize)]
+struct Order {
+    field: String,
+    direction: Direction,
+}
+
+/// 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.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BoundedQuery {
+    collection: String,
+    #[serde(rename = "where", skip_serializing_if = "Vec::is_empty")]
+    conditions: Vec<Condition>,
+    order_by: Vec<Order>,
+    limit: usize,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    cursor: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    semantic: Option<SemanticQueryClause>,
+}
+
+impl BoundedQuery {
+    /// A query over `collection` returning at most `limit` records. Add at least one
+    /// [`BoundedQuery::order_by`]: the server requires a total order.
+    pub fn new(collection: impl Into<String>, limit: usize) -> Self {
+        Self {
+            collection: collection.into(),
+            conditions: Vec::new(),
+            order_by: Vec::new(),
+            limit,
+            cursor: None,
+            semantic: None,
+        }
+    }
+
+    fn condition(mut self, field: impl Into<String>, operator: Operator, value: Value) -> Self {
+        self.conditions.push(Condition {
+            field: field.into(),
+            operator,
+            value,
+        });
+        self
+    }
+
+    pub fn eq(self, field: impl Into<String>, value: Value) -> Self {
+        self.condition(field, Operator::Eq, value)
+    }
+    pub fn neq(self, field: impl Into<String>, value: Value) -> Self {
+        self.condition(field, Operator::Neq, value)
+    }
+    pub fn lt(self, field: impl Into<String>, value: Value) -> Self {
+        self.condition(field, Operator::Lt, value)
+    }
+    pub fn lte(self, field: impl Into<String>, value: Value) -> Self {
+        self.condition(field, Operator::Lte, value)
+    }
+    pub fn gt(self, field: impl Into<String>, value: Value) -> Self {
+        self.condition(field, Operator::Gt, value)
+    }
+    pub fn gte(self, field: impl Into<String>, value: Value) -> Self {
+        self.condition(field, Operator::Gte, value)
+    }
+
+    pub fn order_by(mut self, field: impl Into<String>, direction: Direction) -> Self {
+        self.order_by.push(Order {
+            field: field.into(),
+            direction,
+        });
+        self
+    }
+
+    /// Continue from a previous page's [`QueryPage::next_cursor`].
+    pub fn after(mut self, cursor: impl Into<String>) -> Self {
+        self.cursor = Some(cursor.into());
+        self
+    }
+
+    /// Compose a semantic clause over the page this query produces (experimental; see
+    /// `docs/reference/semantic-query.md`). The page is never enlarged or refilled.
+    pub fn semantic(mut self, clause: SemanticQueryClause) -> Self {
+        self.semantic = Some(clause);
+        self
+    }
+}
+
+/// One page of a [`BoundedQuery`].
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct QueryPage {
+    pub records: Vec<Value>,
+    #[serde(default)]
+    pub next_cursor: Option<String>,
+    pub exhausted: bool,
+    /// Present exactly when the query carried a semantic clause.
+    #[serde(default)]
+    pub semantic: Option<Value>,
+}
+
+impl Client {
+    /// The record `collection/id`, or `None` if it does not exist.
+    pub async fn get(&self, collection: &str, id: &str) -> Result<Option<Record>> {
+        match self
+            .send::<Record, ()>(Method::GET, &record_path(collection, id), None)
+            .await
+        {
+            Ok(record) => Ok(Some(record)),
+            Err(Error::Api(error)) if error.status == 404 => Ok(None),
+            Err(error) => Err(error),
+        }
+    }
+
+    /// Every record of `collection`. This reads the whole collection: on a request path use
+    /// [`Client::query`], which is bounded.
+    pub async fn list(&self, collection: &str) -> Result<Vec<Record>> {
+        self.send::<_, ()>(Method::GET, &collection_path(collection), None)
+            .await
+    }
+
+    /// Create a record only if `id` is free; refused with HTTP 409 if it exists. `value` must be a
+    /// JSON object. Without an id, the server assigns one.
+    pub async fn create(&self, collection: &str, id: Option<&str>, value: Value) -> Result<Record> {
+        let Value::Object(mut fields) = value else {
+            return Err(Error::InvalidRequest(
+                "a record must be a JSON object".into(),
+            ));
+        };
+        if let Some(id) = id {
+            fields.insert("id".into(), Value::String(id.to_owned()));
+        }
+        self.send(Method::POST, &collection_path(collection), Some(&fields))
+            .await
+    }
+
+    /// Merge `changes` into an existing record (unconditionally). Refused with HTTP 404 if the
+    /// record does not exist; use a [`Transaction`] or [`Client::compare_and_set`] to fence it.
+    pub async fn update(
+        &self,
+        collection: &str,
+        id: &str,
+        changes: Map<String, Value>,
+    ) -> Result<Record> {
+        self.send(Method::PATCH, &record_path(collection, id), Some(&changes))
+            .await
+    }
+
+    /// Delete an existing record. Refused with HTTP 404 if it does not exist.
+    pub async fn delete(&self, collection: &str, id: &str) -> Result<()> {
+        self.exchange::<()>(Method::DELETE, &record_path(collection, id), None)
+            .await
+            .map(drop)
+    }
+
+    /// Replace a record if it still has the version (and epoch and lease) you read.
+    pub async fn compare_and_set(
+        &self,
+        collection: &str,
+        id: &str,
+        request: &CasRequest,
+    ) -> Result<CasOutcome> {
+        let path = format!("{}/cas", record_path(collection, id));
+        let body: CasBody = match self.send(Method::POST, &path, Some(request)).await {
+            Ok(body) => body,
+            // A conflict is an answer, carried in the error body; anything else stays an error.
+            Err(Error::Api(error)) if error.status == 409 || error.status == 404 => {
+                if error.status == 404 && error.code == "NOT_FOUND" {
+                    return Ok(CasOutcome::NotFound);
+                }
+                match serde_json::from_value::<CasBody>(error.body.clone()) {
+                    Ok(body) if body.code.is_some() => body,
+                    _ => return Err(Error::Api(error)),
+                }
+            }
+            Err(error) => return Err(error),
+        };
+        if body.updated {
+            return Ok(CasOutcome::Updated {
+                current_version: body.current_version,
+                current_epoch: body.current_epoch,
+                item: body.item,
+            });
+        }
+        let code = body.code.unwrap_or_default();
+        let conflict = serde_json::from_value(Value::String(code.clone())).map_err(|_| {
+            Error::InvalidRequest(format!("unrecognized compare-and-set refusal {code:?}"))
+        })?;
+        Ok(CasOutcome::Conflict {
+            conflict,
+            current_version: body.current_version,
+            current_epoch: body.current_epoch,
+        })
+    }
+
+    /// Commit a transaction atomically. A refusal applied nothing; a failed precondition or fence
+    /// is reported in [`Error::precondition_failure`].
+    pub async fn commit(&self, transaction: &Transaction) -> Result<CommitReceipt> {
+        transaction.validate()?;
+        self.send(Method::POST, "/transactions", Some(transaction))
+            .await
+    }
+
+    /// Capture what the authority holds for `reads`, to fence a later transaction on it.
+    pub async fn read_basis(&self, reads: &ReadSet) -> Result<ReadBasis> {
+        self.send(Method::POST, "/transactions/read-basis", Some(reads))
+            .await
+    }
+
+    /// Run one page of a bounded query.
+    pub async fn query(&self, query: &BoundedQuery) -> Result<QueryPage> {
+        self.send(Method::POST, "/query", Some(query)).await
+    }
+
+    /// The authority's committed revision.
+    pub async fn revision(&self) -> Result<Revision> {
+        self.send::<_, ()>(Method::GET, "/revision", None).await
+    }
+
+    /// Committed changes as they happen, from `cursor` (a previous event's id) or from now.
+    pub async fn events(&self, cursor: Option<&str>) -> Result<EventStream> {
+        self.open_events("/events", cursor).await
+    }
+}
+
+fn collection_path(collection: &str) -> String {
+    format!("/collections/{}", encode(collection))
+}
+
+fn record_path(collection: &str, id: &str) -> String {
+    format!("/collections/{}/{}", encode(collection), encode(id))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn a_transaction_serializes_as_the_authority_reads_it() {
+        let transaction = Transaction::new("tx-1")
+            .operation(Operation::create("orders", "o-1", json!({ "n": 1 })))
+            .operation(Operation::put("orders", "o-2", json!({ "n": 2 })).expect_version(3))
+            .operation(Operation::delete("orders", "o-3"))
+            .precondition(Precondition::absent("locks", "l-1"));
+        assert_eq!(
+            serde_json::to_value(&transaction).unwrap(),
+            json!({
+                "transactionId": "tx-1",
+                "operations": [
+                    { "collection": "orders", "id": "o-1", "value": { "n": 1 }, "requireAbsent": true },
+                    { "collection": "orders", "id": "o-2", "value": { "n": 2 }, "expectedVersion": 3 },
+                    { "collection": "orders", "id": "o-3" }
+                ],
+                "preconditions": [{ "collection": "locks", "id": "l-1", "requireAbsent": true }]
+            })
+        );
+    }
+
+    #[test]
+    fn a_transaction_the_server_would_refuse_is_refused_here() {
+        assert!(Transaction::new("tx").validate().is_err());
+        assert!(Transaction::new("tx")
+            .operation(Operation::put("c", "i", json!([1])))
+            .validate()
+            .is_err());
+    }
+
+    #[test]
+    fn a_bounded_query_serializes_its_conditions_by_operator() {
+        let query = BoundedQuery::new("orders", 10)
+            .eq("status", json!("open"))
+            .gte("total", json!(5))
+            .order_by("id", Direction::Asc)
+            .after("cursor-1");
+        assert_eq!(
+            serde_json::to_value(&query).unwrap(),
+            json!({
+                "collection": "orders",
+                "where": [{ "field": "status", "eq": "open" }, { "field": "total", "gte": 5 }],
+                "orderBy": [{ "field": "id", "direction": "asc" }],
+                "limit": 10,
+                "cursor": "cursor-1"
+            })
+        );
+    }
+}