1use 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#[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
56fn 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
94fn 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
103async 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 return envelope::error_reply(ErrorCode::EvalUnavailable);
134 };
135 pend(inner, request, task)
136 }
137 }
138}
139
140fn 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
149fn 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
217pub fn openapi() -> utoipa::openapi::OpenApi {
219 ApiDoc::openapi()
220}
221
222#[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#[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 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 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
320fn parse_batch(body: &[u8], max: usize) -> Result<Vec<String>, (ErrorCode, String)> {
323 let pu = |m: String| (ErrorCode::ParseUri, m);
324 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#[derive(Default)]
355struct Written {
356 bytes: Vec<u8>,
357 outcomes: Vec<(String, u64)>,
358}
359
360impl Written {
361 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
392fn 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
407fn 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
414async 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 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 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 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 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#[derive(Default)]
559struct Slot {
560 late: bool,
561 answers: Vec<(usize, Reply)>,
562 written: Option<Written>,
563}
564
565type Slots = Arc<Vec<Mutex<Slot>>>;
567
568async 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#[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
604const VERSIONS_PAGE: usize = 1000;
606
607impl Inner {
608 fn versions(&self, rest: &str) -> Reply {
609 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 let mut vs = match self.store.versions(target.cell_id(), &lo, &hi) {
643 Ok(v) => v,
644 Err(_) => return envelope::error_answer_reply(ErrorCode::InputUnavailable, Some(&target.bound.fn_hash)),
645 };
646 vs.sort_by(|a, b| (&a.tx, &a.receipt_hash).cmp(&(&b.tx, &b.receipt_hash)));
647 let more = vs.len() > VERSIONS_PAGE;
648 vs.truncate(VERSIONS_PAGE);
649 let list: Vec<Value> = vs
650 .iter()
651 .map(|v| {
652 Value::Object(vec![
653 ("asof".into(), Value::String(v.asof.clone())),
654 ("receipt".into(), Value::String(v.receipt_hash.clone())),
655 ("tx".into(), Value::String(v.tx.clone())),
656 ])
657 })
658 .collect();
659 let mut body = vec![("cell".to_string(), target.cell.to_value()), ("versions".to_string(), Value::Array(list))];
660 if more {
661 if let Some(last) = vs.last() {
662 let us = datumesh_formula::calendar::parse_instant(&last.tx).unwrap_or(0) + 1;
663 let next_from = datumesh_formula::calendar::instant_text(us).unwrap_or_default();
664 let mut next = format!("{}/versions/{cell_rest}", self.config.origin());
665 next.push(if cell_rest.contains('?') { '&' } else { '?' });
666 next.push_str(&format!("from={next_from}"));
667 if let Some(t) = &to {
668 next.push_str(&format!("&to={t}"));
669 }
670 body.push(("next".to_string(), Value::String(next)));
671 }
672 }
673 Reply::json(200, Value::Object(body).to_jcs(), Cache::Public(self.config.ttl.latest_max_age.as_secs()))
674 }
675}
676
677#[utoipa::path(get, path = "/slice/{cell}",
679 params(
680 ("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)."),
681 ),
682 responses(
683 (status = 200, description = "JSON page of members, or with `Accept: application/vnd.apache.arrow.stream` an Arrow IPC stream", content_type = "application/json"),
684 (status = 400, description = "`bad_request`", content_type = "application/json"),
685 (status = 404, description = "`not_covered`", content_type = "application/json"),
686 ))]
687async fn slice(State(mesh): State<Mesh>, uri: Uri, headers: HeaderMap, req: Request) -> Response {
688 let inner = mesh.inner.clone();
689 let (client, _) = match who(&inner, &headers, peer_of(&req)) {
690 Ok(x) => x,
691 Err(r) => return to_response(r),
692 };
693 if let Err(r) = admit(&inner, &client, 1) {
694 return to_response(r);
695 }
696 let rest = rest_of(&uri, "/slice/");
698 if crate::series::redirect_reads_store(&inner, &rest, &headers) {
699 let (i2, r2, h2) = (inner.clone(), rest.clone(), headers.clone());
701 match inner.pool.clone().run(move || crate::series::slice_redirect(&i2, &r2, &h2)).await {
702 None => return to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
703 Some(Some(to)) => return see_other(&to),
704 Some(None) if !acceptable(&headers, Some(crate::slice::ARROW)) => return not_acceptable(),
706 Some(None) => {}
707 }
708 } else if let Some(to) = crate::series::slice_redirect(&inner, &rest, &headers) {
709 return see_other(&to);
710 }
711 let (rest, format) = match crate::slice::split_format(&rest) {
712 Ok(x) => x,
713 Err(c) => return to_response(envelope::bad_request_reply(c)),
714 };
715 let accept_arrow = format.is_none() && accepts(&headers, crate::slice::ARROW);
717 let form = if accept_arrow { crate::slice::Form::Arrow } else { format.unwrap_or_default() };
718 let r = inner
719 .pool
720 .clone()
721 .run(move || {
722 let now = inner.now();
723 inner.slice(&rest, &now, form)
724 })
725 .await
726 .unwrap_or_else(|| envelope::error_reply(ErrorCode::EvalUnavailable));
727 let mut r = r;
728 if accept_arrow {
729 r.cache = Cache::NoStore;
730 }
731 to_response(r)
732}
733
734fn see_other(location: &str) -> Response {
736 let mut resp = Response::new(Body::empty());
737 *resp.status_mut() = StatusCode::SEE_OTHER;
738 if let Ok(v) = HeaderValue::from_str(location) {
739 resp.headers_mut().insert(header::LOCATION, v);
740 }
741 resp.headers_mut().insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
742 resp
743}
744
745fn accepts(headers: &HeaderMap, media: &str) -> bool {
746 headers
747 .get_all(header::ACCEPT)
748 .iter()
749 .filter_map(|v| v.to_str().ok())
750 .any(|v| v.split(',').any(|p| p.split(';').next().unwrap_or("").trim() == media))
751}
752
753fn not_acceptable() -> Response {
757 let mut r = Reply::json(
758 406,
759 Value::Object(vec![("error".into(), Value::String("not acceptable: application/json only".into()))]).to_jcs(),
760 Cache::NoStore,
761 );
762 r.content_type = JSON;
763 to_response(r)
764}
765
766fn acceptable(headers: &HeaderMap, also: Option<&str>) -> bool {
767 let vals: Vec<&str> = headers.get_all(header::ACCEPT).iter().filter_map(|v| v.to_str().ok()).collect();
768 if vals.is_empty() {
769 return true;
770 }
771 vals.iter().flat_map(|v| v.split(',')).any(|p| {
772 let mut parts = p.split(';');
773 let m = parts.next().unwrap_or("").trim();
774 let q0 = parts.any(|x| {
775 let x = x.trim();
776 x == "q=0" || x == "q=0.0" || x == "q=0.00" || x == "q=0.000"
777 });
778 !q0 && (m == "*/*" || m == "application/*" || m == JSON || also == Some(m))
779 })
780}
781
782async fn object(
783 inner: Arc<Inner>,
784 what: &'static str,
785 f: impl FnOnce(&Inner) -> Option<Vec<u8>> + Send + 'static,
786) -> Response {
787 let i2 = inner.clone();
788 match inner.pool.run(move || f(&i2)).await.flatten() {
789 Some(bytes) => {
790 let ct = if what == "blob" { "application/octet-stream" } else { JSON };
791 to_response(Reply {
792 status: 200,
793 body: bytes.into(),
794 content_type: ct,
795 cache: Cache::Immutable,
796 canonical: None,
797 retry_after: None,
798 })
799 }
800 None => not_found(what),
801 }
802}
803
804fn ip_admit(inner: &Inner, headers: &HeaderMap, req: &Request) -> Option<Response> {
806 let client = match who(inner, headers, peer_of(req)) {
807 Ok((c, _)) => c,
808 Err(r) => return Some(to_response(r)),
809 };
810 admit(inner, &client, 1).err().map(to_response)
811}
812
813#[utoipa::path(get, path = "/receipt/{hash}", params(("hash" = String, Path, description = "The receipt hash (SPEC 8.3).")),
815 responses((status = 200, description = "The receipt's canonical JSON; immutable", content_type = "application/json"), (status = 404, description = "Not held")))]
816async fn receipt(State(mesh): State<Mesh>, Path(hash): Path<String>, headers: HeaderMap, req: Request) -> Response {
817 if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
818 return r;
819 }
820 if lexical::check_hex(&hash, 64, "$").is_err() {
821 return not_found("receipt");
822 }
823 object(mesh.inner.clone(), "receipt", move |i| i.store.receipt(&hash).map(|c| c.into_owned())).await
824}
825
826#[utoipa::path(get, path = "/descriptor/{hash}", params(("hash" = String, Path, description = "The function hash.")),
828 responses((status = 200, description = "The descriptor's canonical JSON; immutable", content_type = "application/json"), (status = 404, description = "Not held")))]
829async fn descriptor(State(mesh): State<Mesh>, Path(hash): Path<String>, headers: HeaderMap, req: Request) -> Response {
830 if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
831 return r;
832 }
833 if lexical::check_hex(&hash, 64, "$").is_err() {
834 return not_found("descriptor");
835 }
836 object(mesh.inner.clone(), "descriptor", move |i| i.store.descriptor(&hash).map(|c| c.into_owned())).await
837}
838
839async fn manifest_of(inner: Arc<Inner>, entry: String) -> Response {
840 object(inner, "manifest", move |i| i.store.manifest(&entry).map(|c| c.into_owned())).await
841}
842
843#[utoipa::path(get, path = "/manifest/{slice_id}/{members_hash}",
845 params(("slice_id" = String, Path, description = "The slice id."), ("members_hash" = String, Path, description = "The members hash.")),
846 responses((status = 200, description = "The manifest's canonical JSON; immutable", content_type = "application/json"), (status = 404, description = "Not held")))]
847async fn manifest(
848 State(mesh): State<Mesh>,
849 Path((slice_id, members)): Path<(String, String)>,
850 headers: HeaderMap,
851 req: Request,
852) -> Response {
853 if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
854 return r;
855 }
856 if lexical::check_hex(&slice_id, 64, "$").is_err() || lexical::check_hex(&members, 64, "$").is_err() {
857 return not_found("manifest");
858 }
859 manifest_of(mesh.inner.clone(), format!("slice:{slice_id}:{members}")).await
860}
861
862#[utoipa::path(get, path = "/blob/{sha256}", params(("sha256" = String, Path, description = "The content's SHA-256.")),
864 responses((status = 200, description = "The bytes; immutable", content_type = "application/octet-stream"), (status = 404, description = "Not held")))]
865async fn blob(State(mesh): State<Mesh>, Path(sha): Path<String>, headers: HeaderMap, req: Request) -> Response {
866 if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
867 return r;
868 }
869 if lexical::check_hex(&sha, 64, "$").is_err() {
870 return not_found("blob");
871 }
872 object(mesh.inner.clone(), "blob", move |i| i.store.blob(&sha).ok().flatten().map(|c| c.into_owned())).await
873}
874
875#[utoipa::path(get, path = "/explain/{cell}",
877 params(("cell" = String, Path, description = "As for /cell; `depth=` (default 4, at most 16) bounds the walk.")),
878 responses(
879 (status = 200, description = "`{\"envelope\", \"inputs\": [{\"entry\", \"envelope\", \"inputs\"} | {\"entry\", \"slice\", \"members\"}], \"truncated\"}`", content_type = "application/json"),
880 (status = 202, description = "`pending`: the cell is being computed; ask again", content_type = "application/json"),
881 (status = 400, description = "`bad_request`", content_type = "application/json"),
882 (status = 404, description = "`not_covered`", content_type = "application/json"),
883 ))]
884async fn explain(State(mesh): State<Mesh>, uri: Uri, headers: HeaderMap, req: Request) -> Response {
885 let inner = mesh.inner.clone();
886 let (client, principal) = match who(&inner, &headers, peer_of(&req)) {
887 Ok(x) => x,
888 Err(r) => return to_response(r),
889 };
890 if let Err(r) = admit(&inner, &client, 1) {
891 return to_response(r);
892 }
893 let mut rest = rest_of(&uri, "/explain/");
894 let mut depth = inner.config.explain_depth;
895 if let Some((p, q)) = rest.clone().split_once('?') {
897 let kept: Vec<&str> = q.split('&').filter(|x| !x.starts_with("depth=")).collect();
898 if let Some(d) = q.split('&').find_map(|x| x.strip_prefix("depth=")) {
899 depth = d.parse::<usize>().unwrap_or(depth);
900 }
901 rest = if kept.is_empty() { p.to_string() } else { format!("{p}?{}", kept.join("&")) };
902 }
903 let depth = depth.min(16);
904 let r = within_budget(inner, move |i, on| {
905 let now = i.now();
906 let r = i.answer(&rest, principal.as_ref(), i, &now, on);
907 if r.status != 200 {
908 return r;
909 }
910 let env = json::parse(&r.body).unwrap_or(Value::Null);
911 let mut budget = 2_000usize;
912 let v = i.explain_node(env, depth, &mut budget);
913 Reply::json(200, v.to_jcs(), Cache::NoStore)
914 })
915 .await;
916 to_response(r)
917}
918
919impl Inner {
920 fn explain_node(&self, envelope: Value, depth: usize, budget: &mut usize) -> Value {
922 let inputs: Vec<String> = envelope
923 .get("receipt")
924 .and_then(|r| r.get("inputs"))
925 .and_then(|i| {
926 if let Value::Array(a) = i {
927 Some(a.iter().filter_map(Value::as_str).map(str::to_string).collect())
928 } else {
929 None
930 }
931 })
932 .unwrap_or_default();
933 let mut truncated = false;
934 let mut out = Vec::new();
935 for e in inputs {
936 if depth == 0 || *budget == 0 {
937 truncated = true;
938 break;
939 }
940 *budget -= 1;
941 if e.starts_with("slice:") {
942 let m = self.store.manifest(&e).and_then(|m| datumesh_core::Manifest::from_json(&m).ok());
943 let mut node = vec![("entry".to_string(), Value::String(e.clone()))];
944 if let Some(m) = m {
945 node.push(("members".to_string(), envelope::num(m.members().len() as u64)));
946 node.push(("slice".to_string(), m.slice().to_value()));
947 }
948 out.push(Value::Object(node));
949 continue;
950 }
951 let child = match self.receipt_info_by_hash(&e) {
952 Some(info) => self.explain_node(json::parse(&info.ok).unwrap_or(Value::Null), depth - 1, budget),
953 None => json::parse(&envelope::not_covered(None)).unwrap_or(Value::Null),
954 };
955 let mut node = vec![("entry".to_string(), Value::String(e.clone()))];
956 if let Value::Object(m) = child {
957 node.extend(m);
958 }
959 out.push(Value::Object(node));
960 }
961 let mut node = vec![("envelope".to_string(), envelope.clone()), ("inputs".to_string(), Value::Array(out))];
962 node.push(("truncated".to_string(), Value::Bool(truncated)));
963 Value::Object(node)
964 }
965}
966
967#[derive(serde::Deserialize)]
968struct FindQuery {
969 q: Option<String>,
970 limit: Option<usize>,
971 summary: Option<String>,
972}
973
974#[utoipa::path(get, path = "/find",
976 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.")),
977 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")))]
978async fn find(State(mesh): State<Mesh>, Query(q): Query<FindQuery>, headers: HeaderMap, req: Request) -> Response {
979 if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
980 return r;
981 }
982 let inner = mesh.inner.clone();
983 let query = q.q.unwrap_or_default();
984 let limit = q.limit.unwrap_or(crate::find::DEFAULT_LIMIT).clamp(1, crate::find::MAX_LIMIT);
985 let summary = q.summary.as_deref() == Some("1");
986 let r = inner
987 .pool
988 .clone()
989 .run(move || if summary { crate::find::summary(&inner) } else { crate::find::answer(&inner, &query, limit) })
990 .await
991 .unwrap_or(Value::Null);
992 plain_json(200, r, Cache::Public(60))
993}
994
995#[derive(serde::Deserialize)]
996struct VerifyQuery {
997 level: Option<String>,
998 blob: Option<String>,
999 form: Option<String>,
1000}
1001
1002#[utoipa::path(post, path = "/verify",
1005 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.")),
1006 request_body(content = String, description = "The receipt's JSON text, exactly as received (or the offered form).", content_type = "application/json"),
1007 responses(
1008 (status = 200, description = "`{\"ok\", \"level\", \"code\", \"hash\", \"computed_by\", \"path\", \"detail\", \"blob_checked\"}`", content_type = "application/json"),
1009 (status = 429, description = "`rate_limited`", content_type = "application/json"),
1010 ))]
1011async fn verify_receipt(
1012 State(mesh): State<Mesh>,
1013 Query(q): Query<VerifyQuery>,
1014 headers: HeaderMap,
1015 req: Request,
1016) -> Response {
1017 let inner = mesh.inner.clone();
1018 let ip = client_ip(&inner, &headers, peer_of(&req));
1019 if let Err(s) = inner.limiter.admit_verify(ip) {
1020 return to_response(envelope::rate_limited_reply(s));
1021 }
1022 let body: Bytes = match axum::body::to_bytes(req.into_body(), 4 << 20).await {
1023 Ok(b) => b,
1024 Err(_) => return batch_error("body too large"),
1025 };
1026 if q.form.as_deref() == Some("offered") {
1027 let Ok(v) = json::parse(&body) else { return batch_error("form=offered: not strict JSON") };
1028 let Some(receipt) = v.get("receipt").and_then(Value::as_str).map(|s| s.as_bytes().to_vec()) else {
1029 return batch_error("form=offered: no receipt text");
1030 };
1031 let blob = match v.get("blob_hex").and_then(Value::as_str).map(hex) {
1032 None => None,
1033 Some(Some(b)) if b.len() <= 1 << 20 => Some(b),
1034 Some(_) => return batch_error("blob_hex: hex of at most 1 MiB"),
1035 };
1036 let m = mesh.clone();
1037 let rc = v.get("recompute").cloned();
1038 let r = inner.pool.run(move || m.verify_offered(&receipt, rc.as_ref(), blob.as_deref())).await;
1039 return match r {
1040 Some(v) => to_response(Reply::json(200, v.body, Cache::NoStore)),
1041 None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1042 };
1043 }
1044 let signed = q.level.as_deref() == Some("signed");
1045 let blob = match q.blob.as_deref().map(hex) {
1046 None => None,
1047 Some(Some(b)) if b.len() <= 1 << 20 => Some(b),
1048 Some(_) => return batch_error("blob: hex of at most 1 MiB"),
1049 };
1050 let m = mesh.clone();
1051 let r = inner.pool.run(move || m.verify(&body, signed, blob.as_deref())).await;
1052 match r {
1053 Some(v) => to_response(Reply::json(200, v.body, Cache::NoStore)),
1054 None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1055 }
1056}
1057
1058fn hex(s: &str) -> Option<Vec<u8>> {
1059 if !s.len().is_multiple_of(2) {
1060 return None;
1061 }
1062 (0..s.len()).step_by(2).map(|i| u8::from_str_radix(s.get(i..i + 2)?, 16).ok()).collect()
1063}
1064
1065#[utoipa::path(get, path = "/jobs/{job}", params(("job" = String, Path, description = "The job id of a `pending` envelope.")),
1067 responses(
1068 (status = 202, description = "`pending`, the same job and request", content_type = "application/json"),
1069 (status = 400, description = "`bad_request` with `E_JOB_UNKNOWN`: unknown or expired", content_type = "application/json"),
1070 (status = 200, description = "The completed envelope (any outcome but pending, with its status), bound to the original request", content_type = "application/json"),
1071 ))]
1072async fn job(State(mesh): State<Mesh>, Path(id): Path<String>, headers: HeaderMap, req: Request) -> Response {
1073 let inner = mesh.inner.clone();
1074 let (client, _) = match who(&inner, &headers, peer_of(&req)) {
1075 Ok(x) => x,
1076 Err(r) => return to_response(r),
1077 };
1078 if let Err(r) = admit(&inner, &client, 1) {
1079 return to_response(r);
1080 }
1081 let unknown = || to_response(Reply::json(400, envelope::bad_request(ErrorCode::JobUnknown), Cache::NoStore));
1082 let valid = (32..=64).contains(&id.len()) && id.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b));
1083 if !valid {
1084 return unknown();
1085 }
1086 match inner.jobs.poll(&id) {
1087 Poll::Unknown => unknown(),
1088 Poll::Done(r) => to_response(r),
1089 Poll::Running(request, elapsed) => {
1090 let poll = format!("{}/jobs/{id}", inner.config.origin());
1091 match Pending::new(&id, inner.jobs.estimate(elapsed), &poll, request) {
1092 Ok(p) => to_response(Reply::json(202, envelope::pending(&p), Cache::NoStore)),
1093 Err(_) => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1094 }
1095 }
1096 }
1097}
1098
1099#[utoipa::path(get, path = "/.well-known/datumesh.json", responses((status = 200, description = "The key document", content_type = "application/json"), (status = 404, description = "None stored")))]
1101async fn key_document(State(mesh): State<Mesh>) -> Response {
1102 let m = mesh.clone();
1103 match mesh.inner.pool.run(move || m.key_document()).await.flatten() {
1104 Some(doc) => to_response(Reply::json(200, doc, Cache::Public(300))),
1105 None => not_found("key document"),
1106 }
1107}
1108
1109#[utoipa::path(get, path = "/.well-known/datumesh-mesh.json", responses((status = 200, description = "The mesh document", content_type = "application/json")))]
1111async fn mesh_document(State(mesh): State<Mesh>) -> Response {
1112 to_response(Reply::json(200, mesh.mesh_document(), Cache::Public(300)))
1113}
1114
1115#[utoipa::path(get, path = "/bindings",
1117 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).")),
1118 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")))]
1119async fn bindings(State(mesh): State<Mesh>, uri: Uri, headers: HeaderMap, req: Request) -> Response {
1120 if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
1121 return r;
1122 }
1123 let inner = mesh.inner.clone();
1124 let mut names = Vec::new();
1125 let mut asof = None;
1126 for p in uri.query().unwrap_or("").split('&').filter(|p| !p.is_empty()) {
1127 let (k, v) = p.split_once('=').unwrap_or((p, ""));
1128 let Some(v) = pct_decode(v) else { return batch_error("percent-encoding (SPEC 5.1)") };
1129 match k {
1130 "name" if lexical::check_function_name(&v, "$").is_ok() => names.push(v),
1131 "asof" if lexical::check_instant(&v, "$").is_ok() && asof.is_none() => asof = Some(v),
1132 _ => return batch_error(&format!("parameter {k}")),
1133 }
1134 }
1135 let r = inner
1136 .pool
1137 .clone()
1138 .run(move || {
1139 let at = asof.unwrap_or_else(|| inner.now());
1140 let mut out = Vec::new();
1141 for n in names {
1142 if !inner.config.owns(crate::foreign::host_of(&n)) {
1143 continue;
1144 }
1145 let found = match inner.store.resolve_class_binding(&n, &at) {
1148 Ok(Some(c)) => ("class_hash", c.class_hash, c.tx),
1149 Ok(None) => match inner.store.resolve_binding(&n, &at) {
1150 Ok(Some(b)) => ("fn_hash", b.fn_hash, b.tx),
1151 Ok(None) => continue,
1152 Err(_) => return None,
1153 },
1154 Err(_) => return None,
1155 };
1156 out.push((
1157 n,
1158 Value::Object(vec![
1159 (found.0.into(), Value::String(found.1)),
1160 ("since".into(), Value::String(found.2)),
1161 ]),
1162 ));
1163 }
1164 Some(Value::Object(vec![("asof".into(), Value::String(at)), ("bindings".into(), Value::Object(out))]))
1165 })
1166 .await
1167 .flatten();
1168 match r {
1169 Some(v) => plain_json(200, v, Cache::Public(inner_latest(&mesh))),
1170 None => to_response(envelope::error_reply(ErrorCode::InputUnavailable)),
1171 }
1172}
1173
1174fn inner_latest(mesh: &Mesh) -> u64 {
1175 mesh.inner.config.ttl.latest_max_age.as_secs()
1176}
1177
1178fn pct_decode(s: &str) -> Option<String> {
1181 let b = s.as_bytes();
1182 let mut out = Vec::new();
1183 let mut i = 0;
1184 while i < b.len() {
1185 let c = b[i];
1186 if c == b'%' {
1187 let h = b.get(i + 1..i + 3)?;
1188 if !h.iter().all(|x| x.is_ascii_digit() || (b'A'..=b'F').contains(x)) {
1189 return None;
1190 }
1191 let v = u8::from_str_radix(std::str::from_utf8(h).ok()?, 16).ok()?;
1192 if v.is_ascii_alphanumeric() || matches!(v, b'-' | b'.' | b'_' | b'~' | b':') {
1193 return None;
1194 }
1195 out.push(v);
1196 i += 3;
1197 } else if c.is_ascii_alphanumeric() || matches!(c, b'-' | b'.' | b'_' | b'~' | b':') {
1198 out.push(c);
1199 i += 1;
1200 } else {
1201 return None;
1202 }
1203 }
1204 String::from_utf8(out).ok()
1205}
1206
1207#[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")))]
1209async fn health(State(mesh): State<Mesh>) -> Response {
1210 let m = mesh.clone();
1211 let ok = tokio::time::timeout(
1212 Duration::from_secs(5),
1213 mesh.inner.pool.run(move || m.inner.store.namespace(&m.inner.config.host).is_ok()),
1214 )
1215 .await
1216 .ok()
1217 .flatten()
1218 .unwrap_or(false);
1219 let v = Value::Object(vec![("status".into(), Value::String(if ok { "ok" } else { "store unavailable" }.into()))]);
1220 plain_json(if ok { 200 } else { 503 }, v, Cache::NoStore)
1221}
1222
1223#[utoipa::path(get, path = "/metrics", responses((status = 200, description = "Prometheus text", content_type = "text/plain")))]
1225async fn metrics(State(mesh): State<Mesh>) -> Response {
1226 let mut r = Reply::json(200, metrics_text(&mesh.inner).into_bytes(), Cache::NoStore);
1227 r.content_type = "text/plain; version=0.0.4";
1228 to_response(r)
1229}
1230
1231#[utoipa::path(get, path = "/openapi.json", responses((status = 200, description = "The OpenAPI document", content_type = "application/json")))]
1233async fn openapi_json() -> Response {
1234 let mut r = Reply::json(200, openapi().to_json().unwrap_or_default().into_bytes(), Cache::Public(300));
1235 r.content_type = JSON;
1236 to_response(r)
1237}
1238
1239pub(crate) fn metrics_text(inner: &Inner) -> String {
1240 use std::fmt::Write;
1241 use std::sync::atomic::Ordering::Relaxed;
1242 let mut out = String::new();
1243 inner.metrics.write(&mut out);
1244 let p = &inner.pool;
1245 let g = |out: &mut String, name: &str, help: &str, kind: &str, v: String| {
1246 let _ = writeln!(out, "# HELP {name} {help}\n# TYPE {name} {kind}\n{name} {v}");
1247 };
1248 g(&mut out, "datumesh_pool_size", "The blocking pool's size: the concurrency limit.", "gauge", p.size.to_string());
1249 g(&mut out, "datumesh_pool_in_use", "Pool threads busy now.", "gauge", p.in_use.load(Relaxed).to_string());
1250 g(&mut out, "datumesh_pool_peak", "The most pool threads busy at once.", "gauge", p.peak.load(Relaxed).to_string());
1251 g(&mut out, "datumesh_pool_runs_total", "Tasks run on the pool.", "counter", p.runs.load(Relaxed).to_string());
1252 g(
1253 &mut out,
1254 "datumesh_pool_waited_total",
1255 "Tasks that found the pool saturated and waited for a thread.",
1256 "counter",
1257 p.waited.load(Relaxed).to_string(),
1258 );
1259 let (held, running) = inner.jobs.counts();
1260 g(&mut out, "datumesh_jobs_held", "Jobs held (running or done).", "gauge", held.to_string());
1261 g(&mut out, "datumesh_jobs_running", "Jobs running.", "gauge", running.to_string());
1262 g(
1263 &mut out,
1264 "datumesh_jobs_created_total",
1265 "Requests answered pending.",
1266 "counter",
1267 inner.jobs.created.load(Relaxed).to_string(),
1268 );
1269 g(
1270 &mut out,
1271 "datumesh_rate_limited_total",
1272 "Requests refused by a rate limit.",
1273 "counter",
1274 inner.limiter.refused.load(Relaxed).to_string(),
1275 );
1276 g(
1277 &mut out,
1278 "datumesh_peer_fetches_total",
1279 "Requests to other meshes.",
1280 "counter",
1281 inner.foreign.fetches.load(Relaxed).to_string(),
1282 );
1283 g(
1284 &mut out,
1285 "datumesh_peer_failures_total",
1286 "Requests to other meshes that failed.",
1287 "counter",
1288 inner.foreign.failures.load(Relaxed).to_string(),
1289 );
1290 g(
1291 &mut out,
1292 "datumesh_peer_imported_total",
1293 "Foreign versions imported into the store.",
1294 "counter",
1295 inner.foreign.imported.load(Relaxed).to_string(),
1296 );
1297 let m = inner.engine.memo_stats();
1298 g(&mut out, "datumesh_memo_entries", "Engine memo entries.", "gauge", m.entries.to_string());
1299 g(&mut out, "datumesh_memo_bytes", "Engine memo size, approximately.", "gauge", m.approx_bytes.to_string());
1300 g(
1301 &mut out,
1302 "datumesh_uptime_seconds",
1303 "Seconds since the mesh started.",
1304 "gauge",
1305 inner.started.elapsed().as_secs().to_string(),
1306 );
1307 out
1308}
1309
1310async fn around(State(mesh): State<Mesh>, req: Request, next: Next) -> Response {
1312 let start = Instant::now();
1313 let route = req.extensions().get::<MatchedPath>().map(|m| m.as_str().to_string()).unwrap_or_else(|| "other".into());
1314 let route = match route.as_str() {
1315 "/cell/{*rest}" => "/cell/{cell}".to_string(),
1316 "/slice/{*rest}" => "/slice/{cell}".to_string(),
1317 "/explain/{*rest}" => "/explain/{cell}".to_string(),
1318 "/versions/{*rest}" => "/versions/{cell}".to_string(),
1319 "/fn/{*name}" => "/fn/{name}".to_string(),
1320 "/takeover/{*domain}" => "/takeover/{domain}".to_string(),
1321 "/series/{*rest}" => "/series/{page}".to_string(),
1322 "/x/interval/{*function}" => "/x/interval/{function}".to_string(),
1323 _ => route,
1324 };
1325 let id = req
1326 .headers()
1327 .get("x-request-id")
1328 .and_then(|v| v.to_str().ok())
1329 .filter(|s| !s.is_empty() && s.len() <= 64 && s.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-'))
1330 .map(str::to_string)
1331 .unwrap_or_else(|| {
1332 let mut b = [0u8; 8];
1333 let _ = getrandom::fill(&mut b);
1334 lexical::to_hex(&b)
1335 });
1336 let ip = client_ip(&mesh.inner, req.headers(), peer_of(&req));
1337 let method = req.method().clone();
1338 let also = if route == "/slice/{cell}" { Some(crate::slice::ARROW) } else { None };
1339 let html_ok = (route == "/fn/{name}" || route == "/takeover/{domain}") && accepts(req.headers(), "text/html");
1341 let own_form = matches!(route.as_str(), "/series/{page}" | "/series/sitemap.xml" | "/x/interval/{function}")
1344 || (route == "/slice/{cell}"
1345 && crate::series::negotiation_free(&mesh.inner, &rest_of(req.uri(), "/slice/"), req.headers()));
1346 let mut resp = if route != "/blob/{sha256}"
1347 && route != "/metrics"
1348 && !html_ok
1349 && !own_form
1350 && !acceptable(req.headers(), also)
1351 {
1352 not_acceptable()
1353 } else {
1354 next.run(req).instrument(tracing::info_span!("request", request_id = %id)).await
1355 };
1356 let elapsed = start.elapsed();
1357 let status = resp.status().as_u16();
1358 mesh.inner.metrics.record(&route, status, elapsed);
1359 let principal = resp.extensions().get::<Who>().and_then(|w| w.0.clone());
1360 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");
1361 if let Ok(v) = HeaderValue::from_str(&id) {
1362 resp.headers_mut().insert("x-request-id", v);
1363 }
1364 resp.headers_mut().insert(header::VARY, HeaderValue::from_static("Accept, Accept-Encoding, Authorization"));
1365 if let Ok(v) = HeaderValue::from_str(&format!("app;dur={:.3}", elapsed.as_secs_f64() * 1000.0)) {
1366 resp.headers_mut().insert("server-timing", v);
1367 }
1368 resp
1369}
1370
1371#[utoipa::path(post, path = "/whatif",
1377 request_body(content = String, description = "The JSON of 5.9: `cell`, `asof`?, `overrides`, `solve`?", content_type = "application/json"),
1378 responses(
1379 (status = 200, description = "`scenario`: `{asof, cell, overrides, type, value[, solved]}`, no receipt", content_type = "application/json"),
1380 (status = 400, description = "`bad_request`", content_type = "application/json"),
1381 (status = 404, description = "`not_covered`, with `fault` when the scenario faulted or has no solution", content_type = "application/json"),
1382 (status = 500, description = "`error`", content_type = "application/json"),
1383 ))]
1384async fn whatif(State(mesh): State<Mesh>, headers: HeaderMap, req: Request) -> Response {
1385 let inner = mesh.inner.clone();
1386 let peer = peer_of(&req);
1387 let (client, principal) = match who(&inner, &headers, peer) {
1388 Ok(x) => x,
1389 Err(r) => return to_response(r),
1390 };
1391 if let Err(r) = admit(&inner, &client, 1) {
1392 return to_response(r);
1393 }
1394 let body = match axum::body::to_bytes(req.into_body(), 1 << 20).await {
1395 Ok(b) => b,
1396 Err(_) => return to_response(envelope::bad_request_reply(ErrorCode::CanonLimit)),
1397 };
1398 let mesh2 = mesh.clone();
1399 match inner.pool.clone().run(move || mesh2.whatif(&body, principal.as_ref())).await {
1400 Some(r) => to_response(r),
1401 None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1402 }
1403}
1404
1405#[utoipa::path(post, path = "/x/calc",
1409 request_body(content = String, description = "`{\"formula\": <body>, \"asof\"?: <instant>}`; the body is at most 4096 bytes", content_type = "application/json"),
1410 responses(
1411 (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"),
1412 (status = 400, description = "`bad_request`, with the code (a request code, or a formula's `E_FORMULA_*`)", content_type = "application/json"),
1413 (status = 404, description = "`not_covered`, with `fault` when the calculation faulted", content_type = "application/json"),
1414 (status = 413, description = "`E_TOO_LARGE`: the formula is more than 4096 bytes", content_type = "application/json"),
1415 (status = 429, description = "`rate_limited`", content_type = "application/json"),
1416 (status = 500, description = "`error`", content_type = "application/json"),
1417 (status = 503, description = "`error` with `E_EVAL_BUDGET` (the mesh's budget ran out; no job) or `E_EVAL_UNAVAILABLE`", content_type = "application/json"),
1418 ))]
1419async fn x_calc(State(mesh): State<Mesh>, headers: HeaderMap, req: Request) -> Response {
1420 let inner = mesh.inner.clone();
1421 let peer = peer_of(&req);
1422 let (client, principal) = match who(&inner, &headers, peer) {
1423 Ok(x) => x,
1424 Err(r) => return to_response(r),
1425 };
1426 if let Err(r) = admit(&inner, &client, 1) {
1427 return to_response(r);
1428 }
1429 if let Err(s) = inner.limiter.admit_calc(client_ip(&inner, &headers, peer)) {
1430 return to_response(envelope::rate_limited_reply(s));
1431 }
1432 let body = match axum::body::to_bytes(req.into_body(), 64 << 10).await {
1434 Ok(b) => b,
1435 Err(_) => return to_response(crate::calc::too_large_reply()),
1436 };
1437 let mesh2 = mesh.clone();
1438 match inner.pool.clone().run(move || mesh2.calc(&body, principal.as_ref())).await {
1439 Some(r) => to_response(r),
1440 None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1441 }
1442}
1443
1444#[utoipa::path(get, path = "/x/keys/challenge",
1447 responses(
1448 (status = 200, description = "`{\"challenge\", \"expires\"}`, no-store", content_type = "application/json"),
1449 (status = 404, description = "Key-derived names are off on this mesh", content_type = "application/json"),
1450 (status = 429, description = "`rate_limited`, with `Retry-After`", content_type = "application/json")))]
1451async fn x_keys_challenge(State(mesh): State<Mesh>, headers: HeaderMap, req: Request) -> Response {
1452 if !mesh.inner.config.key_names {
1453 return not_found("endpoint");
1454 }
1455 if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
1456 return r;
1457 }
1458 let inner = mesh.inner.clone();
1459 match inner.pool.clone().run(move || crate::keynames::challenge(&inner)).await {
1460 Some(r) => to_response(r),
1461 None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1462 }
1463}
1464
1465#[utoipa::path(post, path = "/x/keys",
1469 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"),
1470 responses(
1471 (status = 201, description = "`{\"namespace\", \"key_id\"}`: the key is added to the key document", content_type = "application/json"),
1472 (status = 200, description = "The same body: the key was registered before", content_type = "application/json"),
1473 (status = 400, description = "`E_KEY_MALFORMED`, or `E_CHALLENGE` (unknown, expired or used)", content_type = "application/json"),
1474 (status = 403, description = "`E_KEY_SIGNATURE`", content_type = "application/json"),
1475 (status = 404, description = "Key-derived names are off on this mesh", content_type = "application/json"),
1476 (status = 429, description = "`rate_limited`, with `Retry-After` (`DATUMESH_RATE_KEYS_PER_IP`)", content_type = "application/json")))]
1477async fn x_keys(State(mesh): State<Mesh>, headers: HeaderMap, req: Request) -> Response {
1478 let inner = mesh.inner.clone();
1479 if !inner.config.key_names {
1480 return not_found("endpoint");
1481 }
1482 if let Some(r) = ip_admit(&inner, &headers, &req) {
1483 return r;
1484 }
1485 let ip = client_ip(&inner, &headers, peer_of(&req));
1486 if let Err(s) = inner.limiter.admit_keys(ip) {
1487 return to_response(crate::keynames::rate_limited(s));
1488 }
1489 let body = axum::body::to_bytes(req.into_body(), crate::keynames::MAX_BODY).await.unwrap_or_default();
1491 let i2 = inner.clone();
1492 match inner
1493 .pool
1494 .clone()
1495 .run(move || match crate::keynames::parse(&body) {
1496 Ok(p) => crate::keynames::register(&i2, &p),
1497 Err(detail) => crate::keynames::refuse(400, "E_KEY_MALFORMED", &detail),
1498 })
1499 .await
1500 {
1501 Some(r) => to_response(r),
1502 None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1503 }
1504}
1505
1506#[utoipa::path(get, path = "/describe/{id}",
1507 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).")),
1508 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")))]
1509async fn describe(State(mesh): State<Mesh>, uri: Uri, headers: HeaderMap, req: Request) -> Response {
1510 if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
1511 return r;
1512 }
1513 let Some(id) = crate::call::url_decode(uri.path().strip_prefix("/describe/").unwrap_or("")) else {
1514 return to_response(envelope::bad_request_reply(ErrorCode::CanonPercent));
1515 };
1516 let inner = mesh.inner.clone();
1517 match inner.pool.clone().run(move || mesh.describe(&id)).await {
1518 Some(r) => {
1519 let link = function_describe_link(&inner, &r);
1522 let mut resp = to_response(r);
1523 if let Some(v) = link.and_then(|l| HeaderValue::from_str(&l).ok()) {
1524 resp.headers_mut().insert(header::LINK, v);
1525 }
1526 resp
1527 }
1528 None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1529 }
1530}
1531
1532fn function_describe_link(inner: &Inner, r: &Reply) -> Option<String> {
1534 if r.status != 200 {
1535 return None;
1536 }
1537 let v = json::parse(&r.body).ok()?;
1538 if v.get("kind")?.as_str()? != "function" {
1539 return None;
1540 }
1541 let name = v.get("fn")?.as_str()?;
1542 Some(format!("<{}>; rel=\"describedby\"", crate::fnpage::page_url(inner, name)))
1543}
1544
1545async fn bundles(State(mesh): State<Mesh>, req: Request) -> Response {
1547 to_response(crate::bundles::post(mesh.inner.clone(), req.into_body()).await)
1548}
1549
1550async fn function_page(
1553 State(mesh): State<Mesh>,
1554 Path(name): Path<String>,
1555 uri: Uri,
1556 headers: HeaderMap,
1557 req: Request,
1558) -> Response {
1559 if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
1560 return r;
1561 }
1562 let format_json = uri.query().is_some_and(|q| q.split('&').any(|p| p == "format=json"));
1563 let json_form = format_json || (accepts(&headers, JSON) && !accepts(&headers, "text/html"));
1564 let inner = mesh.inner.clone();
1565 match inner.pool.clone().run(move || crate::fnpage::respond(&mesh.inner, &name, json_form)).await {
1566 Some(r) => to_response(r),
1567 None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1568 }
1569}
1570
1571#[utoipa::path(get, path = "/takeover/{domain}",
1574 params(("domain" = String, Path, description = "The source's DNS name (SPEC 2.1)")),
1575 responses(
1576 (status = 200, description = "`{\"domain\", \"host\", \"functions\": [{\"name\", \"page\", \"fn_hash\"}], \"steps\": [...]}`, or the HTML page", content_type = "application/json"),
1577 (status = 400, description = "E_CANON_NAME: not a DNS name", content_type = "application/json"),
1578 (status = 404, description = "not_covered: no function relayed from the domain on this mesh", content_type = "application/json")))]
1579async fn takeover_page(
1580 State(mesh): State<Mesh>,
1581 Path(domain): Path<String>,
1582 uri: Uri,
1583 headers: HeaderMap,
1584 req: Request,
1585) -> Response {
1586 if let Some(r) = ip_admit(&mesh.inner, &headers, &req) {
1587 return r;
1588 }
1589 let format_json = uri.query().is_some_and(|q| q.split('&').any(|p| p == "format=json"));
1590 let json_form = format_json || (accepts(&headers, JSON) && !accepts(&headers, "text/html"));
1591 let inner = mesh.inner.clone();
1592 match inner.pool.clone().run(move || crate::takeover::respond(&mesh.inner, &domain, json_form)).await {
1593 Some(r) => to_response(r),
1594 None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1595 }
1596}
1597
1598fn series_admit(inner: &Inner, headers: &HeaderMap, req: &Request) -> Option<Response> {
1600 let peer = peer_of(req);
1601 let client = match who(inner, headers, peer) {
1602 Ok((c, _)) => c,
1603 Err(r) => return Some(to_response(r)),
1604 };
1605 if let Err(r) = admit(inner, &client, 1) {
1606 return Some(to_response(r));
1607 }
1608 let ip = client_ip(inner, headers, peer);
1609 inner.limiter.admit_series(ip).err().map(|s| to_response(envelope::rate_limited_reply(s)))
1610}
1611
1612fn series_response(o: crate::series::Out) -> Response {
1614 let mut resp = Response::new(Body::from(o.body));
1615 *resp.status_mut() = StatusCode::from_u16(o.status).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR);
1616 let h = resp.headers_mut();
1617 h.insert(header::CONTENT_TYPE, HeaderValue::from_static(o.content_type));
1618 if let Ok(v) = HeaderValue::from_str(&o.cache) {
1619 h.insert(header::CACHE_CONTROL, v);
1620 }
1621 if let Some(e) = o.etag.as_deref().and_then(|e| HeaderValue::from_str(e).ok()) {
1622 h.insert(header::ETAG, e);
1623 }
1624 if let Some(s) = o.retry_after {
1625 h.insert(header::RETRY_AFTER, HeaderValue::from(s));
1626 }
1627 resp
1628}
1629
1630async fn series_answer(mesh: Mesh, headers: &HeaderMap, rest: String) -> Response {
1631 let inm = headers.get(header::IF_NONE_MATCH).and_then(|v| v.to_str().ok()).map(str::to_string);
1632 let inner = mesh.inner.clone();
1633 match inner.pool.clone().run(move || crate::series::respond(&mesh.inner, &rest, inm.as_deref())).await {
1634 Some(o) => series_response(o),
1635 None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1636 }
1637}
1638
1639#[utoipa::path(get, path = "/series/{page}",
1642 params(("page" = String, Path, description = "The series' function name, then `/YYYY-MM`, `/YYYY` (each with an optional `.csv`) or `/` for the index")),
1643 responses(
1644 (status = 200, description = "The page (HTML with a JSON-LD dataset), its CSV (`text/csv`), or the index", content_type = "text/html"),
1645 (status = 304, description = "`ETag` unchanged"),
1646 (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"),
1647 (status = 429, description = "`rate_limited`, with `Retry-After` (the per-IP and the series budgets)", content_type = "application/json"),
1648 ))]
1649async fn series_page(State(mesh): State<Mesh>, uri: Uri, headers: HeaderMap, req: Request) -> Response {
1650 if let Some(r) = series_admit(&mesh.inner, &headers, &req) {
1651 return r;
1652 }
1653 let rest = uri.path().strip_prefix("/series/").unwrap_or("").to_string();
1654 series_answer(mesh, &headers, rest).await
1655}
1656
1657#[utoipa::path(get, path = "/series/sitemap.xml",
1660 responses(
1661 (status = 200, description = "A sitemap (`application/xml`) or a sitemap index", content_type = "application/xml"),
1662 (status = 404, description = "No series file: no pages", content_type = "text/html"),
1663 (status = 429, description = "`rate_limited`, with `Retry-After`", content_type = "application/json"),
1664 ))]
1665async fn series_sitemap(State(mesh): State<Mesh>, headers: HeaderMap, req: Request) -> Response {
1666 if let Some(r) = series_admit(&mesh.inner, &headers, &req) {
1667 return r;
1668 }
1669 series_answer(mesh, &headers, "sitemap.xml".to_string()).await
1670}
1671
1672#[utoipa::path(get, path = "/x/interval/{function}",
1675 params(
1676 ("function" = String, Path, description = "The function name of a series listed in the series file"),
1677 ("from" = String, Query, description = "The first date, `YYYY-MM-DD`, inclusive"),
1678 ("to" = String, Query, description = "The last date, `YYYY-MM-DD`, inclusive; at most 10 years after `from` for a series with month pages"),
1679 ("format" = Option<String>, Query, description = "`csv` or `arrow`; JSON without it. Each is an address of its own"),
1680 ),
1681 responses(
1682 (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"),
1683 (status = 304, description = "`ETag` unchanged"),
1684 (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"),
1685 (status = 404, description = "The function is not in the series file", content_type = "application/json"),
1686 (status = 429, description = "`rate_limited`, with `Retry-After` (the per-IP and the series budgets)", content_type = "application/json"),
1687 ))]
1688async fn x_interval(State(mesh): State<Mesh>, uri: Uri, headers: HeaderMap, req: Request) -> Response {
1689 if let Some(r) = series_admit(&mesh.inner, &headers, &req) {
1690 return r;
1691 }
1692 let function = uri.path().strip_prefix("/x/interval/").unwrap_or("").to_string();
1693 let query = uri.query().unwrap_or("").to_string();
1694 let inm = headers.get(header::IF_NONE_MATCH).and_then(|v| v.to_str().ok()).map(str::to_string);
1695 let inner = mesh.inner.clone();
1696 match inner.pool.clone().run(move || crate::series::interval(&mesh.inner, &function, &query, inm.as_deref())).await
1697 {
1698 Some(o) => series_response(o),
1699 None => to_response(envelope::error_reply(ErrorCode::EvalUnavailable)),
1700 }
1701}
1702
1703async fn fallback() -> Response {
1704 not_found("endpoint")
1705}
1706
1707impl Mesh {
1708 pub fn router(&self) -> Router {
1711 Router::new()
1712 .route("/cell/{*rest}", get(cell))
1713 .route("/cells", post(cells))
1714 .route("/slice/{*rest}", get(slice))
1715 .route("/receipt/{hash}", get(receipt))
1716 .route("/descriptor/{hash}", get(descriptor))
1717 .route("/manifest/{slice_id}/{members_hash}", get(manifest))
1718 .route("/versions/{*rest}", get(versions))
1719 .route("/blob/{sha256}", get(blob))
1720 .route("/explain/{*rest}", get(explain))
1721 .route("/find", get(find))
1722 .route("/verify", post(verify_receipt))
1723 .route("/jobs/{job}", get(job))
1724 .route("/.well-known/datumesh.json", get(key_document))
1725 .route("/.well-known/datumesh-mesh.json", get(mesh_document))
1726 .route("/bindings", get(bindings))
1727 .route("/describe/{*id}", get(describe))
1728 .route("/fn/{*name}", get(function_page))
1729 .route("/takeover/{*domain}", get(takeover_page))
1730 .route("/series/sitemap.xml", get(series_sitemap))
1731 .route("/series/{*rest}", get(series_page))
1732 .route("/bundles", post(bundles))
1733 .route("/whatif", post(whatif))
1734 .route("/x/calc", post(x_calc))
1735 .route("/x/keys/challenge", get(x_keys_challenge))
1736 .route("/x/keys", post(x_keys))
1737 .route("/x/interval/{*function}", get(x_interval))
1738 .route("/health", get(health))
1739 .route("/metrics", get(metrics))
1740 .route("/openapi.json", get(openapi_json))
1741 .fallback(fallback)
1742 .layer(middleware::from_fn_with_state(self.clone(), around))
1743 .layer(tower_http::compression::CompressionLayer::new().gzip(true))
1744 .with_state(self.clone())
1745 }
1746
1747 pub async fn serve(
1749 &self,
1750 listener: tokio::net::TcpListener,
1751 shutdown: impl std::future::Future<Output = ()> + Send + 'static,
1752 ) -> std::io::Result<()> {
1753 axum::serve(listener, self.router().into_make_service_with_connect_info::<SocketAddr>())
1754 .with_graceful_shutdown(shutdown)
1755 .await
1756 }
1757}
1758
1759impl IntoResponse for Reply {
1760 fn into_response(self) -> Response {
1761 to_response(self)
1762 }
1763}
1764
1765#[cfg(test)]
1766mod tests {
1767 use super::*;
1768
1769 fn reply(status: u16, body: &str) -> Reply {
1770 Reply::json(status, body.as_bytes().to_vec(), Cache::NoStore)
1771 }
1772
1773 #[test]
1776 fn runs_make_the_batch() {
1777 let h = "a".repeat(64);
1778 let replies = [
1779 reply(200, &format!(r#"{{"fn_hash":"{h}","outcome":"ok","receipt":{{"value":"1"}},"trust":"primary"}}"#)),
1780 reply(400, r#"{"error":"E_CANON_NUMBER","outcome":"bad_request"}"#),
1781 reply(
1782 200,
1783 &format!(r#"{{"age_seconds":3,"fn_hash":"{h}","outcome":"stale","receipt":{{}},"trust":"computed"}}"#),
1784 ),
1785 reply(404, r#"{"error":"E_NAME_UNBOUND","outcome":"not_covered"}"#),
1786 reply(200, &format!(r#"{{"fn_hash":"{h}","outcome":"ok","receipt":{{"value":"2"}},"trust":"primary"}}"#)),
1787 ];
1788 let mut want = b"[".to_vec();
1789 for (i, r) in replies.iter().enumerate() {
1790 if i > 0 {
1791 want.push(b',');
1792 }
1793 want.extend_from_slice(b"{\"envelope\":");
1794 want.extend_from_slice(&r.body);
1795 want.extend_from_slice(format!(",\"status\":{}}}", r.status).as_bytes());
1796 }
1797 want.push(b']');
1798 for split in 1..replies.len() {
1799 let runs = [Written::of(true, replies[..split].iter()), Written::of(false, replies[split..].iter())];
1800 let mut got: Vec<u8> = runs.iter().flat_map(|w| w.bytes.iter().copied()).collect();
1801 got.push(b']');
1802 assert_eq!(String::from_utf8(got).unwrap(), String::from_utf8(want.clone()).unwrap());
1803 let mut counts = std::collections::BTreeMap::new();
1804 for (o, k) in runs.iter().flat_map(|w| w.outcomes.iter()) {
1805 *counts.entry(o.as_str()).or_insert(0) += k;
1806 }
1807 let want_counts: std::collections::BTreeMap<&str, u64> =
1808 [("bad_request", 1), ("not_covered", 1), ("ok", 2), ("stale", 1)].into_iter().collect();
1809 assert_eq!(counts, want_counts);
1810 }
1811 for (n, s) in [(0u16, "0"), (7, "7"), (200, "200"), (404, "404"), (65535, "65535")] {
1812 let mut out = Vec::new();
1813 push_u16(&mut out, n);
1814 assert_eq!(out, s.as_bytes());
1815 }
1816 }
1817
1818 #[test]
1820 fn outcomes() {
1821 let h = "0".repeat(64);
1822 for (body, want) in [
1823 (format!(r#"{{"fn_hash":"{h}","outcome":"ok","receipt":{{"outcome":"x"}}}}"#), Some("ok")),
1824 (r#"{"age_seconds":12,"outcome":"stale"}"#.to_string(), Some("stale")),
1825 (r#"{"error":"E_PARSE_URI","outcome":"bad_request"}"#.to_string(), Some("bad_request")),
1826 (r#"{"outcome":"pending","poll":"https://a.example/jobs/1"}"#.to_string(), Some("pending")),
1827 (r#"{"error":"no such endpoint"}"#.to_string(), None),
1828 (r#"{"outcome""#.to_string(), None),
1829 ] {
1830 assert_eq!(reply(200, &body).outcome_str(), want, "{body}");
1831 assert_eq!(reply(200, &body).outcome(), want.map(str::to_string), "{body}");
1832 }
1833 let mut arrow = reply(200, r#"{"outcome":"ok"}"#);
1834 arrow.content_type = "application/vnd.apache.arrow.stream";
1835 assert_eq!(arrow.outcome(), None);
1836 }
1837}