diff options
| -rw-r--r-- | docs/openapi.yaml | 230 | ||||
| -rw-r--r-- | src/api/access.rs | 8 | ||||
| -rw-r--r-- | src/api/events.rs | 266 | ||||
| -rw-r--r-- | src/api/mod.rs | 7 |
4 files changed, 510 insertions, 1 deletions
diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 0f1af33..0bce165 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -51,6 +51,12 @@ tags: refused (`409`). - name: Debug description: Test hooks, only with `--debug-api`. + - name: Events + description: | + A swarm holding a store (docs/store.md): its events, which whoever this node lets + in may have it put, whoever signed them; what its fold reads from them; and this + node's own refusals and drops. Only with the `federation` cargo feature; `404` + while the node holds no store (its swarm holds none, or it hasn't read it yet). paths: /store: @@ -1405,6 +1411,221 @@ paths: text/event-stream: schema: type: string + /events: + get: + tags: [Events] + summary: The store + description: | + The store's ID (its root's), its checkpoint's ID, its heads (what a new event + builds on) and how many events it took after its checkpoint, as this node reads + it now. + responses: + '200': + description: The store. + content: + application/json: + schema: + type: object + required: [store, checkpoint, heads, taken] + properties: + store: + type: string + checkpoint: + type: string + heads: + type: array + items: + type: string + taken: + type: integer + '404': + $ref: '#/components/responses/Error' + post: + tags: [Events] + summary: Put an event + description: | + Puts an event, the body as its bytes, whoever signed it: offered to the store, + and written into the document at its ID (the SHA-256 of its bytes) unless the + store refuses it. `event` says what became of it: `taken`, `held` (taken + before), or `waiting` for what it builds on. + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + '200': + description: Put. + content: + application/json: + schema: + type: object + required: [id, event] + properties: + id: + type: string + event: + type: string + enum: [taken, held, waiting] + '404': + $ref: '#/components/responses/Error' + '422': + description: The store refuses it; `id` and `why` say which, and why. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /events/{id}: + get: + tags: [Events] + summary: An event + description: | + An event the store holds, taken or kept by its checkpoint, or its checkpoint, as + its bytes. + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '200': + description: Its bytes. + content: + application/json: + schema: + type: object + '400': + $ref: '#/components/responses/Error' + '404': + $ref: '#/components/responses/Error' + /events/counts: + get: + tags: [Events] + summary: What counts + description: | + What counts, as the store reads now (docs/federation.md): the current version + (its number, its hash, and the version itself), each party's keys and nodes, the + value at each place, and the members, each `[node, party]`. + responses: + '200': + description: What counts. + content: + application/json: + schema: + type: object + required: [version, parties, values, members] + properties: + version: + type: object + parties: + type: object + values: + type: object + members: + type: array + items: + type: array + items: + type: string + '404': + $ref: '#/components/responses/Error' + /events/refused: + get: + tags: [Events] + summary: What the store refused + description: | + The events the store refused: `own`, those its history takes but this node + doesn't, by what it took before (a version changing another than the one it + reads), apart from the rest; `dropped`, those its operator had it drop; and + `refused`, every other, with why. + responses: + '200': + description: What it refused. + content: + application/json: + schema: + type: object + required: [own, dropped, refused] + properties: + own: + type: array + items: + type: string + dropped: + type: array + items: + type: string + refused: + type: array + items: + type: object + required: [id, why] + properties: + id: + type: string + why: + type: string + '404': + $ref: '#/components/responses/Error' + /admin/events/drop: + post: + tags: [Events] + summary: Drop events this node took + description: | + Drops events the store took after its checkpoint, with everything built on + them: this node refuses them from then on, from whoever brings them, and keeps + so across restarts (`--store-file`), until it is told otherwise + (`/admin/events/allow`). Not what the checkpoint keeps or holds by ID. Answers + what it dropped, in the order taken. Needs `write` on `_continuum`. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/EventIds' + responses: + '200': + description: Dropped. + content: + application/json: + schema: + type: object + required: [dropped] + properties: + dropped: + type: array + items: + type: string + '400': + $ref: '#/components/responses/Error' + '404': + $ref: '#/components/responses/Error' + '422': + $ref: '#/components/responses/Error' + /admin/events/allow: + post: + tags: [Events] + summary: Take back what this node refused of its own, or dropped + description: | + Takes back what this node refused of its own, or dropped, among the events + named, and what was refused for building on them: they are taken again where the + store takes them, as it reads its document again. Needs `write` on + `_continuum`. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/EventIds' + responses: + '204': + description: Taken back. + '400': + $ref: '#/components/responses/Error' + '404': + $ref: '#/components/responses/Error' /admin/remakes: get: tags: [Remakes] @@ -2078,6 +2299,15 @@ components: $ref: '#/components/schemas/Error' schemas: + EventIds: + type: object + required: [ids] + properties: + ids: + type: array + items: + type: string + description: Events by their IDs, in hex. Limit: type: object properties: diff --git a/src/api/access.rs b/src/api/access.rs index ddcaad0..9157e1d 100644 --- a/src/api/access.rs +++ b/src/api/access.rs @@ -274,7 +274,7 @@ fn needed(method: &Method, path: &str, node: &str) -> Need { let under = |prefix: &str| path == prefix || path.starts_with(&format!("{prefix}/")); // What this node holds alone: `_continuum/local/<node>/<name>`, never stored. let local = |right, name: &str| protocol(right, &[meta::LOCAL, node, name]); - if under("/store") || under("/stream") { + if under("/store") || under("/stream") || under("/events") { Need::Store } else if (under("/auth/keys") && !looking) || path == "/auth/logout" { Need::Credentials @@ -482,6 +482,12 @@ mod tests { assert_eq!(needed(&Method::GET, "/auth/whoami", "n1"), Need::Auth); assert_eq!(needed(&Method::PUT, "/store/a/b", "n1"), Need::Store); assert_eq!(needed(&Method::GET, "/stream/a", "n1"), Need::Store); + assert_eq!(needed(&Method::POST, "/events", "n1"), Need::Store); + assert_eq!(needed(&Method::GET, "/events/counts", "n1"), Need::Store); + assert_eq!( + needed(&Method::POST, "/admin/events/drop", "n1"), + write(&[]) + ); assert_eq!(needed(&Method::GET, "/storehouse", "n1"), read(&[])); assert_eq!(needed(&Method::GET, "/peers", "n1"), Need::Observe); assert_eq!(needed(&Method::GET, "/admin/stats", "n1"), Need::Observe); diff --git a/src/api/events.rs b/src/api/events.rs new file mode 100644 index 0000000..3291f02 --- /dev/null +++ b/src/api/events.rs @@ -0,0 +1,266 @@ +//! A swarm holding a store at a node's API (`docs/store.md`, Members): whoever its operator +//! lets in may have it put events, whoever signed them; it shows its store (its ID, its +//! checkpoint and its heads), an event it holds, what its fold reads from them, and what +//! it refused; and its operator has it drop what it took, and take it back. + +use axum::{ + Extension, Json, Router, + body::Bytes, + extract::{Path, State}, + http::{StatusCode, header::CONTENT_TYPE}, + response::{IntoResponse, Response}, + routing::{get, post}, +}; +use serde::Deserialize; +use serde_json::{Value as JsonValue, json}; + +use super::auth::AuthenticatedUser; +use super::{ApiError, error_response, store_status}; +use crate::document::events; +use crate::document::typed::{TimestampFormat, Val}; +use crate::document::{ScalarValue, store}; +use crate::federation::fold::Federation; +use crate::federation::jcs::Json as Jcs; +use crate::federation::store::Id; +use crate::federation::store::memory::{Offered, Refusal, Store}; +use crate::state::AppState; + +pub(super) fn router() -> Router<AppState> { + Router::new() + .route("/events", get(summary).post(put)) + .route("/events/counts", get(counts)) + .route("/events/refused", get(refused)) + .route("/events/{id}", get(event)) + .route("/admin/events/drop", post(drop_taken)) + .route("/admin/events/allow", post(allow)) +} + +/// The answer while the node holds no store. +fn no_store() -> Response { + error_response( + StatusCode::NOT_FOUND, + "this node holds no store: its swarm holds none, or it hasn't read it yet", + None, + ) +} + +/// `f` of the node's store, as JSON; `no_store` without one. +fn with_store(state: &AppState, f: impl FnOnce(&Store<Federation>) -> JsonValue) -> Response { + match state.holding.with(f) { + Some(body) => Json(body).into_response(), + None => no_store(), + } +} + +fn ids(ids: impl IntoIterator<Item = Id>) -> Vec<String> { + ids.into_iter().map(|id| id.to_string()).collect() +} + +/// A JCS value as plain JSON: its integers fit, by what an event may hold. +fn plain(json: &Jcs) -> JsonValue { + serde_json::from_slice(&json.bytes()).unwrap_or(JsonValue::Null) +} + +/// Why the store refused an event, said. +fn why(refusal: &Refusal) -> String { + match refusal { + Refusal::None => "none of the federation's events, or larger than it allows".to_owned(), + Refusal::Judged(why) => why.0.clone(), + Refusal::BuiltOn(id) => format!("it builds on {id}, refused"), + Refusal::NotAbove => "it isn't above the checkpoint's heads".to_owned(), + Refusal::Own => { + "its history takes it, but this node doesn't, by what it took before".to_owned() + } + Refusal::Dropped => "this node's operator had it drop it".to_owned(), + } +} + +/// `GET /events`: the store's ID, its checkpoint's, its heads, and how many events it +/// took after its checkpoint. +async fn summary(State(state): State<AppState>) -> Response { + with_store(&state, |store| { + json!({ + "store": store.id().to_string(), + "checkpoint": Id::of(store.checkpoint()).to_string(), + "heads": ids(store.heads()), + "taken": store.taken().len(), + }) + }) +} + +/// `GET /events/{id}`: an event the store holds, taken or kept by its checkpoint, or its +/// checkpoint, as its bytes. +async fn event(State(state): State<AppState>, Path(id): Path<String>) -> Response { + let Some(id) = Id::from_hex(&id) else { + return error_response(StatusCode::BAD_REQUEST, "not an event's ID", None); + }; + let bytes = state.holding.with(|store| { + store + .get(&id) + .map(<[u8]>::to_vec) + .or_else(|| (Id::of(store.checkpoint()) == id).then(|| store.checkpoint().to_vec())) + }); + match bytes { + None => no_store(), + Some(None) => error_response(StatusCode::NOT_FOUND, "no event this store holds", None), + Some(Some(bytes)) => ([(CONTENT_TYPE, "application/json")], bytes).into_response(), + } +} + +/// `GET /events/counts`: what counts, as the store reads now: the current version, each +/// party's keys and nodes, the values at places, and the members. +async fn counts(State(state): State<AppState>) -> Response { + with_store(&state, |store| { + let read = store.state(); + let current = read.current(); + let parties: serde_json::Map<String, JsonValue> = current + .parties + .keys() + .map(|party| { + ( + party.clone(), + json!({ + "keys": read.keys_of(party, current), + "nodes": read.nodes_of(party, current), + }), + ) + }) + .collect(); + let values: serde_json::Map<String, JsonValue> = read + .values() + .iter() + .map(|(path, value)| (path.clone(), plain(value))) + .collect(); + json!({ + "version": { + "number": current.number, + "hash": current.hash.to_string(), + "version": plain(¤t.json), + }, + "parties": parties, + "values": values, + "members": read.members(), + }) + }) +} + +/// `GET /events/refused`: what the store refused: of its own, by what it took before (the +/// federation: a version changing another than the one it reads), apart; what its +/// operator had it drop; and the rest, each with why. +async fn refused(State(state): State<AppState>) -> Response { + with_store(&state, |store| { + let (own, dropped) = store.own(); + let mut rest: Vec<(&Id, &Refusal)> = store + .refused() + .filter(|(_, refusal)| !matches!(refusal, Refusal::Own | Refusal::Dropped)) + .collect(); + rest.sort_unstable_by_key(|(id, _)| **id); + json!({ + "own": ids(own), + "dropped": ids(dropped), + "refused": rest + .into_iter() + .map(|(id, refusal)| json!({"id": id.to_string(), "why": why(refusal)})) + .collect::<Vec<_>>(), + }) + }) +} + +/// `POST /events`: puts an event, the request's body, whoever signed it: offered to the +/// store, and written into the document at its ID unless the store refuses it. Taken, +/// held already, or waiting for what it builds on. +async fn put( + State(state): State<AppState>, + Extension(AuthenticatedUser(user)): Extension<AuthenticatedUser>, + body: Bytes, +) -> Response { + let bytes = body.to_vec(); + let id = Id::of(&bytes); + let became = match state.holding.offer(bytes.clone()) { + None => return no_store(), + Some(Offered::Refused(refusal)) => { + return error_response( + StatusCode::UNPROCESSABLE_ENTITY, + "the store refuses it", + Some(json!({"id": id.to_string(), "why": why(&refusal)})), + ); + } + Some(Offered::Taken(_)) => "taken", + Some(Offered::Held) => "held", + Some(Offered::Waiting) => "waiting", + }; + let written = state + .mutate_doc_for( + Some(user), + crate::document::signatures::Sign::Protocol, + move |doc| { + if events::bytes(doc, &id).is_none() { + store::write_val_path( + doc, + &events::event(&id), + &Val::Scalar(ScalarValue::Bytes(bytes)), + store::Writing::sticky(TimestampFormat::default()), + )?; + } + Ok::<(), store::StoreError>(()) + }, + ) + .await; + match written { + Ok(_) => Json(json!({"id": id.to_string(), "event": became})).into_response(), + Err(error) => store_status(error, "Failed to put an event").into_response(), + } +} + +/// The events an operator names. +#[derive(Deserialize)] +struct Named { + ids: Vec<String>, +} + +impl Named { + fn ids(&self) -> Result<Vec<Id>, ApiError> { + self.ids + .iter() + .map(|id| { + Id::from_hex(id).ok_or_else(|| { + ApiError( + StatusCode::BAD_REQUEST, + Some(format!("{id:?} isn't an event's ID")), + ) + }) + }) + .collect() + } +} + +/// `POST /admin/events/drop`: drops events the store took after its checkpoint, with +/// everything built on them, as the operator has the node do: it refuses them from then +/// on, from whoever brings them, and keeps so across restarts (`--store-file`). What it +/// dropped, in the order taken. +async fn drop_taken(State(state): State<AppState>, Json(named): Json<Named>) -> Response { + let named = match named.ids() { + Ok(ids) => ids, + Err(error) => return error.into_response(), + }; + match state.holding.drop_taken(&named) { + None => no_store(), + Some(Err(why)) => error_response(StatusCode::UNPROCESSABLE_ENTITY, why.0, None), + Some(Ok(dropped)) => Json(json!({"dropped": ids(dropped)})).into_response(), + } +} + +/// `POST /admin/events/allow`: takes back what the node refused of its own, or dropped, +/// among the events named, and what was refused for building on them: taken again where +/// the store takes them, as it reads its document again. +async fn allow(State(state): State<AppState>, Json(named): Json<Named>) -> Response { + let named = match named.ids() { + Ok(ids) => ids, + Err(error) => return error.into_response(), + }; + if state.holding.allow(&named) { + StatusCode::NO_CONTENT.into_response() + } else { + no_store() + } +} diff --git a/src/api/mod.rs b/src/api/mod.rs index 97724ff..d91c434 100644 --- a/src/api/mod.rs +++ b/src/api/mod.rs @@ -10,6 +10,8 @@ mod cors; mod dashboard; mod debug; mod document; +#[cfg(feature = "federation")] +mod events; mod health; pub(crate) mod listen; mod log; @@ -102,6 +104,11 @@ pub(crate) fn router(state: AppState, auth_state: AuthState, debug_api: bool) -> api = api.merge(dashboard::router(state.clone())); } + #[cfg(feature = "federation")] + { + api = api.merge(events::router()); + } + if debug_api { warn!("Debug API enabled"); api = api.route( |
