create-feltdb 0.7.1 → 0.7.3

package/dist/server-source/crates/feltdb-server/src/main.rs

@@ -60,7 +60,7 @@ use feltdb::{
     DatabaseSnapshot, FeltDb, JsonCasResult, Operation, PeerAdvertisement, PeerId, StoredRow, FlowError, RecordPrecondition,
 };
 use feltdb_server::{
-    app_state::AppState,
+    app_state::{AppState, BoundedQueryCursor},
     application_contract::{ApplicationContractStore, ContractPatch},
     artifacts::{ArtifactKind, ArtifactLifecycle, ArtifactMetadata, ArtifactStore, ProducerRef},
     audit::{AuditEvent, AuditLog},
@@ -5803,6 +5803,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         workloads: Arc::new(std::sync::Mutex::new(workload_store)),
         mesh: Arc::new(std::sync::Mutex::new(mesh_store)),
         readiness_probe: Arc::new(readiness_probe),
+        bounded_query_cursors: Arc::new(std::sync::Mutex::new(HashMap::new())),
     };
     start_peer_sessions(&state, &config)?;
     start_membership_recovery(&state);
@@ -6310,6 +6311,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             axum::routing::delete(delete_connection_control),
         )
         .route("/transactions", axum::routing::post(commit_transaction))
+        .route("/query", axum::routing::post(execute_bounded_query))
         .route("/revision", get(get_revision))
         .route(
             "/collections/{collection}",
@@ -9011,6 +9013,187 @@ async fn get_revision(State(state): State<AppState>) -> Result<Json<RevisionResp
     }))
 }
 
