Skip to main content

datumesh_http/
http.rs

1//! The endpoints: an axum router over a [`Mesh`].
2
3use std::net::{IpAddr, Ipv4Addr, SocketAddr};
4use std::sync::{Arc, Mutex};
5use std::time::{Duration, Instant};
6
7use axum::body::{Body, Bytes};
8use axum::extract::{ConnectInfo, MatchedPath, Path, Query, Request, State};
9use axum::http::{header, HeaderMap, HeaderValue, StatusCode, Uri};
10use axum::middleware::{self, Next};
11use axum::response::{IntoResponse, Response};
12use axum::routing::{get, post};
13use axum::Router;
14use datumesh_core::json::{self, Value};
15use datumesh_core::{lexical, ErrorCode, Pending, Request as CoreRequest};
16use tracing::Instrument;
17use utoipa::OpenApi;
18
19use crate::apikeys::Principal;
20use crate::envelope::{self, Cache, Reply, JSON};
21use crate::jobs::Poll;
22use crate::limit::Client;
23use crate::mesh::{Inner, Memo, Mesh};
24
25/// The principal of a request, for the access log.
26#[derive(Clone)]
27struct Who(Option<String>);
28
29fn to_response(r: Reply) -> Response {
30    let mut resp = Response::new(Body::from(r.body));
31    *resp.status_mut() = StatusCode::from_u16(r.status).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR);
32    let h = resp.headers_mut();
33    h.insert(header::CONTENT_TYPE, HeaderValue::from_static(r.content_type));
34    if let Ok(v) = HeaderValue::from_str(&r.cache.header()) {
35        h.insert(header::CACHE_CONTROL, v);
36    }
37    if let Some(c) = r.canonical {
38        if let Ok(v) = HeaderValue::from_str(&format!("<{c}>; rel=\"canonical\"")) {
39            h.insert(header::LINK, v);
40        }
41    }
42    if let Some(s) = r.retry_after {
43        h.insert(header::RETRY_AFTER, HeaderValue::from(s));
44    }
45    resp
46}
47
48fn plain_json(status: u16, v: Value, cache: Cache) -> Response {
49    to_response(Reply::json(status, v.to_jcs(), cache))
50}
51
52fn not_found(what: &str) -> Response {
53    plain_json(404, Value::Object(vec![("error".into(), Value::String(format!("no such {what}")))]), Cache::Public(60))
54}
55
56/// The client: its IP and, with a valid API key, its principal. An `Authorization` header
57/// that is not a key of this mesh is answered `unlicensed`.
58fn who(inner: &Inner, headers: &HeaderMap, peer: IpAddr) -> Result<(Client, Option<Principal>), Reply> {
59    let ip = client_ip(inner, headers, peer);
60    match headers.get(header::AUTHORIZATION) {
61        None => Ok((Client::Ip(ip), None)),
62        Some(v) => {
63            let p = v
64                .to_str()
65                .ok()
66                .and_then(|s| s.strip_prefix("Bearer "))
67                .and_then(|k| inner.config.api_keys.principal(k.trim()));
68            match p {
69                Some(p) => Ok((Client::Key(p.id.clone(), p.per_minute), Some(p.clone()))),
70                None => Err(Reply::json(403, envelope::unlicensed(), Cache::Private)),
71            }
72        }
73    }
74}
75
76fn client_ip(inner: &Inner, headers: &HeaderMap, peer: IpAddr) -> IpAddr {
77    if inner.config.trust_proxy {
78        if let Some(ip) = headers
79            .get("x-forwarded-for")
80            .and_then(|v| v.to_str().ok())
81            .and_then(|s| s.rsplit(',').next())
82            .and_then(|s| s.trim().parse::<IpAddr>().ok())
83        {
84            return ip;
85        }
86    }
87    peer
88}
89
90fn peer_of(req: &Request) -> IpAddr {
91    req.extensions().get::<ConnectInfo<SocketAddr>>().map(|c| c.0.ip()).unwrap_or(IpAddr::V4(Ipv4Addr::UNSPECIFIED))
92}
93
94/// `rest` of a `/<prefix>/<rest>` request, query included, as received.
95fn rest_of(uri: &Uri, prefix: &str) -> String {
96    let path = uri.path().strip_prefix(prefix).unwrap_or("");
97    match uri.query() {
98        Some(q) => format!("{path}?{q}"),
99        None => path.to_string(),
100    }
101}
102
103/// Runs `f` on the pool within the request's budget: its reply, or, past the budget, a
104/// `pending` envelope whose job gets the reply when `f` finishes. `f` reports the request
105/// description as soon as it knows it.
106async fn within_budget(
107    inner: Arc<Inner>,
108    f: impl FnOnce(&Inner, &mut dyn FnMut(&crate::call::Target)) -> Reply + Send + 'static,
109) -> Reply {
110    let deadline = tokio::time::Instant::now() + inner.config.budget;
111    let (tx, mut rx) = tokio::sync::watch::channel::<Option<CoreRequest>>(None);
112    let pool = inner.pool.clone();
113    let i2 = inner.clone();
114    let mut task = tokio::spawn(async move {
115        pool.run(move || {
116            let mut on = |t: &crate::call::Target| {
117                if let Some(r) = request_of(t) {
118                    let _ = tx.send(Some(r));
119                }
120            };
121            f(&i2, &mut on)
122        })
123        .await
124    });
125    match tokio::time::timeout_at(deadline, &mut task).await {
126        Ok(Ok(Some(r))) => r,
127        Ok(_) => envelope::error_reply(ErrorCode::EvalUnavailable),
128        Err(_) => {
129            let request = rx.borrow_and_update().clone();
130            let Some(request) = request else {
131                // Past the budget before the request was even resolved (the store or another
132                // mesh is slow): the mesh cannot say what it is computing.
133                return envelope::error_reply(ErrorCode::EvalUnavailable);
134            };
135            pend(inner, request, task)
136        }
137    }
138}
139
140/// The request description of a target: its cell id, asof and pin (spec-0.4.2).
141fn request_of(t: &crate::call::Target) -> Option<CoreRequest> {
142    let r = CoreRequest::new(t.cell_id(), t.asof()).ok()?;
143    match &t.pin {
144        Some(p) => r.with_pin(p).ok(),
145        None => Some(r),
146    }
147}
148
149/// A job for a request still running in `task`.
150fn pend(inner: Arc<Inner>, request: CoreRequest, task: tokio::task::JoinHandle<Option<Reply>>) -> Reply {
151    let Some(id) = inner.jobs.create(request.clone()) else {
152        return envelope::error_reply(ErrorCode::EvalUnavailable);
153    };
154    let poll = format!("{}/jobs/{id}", inner.config.origin());
155    let est = inner.jobs.estimate(inner.config.budget.as_secs());
156    let i2 = inner.clone();
157    let id2 = id.clone();
158    tokio::spawn(async move {
159        let r = match task.await {
160            Ok(Some(r)) if r.status != 202 => r,
161            _ => envelope::error_reply(ErrorCode::EvalUnavailable),
162        };
163        let mut r = r;
164        r.cache = Cache::NoStore;
165        r.canonical = None;
166        i2.jobs.complete(&id2, r);
167    });
168    match Pending::new(&id, est, &poll, request) {
169        Ok(p) => Reply::json(202, envelope::pending(&p), Cache::NoStore),
170        Err(_) => envelope::error_reply(ErrorCode::EvalUnavailable),
171    }
172}
173
174fn admit(inner: &Inner, client: &Client, cost: u32) -> Result<(), Reply> {
175    inner.limiter.admit(client, cost).map_err(envelope::rate_limited_reply)
176}
177
178#[derive(OpenApi)]
179#[openapi(
180    info(
181        title = "datumesh-mesh",
182        description = "The Datumesh engine behind HTTPS (spec-0.4.1): cell envelopes (SPEC 5.5), batches, slices, receipts, descriptors, manifests, blobs, lineage, search, verification, jobs, key and mesh documents (SPEC 9.2, 9.6), bindings (SPEC 9.7).",
183        license(name = "Apache-2.0")
184    ),
185    paths(
186        cell,
187        cells,
188        slice,
189        versions,
190        receipt,
191        descriptor,
192        manifest,
193        blob,
194        explain,
195        find,
196        verify_receipt,
197        job,
198        key_document,
199        mesh_document,
200        bindings,
201        describe,
202        takeover_page,
203        series_page,
204        series_sitemap,
205        whatif,
206        x_calc,
207        x_keys_challenge,
208        x_keys,
209        x_interval,
210        health,
211        metrics,
212        openapi_json
213    )
214)]
215struct ApiDoc;
216
217/// The OpenAPI document (generated from the handlers' annotations).
218pub fn openapi() -> utoipa::openapi::OpenApi {
219    ApiDoc::openapi()
220}
221
222/// The envelope of a cell.
223#[utoipa::path(get, path = "/cell/{cell}",
224    params(("cell" = String, Path, description = "A cell URI's rest (SPEC 5.3), byte for byte, `asof` included; or a call (SPEC 15.3's read syntax, URL-encoded) with an optional `?asof=`.")),
225    responses(
226        (status = 200, description = "`ok` or `stale`", content_type = "application/json"),
227        (status = 202, description = "`pending`: poll the job (SPEC 5.5)", content_type = "application/json"),
228        (status = 400, description = "`bad_request`", content_type = "application/json"),
229        (status = 402, description = "`payment_required`", content_type = "application/json"),
230        (status = 403, description = "`unlicensed`", content_type = "application/json"),
231        (status = 404, description = "`not_covered` (with `fault` when the evaluation faulted)", content_type = "application/json"),
232        (status = 406, description = "the Accept header excludes JSON"),
233        (status = 429, description = "`rate_limited`, with `Retry-After`", content_type = "application/json"),
234        (status = 500, description = "`error`", content_type = "application/json"),
235        (status = 503, description = "`error`: the store or another mesh is unavailable", content_type = "application/json"),
236    ))]
237async fn cell(State(mesh): State<Mesh>, uri: Uri, headers: HeaderMap, req: Request) -> Response {
238    let inner = mesh.inner.clone();
239    let (client, principal) = match who(&inner, &headers, peer_of(&req)) {
240        Ok(x) => x,
241        Err(r) => return to_response(r),
242    };
243    let mut resp = match admit(&inner, &client, 1) {
244        Err(r) => to_response(r),
245        Ok(()) => {
246            let rest = rest_of(&uri, "/cell/");
247            let p = principal.clone();
248            let r = within_budget(inner.clone(), move |i, on| {
249                let now = i.now();
250                i.answer(&rest, p.as_ref(), i, &now, on)
251            })
252            .await;
253            if let Some(o) = r.outcome() {
254                inner.metrics.outcome("/cell/{cell}", &o);
255            }
256            to_response(r)
257        }
258    };
259    resp.extensions_mut().insert(Who(principal.map(|p| p.id)));
260    resp
261}
262
263/// A batch of cells.
264#[utoipa::path(post, path = "/cells",
265    request_body(content = String, description = "A JSON array of requests, each a call or a cell URI (`cell://...`) as a string, or `{\"cell\": <that>}`; at most the configured bound (1,000).", content_type = "application/json"),
266    responses(
267        (status = 200, description = "A JSON array of envelopes, in order; each has the HTTP status its outcome has (`error`: 500)", content_type = "application/json"),
268        (status = 400, description = "Not such an array, or too long", content_type = "application/json"),
269        (status = 429, description = "`rate_limited` (a batch of n cells counts as n / 50 requests)", content_type = "application/json"),
270    ))]
271async fn cells(State(mesh): State<Mesh>, headers: HeaderMap, req: Request) -> Response {
272    let inner = mesh.inner.clone();
273    let peer = peer_of(&req);
274    let (client, principal) = match who(&inner, &headers, peer) {
275        Ok(x) => x,
276        Err(r) => return to_response(r),
277    };
278    let body = match axum::body::to_bytes(req.into_body(), 64 << 20).await {
279        Ok(b) => b,
280        Err(_) => return to_response(envelope::bad_request_reply(ErrorCode::CanonLimit)),
281    };
282    let items = match parse_batch(&body, inner.config.batch_max) {
283        Ok(i) => i,
284        // A refusal of the whole batch (5.7): one envelope.
285        Err((code, detail)) => {
286            tracing::info!(target: "datumesh_http", detail = %detail, "batch refused");
287            return to_response(envelope::bad_request_reply(code));
288        }
289    };
290    if let Err(r) = admit(&inner, &client, inner.limiter.batch_cost(items.len())) {
291        return to_response(r);
292    }
293    let pieces = batch(inner.clone(), items, principal.clone()).await;
294    let mut counts: std::collections::BTreeMap<&str, u64> = std::collections::BTreeMap::new();
295    for w in &pieces {
296        for (o, k) in &w.outcomes {
297            *counts.entry(o).or_default() += k;
298        }
299    }
300    for (o, k) in counts {
301        inner.metrics.outcomes("/cells", o, k);
302    }
303    // 5.7: [{"envelope": <the envelope>, "status": <its status>}] in request order: the
304    // chunks' runs as they wrote them (the first opening the array).
305    let mut out = Vec::with_capacity(pieces.iter().map(|w| w.bytes.len()).sum::<usize>() + 2);
306    for w in &pieces {
307        out.extend_from_slice(&w.bytes);
308    }
309    out.extend_from_slice(if pieces.is_empty() { b"[]" } else { b"]" });
310    let mut resp =
311        to_response(Reply::json(200, out, if principal.is_some() { Cache::Private } else { Cache::NoStore }));
312    resp.extensions_mut().insert(Who(principal.map(|p| p.id)));
313    resp
314}
315
316fn batch_error(e: &str) -> Response {
317    plain_json(400, Value::Object(vec![("error".into(), Value::String(e.to_string()))]), Cache::NoStore)
318}
319
320/// The batch's requests, or the code of its refusal: `E_PARSE_URI` for a body that is not an
321/// array of requests, `E_CANON_LIMIT` for more than the mesh accepts (5.7).
322fn parse_batch(body: &[u8], max: usize) -> Result<Vec<String>, (ErrorCode, String)> {
323    let pu = |m: String| (ErrorCode::ParseUri, m);
324    // The body is a list of requests, not a protocol object: plain JSON.
325    let v: serde_json::Value = serde_json::from_slice(body).map_err(|e| pu(format!("not JSON: {e}")))?;
326    let serde_json::Value::Array(items) = v else { return Err(pu("not a JSON array".into())) };
327    if items.len() > max {
328        return Err((ErrorCode::CanonLimit, format!("{} requests: at most {max}", items.len())));
329    }
330    items
331        .into_iter()
332        .map(|i| {
333            let s = match i {
334                serde_json::Value::String(s) => s,
335                serde_json::Value::Object(mut o) => match o.remove("cell") {
336                    Some(serde_json::Value::String(s)) => s,
337                    _ => return Err(pu("an object without a string cell".to_string())),
338                },
339                _ => return Err(pu("an item that is neither a string nor an object".to_string())),
340            };
341            Ok(match s.strip_prefix("cell://") {
342                Some(r) => r.to_string(),
343                None => s,
344            })
345        })
346        .collect()
347}
348
349/// A run of a batch's answers as 5.7 writes them: the items
350/// `{"envelope": <the envelope>, "status": <its status>}` (JCS member order) joined by commas,
351/// and how many of each outcome they hold. Each chunk writes its own on the pool, in
352/// parallel: reading 1,000 envelopes (each a receipt, the function hash echoed) to copy and
353/// count them is the costliest part of a warm batch after the answers themselves.
354#[derive(Default)]
355struct Written {
356    bytes: Vec<u8>,
357    outcomes: Vec<(String, u64)>,
358}
359
360impl Written {
361    /// The run of `replies`, opening the array when `first`, else continuing it.
362    fn of<'a>(first: bool, replies: impl Iterator<Item = &'a Reply> + Clone) -> Written {
363        let mut w = Written {
364            bytes: Vec::with_capacity(replies.clone().map(|r| r.body.len() + 32).sum::<usize>() + 1),
365            outcomes: vec![],
366        };
367        w.bytes.push(if first { b'[' } else { b',' });
368        for (i, r) in replies.enumerate() {
369            if i > 0 {
370                w.bytes.push(b',');
371            }
372            w.push(r);
373        }
374        w
375    }
376
377    fn push(&mut self, r: &Reply) {
378        self.bytes.extend_from_slice(b"{\"envelope\":");
379        self.bytes.extend_from_slice(&r.body);
380        self.bytes.extend_from_slice(b",\"status\":");
381        push_u16(&mut self.bytes, r.status);
382        self.bytes.push(b'}');
383        if let Some(o) = r.outcome_str() {
384            match self.outcomes.iter_mut().find(|(x, _)| x == o) {
385                Some((_, k)) => *k += 1,
386                None => self.outcomes.push((o.to_string(), 1)),
387            }
388        }
389    }
390}
391
392/// Appends `n` in decimal (a JSON integer).
393fn push_u16(out: &mut Vec<u8>, n: u16) {
394    let mut buf = [0u8; 5];
395    let (mut i, mut n) = (buf.len(), n);
396    loop {
397        i -= 1;
398        buf[i] = b'0' + (n % 10) as u8;
399        n /= 10;
400        if n == 0 {
401            break;
402        }
403    }
404    out.extend_from_slice(&buf[i..]);
405}
406
407/// The machine's parallelism, read once: `available_parallelism` reads the cgroup files on
408/// Linux (hundreds of microseconds in a container), too slow to pay on every batch.
409fn cores() -> usize {
410    static CORES: std::sync::OnceLock<usize> = std::sync::OnceLock::new();
411    *CORES.get_or_init(|| std::thread::available_parallelism().map(|c| c.get()).unwrap_or(4))
412}
413
414/// Answers a batch within the budget: the requests are answered in chunks across the pool
415/// (one chunk per core; bindings looked up once per name and asof within the batch), each
416/// chunk writing its answers ([`Written`]). Those not answered within the budget become
417/// jobs: each is resolved again to the request it describes (a store read), and its chunk's
418/// answer completes the job. The runs are in request order.
419async fn batch(inner: Arc<Inner>, items: Vec<String>, principal: Option<Principal>) -> Vec<Written> {
420    let n = items.len();
421    let deadline = tokio::time::Instant::now() + inner.config.budget;
422    let chunks = n.div_ceil(64).clamp(1, inner.config.pool_size.min(cores()));
423    let per = n.div_ceil(chunks).max(1);
424    let ranges: Vec<(usize, usize)> =
425        (0..chunks).map(|c| (c * per, ((c + 1) * per).min(n))).take_while(|(lo, hi)| lo < hi).collect();
426    let now = inner.now();
427    let items = Arc::new(items);
428    // Each chunk's answers so far; once the budget has passed (`late`), its answers go to
429    // the channel instead, to complete their jobs. A chunk done within the budget leaves
430    // its answers written instead.
431    let shared: Slots = Arc::new(ranges.iter().map(|_| Mutex::new(Slot::default())).collect());
432    let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel::<(usize, Reply)>();
433    let seen = Arc::new(crate::mesh::Seen::default());
434    let mut tasks = Vec::new();
435    for (c, &(lo, hi)) in ranges.iter().enumerate() {
436        let (i2, items, tx, p, now, shared) =
437            (inner.clone(), items.clone(), tx.clone(), principal.clone(), now.clone(), shared.clone());
438        let seen = seen.clone();
439        let pool = inner.pool.clone();
440        tasks.push(tokio::spawn(async move {
441            pool.run(move || {
442                let memo = Memo::shared(&i2, &seen);
443                for k in lo..hi {
444                    let reply = i2.answer_with(&items[k], p.as_ref(), &memo, &now, &mut |_| {}, false);
445                    let mut slot = shared[c].lock().unwrap_or_else(|p| p.into_inner());
446                    if slot.late {
447                        let _ = tx.send((k, reply));
448                    } else {
449                        slot.answers.push((k, reply));
450                    }
451                }
452                let mut slot = shared[c].lock().unwrap_or_else(|p| p.into_inner());
453                if !slot.late {
454                    let answers = std::mem::take(&mut slot.answers);
455                    slot.written = Some(Written::of(c == 0, answers.iter().map(|(_, r)| r)));
456                }
457            })
458            .await
459        }));
460    }
461    drop(tx);
462    let all = futures_join(&mut tasks, deadline).await;
463    let mut done: Vec<Option<Reply>> = vec![None; n];
464    let mut written: Vec<Option<Written>> = Vec::with_capacity(ranges.len());
465    for slot in shared.iter() {
466        let mut s = slot.lock().unwrap_or_else(|p| p.into_inner());
467        s.late = true;
468        for (k, r) in s.answers.drain(..) {
469            done[k] = Some(r);
470        }
471        written.push(s.written.take());
472    }
473    // A chunk's run: as it wrote it, else its answers (an error for any it has none of: its
474    // task panicked, or the answer completes a job).
475    let runs = |done: Vec<Option<Reply>>, written: Vec<Option<Written>>| -> Vec<Written> {
476        let error = envelope::error_reply(ErrorCode::EvalUnavailable);
477        ranges
478            .iter()
479            .zip(written)
480            .enumerate()
481            .map(|(c, (&(lo, hi), w))| {
482                w.unwrap_or_else(|| Written::of(c == 0, done[lo..hi].iter().map(|d| d.as_ref().unwrap_or(&error))))
483            })
484            .collect()
485    };
486    if all {
487        return runs(done, written);
488    }
489    // Past the budget: every request not answered yet becomes a job, resolved again to the
490    // request it describes.
491    let open: Vec<usize> = ranges
492        .iter()
493        .zip(&written)
494        .filter(|(_, w)| w.is_none())
495        .flat_map(|(&(lo, hi), _)| lo..hi)
496        .filter(|k| done[*k].is_none())
497        .collect();
498    let (i2, items2, open2, now2) = (inner.clone(), items.clone(), open.clone(), now.clone());
499    let requests: Vec<Option<CoreRequest>> = inner
500        .pool
501        .run(move || {
502            let memo = Memo::new(&i2);
503            open2
504                .iter()
505                .map(|k| {
506                    crate::call::resolve(&items2[*k], &now2, &i2.config.aliases, &memo, false)
507                        .ok()
508                        .and_then(|t| request_of(&t))
509                })
510                .collect()
511        })
512        .await
513        .unwrap_or_default();
514    let poll_base = format!("{}/jobs/", inner.config.origin());
515    let est = inner.jobs.estimate(inner.config.budget.as_secs());
516    let mut jobs: Vec<Option<String>> = vec![None; n];
517    for (i, k) in open.iter().enumerate() {
518        let reply = match requests.get(i).cloned().flatten() {
519            Some(req) => match inner.jobs.create(req.clone()) {
520                Some(id) => {
521                    let p = Pending::new(&id, est, &format!("{poll_base}{id}"), req);
522                    jobs[*k] = Some(id);
523                    match p {
524                        Ok(p) => Reply::json(202, envelope::pending(&p), Cache::NoStore),
525                        Err(_) => envelope::error_reply(ErrorCode::EvalUnavailable),
526                    }
527                }
528                None => envelope::error_reply(ErrorCode::EvalUnavailable),
529            },
530            None => envelope::error_reply(ErrorCode::EvalUnavailable),
531        };
532        done[*k] = Some(reply);
533    }
534    let i3 = inner.clone();
535    tokio::spawn(async move {
536        while let Some((k, mut reply)) = rx.recv().await {
537            if let Some(id) = &jobs[k] {
538                reply.cache = Cache::NoStore;
539                reply.canonical = None;
540                i3.jobs.complete(id, reply);
541            }
542        }
543        for t in tasks {
544            let _ = t.await;
545        }
546        // Jobs whose task ended without an answer (a panic) are given up.
547        for id in jobs.into_iter().flatten() {
548            if let Poll::Running(..) = i3.jobs.poll_peek(&id) {
549                i3.jobs.complete(&id, envelope::error_reply(ErrorCode::EvalUnavailable));
550            }
551        }
552    });
553    runs(done, written)
554}
555
556/// A batch chunk's state: whether the budget has passed, its answers so far, and its
557/// answers written once it is done within the budget.
558#[derive(Default)]
559struct Slot {
560    late: bool,
561    answers: Vec<(usize, Reply)>,
562    written: Option<Written>,
563}
564
565/// Each batch chunk's state.
566type Slots = Arc<Vec<Mutex<Slot>>>;
567
568/// Waits for every task until `deadline`: whether all finished.
569async fn futures_join(tasks: &mut [tokio::task::JoinHandle<Option<()>>], deadline: tokio::time::Instant) -> bool {
570    for t in tasks.iter_mut() {
571        if t.is_finished() {
572            continue;
573        }
574        if tokio::time::timeout_at(deadline, t).await.is_err() {
575            return false;
576        }
577    }
578    true
579}
580
581/// The versions of a stored cell (SPEC 9.8, spec-0.4.2).
582#[utoipa::path(get, path = "/versions/{cell}",
583    params(("cell" = String, Path, description = "A cell URI's rest without asof (a pin allowed), then optionally `from=` and `to=` (instants, inclusive bounds on tx) as its last parameters.")),
584    responses(
585        (status = 200, description = "`{\"cell\", \"versions\": [{\"asof\", \"receipt\", \"tx\"}], \"next\"?}` ascending by tx", content_type = "application/json"),
586        (status = 400, description = "`bad_request`", content_type = "application/json"),
587        (status = 404, description = "`not_covered` (with `E_NAME_UNBOUND` for an unbound name)", content_type = "application/json"),
588    ))]
589async fn versions(State(mesh): State<Mesh>, uri: Uri, headers: HeaderMap, req: Request) -> Response {
590    if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
591        return r;
592    }
593    let inner = mesh.inner.clone();
594    let rest = rest_of(&uri, "/versions/");
595    let r = inner
596        .pool
597        .clone()
598        .run(move || inner.versions(&rest))
599        .await
600        .unwrap_or_else(|| envelope::error_reply(ErrorCode::EvalUnavailable));
601    to_response(r)
602}
603
604/// The most versions in one answer of the versions endpoint.
605const VERSIONS_PAGE: usize = 1000;
606
607impl Inner {
608    fn versions(&self, rest: &str) -> Reply {
609        // `from=` and `to=` are the endpoint's, taken off the end of the query.
610        let (path, query) = match rest.split_once('?') {
611            Some((p, q)) => (p, q),
612            None => (rest, ""),
613        };
614        let mut ps: Vec<&str> = if query.is_empty() { vec![] } else { query.split('&').collect() };
615        let (mut from, mut to) = (None, None);
616        while let Some(last) = ps.last() {
617            if let Some(v) = last.strip_prefix("from=") {
618                from = Some(v.to_string());
619            } else if let Some(v) = last.strip_prefix("to=") {
620                to = Some(v.to_string());
621            } else {
622                break;
623            }
624            ps.pop();
625        }
626        for t in [&from, &to].into_iter().flatten() {
627            if lexical::check_instant(t, "$").is_err() {
628                return envelope::bad_request_reply(ErrorCode::CanonInstant);
629            }
630        }
631        let cell_rest = if ps.is_empty() { path.to_string() } else { format!("{path}?{}", ps.join("&")) };
632        let now = self.now();
633        let target = match crate::call::resolve(&cell_rest, &now, &self.config.aliases, self, false) {
634            Ok(t) => t,
635            Err(r) => return self.rejection(r, None),
636        };
637        if target.asof().is_some() {
638            return envelope::bad_request_reply(ErrorCode::ParseUri);
639        }
640        let lo = from.unwrap_or_else(|| "0001-01-01T00:00:00.000000Z".into());
641        let hi = to.clone().unwrap_or_else(|| "9999-12-31T23:59:59.999999Z".into());
642        // One more than a page, to know there is a next (CONTRACT-0.4.9 H5): the store stops there.
643        let mut vs = match self.store.versions_limit(target.cell_id(), &lo, &hi, VERSIONS_PAGE + 1) {
644            Ok(v) => v,
645            Err(_) => return envelope::error_answer_reply(ErrorCode::InputUnavailable, Some(&target.bound.fn_hash)),
646        };
647        vs.sort_by(|a, b| (&a.tx, &a.receipt_hash).cmp(&(&b.tx, &b.receipt_hash)));
648        let more = vs.len() > VERSIONS_PAGE;
649        vs.truncate(VERSIONS_PAGE);
650        let list: Vec<Value> = vs
651            .iter()
652            .map(|v| {
653                Value::Object(vec![
654                    ("asof".into(), Value::String(v.asof.clone())),
655                    ("receipt".into(), Value::String(v.receipt_hash.clone())),
656                    ("tx".into(), Value::String(v.tx.clone())),
657                ])
658            })
659            .collect();
660        let mut body = vec![("cell".to_string(), target.cell.to_value()), ("versions".to_string(), Value::Array(list))];
661        if more {
662            if let Some(last) = vs.last() {
663                let us = datumesh_formula::calendar::parse_instant(&last.tx).unwrap_or(0) + 1;
664                let next_from = datumesh_formula::calendar::instant_text(us).unwrap_or_default();
665                let mut next = format!("{}/versions/{cell_rest}", self.config.origin());
666                next.push(if cell_rest.contains('?') { '&' } else { '?' });
667                next.push_str(&format!("from={next_from}"));
668                if let Some(t) = &to {
669                    next.push_str(&format!("&to={t}"));
670                }
671                body.push(("next".to_string(), Value::String(next)));
672            }
673        }
674        Reply::json(200, Value::Object(body).to_jcs(), Cache::Public(self.config.ttl.latest_max_age.as_secs()))
675    }
676}
677
678/// The members of a slice.
679#[utoipa::path(get, path = "/slice/{cell}",
680    params(
681        ("cell" = String, Path, description = "A slice: a cell URI's rest or a call with `*` for open arguments, of a stored function; `?asof=`, `limit=` (JSON, default 1,000, at most 10,000), `after=` (the cursor of the previous page)."),
682    ),
683    responses(
684        (status = 200, description = "JSON page of members, or with `Accept: application/vnd.apache.arrow.stream` an Arrow IPC stream", content_type = "application/json"),
685        (status = 400, description = "`bad_request`", content_type = "application/json"),
686        (status = 404, description = "`not_covered`", content_type = "application/json"),
687    ))]
688async fn slice(State(mesh): State<Mesh>, uri: Uri, headers: HeaderMap, req: Request) -> Response {
689    let inner = mesh.inner.clone();
690    let (client, _) = match who(&inner, &headers, peer_of(&req)) {
691        Ok(x) => x,
692        Err(r) => return to_response(r),
693    };
694    if let Err(r) = admit(&inner, &client, 1) {
695        return to_response(r);
696    }
697    // A browser on a listed series is sent to its page (Build 2 Part 6, G1): never cached.
698    let rest = rest_of(&uri, "/slice/");
699    if crate::series::redirect_reads_store(&inner, &rest, &headers) {
700        // The call is resolved against the store: on the pool, not on this thread (0.4.7).
701        let (i2, r2, h2) = (inner.clone(), rest.clone(), headers.clone());
702        match inner.pool.clone().run(move || crate::series::slice_redirect(&i2, &r2, &h2)).await {
703            None => return to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
704            Some(Some(to)) => return see_other(&to),
705            // no redirect: the middleware left the `Accept` check to this point
706            Some(None) if !acceptable(&headers, Some(crate::slice::ARROW)) => return not_acceptable(),
707            Some(None) => {}
708        }
709    } else if let Some(to) = crate::series::slice_redirect(&inner, &rest, &headers) {
710        return see_other(&to);
711    }
712    let (rest, format) = match crate::slice::split_format(&rest) {
713        Ok(x) => x,
714        Err(c) => return to_response(envelope::bad_request_reply(c)),
715    };
716    // `?format=` is its own address; without it, an Accept that chooses Arrow gets Arrow, uncached (G1).
717    let accept_arrow = format.is_none() && accepts(&headers, crate::slice::ARROW);
718    let form = if accept_arrow { crate::slice::Form::Arrow } else { format.unwrap_or_default() };
719    let r = inner
720        .pool
721        .clone()
722        .run(move || {
723            let now = inner.now();
724            inner.slice(&rest, &now, form)
725        })
726        .await
727        .unwrap_or_else(|| envelope::error_reply(ErrorCode::EvalUnavailable));
728    let mut r = r;
729    if accept_arrow {
730        r.cache = Cache::NoStore;
731    }
732    to_response(r)
733}
734
735/// `303 See Other` to `location`, `no-store`.
736fn see_other(location: &str) -> Response {
737    let mut resp = Response::new(Body::empty());
738    *resp.status_mut() = StatusCode::SEE_OTHER;
739    if let Ok(v) = HeaderValue::from_str(location) {
740        resp.headers_mut().insert(header::LOCATION, v);
741    }
742    resp.headers_mut().insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
743    resp
744}
745
746fn accepts(headers: &HeaderMap, media: &str) -> bool {
747    headers
748        .get_all(header::ACCEPT)
749        .iter()
750        .filter_map(|v| v.to_str().ok())
751        .any(|v| v.split(',').any(|p| p.split(';').next().unwrap_or("").trim() == media))
752}
753
754/// Whether the client takes JSON (no `Accept`, `*/*`, `application/*` or
755/// `application/json`); for slices also Arrow.
756/// The `406` of a request whose `Accept` allows no media type the route has.
757fn not_acceptable() -> Response {
758    let mut r = Reply::json(
759        406,
760        Value::Object(vec![("error".into(), Value::String("not acceptable: application/json only".into()))]).to_jcs(),
761        Cache::NoStore,
762    );
763    r.content_type = JSON;
764    to_response(r)
765}
766
767fn acceptable(headers: &HeaderMap, also: Option<&str>) -> bool {
768    let vals: Vec<&str> = headers.get_all(header::ACCEPT).iter().filter_map(|v| v.to_str().ok()).collect();
769    if vals.is_empty() {
770        return true;
771    }
772    vals.iter().flat_map(|v| v.split(',')).any(|p| {
773        let mut parts = p.split(';');
774        let m = parts.next().unwrap_or("").trim();
775        let q0 = parts.any(|x| {
776            let x = x.trim();
777            x == "q=0" || x == "q=0.0" || x == "q=0.00" || x == "q=0.000"
778        });
779        !q0 && (m == "*/*" || m == "application/*" || m == JSON || also == Some(m))
780    })
781}
782
783async fn object(
784    inner: Arc<Inner>,
785    what: &'static str,
786    f: impl FnOnce(&Inner) -> Option<Vec<u8>> + Send + 'static,
787) -> Response {
788    let i2 = inner.clone();
789    match inner.pool.run(move || f(&i2)).await.flatten() {
790        Some(bytes) => {
791            let ct = if what == "blob" { "application/octet-stream" } else { JSON };
792            to_response(Reply {
793                status: 200,
794                body: bytes.into(),
795                content_type: ct,
796                cache: Cache::Immutable,
797                canonical: None,
798                retry_after: None,
799            })
800        }
801        None => not_found(what),
802    }
803}
804
805/// The refusal of a request by its client's rate limit (or key), if it is refused.
806fn ip_admit(inner: &Inner, headers: &HeaderMap, req: &Request) -> Option<Response> {
807    let client = match who(inner, headers, peer_of(req)) {
808        Ok((c, _)) => c,
809        Err(r) => return Some(to_response(r)),
810    };
811    admit(inner, &client, 1).err().map(to_response)
812}
813
814/// A receipt by its hash (canonical bytes; gzip when asked).
815#[utoipa::path(get, path = "/receipt/{hash}", params(("hash" = String, Path, description = "The receipt hash (SPEC 8.3).")),
816    responses((status = 200, description = "The receipt's canonical JSON; immutable", content_type = "application/json"), (status = 404, description = "Not held")))]
817async fn receipt(State(mesh): State<Mesh>, Path(hash): Path<String>, headers: HeaderMap, req: Request) -> Response {
818    if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
819        return r;
820    }
821    if lexical::check_hex(&hash, 64, "$").is_err() {
822        return not_found("receipt");
823    }
824    object(mesh.inner.clone(), "receipt", move |i| i.store.receipt(&hash).map(|c| c.into_owned())).await
825}
826
827/// A descriptor by its function hash.
828#[utoipa::path(get, path = "/descriptor/{hash}", params(("hash" = String, Path, description = "The function hash.")),
829    responses((status = 200, description = "The descriptor's canonical JSON; immutable", content_type = "application/json"), (status = 404, description = "Not held")))]
830async fn descriptor(State(mesh): State<Mesh>, Path(hash): Path<String>, headers: HeaderMap, req: Request) -> Response {
831    if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
832        return r;
833    }
834    if lexical::check_hex(&hash, 64, "$").is_err() {
835        return not_found("descriptor");
836    }
837    object(mesh.inner.clone(), "descriptor", move |i| i.store.descriptor(&hash).map(|c| c.into_owned())).await
838}
839
840async fn manifest_of(inner: Arc<Inner>, entry: String) -> Response {
841    object(inner, "manifest", move |i| i.store.manifest(&entry).map(|c| c.into_owned())).await
842}
843
844/// A slice manifest (SPEC 15.13), by its entry's slice id and members hash.
845#[utoipa::path(get, path = "/manifest/{slice_id}/{members_hash}",
846    params(("slice_id" = String, Path, description = "The slice id."), ("members_hash" = String, Path, description = "The members hash.")),
847    responses((status = 200, description = "The manifest's canonical JSON; immutable", content_type = "application/json"), (status = 404, description = "Not held")))]
848async fn manifest(
849    State(mesh): State<Mesh>,
850    Path((slice_id, members)): Path<(String, String)>,
851    headers: HeaderMap,
852    req: Request,
853) -> Response {
854    if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
855        return r;
856    }
857    if lexical::check_hex(&slice_id, 64, "$").is_err() || lexical::check_hex(&members, 64, "$").is_err() {
858        return not_found("manifest");
859    }
860    manifest_of(mesh.inner.clone(), format!("slice:{slice_id}:{members}")).await
861}
862
863/// Blob content by SHA-256.
864#[utoipa::path(get, path = "/blob/{sha256}", params(("sha256" = String, Path, description = "The content's SHA-256.")),
865    responses((status = 200, description = "The bytes; immutable", content_type = "application/octet-stream"), (status = 404, description = "Not held")))]
866async fn blob(State(mesh): State<Mesh>, Path(sha): Path<String>, headers: HeaderMap, req: Request) -> Response {
867    if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
868        return r;
869    }
870    if lexical::check_hex(&sha, 64, "$").is_err() {
871        return not_found("blob");
872    }
873    object(mesh.inner.clone(), "blob", move |i| i.store.blob(&sha).ok().flatten().map(|c| c.into_owned())).await
874}
875
876/// A cell's lineage as nested envelopes.
877#[utoipa::path(get, path = "/explain/{cell}",
878    params(("cell" = String, Path, description = "As for /cell; `depth=` (default 4, at most 16) bounds the walk.")),
879    responses(
880        (status = 200, description = "`{\"envelope\", \"inputs\": [{\"entry\", \"envelope\", \"inputs\"} | {\"entry\", \"slice\", \"members\"}], \"truncated\"}`", content_type = "application/json"),
881        (status = 202, description = "`pending`: the cell is being computed; ask again", content_type = "application/json"),
882        (status = 400, description = "`bad_request`", content_type = "application/json"),
883        (status = 404, description = "`not_covered`", content_type = "application/json"),
884    ))]
885async fn explain(State(mesh): State<Mesh>, uri: Uri, headers: HeaderMap, req: Request) -> Response {
886    let inner = mesh.inner.clone();
887    let (client, principal) = match who(&inner, &headers, peer_of(&req)) {
888        Ok(x) => x,
889        Err(r) => return to_response(r),
890    };
891    if let Err(r) = admit(&inner, &client, 1) {
892        return to_response(r);
893    }
894    let mut rest = rest_of(&uri, "/explain/");
895    let mut depth = inner.config.explain_depth;
896    // `depth=` is the explain's own parameter: taken off the query.
897    if let Some((p, q)) = rest.clone().split_once('?') {
898        let kept: Vec<&str> = q.split('&').filter(|x| !x.starts_with("depth=")).collect();
899        if let Some(d) = q.split('&').find_map(|x| x.strip_prefix("depth=")) {
900            depth = d.parse::<usize>().unwrap_or(depth);
901        }
902        rest = if kept.is_empty() { p.to_string() } else { format!("{p}?{}", kept.join("&")) };
903    }
904    let depth = depth.min(16);
905    let r = within_budget(inner, move |i, on| {
906        let now = i.now();
907        let r = i.answer(&rest, principal.as_ref(), i, &now, on);
908        if r.status != 200 {
909            return r;
910        }
911        let env = json::parse(&r.body).unwrap_or(Value::Null);
912        let mut budget = 2_000usize;
913        let v = i.explain_node(env, depth, &mut budget);
914        Reply::json(200, v.to_jcs(), Cache::NoStore)
915    })
916    .await;
917    to_response(r)
918}
919
920impl Inner {
921    /// An envelope with its inputs' envelopes, `depth` levels down, at most `budget` nodes.
922    fn explain_node(&self, envelope: Value, depth: usize, budget: &mut usize) -> Value {
923        let inputs: Vec<String> = envelope
924            .get("receipt")
925            .and_then(|r| r.get("inputs"))
926            .and_then(|i| {
927                if let Value::Array(a) = i {
928                    Some(a.iter().filter_map(Value::as_str).map(str::to_string).collect())
929                } else {
930                    None
931                }
932            })
933            .unwrap_or_default();
934        let mut truncated = false;
935        let mut out = Vec::new();
936        for e in inputs {
937            if depth == 0 || *budget == 0 {
938                truncated = true;
939                break;
940            }
941            *budget -= 1;
942            if e.starts_with("slice:") {
943                let m = self.store.manifest(&e).and_then(|m| datumesh_core::Manifest::from_json(&m).ok());
944                let mut node = vec![("entry".to_string(), Value::String(e.clone()))];
945                if let Some(m) = m {
946                    node.push(("members".to_string(), envelope::num(m.members().len() as u64)));
947                    node.push(("slice".to_string(), m.slice().to_value()));
948                }
949                out.push(Value::Object(node));
950                continue;
951            }
952            let child = match self.receipt_info_by_hash(&e) {
953                Some(info) => self.explain_node(json::parse(&info.ok).unwrap_or(Value::Null), depth - 1, budget),
954                None => json::parse(&envelope::not_covered(None)).unwrap_or(Value::Null),
955            };
956            let mut node = vec![("entry".to_string(), Value::String(e.clone()))];
957            if let Value::Object(m) = child {
958                node.extend(m);
959            }
960            out.push(Value::Object(node));
961        }
962        let mut node = vec![("envelope".to_string(), envelope.clone()), ("inputs".to_string(), Value::Array(out))];
963        node.push(("truncated".to_string(), Value::Bool(truncated)));
964        Value::Object(node)
965    }
966}
967
968#[derive(serde::Deserialize)]
969struct FindQuery {
970    q: Option<String>,
971    limit: Option<usize>,
972    summary: Option<String>,
973}
974
975/// `Retry-After` of a find answer before the find thread's first build (CONTRACT-0.4.9 H4).
976const FIND_RETRY_SECS: u64 = 5;
977
978/// The hybrid `/find` (CONTRACT-build2-part2-read R3; see `crate::find`), and `/find?summary=1`.
979#[utoipa::path(get, path = "/find",
980    params(("q" = Option<String>, Query, description = "The query: words, a name, a label, an alias or a value, or a request such as `<book> <chapter>:<verse>`. Matching is case-insensitive after NFC."), ("limit" = Option<usize>, Query, description = "At most this many results (default 10, at most 50)."), ("summary" = Option<String>, Query, description = "`1`: the catalogue summary (`classes`, `functions`, with labels, cell counts and small dictionaries) instead of results.")),
981    responses((status = 200, description = "`{\"query\", \"vector\": bool, \"results\": [...], \"resolution\"?: {...}}`. Each result has `kind` (`function`, `method` or `class`), `name`, `label`, `description`, `call` (the template with typed placeholders, or the filled call of a resolved request), `match` (`exact`, `text` or `vector`), `score`, and the members of its kind (`descriptor`, `fn_hash`, `since`; a class has `class_hash` and `methods`; a method has `class`). `resolution` has `status` `exact` (`call`, `label`), `ambiguous` (`candidates`, `keys`) or `range` (`error`: `E_RANGE_REFUSED`).", content_type = "application/json")))]
982async fn find(State(mesh): State<Mesh>, Query(q): Query<FindQuery>, headers: HeaderMap, req: Request) -> Response {
983    if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
984        return r;
985    }
986    let inner = mesh.inner.clone();
987    let query = q.q.unwrap_or_default();
988    let limit = q.limit.unwrap_or(crate::find::DEFAULT_LIMIT).clamp(1, crate::find::MAX_LIMIT);
989    let summary = q.summary.as_deref() == Some("1");
990    // The summary and the empty query are read from the find thread's last build (CONTRACT-0.4.9 H4): before
991    // its first build they are `503`. Any other query is answered on the request.
992    let empty = query.trim().is_empty();
993    let r = inner
994        .pool
995        .clone()
996        .run(move || {
997            if summary {
998                crate::find::summary(&inner)
999            } else if empty {
1000                crate::find::empty_answer(&inner, limit)
1001            } else {
1002                Some(crate::find::answer(&inner, &query, limit))
1003            }
1004        })
1005        .await
1006        .unwrap_or(None);
1007    match r {
1008        Some(v) => plain_json(200, v, Cache::Public(60)),
1009        None => to_response(crate::envelope::not_yet_reply(FIND_RETRY_SECS, "The catalogue summary")),
1010    }
1011}
1012
1013#[derive(serde::Deserialize)]
1014struct VerifyQuery {
1015    level: Option<String>,
1016    blob: Option<String>,
1017    form: Option<String>,
1018}
1019
1020/// Verification as a service: the core verifier on a submitted receipt, with this mesh's
1021/// keys; free, unauthenticated, rate-limited per IP.
1022#[utoipa::path(post, path = "/verify",
1023    params(("level" = Option<String>, Query, description = "`recomputed` (default: recompute with the engine as the resolver) or `signed` (steps 1-6)."), ("blob" = Option<String>, Query, description = "Blob content for step 7.7, as hex (at most 1 MiB)."), ("form" = Option<String>, Query, description = "`offered`: the body is `{\"receipt\": <its JSON text>, \"recompute\"?: <SPEC 11's recompute object>, \"blob_hex\"?}` and step 7 uses what is offered instead of this mesh's engine.")),
1024    request_body(content = String, description = "The receipt's JSON text, exactly as received (or the offered form).", content_type = "application/json"),
1025    responses(
1026        (status = 200, description = "`{\"ok\", \"level\", \"code\", \"hash\", \"computed_by\", \"path\", \"detail\", \"blob_checked\"}`", content_type = "application/json"),
1027        (status = 429, description = "`rate_limited`", content_type = "application/json"),
1028    ))]
1029async fn verify_receipt(
1030    State(mesh): State<Mesh>,
1031    Query(q): Query<VerifyQuery>,
1032    headers: HeaderMap,
1033    req: Request,
1034) -> Response {
1035    let inner = mesh.inner.clone();
1036    let ip = client_ip(&inner, &headers, peer_of(&req));
1037    if let Err(s) = inner.limiter.admit_verify(ip) {
1038        return to_response(envelope::rate_limited_reply(s));
1039    }
1040    let body: Bytes = match axum::body::to_bytes(req.into_body(), 4 << 20).await {
1041        Ok(b) => b,
1042        Err(_) => return batch_error("body too large"),
1043    };
1044    if q.form.as_deref() == Some("offered") {
1045        let Ok(v) = json::parse(&body) else { return batch_error("form=offered: not strict JSON") };
1046        let Some(receipt) = v.get("receipt").and_then(Value::as_str).map(|s| s.as_bytes().to_vec()) else {
1047            return batch_error("form=offered: no receipt text");
1048        };
1049        let blob = match v.get("blob_hex").and_then(Value::as_str).map(hex) {
1050            None => None,
1051            Some(Some(b)) if b.len() <= 1 << 20 => Some(b),
1052            Some(_) => return batch_error("blob_hex: hex of at most 1 MiB"),
1053        };
1054        let m = mesh.clone();
1055        let rc = v.get("recompute").cloned();
1056        let r = inner.pool.run(move || m.verify_offered(&receipt, rc.as_ref(), blob.as_deref())).await;
1057        return match r {
1058            Some(v) => to_response(Reply::json(200, v.body, Cache::NoStore)),
1059            None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1060        };
1061    }
1062    let signed = q.level.as_deref() == Some("signed");
1063    let blob = match q.blob.as_deref().map(hex) {
1064        None => None,
1065        Some(Some(b)) if b.len() <= 1 << 20 => Some(b),
1066        Some(_) => return batch_error("blob: hex of at most 1 MiB"),
1067    };
1068    let m = mesh.clone();
1069    let r = inner.pool.run(move || m.verify(&body, signed, blob.as_deref())).await;
1070    match r {
1071        Some(v) => to_response(Reply::json(200, v.body, Cache::NoStore)),
1072        None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1073    }
1074}
1075
1076fn hex(s: &str) -> Option<Vec<u8>> {
1077    if !s.len().is_multiple_of(2) {
1078        return None;
1079    }
1080    (0..s.len()).step_by(2).map(|i| u8::from_str_radix(s.get(i..i + 2)?, 16).ok()).collect()
1081}
1082
1083/// A job: `pending` again while it runs, then the envelope of the original request.
1084#[utoipa::path(get, path = "/jobs/{job}", params(("job" = String, Path, description = "The job id of a `pending` envelope.")),
1085    responses(
1086        (status = 202, description = "`pending`, the same job and request", content_type = "application/json"),
1087        (status = 400, description = "`bad_request` with `E_JOB_UNKNOWN`: unknown or expired", content_type = "application/json"),
1088        (status = 200, description = "The completed envelope (any outcome but pending, with its status), bound to the original request", content_type = "application/json"),
1089    ))]
1090async fn job(State(mesh): State<Mesh>, Path(id): Path<String>, headers: HeaderMap, req: Request) -> Response {
1091    let inner = mesh.inner.clone();
1092    let (client, _) = match who(&inner, &headers, peer_of(&req)) {
1093        Ok(x) => x,
1094        Err(r) => return to_response(r),
1095    };
1096    if let Err(r) = admit(&inner, &client, 1) {
1097        return to_response(r);
1098    }
1099    let unknown = || to_response(Reply::json(400, envelope::bad_request(ErrorCode::JobUnknown), Cache::NoStore));
1100    let valid = (32..=64).contains(&id.len()) && id.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b));
1101    if !valid {
1102        return unknown();
1103    }
1104    match inner.jobs.poll(&id) {
1105        Poll::Unknown => unknown(),
1106        Poll::Done(r) => to_response(r),
1107        Poll::Running(request, elapsed) => {
1108            let poll = format!("{}/jobs/{id}", inner.config.origin());
1109            match Pending::new(&id, inner.jobs.estimate(elapsed), &poll, request) {
1110                Ok(p) => to_response(Reply::json(202, envelope::pending(&p), Cache::NoStore)),
1111                Err(_) => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1112            }
1113        }
1114    }
1115}
1116
1117/// The key document (SPEC 9.2): the store's namespace record for this mesh's host.
1118#[utoipa::path(get, path = "/.well-known/datumesh.json", responses((status = 200, description = "The key document", content_type = "application/json"), (status = 404, description = "None stored")))]
1119async fn key_document(State(mesh): State<Mesh>) -> Response {
1120    let m = mesh.clone();
1121    match mesh.inner.pool.run(move || m.key_document()).await.flatten() {
1122        Some(doc) => to_response(Reply::json(200, doc, Cache::Public(300))),
1123        None => not_found("key document"),
1124    }
1125}
1126
1127/// The mesh document (SPEC 9.6).
1128#[utoipa::path(get, path = "/.well-known/datumesh-mesh.json", responses((status = 200, description = "The mesh document", content_type = "application/json")))]
1129async fn mesh_document(State(mesh): State<Mesh>) -> Response {
1130    to_response(Reply::json(200, mesh.mesh_document(), Cache::Public(300)))
1131}
1132
1133/// Which function each name denotes as of an instant (SPEC 9.7).
1134#[utoipa::path(get, path = "/bindings",
1135    params(("name" = String, Query, description = "A function name, percent-encoded as in SPEC 5.1; repeat for several."), ("asof" = Option<String>, Query, description = "An instant (default: now).")),
1136    responses((status = 200, description = "`{\"asof\", \"bindings\": {name: {\"fn_hash\", \"since\"}}}`", content_type = "application/json"), (status = 400, description = "A malformed name or asof", content_type = "application/json")))]
1137async fn bindings(State(mesh): State<Mesh>, uri: Uri, headers: HeaderMap, req: Request) -> Response {
1138    if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
1139        return r;
1140    }
1141    let inner = mesh.inner.clone();
1142    let mut names = Vec::new();
1143    let mut asof = None;
1144    for p in uri.query().unwrap_or("").split('&').filter(|p| !p.is_empty()) {
1145        let (k, v) = p.split_once('=').unwrap_or((p, ""));
1146        let Some(v) = pct_decode(v) else { return batch_error("percent-encoding (SPEC 5.1)") };
1147        match k {
1148            "name" if lexical::check_function_name(&v, "$").is_ok() => names.push(v),
1149            "asof" if lexical::check_instant(&v, "$").is_ok() && asof.is_none() => asof = Some(v),
1150            _ => return batch_error(&format!("parameter {k}")),
1151        }
1152    }
1153    let r = inner
1154        .pool
1155        .clone()
1156        .run(move || {
1157            let at = asof.unwrap_or_else(|| inner.now());
1158            let mut out = Vec::new();
1159            for n in names {
1160                if !inner.config.owns(crate::foreign::host_of(&n)) {
1161                    continue;
1162                }
1163                // A class name is answered with its class hash (9.7, spec-0.5.0); any other name
1164                // with the function it means.
1165                let found = match inner.store.resolve_class_binding(&n, &at) {
1166                    Ok(Some(c)) => ("class_hash", c.class_hash, c.tx),
1167                    Ok(None) => match inner.store.resolve_binding(&n, &at) {
1168                        Ok(Some(b)) => ("fn_hash", b.fn_hash, b.tx),
1169                        Ok(None) => continue,
1170                        Err(_) => return None,
1171                    },
1172                    Err(_) => return None,
1173                };
1174                out.push((
1175                    n,
1176                    Value::Object(vec![
1177                        (found.0.into(), Value::String(found.1)),
1178                        ("since".into(), Value::String(found.2)),
1179                    ]),
1180                ));
1181            }
1182            Some(Value::Object(vec![("asof".into(), Value::String(at)), ("bindings".into(), Value::Object(out))]))
1183        })
1184        .await
1185        .flatten();
1186    match r {
1187        Some(v) => plain_json(200, v, Cache::Public(inner_latest(&mesh))),
1188        None => to_response(envelope::error_reply(ErrorCode::InputUnavailable)),
1189    }
1190}
1191
1192fn inner_latest(mesh: &Mesh) -> u64 {
1193    mesh.inner.config.ttl.latest_max_age.as_secs()
1194}
1195
1196/// Strict percent-decoding (SPEC 5.1): literal characters as themselves, `%` and two
1197/// uppercase hex digits for other bytes, UTF-8.
1198fn pct_decode(s: &str) -> Option<String> {
1199    let b = s.as_bytes();
1200    let mut out = Vec::new();
1201    let mut i = 0;
1202    while i < b.len() {
1203        let c = b[i];
1204        if c == b'%' {
1205            let h = b.get(i + 1..i + 3)?;
1206            if !h.iter().all(|x| x.is_ascii_digit() || (b'A'..=b'F').contains(x)) {
1207                return None;
1208            }
1209            let v = u8::from_str_radix(std::str::from_utf8(h).ok()?, 16).ok()?;
1210            if v.is_ascii_alphanumeric() || matches!(v, b'-' | b'.' | b'_' | b'~' | b':') {
1211                return None;
1212            }
1213            out.push(v);
1214            i += 3;
1215        } else if c.is_ascii_alphanumeric() || matches!(c, b'-' | b'.' | b'_' | b'~' | b':') {
1216            out.push(c);
1217            i += 1;
1218        } else {
1219            return None;
1220        }
1221    }
1222    String::from_utf8(out).ok()
1223}
1224
1225/// Liveness and the store's health.
1226#[utoipa::path(get, path = "/health", responses((status = 200, description = "`{\"status\": \"ok\"}`", content_type = "application/json"), (status = 503, description = "The store does not answer", content_type = "application/json")))]
1227async fn health(State(mesh): State<Mesh>) -> Response {
1228    let m = mesh.clone();
1229    let ok = tokio::time::timeout(
1230        Duration::from_secs(5),
1231        mesh.inner.pool.run(move || m.inner.store.namespace(&m.inner.config.host).is_ok()),
1232    )
1233    .await
1234    .ok()
1235    .flatten()
1236    .unwrap_or(false);
1237    let v = Value::Object(vec![("status".into(), Value::String(if ok { "ok" } else { "store unavailable" }.into()))]);
1238    plain_json(if ok { 200 } else { 503 }, v, Cache::NoStore)
1239}
1240
1241/// Prometheus metrics.
1242#[utoipa::path(get, path = "/metrics", responses((status = 200, description = "Prometheus text", content_type = "text/plain")))]
1243async fn metrics(State(mesh): State<Mesh>) -> Response {
1244    let mut r = Reply::json(200, metrics_text(&mesh.inner).into_bytes(), Cache::NoStore);
1245    r.content_type = "text/plain; version=0.0.4";
1246    to_response(r)
1247}
1248
1249/// This document.
1250#[utoipa::path(get, path = "/openapi.json", responses((status = 200, description = "The OpenAPI document", content_type = "application/json")))]
1251async fn openapi_json() -> Response {
1252    let mut r = Reply::json(200, openapi().to_json().unwrap_or_default().into_bytes(), Cache::Public(300));
1253    r.content_type = JSON;
1254    to_response(r)
1255}
1256
1257pub(crate) fn metrics_text(inner: &Inner) -> String {
1258    use std::fmt::Write;
1259    use std::sync::atomic::Ordering::Relaxed;
1260    let mut out = String::new();
1261    inner.metrics.write(&mut out);
1262    let p = &inner.pool;
1263    let g = |out: &mut String, name: &str, help: &str, kind: &str, v: String| {
1264        let _ = writeln!(out, "# HELP {name} {help}\n# TYPE {name} {kind}\n{name} {v}");
1265    };
1266    g(&mut out, "datumesh_pool_size", "The blocking pool's size: the concurrency limit.", "gauge", p.size.to_string());
1267    g(&mut out, "datumesh_pool_in_use", "Pool threads busy now.", "gauge", p.in_use.load(Relaxed).to_string());
1268    g(&mut out, "datumesh_pool_peak", "The most pool threads busy at once.", "gauge", p.peak.load(Relaxed).to_string());
1269    g(&mut out, "datumesh_pool_runs_total", "Tasks run on the pool.", "counter", p.runs.load(Relaxed).to_string());
1270    g(
1271        &mut out,
1272        "datumesh_pool_waited_total",
1273        "Tasks that found the pool saturated and waited for a thread.",
1274        "counter",
1275        p.waited.load(Relaxed).to_string(),
1276    );
1277    let (held, running) = inner.jobs.counts();
1278    g(&mut out, "datumesh_jobs_held", "Jobs held (running or done).", "gauge", held.to_string());
1279    g(&mut out, "datumesh_jobs_running", "Jobs running.", "gauge", running.to_string());
1280    g(
1281        &mut out,
1282        "datumesh_jobs_created_total",
1283        "Requests answered pending.",
1284        "counter",
1285        inner.jobs.created.load(Relaxed).to_string(),
1286    );
1287    g(
1288        &mut out,
1289        "datumesh_rate_limited_total",
1290        "Requests refused by a rate limit.",
1291        "counter",
1292        inner.limiter.refused.load(Relaxed).to_string(),
1293    );
1294    g(
1295        &mut out,
1296        "datumesh_peer_fetches_total",
1297        "Requests to other meshes.",
1298        "counter",
1299        inner.foreign.fetches.load(Relaxed).to_string(),
1300    );
1301    g(
1302        &mut out,
1303        "datumesh_peer_failures_total",
1304        "Requests to other meshes that failed.",
1305        "counter",
1306        inner.foreign.failures.load(Relaxed).to_string(),
1307    );
1308    g(
1309        &mut out,
1310        "datumesh_peer_imported_total",
1311        "Foreign versions imported into the store.",
1312        "counter",
1313        inner.foreign.imported.load(Relaxed).to_string(),
1314    );
1315    let m = inner.engine.memo_stats();
1316    g(&mut out, "datumesh_memo_entries", "Engine memo entries.", "gauge", m.entries.to_string());
1317    g(&mut out, "datumesh_memo_bytes", "Engine memo size, approximately.", "gauge", m.approx_bytes.to_string());
1318    g(
1319        &mut out,
1320        "datumesh_uptime_seconds",
1321        "Seconds since the mesh started.",
1322        "gauge",
1323        inner.started.elapsed().as_secs().to_string(),
1324    );
1325    out
1326}
1327
1328/// Request ids, the access log, metrics and `Accept`.
1329async fn around(State(mesh): State<Mesh>, req: Request, next: Next) -> Response {
1330    let start = Instant::now();
1331    let route = req.extensions().get::<MatchedPath>().map(|m| m.as_str().to_string()).unwrap_or_else(|| "other".into());
1332    let route = match route.as_str() {
1333        "/cell/{*rest}" => "/cell/{cell}".to_string(),
1334        "/slice/{*rest}" => "/slice/{cell}".to_string(),
1335        "/explain/{*rest}" => "/explain/{cell}".to_string(),
1336        "/versions/{*rest}" => "/versions/{cell}".to_string(),
1337        "/fn/{*name}" => "/fn/{name}".to_string(),
1338        "/takeover/{*domain}" => "/takeover/{domain}".to_string(),
1339        "/series/{*rest}" => "/series/{page}".to_string(),
1340        "/x/interval/{*function}" => "/x/interval/{function}".to_string(),
1341        _ => route,
1342    };
1343    let id = req
1344        .headers()
1345        .get("x-request-id")
1346        .and_then(|v| v.to_str().ok())
1347        .filter(|s| !s.is_empty() && s.len() <= 64 && s.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-'))
1348        .map(str::to_string)
1349        .unwrap_or_else(|| {
1350            let mut b = [0u8; 8];
1351            let _ = getrandom::fill(&mut b);
1352            lexical::to_hex(&b)
1353        });
1354    let ip = client_ip(&mesh.inner, req.headers(), peer_of(&req));
1355    let method = req.method().clone();
1356    let also = if route == "/slice/{cell}" { Some(crate::slice::ARROW) } else { None };
1357    // The function page is HTML for people (Build 2 Part 4, P2) as well as JSON for agents.
1358    let html_ok = (route == "/fn/{name}" || route == "/takeover/{domain}") && accepts(req.headers(), "text/html");
1359    // The series pages and the sitemap choose their own media type, and a slice's browser redirect or
1360    // format is answered whatever its Accept (Build 2 Part 6, G1).
1361    let own_form = matches!(route.as_str(), "/series/{page}" | "/series/sitemap.xml" | "/x/interval/{function}")
1362        || (route == "/slice/{cell}"
1363            && crate::series::negotiation_free(&mesh.inner, &rest_of(req.uri(), "/slice/"), req.headers()));
1364    let mut resp = if route != "/blob/{sha256}"
1365        && route != "/metrics"
1366        && !html_ok
1367        && !own_form
1368        && !acceptable(req.headers(), also)
1369    {
1370        not_acceptable()
1371    } else {
1372        next.run(req).instrument(tracing::info_span!("request", request_id = %id)).await
1373    };
1374    let elapsed = start.elapsed();
1375    let status = resp.status().as_u16();
1376    mesh.inner.metrics.record(&route, status, elapsed);
1377    let principal = resp.extensions().get::<Who>().and_then(|w| w.0.clone());
1378    tracing::info!(target: "datumesh_http::access", request_id = %id, %method, route = %route, status, ms = elapsed.as_secs_f64() * 1000.0, ip = %ip, principal = principal.as_deref().unwrap_or("-"), "request");
1379    if let Ok(v) = HeaderValue::from_str(&id) {
1380        resp.headers_mut().insert("x-request-id", v);
1381    }
1382    resp.headers_mut().insert(header::VARY, HeaderValue::from_static("Accept, Accept-Encoding, Authorization"));
1383    if let Ok(v) = HeaderValue::from_str(&format!("app;dur={:.3}", elapsed.as_secs_f64() * 1000.0)) {
1384        resp.headers_mut().insert("server-timing", v);
1385    }
1386    resp
1387}
1388
1389/// describe (SPEC 16.8): a class or an object, by class name, key encoding, object id, cell id or
1390/// short id (`{id}`, percent-encoded as a path). A class's method table gives each method its
1391/// `description` from the catalog entry `{class}/{method}` when that is 1 to 1,024 bytes.
1392/// `POST /whatif` (spec-0.6.0, 5.9): the scenario of a cell under overrides, labelled a scenario,
1393/// never a fact.
1394#[utoipa::path(post, path = "/whatif",
1395    request_body(content = String, description = "The JSON of 5.9: `cell`, `asof`?, `overrides`, `solve`?", content_type = "application/json"),
1396    responses(
1397        (status = 200, description = "`scenario`: `{asof, cell, overrides, type, value[, solved]}`, no receipt", content_type = "application/json"),
1398        (status = 400, description = "`bad_request`", content_type = "application/json"),
1399        (status = 404, description = "`not_covered`, with `fault` when the scenario faulted or has no solution", content_type = "application/json"),
1400        (status = 500, description = "`error`", content_type = "application/json"),
1401    ))]
1402async fn whatif(State(mesh): State<Mesh>, headers: HeaderMap, req: Request) -> Response {
1403    let inner = mesh.inner.clone();
1404    let peer = peer_of(&req);
1405    let (client, principal) = match who(&inner, &headers, peer) {
1406        Ok(x) => x,
1407        Err(r) => return to_response(r),
1408    };
1409    if let Err(r) = admit(&inner, &client, 1) {
1410        return to_response(r);
1411    }
1412    let body = match axum::body::to_bytes(req.into_body(), 1 << 20).await {
1413        Ok(b) => b,
1414        Err(_) => return to_response(envelope::bad_request_reply(ErrorCode::CanonLimit)),
1415    };
1416    let mesh2 = mesh.clone();
1417    match inner.pool.clone().run(move || mesh2.whatif(&body, principal.as_ref())).await {
1418        Some(r) => to_response(r),
1419        None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1420    }
1421}
1422
1423/// `POST /x/calc` (Build 2 Part 3 addition, C3; D27, D30): a formula over cells, evaluated in a
1424/// scope: the value, its type, the formula and its canonical form, the asof and the lineage of the
1425/// cells read. Nothing is written: no receipt, no version, no binding.
1426#[utoipa::path(post, path = "/x/calc",
1427    request_body(content = String, description = "`{\"formula\": <body>, \"asof\"?: <instant>}`; the body is at most 4096 bytes", content_type = "application/json"),
1428    responses(
1429        (status = 200, description = "`kind: calculation`: `{outcome, kind, value, type, unit?, formula, canonical, asof, lineage}`, no receipt, no trust; `lineage` is `[{call, receipt, publisher, trust}]`", content_type = "application/json"),
1430        (status = 400, description = "`bad_request`, with the code (a request code, or a formula's `E_FORMULA_*`)", content_type = "application/json"),
1431        (status = 404, description = "`not_covered`, with `fault` when the calculation faulted", content_type = "application/json"),
1432        (status = 413, description = "`E_TOO_LARGE`: the formula is more than 4096 bytes", content_type = "application/json"),
1433        (status = 429, description = "`rate_limited`", content_type = "application/json"),
1434        (status = 500, description = "`error`", content_type = "application/json"),
1435        (status = 503, description = "`error` with `E_EVAL_BUDGET` (the mesh's budget ran out; no job) or `E_EVAL_UNAVAILABLE`", content_type = "application/json"),
1436    ))]
1437async fn x_calc(State(mesh): State<Mesh>, headers: HeaderMap, req: Request) -> Response {
1438    let inner = mesh.inner.clone();
1439    let peer = peer_of(&req);
1440    let (client, principal) = match who(&inner, &headers, peer) {
1441        Ok(x) => x,
1442        Err(r) => return to_response(r),
1443    };
1444    if let Err(r) = admit(&inner, &client, 1) {
1445        return to_response(r);
1446    }
1447    if let Err(s) = inner.limiter.admit_calc(client_ip(&inner, &headers, peer)) {
1448        return to_response(envelope::rate_limited_reply(s));
1449    }
1450    // A body of a 4 KiB formula with its JSON escapes is well under 64 KiB; more is refused as too large.
1451    let body = match axum::body::to_bytes(req.into_body(), 64 << 10).await {
1452        Ok(b) => b,
1453        Err(_) => return to_response(crate::calc::too_large_reply()),
1454    };
1455    let mesh2 = mesh.clone();
1456    match inner.pool.clone().run(move || mesh2.calc(&body, principal.as_ref())).await {
1457        Some(r) => to_response(r),
1458        None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1459    }
1460}
1461
1462/// `GET /x/keys/challenge` (QUESTIONS-build2 D39, `DATUMESH_KEY_NAMES=1`): a challenge to sign with the key to
1463/// register. Off: `404`.
1464#[utoipa::path(get, path = "/x/keys/challenge",
1465    responses(
1466        (status = 200, description = "`{\"challenge\", \"expires\"}`, no-store", content_type = "application/json"),
1467        (status = 404, description = "Key-derived names are off on this mesh", content_type = "application/json"),
1468        (status = 429, description = "`rate_limited`, with `Retry-After`", content_type = "application/json")))]
1469async fn x_keys_challenge(State(mesh): State<Mesh>, headers: HeaderMap, req: Request) -> Response {
1470    if !mesh.inner.config.key_names {
1471        return not_found("endpoint");
1472    }
1473    if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
1474        return r;
1475    }
1476    let inner = mesh.inner.clone();
1477    match inner.pool.clone().run(move || crate::keynames::challenge(&inner)).await {
1478        Some(r) => to_response(r),
1479        None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1480    }
1481}
1482
1483/// `POST /x/keys` (QUESTIONS-build2 D39, `DATUMESH_KEY_NAMES=1`): registers a public key by its proof of
1484/// possession (`{"public_key", "challenge", "signature"}`). The key's namespace is `<host>/key/k<24 hex>`.
1485/// `201` when the key is added, `200` when it was there. Off: `404`.
1486#[utoipa::path(post, path = "/x/keys",
1487    request_body(content = String, description = "`{\"public_key\": <64 hex>, \"challenge\": <as issued>, \"signature\": <128 hex, Ed25519 over the challenge's UTF-8 bytes>}`", content_type = "application/json"),
1488    responses(
1489        (status = 201, description = "`{\"namespace\", \"key_id\"}`: the key is added to the key document", content_type = "application/json"),
1490        (status = 200, description = "The same body: the key was registered before", content_type = "application/json"),
1491        (status = 400, description = "`E_KEY_MALFORMED`, or `E_CHALLENGE` (unknown, expired or used)", content_type = "application/json"),
1492        (status = 403, description = "`E_KEY_SIGNATURE`", content_type = "application/json"),
1493        (status = 404, description = "Key-derived names are off on this mesh", content_type = "application/json"),
1494        (status = 429, description = "`rate_limited`, with `Retry-After` (`DATUMESH_RATE_KEYS_PER_IP`)", content_type = "application/json")))]
1495async fn x_keys(State(mesh): State<Mesh>, headers: HeaderMap, req: Request) -> Response {
1496    let inner = mesh.inner.clone();
1497    if !inner.config.key_names {
1498        return not_found("endpoint");
1499    }
1500    if let Some(r) = ip_admit(&inner, &headers, &req) {
1501        return r;
1502    }
1503    let ip = client_ip(&inner, &headers, peer_of(&req));
1504    if let Err(s) = inner.limiter.admit_keys(ip) {
1505        return to_response(crate::keynames::rate_limited(s));
1506    }
1507    // A body over the limit is read to its end and is then malformed, as any other that does not parse.
1508    let body = axum::body::to_bytes(req.into_body(), crate::keynames::MAX_BODY).await.unwrap_or_default();
1509    let i2 = inner.clone();
1510    match inner
1511        .pool
1512        .clone()
1513        .run(move || match crate::keynames::parse(&body) {
1514            Ok(p) => crate::keynames::register(&i2, &p),
1515            Err(detail) => crate::keynames::refuse(400, "E_KEY_MALFORMED", &detail),
1516        })
1517        .await
1518    {
1519        Some(r) => to_response(r),
1520        None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1521    }
1522}
1523
1524#[utoipa::path(get, path = "/describe/{id}",
1525    params(("id" = String, Path, description = "A class name, an object's key encoding, an object id, a cell id or a short id (12 hex digits).")),
1526    responses((status = 200, description = "A describe-class or describe-object document (SPEC 16.8)", content_type = "application/json"), (status = 400, description = "`E_KEY_ENCODING`, `E_KEY_NORMALISATION` or `E_SHORT_ID_AMBIGUOUS`", content_type = "application/json"), (status = 404, description = "An id the mesh does not know", content_type = "application/json")))]
1527async fn describe(State(mesh): State<Mesh>, uri: Uri, headers: HeaderMap, req: Request) -> Response {
1528    if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
1529        return r;
1530    }
1531    let Some(id) = crate::call::url_decode(uri.path().strip_prefix("/describe/").unwrap_or("")) else {
1532        return to_response(envelope::bad_request_reply(ErrorCode::CanonPercent));
1533    };
1534    let inner = mesh.inner.clone();
1535    match inner.pool.clone().run(move || mesh.describe(&id)).await {
1536        Some(r) => {
1537            // A function's page is named by a `Link` header, not a member of the answer (16.8 is
1538            // checked strictly by core; Build 2 Part 4, P2).
1539            let link = function_describe_link(&inner, &r);
1540            let mut resp = to_response(r);
1541            if let Some(v) = link.and_then(|l| HeaderValue::from_str(&l).ok()) {
1542                resp.headers_mut().insert(header::LINK, v);
1543            }
1544            resp
1545        }
1546        None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1547    }
1548}
1549
1550/// The `Link` header of a describe answer for a function: its page, `rel="describedby"`.
1551fn function_describe_link(inner: &Inner, r: &Reply) -> Option<String> {
1552    if r.status != 200 {
1553        return None;
1554    }
1555    let v = json::parse(&r.body).ok()?;
1556    if v.get("kind")?.as_str()? != "function" {
1557        return None;
1558    }
1559    let name = v.get("fn")?.as_str()?;
1560    Some(format!("<{}>; rel=\"describedby\"", crate::fnpage::page_url(inner, name)))
1561}
1562
1563/// `POST /bundles` (Build 2 Part 4, P1): a publisher's bundle, checked and imported (see `bundles`).
1564async fn bundles(State(mesh): State<Mesh>, req: Request) -> Response {
1565    to_response(crate::bundles::post(mesh.inner.clone(), req.into_body()).await)
1566}
1567
1568/// `GET /fn/<name>` (Build 2 Part 4, P2): the function page, HTML or, by `Accept` or `?format=json`,
1569/// the same data as JSON.
1570async fn function_page(
1571    State(mesh): State<Mesh>,
1572    Path(name): Path<String>,
1573    uri: Uri,
1574    headers: HeaderMap,
1575    req: Request,
1576) -> Response {
1577    if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
1578        return r;
1579    }
1580    let format_json = uri.query().is_some_and(|q| q.split('&').any(|p| p == "format=json"));
1581    let json_form = format_json || (accepts(&headers, JSON) && !accepts(&headers, "text/html"));
1582    let inner = mesh.inner.clone();
1583    match inner.pool.clone().run(move || crate::fnpage::respond(&mesh.inner, &name, json_form)).await {
1584        Some(r) => to_response(r),
1585        None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1586    }
1587}
1588
1589/// `GET /takeover/<domain>` (D24): what a source's domain can do to publish the values this mesh
1590/// relays from it; HTML, or JSON by `Accept` or `?format=json`.
1591#[utoipa::path(get, path = "/takeover/{domain}",
1592    params(("domain" = String, Path, description = "The source's DNS name (SPEC 2.1)")),
1593    responses(
1594        (status = 200, description = "`{\"domain\", \"host\", \"functions\": [{\"name\", \"page\", \"fn_hash\"}], \"steps\": [...]}`, or the HTML page", content_type = "application/json"),
1595        (status = 400, description = "E_CANON_NAME: not a DNS name", content_type = "application/json"),
1596        (status = 404, description = "not_covered: no function relayed from the domain on this mesh", content_type = "application/json")))]
1597async fn takeover_page(
1598    State(mesh): State<Mesh>,
1599    Path(domain): Path<String>,
1600    uri: Uri,
1601    headers: HeaderMap,
1602    req: Request,
1603) -> Response {
1604    if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
1605        return r;
1606    }
1607    let format_json = uri.query().is_some_and(|q| q.split('&').any(|p| p == "format=json"));
1608    let json_form = format_json || (accepts(&headers, JSON) && !accepts(&headers, "text/html"));
1609    let inner = mesh.inner.clone();
1610    match inner.pool.clone().run(move || crate::takeover::respond(&mesh.inner, &domain, json_form)).await {
1611        Some(r) => to_response(r),
1612        None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1613    }
1614}
1615
1616/// The per-IP budget of the series pages (`DATUMESH_RATE_SERIES_PER_IP`), after the ordinary per-IP limit.
1617fn series_admit(inner: &Inner, headers: &HeaderMap, req: &Request) -> Option<Response> {
1618    let peer = peer_of(req);
1619    let client = match who(inner, headers, peer) {
1620        Ok((c, _)) => c,
1621        Err(r) => return Some(to_response(r)),
1622    };
1623    if let Err(r) = admit(inner, &client, 1) {
1624        return Some(to_response(r));
1625    }
1626    let ip = client_ip(inner, headers, peer);
1627    inner.limiter.admit_series(ip).err().map(|s| to_response(envelope::rate_limited_reply(s)))
1628}
1629
1630/// A series answer as a response: its status, body, media type, `Cache-Control` and `ETag`.
1631fn series_response(o: crate::series::Out) -> Response {
1632    let mut resp = Response::new(Body::from(o.body));
1633    *resp.status_mut() = StatusCode::from_u16(o.status).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR);
1634    let h = resp.headers_mut();
1635    h.insert(header::CONTENT_TYPE, HeaderValue::from_static(o.content_type));
1636    if let Ok(v) = HeaderValue::from_str(&o.cache) {
1637        h.insert(header::CACHE_CONTROL, v);
1638    }
1639    if let Some(e) = o.etag.as_deref().and_then(|e| HeaderValue::from_str(e).ok()) {
1640        h.insert(header::ETAG, e);
1641    }
1642    if let Some(s) = o.retry_after {
1643        h.insert(header::RETRY_AFTER, HeaderValue::from(s));
1644    }
1645    resp
1646}
1647
1648async fn series_answer(mesh: Mesh, headers: &HeaderMap, rest: String) -> Response {
1649    let inm = headers.get(header::IF_NONE_MATCH).and_then(|v| v.to_str().ok()).map(str::to_string);
1650    let inner = mesh.inner.clone();
1651    match inner.pool.clone().run(move || crate::series::respond(&mesh.inner, &rest, inm.as_deref())).await {
1652        Some(o) => series_response(o),
1653        None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1654    }
1655}
1656
1657/// `GET /series/<function>/<YYYY-MM>[.csv]`, `/series/<function>/<YYYY>[.csv]` and `/series/<function>/`: the
1658/// month or year page of a relayed or computed series, its CSV, or its index (Build 2 Part 6, G1 to G5).
1659#[utoipa::path(get, path = "/series/{page}",
1660    params(("page" = String, Path, description = "The series' function name, then `/YYYY-MM`, `/YYYY` (each with an optional `.csv`) or `/` for the index")),
1661    responses(
1662        (status = 200, description = "The page (HTML with a JSON-LD dataset), its CSV (`text/csv`), or the index", content_type = "text/html"),
1663        (status = 304, description = "`ETag` unchanged"),
1664        (status = 404, description = "No stored value at this address, or the function is not in the series file (cacheable 600 s)", content_type = "text/html"),
1665        (status = 429, description = "`rate_limited`, with `Retry-After` (the per-IP and the series budgets)", content_type = "application/json"),
1666    ))]
1667async fn series_page(State(mesh): State<Mesh>, uri: Uri, headers: HeaderMap, req: Request) -> Response {
1668    if let Some(r) = series_admit(&mesh.inner, &headers, &req) {
1669        return r;
1670    }
1671    let rest = uri.path().strip_prefix("/series/").unwrap_or("").to_string();
1672    series_answer(mesh, &headers, rest).await
1673}
1674
1675/// `GET /series/sitemap.xml`: every index and page of the listed series, with `lastmod` (the as-of); a sitemap
1676/// index of `sitemap-<n>.xml` files past 50,000 URLs.
1677#[utoipa::path(get, path = "/series/sitemap.xml",
1678    responses(
1679        (status = 200, description = "A sitemap (`application/xml`) or a sitemap index", content_type = "application/xml"),
1680        (status = 404, description = "No series file: no pages", content_type = "text/html"),
1681        (status = 429, description = "`rate_limited`, with `Retry-After`", content_type = "application/json"),
1682    ))]
1683async fn series_sitemap(State(mesh): State<Mesh>, headers: HeaderMap, req: Request) -> Response {
1684    if let Some(r) = series_admit(&mesh.inner, &headers, &req) {
1685        return r;
1686    }
1687    series_answer(mesh, &headers, "sitemap.xml".to_string()).await
1688}
1689
1690/// `GET /x/interval/<function>?<key>=<value|*>...&from=<date>&to=<date>[&format=csv|arrow]` (D32, an extension):
1691/// the stored cells of a listed series in `[from, to]`, each with its receipt.
1692#[utoipa::path(get, path = "/x/interval/{function}",
1693    params(
1694        ("function" = String, Path, description = "The function name of a series listed in the series file"),
1695        ("from" = String, Query, description = "The first date, `YYYY-MM-DD`, inclusive"),
1696        ("to" = String, Query, description = "The last date, `YYYY-MM-DD`, inclusive; at most 10 years after `from` for a series with month pages"),
1697        ("format" = Option<String>, Query, description = "`csv` or `arrow`; JSON without it. Each is an address of its own"),
1698    ),
1699    responses(
1700        (status = 200, description = "JSON `{function, from, to, asof, count, members: [{keys, value, type, tx, asof, receipt_hash, receipt}]}`; CSV (long form: the open keys, `date`, `value`, `receipt`); or an Arrow IPC stream", content_type = "application/json"),
1701        (status = 304, description = "`ETag` unchanged"),
1702        (status = 400, description = "`bad_request`: a missing or malformed `from` or `to`, `from` after `to`, an argument the function lacks, or `E_RANGE_TOO_LARGE`", content_type = "application/json"),
1703        (status = 404, description = "The function is not in the series file", content_type = "application/json"),
1704        (status = 429, description = "`rate_limited`, with `Retry-After` (the per-IP and the series budgets)", content_type = "application/json"),
1705    ))]
1706async fn x_interval(State(mesh): State<Mesh>, uri: Uri, headers: HeaderMap, req: Request) -> Response {
1707    if let Some(r) = series_admit(&mesh.inner, &headers, &req) {
1708        return r;
1709    }
1710    let function = uri.path().strip_prefix("/x/interval/").unwrap_or("").to_string();
1711    let query = uri.query().unwrap_or("").to_string();
1712    let inm = headers.get(header::IF_NONE_MATCH).and_then(|v| v.to_str().ok()).map(str::to_string);
1713    let inner = mesh.inner.clone();
1714    match inner.pool.clone().run(move || crate::series::interval(&mesh.inner, &function, &query, inm.as_deref())).await
1715    {
1716        Some(o) => series_response(o),
1717        None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1718    }
1719}
1720
1721async fn fallback() -> Response {
1722    not_found("endpoint")
1723}
1724
1725impl Mesh {
1726    /// The router of every endpoint. Serve it with
1727    /// `into_make_service_with_connect_info::<SocketAddr>()` (the client IP comes from it).
1728    pub fn router(&self) -> Router {
1729        Router::new()
1730            .route("/cell/{*rest}", get(cell))
1731            .route("/cells", post(cells))
1732            .route("/slice/{*rest}", get(slice))
1733            .route("/receipt/{hash}", get(receipt))
1734            .route("/descriptor/{hash}", get(descriptor))
1735            .route("/manifest/{slice_id}/{members_hash}", get(manifest))
1736            .route("/versions/{*rest}", get(versions))
1737            .route("/blob/{sha256}", get(blob))
1738            .route("/explain/{*rest}", get(explain))
1739            .route("/find", get(find))
1740            .route("/verify", post(verify_receipt))
1741            .route("/jobs/{job}", get(job))
1742            .route("/.well-known/datumesh.json", get(key_document))
1743            .route("/.well-known/datumesh-mesh.json", get(mesh_document))
1744            .route("/bindings", get(bindings))
1745            .route("/describe/{*id}", get(describe))
1746            .route("/fn/{*name}", get(function_page))
1747            .route("/takeover/{*domain}", get(takeover_page))
1748            .route("/series/sitemap.xml", get(series_sitemap))
1749            .route("/series/{*rest}", get(series_page))
1750            .route("/bundles", post(bundles))
1751            .route("/whatif", post(whatif))
1752            .route("/x/calc", post(x_calc))
1753            .route("/x/keys/challenge", get(x_keys_challenge))
1754            .route("/x/keys", post(x_keys))
1755            .route("/x/interval/{*function}", get(x_interval))
1756            .route("/health", get(health))
1757            .route("/metrics", get(metrics))
1758            .route("/openapi.json", get(openapi_json))
1759            .fallback(fallback)
1760            .layer(middleware::from_fn_with_state(self.clone(), around))
1761            .layer(tower_http::compression::CompressionLayer::new().gzip(true))
1762            .with_state(self.clone())
1763    }
1764
1765    /// Serves the router on `listener` until `shutdown` resolves.
1766    pub async fn serve(
1767        &self,
1768        listener: tokio::net::TcpListener,
1769        shutdown: impl std::future::Future<Output = ()> + Send + 'static,
1770    ) -> std::io::Result<()> {
1771        axum::serve(listener, self.router().into_make_service_with_connect_info::<SocketAddr>())
1772            .with_graceful_shutdown(shutdown)
1773            .await
1774    }
1775}
1776
1777impl IntoResponse for Reply {
1778    fn into_response(self) -> Response {
1779        to_response(self)
1780    }
1781}
1782
1783#[cfg(test)]
1784mod tests {
1785    use super::*;
1786
1787    fn reply(status: u16, body: &str) -> Reply {
1788        Reply::json(status, body.as_bytes().to_vec(), Cache::NoStore)
1789    }
1790
1791    /// The runs the chunks write, concatenated and closed, are the batch as 5.7 writes it, and
1792    /// count its outcomes.
1793    #[test]
1794    fn runs_make_the_batch() {
1795        let h = "a".repeat(64);
1796        let replies = [
1797            reply(200, &format!(r#"{{"fn_hash":"{h}","outcome":"ok","receipt":{{"value":"1"}},"trust":"primary"}}"#)),
1798            reply(400, r#"{"error":"E_CANON_NUMBER","outcome":"bad_request"}"#),
1799            reply(
1800                200,
1801                &format!(r#"{{"age_seconds":3,"fn_hash":"{h}","outcome":"stale","receipt":{{}},"trust":"computed"}}"#),
1802            ),
1803            reply(404, r#"{"error":"E_NAME_UNBOUND","outcome":"not_covered"}"#),
1804            reply(200, &format!(r#"{{"fn_hash":"{h}","outcome":"ok","receipt":{{"value":"2"}},"trust":"primary"}}"#)),
1805        ];
1806        let mut want = b"[".to_vec();
1807        for (i, r) in replies.iter().enumerate() {
1808            if i > 0 {
1809                want.push(b',');
1810            }
1811            want.extend_from_slice(b"{\"envelope\":");
1812            want.extend_from_slice(&r.body);
1813            want.extend_from_slice(format!(",\"status\":{}}}", r.status).as_bytes());
1814        }
1815        want.push(b']');
1816        for split in 1..replies.len() {
1817            let runs = [Written::of(true, replies[..split].iter()), Written::of(false, replies[split..].iter())];
1818            let mut got: Vec<u8> = runs.iter().flat_map(|w| w.bytes.iter().copied()).collect();
1819            got.push(b']');
1820            assert_eq!(String::from_utf8(got).unwrap(), String::from_utf8(want.clone()).unwrap());
1821            let mut counts = std::collections::BTreeMap::new();
1822            for (o, k) in runs.iter().flat_map(|w| w.outcomes.iter()) {
1823                *counts.entry(o.as_str()).or_insert(0) += k;
1824            }
1825            let want_counts: std::collections::BTreeMap<&str, u64> =
1826                [("bad_request", 1), ("not_covered", 1), ("ok", 2), ("stale", 1)].into_iter().collect();
1827            assert_eq!(counts, want_counts);
1828        }
1829        for (n, s) in [(0u16, "0"), (7, "7"), (200, "200"), (404, "404"), (65535, "65535")] {
1830            let mut out = Vec::new();
1831            push_u16(&mut out, n);
1832            assert_eq!(out, s.as_bytes());
1833        }
1834    }
1835
1836    /// The outcome of each envelope, whatever members come before it.
1837    #[test]
1838    fn outcomes() {
1839        let h = "0".repeat(64);
1840        for (body, want) in [
1841            (format!(r#"{{"fn_hash":"{h}","outcome":"ok","receipt":{{"outcome":"x"}}}}"#), Some("ok")),
1842            (r#"{"age_seconds":12,"outcome":"stale"}"#.to_string(), Some("stale")),
1843            (r#"{"error":"E_PARSE_URI","outcome":"bad_request"}"#.to_string(), Some("bad_request")),
1844            (r#"{"outcome":"pending","poll":"https://a.example/jobs/1"}"#.to_string(), Some("pending")),
1845            (r#"{"error":"no such endpoint"}"#.to_string(), None),
1846            (r#"{"outcome""#.to_string(), None),
1847        ] {
1848            assert_eq!(reply(200, &body).outcome_str(), want, "{body}");
1849            assert_eq!(reply(200, &body).outcome(), want.map(str::to_string), "{body}");
1850        }
1851        let mut arrow = reply(200, r#"{"outcome":"ok"}"#);
1852        arrow.content_type = "application/vnd.apache.arrow.stream";
1853        assert_eq!(arrow.outcome(), None);
1854    }
1855}