diff options
| author | tv <tv@krebsco.de> | 2026-11-17 00:27:24 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-17 01:47:46 +0100 |
| commit | 202bb27664956f9dc113c751e1fd36877d48978c (patch) | |
| tree | 0d5976d6b173c5b86fed7723f5551c401c31d6ba | |
| parent | 438d4f06103ba7ae17a80f48aa589219c7d8dd61 (diff) | |
api: a fork's root made, and what a node finds of one
`POST /admin/events/fork`: the root of the fork at the heads named by the version
given, as the node's store builds it, with the events it keeps, as the file the fork's
founders start its swarm from (`--store-root`). `POST /events/fork`: what the node finds
of the fork whose root the body holds: whether it builds that root at its heads, and
why not; what it holds that those heads lack; and the parties whose keys the fork's
version gives otherwise than they had there (`federation::fork`).
| -rw-r--r-- | docs/openapi.yaml | 99 | ||||
| -rw-r--r-- | src/api/events.rs | 90 |
2 files changed, 177 insertions, 12 deletions
diff --git a/docs/openapi.yaml b/docs/openapi.yaml index c99cb65..c2cee82 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -1592,6 +1592,66 @@ paths: type: string '404': $ref: '#/components/responses/Error' + /events/fork: + post: + tags: [Events] + summary: What this node finds of a fork's root + description: | + What this node, holding its federation's history, finds of the fork whose root + is the body's first line, as the file the fork's founders start from holds it + (`/admin/events/fork`): whether it builds that root at its heads by its version, + byte for byte, and why it builds none where it doesn't (heads it doesn't hold, + a version that is no fork); what it holds that those heads lack (`lacking`: + events it took that are neither among them, nor in their history, nor above + them); and the parties whose keys the fork's version gives otherwise than they + had at those heads, each with its keys there and in the fork. A node that + doesn't hold that history takes a fork's root on its operator's word, who names + the fork by its ID (`--store-id`). + requestBody: + required: true + content: + application/octet-stream: + schema: + type: string + format: binary + responses: + '200': + description: What it finds. + content: + application/json: + schema: + type: object + required: [fork, builds, why, lacking, keys] + properties: + fork: + type: string + builds: + type: boolean + why: + type: string + nullable: true + lacking: + type: array + items: + type: string + keys: + type: object + additionalProperties: + type: object + required: [there, fork] + properties: + there: + type: array + items: + type: string + fork: + type: array + items: + type: string + '404': + $ref: '#/components/responses/Error' + '422': + $ref: '#/components/responses/Error' /admin/events/drop: post: tags: [Events] @@ -1689,6 +1749,45 @@ paths: $ref: '#/components/responses/Error' '422': $ref: '#/components/responses/Error' + /admin/events/fork: + post: + tags: [Events] + summary: Make a fork's root + description: | + The root of the fork at `heads` by `version` (`docs/federation.md`, Forks), as + this node's store builds it, with the events it keeps there: the file the fork's + founders start its swarm from (`--store-root`), the root on its first line and + each event it keeps on a line of its own. The version changes the one current at + those heads and is numbered one past it; a fork is named by its root's ID. Needs + `write` on `_continuum`. + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [heads, version] + properties: + heads: + type: array + items: + type: string + version: + type: object + responses: + '200': + description: The fork's root, and the events it keeps. + content: + application/octet-stream: + schema: + type: string + format: binary + '400': + $ref: '#/components/responses/Error' + '404': + $ref: '#/components/responses/Error' + '422': + $ref: '#/components/responses/Error' /admin/remakes: get: tags: [Remakes] diff --git a/src/api/events.rs b/src/api/events.rs index 8eb243d..9fa8786 100644 --- a/src/api/events.rs +++ b/src/api/events.rs @@ -1,7 +1,8 @@ //! 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. +//! checkpoint and its heads), an event it holds, what its fold reads from them, what it +//! refused, and what it finds of a fork's root; and its operator has it drop what it +//! took, take it back, and make a fork's root. use axum::{ Extension, Json, Router, @@ -17,6 +18,7 @@ use serde_json::{Value as JsonValue, json}; use super::auth::AuthenticatedUser; use super::{ApiError, error_response, store_status}; use crate::federation::fold::Federation; +use crate::federation::fork; use crate::federation::jcs::Json as Jcs; use crate::federation::store::Id; use crate::federation::store::memory::{Offered, Refusal, Store}; @@ -27,10 +29,12 @@ pub(super) fn router() -> Router<AppState> { .route("/events", get(summary).post(put)) .route("/events/counts", get(counts)) .route("/events/refused", get(refused)) + .route("/events/fork", post(check_fork)) .route("/events/{id}", get(event)) .route("/admin/events/drop", post(drop_taken)) .route("/admin/events/allow", post(allow)) .route("/admin/events/vote", post(vote)) + .route("/admin/events/fork", post(make_fork)) } /// The answer while the node holds no store. @@ -263,17 +267,79 @@ struct Named { 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")), - ) - }) + read_ids(&self.ids) + } +} + +/// `ids`, each an event's ID in hex. +fn read_ids(ids: &[String]) -> Result<Vec<Id>, ApiError> { + 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() + }) + .collect() +} + +/// A fork to make: the heads it forks at, and its version. +#[derive(Deserialize)] +struct Forking { + heads: Vec<String>, + version: JsonValue, +} + +/// `POST /admin/events/fork`: the root of the fork at `heads` by `version`, as this node's +/// store builds it, with the events the root keeps: the file its founders start its swarm +/// from (`--store-root`), the root on its first line, each event it keeps on a line of +/// its own. +async fn make_fork(State(state): State<AppState>, Json(forking): Json<Forking>) -> Response { + let heads = match read_ids(&forking.heads) { + Ok(heads) => heads, + Err(error) => return error.into_response(), + }; + let version = match crate::federation::client::json(&forking.version) { + Ok(version) => version, + Err(why) => return error_response(StatusCode::BAD_REQUEST, why, None), + }; + match state + .holding + .with(|store| fork::make(store, &heads, &version)) + { + None => no_store(), + Some(Err(why)) => error_response(StatusCode::UNPROCESSABLE_ENTITY, why, None), + Some(Ok(file)) => ([(CONTENT_TYPE, "application/octet-stream")], file).into_response(), + } +} + +/// `POST /events/fork`: what this node finds of the fork whose root is the body's first +/// line, as the file its founders start from holds it: whether it builds that root at +/// its heads, and why not; what it holds that those heads lack; and the parties whose keys +/// the fork's version gives otherwise than they had there, each with its keys there and in +/// the fork. +async fn check_fork(State(state): State<AppState>, body: Bytes) -> Response { + let (root, _) = fork::read_root_file(&body); + match state.holding.with(|store| fork::check(store, &root)) { + None => no_store(), + Some(Err(why)) => error_response(StatusCode::UNPROCESSABLE_ENTITY, why, None), + Some(Ok(check)) => { + let keys: serde_json::Map<String, JsonValue> = check + .keys + .into_iter() + .map(|(party, there, forked)| (party, json!({"there": there, "fork": forked}))) + .collect(); + Json(json!({ + "fork": Id::of(&root).to_string(), + "builds": check.builds, + "why": check.why, + "lacking": ids(check.lacking), + "keys": keys, + })) + .into_response() + } } } |