+const MAX_BOUNDED_QUERY_LIMIT: usize = 500;
+const BOUNDED_CURSOR_TTL_SECONDS: u64 = 300;
+
+#[derive(Clone, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct BoundedQueryRequest {
+    collection: String,
+    #[serde(default, rename = "where")]
+    conditions: Vec<BoundedQueryCondition>,
+    #[serde(default)]
+    order_by: Vec<BoundedQueryOrder>,
+    limit: usize,
+    #[serde(default)]
+    cursor: Option<String>,
+}
+
+#[derive(Clone, Deserialize, Serialize)]
+struct BoundedQueryCondition {
+    field: String,
+    #[serde(flatten)]
+    operators: Map<String, Value>,
+}
+
+#[derive(Clone, Deserialize, Serialize)]
+struct BoundedQueryOrder {
+    field: String,
+    direction: String,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct BoundedQueryPage {
+    records: Vec<Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    next_cursor: Option<String>,
+    exhausted: bool,
+}
+
+fn bounded_query_error(code: &str, message: impl Into<String>) -> ApiError {
+    ApiError::structured(StatusCode::UNPROCESSABLE_ENTITY, json!({
+        "code": code,
+        "message": message.into(),
+    }))
+}
+
+fn bounded_query_hash(request: &BoundedQueryRequest) -> Result<String, ApiError> {
+    let context = json!({
+        "collection": request.collection,
+        "where": request.conditions,
+        "orderBy": request.order_by,
+        "limit": request.limit,
+    });
+    let bytes = serde_json::to_vec(&context)
+        .map_err(|error| bounded_query_error("INVALID_QUERY", error.to_string()))?;
+    Ok(format!("sha256:{:x}", Sha256::digest(bytes)))
+}
+
+fn query_scalar_cmp(left: Option<&Value>, right: Option<&Value>) -> std::cmp::Ordering {
+    match (left, right) {
+        (None, None) => std::cmp::Ordering::Equal,
+        (None, Some(_)) => std::cmp::Ordering::Less,
+        (Some(_), None) => std::cmp::Ordering::Greater,
+        (Some(Value::Null), Some(Value::Null)) => std::cmp::Ordering::Equal,
+        (Some(Value::Null), Some(_)) => std::cmp::Ordering::Less,
+        (Some(_), Some(Value::Null)) => std::cmp::Ordering::Greater,
+        (Some(Value::Number(a)), Some(Value::Number(b))) => a.as_f64().partial_cmp(&b.as_f64()).unwrap_or(std::cmp::Ordering::Equal),
+        (Some(Value::String(a)), Some(Value::String(b))) => a.cmp(b),
+        (Some(Value::Bool(a)), Some(Value::Bool(b))) => a.cmp(b),
+        (Some(a), Some(b)) => a.to_string().cmp(&b.to_string()),
+    }
+}
+
+fn condition_matches(record: &Value, condition: &BoundedQueryCondition) -> Result<bool, ApiError> {
+    if condition.operators.len() != 1 || condition.field.trim().is_empty() {
+        return Err(bounded_query_error("INVALID_QUERY", "each where condition requires a field and exactly one operator"));
+    }
+    let (operator, expected) = condition.operators.iter().next().expect("validated operator");
+    let actual = record.get(&condition.field);
+    if operator == "eq" { return Ok(actual == Some(expected)); }
+    if operator == "neq" { return Ok(actual != Some(expected)); }
+    let Some(actual) = actual else { return Ok(false) };
+    let comparison = query_scalar_cmp(Some(actual), Some(expected));
+    Ok(match operator.as_str() {
+        "lt" => comparison.is_lt(),
+        "lte" => !comparison.is_gt(),
+        "gt" => comparison.is_gt(),
+        "gte" => !comparison.is_lt(),
+        _ => return Err(bounded_query_error("INVALID_QUERY", format!("unsupported where operator: {operator}"))),
+    })
+}
+
+fn issue_bounded_cursor(state: &AppState, mut cursor: BoundedQueryCursor) -> Result<String, ApiError> {
+    let token = uuid::Uuid::new_v4().simple().to_string();
+    let now = unix_seconds_i64().max(0) as u64;
+    cursor.created_at = now;
+    let mut cursors = state.bounded_query_cursors.lock().map_err(|_| ApiError(StatusCode::INTERNAL_SERVER_ERROR, "query cursor store unavailable".into()))?;
+    cursors.retain(|_, value| now.saturating_sub(value.created_at) <= BOUNDED_CURSOR_TTL_SECONDS);
+    if cursors.len() >= 1024 {
+        return Err(ApiError(StatusCode::SERVICE_UNAVAILABLE, "query cursor capacity exhausted".into()));
+    }
+    cursors.insert(token.clone(), cursor);
+    Ok(token)
+}
+
+async fn execute_bounded_query(
+    State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
+    Json(request): Json<BoundedQueryRequest>,
+) -> Result<Json<BoundedQueryPage>, ApiError> {
+    validate_segment(&request.collection)?;
+    if request.limit == 0 || request.limit > MAX_BOUNDED_QUERY_LIMIT {
+        return Err(bounded_query_error("INVALID_QUERY", format!("limit must be between 1 and {MAX_BOUNDED_QUERY_LIMIT}")));
+    }
+    if request.order_by.is_empty() {
+        return Err(bounded_query_error("INVALID_QUERY", "orderBy must contain at least one field"));
+    }
+    for order in &request.order_by {
+        if order.field.trim().is_empty() || !matches!(order.direction.as_str(), "asc" | "desc") {
+            return Err(bounded_query_error("INVALID_QUERY", "orderBy directions must be asc or desc"));
+        }
+    }
+    for condition in &request.conditions {
+        if condition.operators.len() != 1 || condition.field.trim().is_empty()
+            || !condition.operators.keys().all(|operator| matches!(operator.as_str(), "eq" | "neq" | "lt" | "lte" | "gt" | "gte")) {
+            return Err(bounded_query_error("INVALID_QUERY", "each where condition requires a field and exactly one operator"));
+        }
+    }
+    let hash = bounded_query_hash(&request)?;
+    let (records, position) = if let Some(token) = &request.cursor {
+        let cursor = state.bounded_query_cursors.lock()
+            .map_err(|_| ApiError(StatusCode::INTERNAL_SERVER_ERROR, "query cursor store unavailable".into()))?
+            .get(token).cloned()
+            .ok_or_else(|| bounded_query_error("INVALID_CURSOR", "cursor is invalid or expired"))?;
+        if cursor.query_hash != hash || cursor.principal_key_id != principal.key_id || cursor.namespace != state.namespace.as_ref() {
+            return Err(bounded_query_error("INVALID_CURSOR", "cursor does not match this query, principal, or namespace"));
+        }
+        if (unix_seconds_i64().max(0) as u64).saturating_sub(cursor.created_at) > BOUNDED_CURSOR_TTL_SECONDS {
+            return Err(bounded_query_error("INVALID_CURSOR", "cursor is expired"));
+        }
+        (cursor.records, cursor.position)
+    } else {
+        let mut records = Vec::new();
+        for row in state.db.list_collection(&request.collection)? {
+            let mut value = row.value;
+            if let Some(object) = value.as_object_mut() {
+                let id = row.key.split_once(':').map(|(_, id)| id).unwrap_or(&row.key);
+                // `recordId` is authority metadata for this query surface, not
+                // caller-controlled document data. It is the final total-order
+                // tie-breaker even when a document contains a field by that name.
+                object.insert("recordId".into(), Value::String(id.to_string()));
+            }
+            if request.conditions.iter().all(|condition| condition_matches(&value, condition).unwrap_or(false)) {
+                records.push(value);
+            }
+        }
+        // The authority always adds its immutable record identity as the final
+        // tie-breaker, so equal user sort values still form a total order.
+        records.sort_by(|left, right| {
+            for order in &request.order_by {
+                let comparison = query_scalar_cmp(left.get(&order.field), right.get(&order.field));
+                if !comparison.is_eq() { return if order.direction == "desc" { comparison.reverse() } else { comparison }; }
+            }
+            query_scalar_cmp(left.get("recordId"), right.get("recordId"))
+        });
+        (Arc::new(records), 0)
+    };
+    let end = position.saturating_add(request.limit).min(records.len());
+    let page = records[position.min(records.len())..end].to_vec();
+    let next_cursor = if end < records.len() {
+        Some(issue_bounded_cursor(&state, BoundedQueryCursor {
+            query_hash: hash,
+            principal_key_id: principal.key_id,
+            namespace: state.namespace.to_string(),
+            records: records.clone(),
+            position: end,
+            created_at: 0,
+        })?)
+    } else { None };
+    Ok(Json(BoundedQueryPage { records: page, exhausted: next_cursor.is_none(), next_cursor }))
+}
+
 async fn list_records(
     State(state): State<AppState>,
     Path(collection): Path<String>,

package/package.json

@@ -2,7 +2,7 @@
   "name": "create-feltdb",
   "private": false,
   "description": "Create a new FeltDB application with one command",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "license": "MIT",
   "bin": {
     "create-feltdb": "bin/create-feltdb.js"