Skip to main content

datumesh_http/
mesh.rs

1//! [`Mesh`]: the engine, its store and everything the endpoints share; the blocking
2//! operations each endpoint is built on, usable as library calls.
3
4use std::collections::{BTreeMap, HashMap};
5use std::path::PathBuf;
6use std::sync::{Arc, Mutex, RwLock};
7use std::time::{Duration, Instant};
8
9use datumesh_core::json::{self, Value};
10use datumesh_core::{keys_from_response, verify, ErrorCode, FunctionDescriptor, KeyDoc, Keys, Receipt, SigningKey};
11use datumesh_engine::{Answer, Clock, Engine, EngineError, Runtime, SystemClock};
12use datumesh_formula::runtime::FormulaRuntime;
13use datumesh_store::Store;
14
15use crate::apikeys::Principal;
16use crate::call::{self, Bindings, Bound, Rejection, Target};
17use crate::config::{Config, ConfigError, Rule};
18use crate::envelope::{self, Cache, Reply};
19use crate::foreign::{host_of, CrossMesh, Foreign, ForeignError, KeyCache};
20use crate::jobs::Jobs;
21use crate::limit::Limiter;
22use crate::metrics::Metrics;
23use crate::pool::Pool;
24
25/// Why a mesh could not be built.
26#[derive(Debug)]
27#[non_exhaustive]
28pub enum BuildError {
29    /// The configuration.
30    Config(ConfigError),
31    /// The engine's configuration (the key, its publication in the store, the runtimes).
32    Engine(datumesh_engine::ConfigError),
33    /// The base URL ([`Config::base_url`]). Since 0.2.0.
34    BaseUrl(crate::config::BaseUrlError),
35}
36
37impl std::fmt::Display for BuildError {
38    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
39        match self {
40            BuildError::Config(e) => write!(f, "{e}"),
41            BuildError::Engine(e) => write!(f, "engine: {e}"),
42            BuildError::BaseUrl(e) => write!(f, "configuration: base URL: {e}"),
43        }
44    }
45}
46
47impl std::error::Error for BuildError {}
48
49/// Builds a [`Mesh`].
50pub struct MeshBuilder {
51    config: Config,
52    store: Arc<dyn Store + Send + Sync>,
53    key: Option<SigningKey>,
54    key_file: Option<PathBuf>,
55    runtimes: Vec<Arc<dyn Runtime>>,
56    formula: bool,
57    clock: Arc<dyn Clock>,
58    fuel: Option<u64>,
59    licence: Option<String>,
60    memo_capacity: Option<usize>,
61}
62
63impl std::fmt::Debug for MeshBuilder {
64    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
65        f.debug_struct("MeshBuilder").field("host", &self.config.host).finish_non_exhaustive()
66    }
67}
68
69impl MeshBuilder {
70    /// The mesh's signing key.
71    pub fn signing_key(mut self, key: SigningKey) -> Self {
72        self.key = Some(key);
73        self.key_file = None;
74        self
75    }
76
77    /// The mesh's signing key, from a file of its 32-byte seed (32 bytes or 64 hex digits),
78    /// which must have mode 0600.
79    pub fn signing_key_file(mut self, path: impl Into<PathBuf>) -> Self {
80        self.key_file = Some(path.into());
81        self.key = None;
82        self
83    }
84
85    /// Adds a runtime (the formula runtime is added unless [`MeshBuilder::without_formula`]).
86    pub fn runtime(mut self, runtime: Arc<dyn Runtime>) -> Self {
87        self.runtimes.push(runtime);
88        self
89    }
90
91    /// No formula runtime.
92    pub fn without_formula(mut self) -> Self {
93        self.formula = false;
94        self
95    }
96
97    /// The clock (default: the system clock).
98    pub fn clock(mut self, clock: Arc<dyn Clock>) -> Self {
99        self.clock = clock;
100        self
101    }
102
103    /// The engine's fuel per request.
104    pub fn fuel(mut self, fuel: u64) -> Self {
105        self.fuel = Some(fuel);
106        self
107    }
108
109    /// The licence of the receipts the engine signs.
110    pub fn licence(mut self, licence: impl Into<String>) -> Self {
111        self.licence = Some(licence.into());
112        self
113    }
114
115    /// The engine's memo capacity.
116    pub fn memo_capacity(mut self, n: usize) -> Self {
117        self.memo_capacity = Some(n);
118        self
119    }
120
121    /// Checks the configuration, builds the engine (its key must be published in the store's
122    /// namespace record for the host) and the mesh.
123    pub fn build(self) -> Result<Mesh, BuildError> {
124        if let Some(u) = &self.config.base_url {
125            crate::config::check_base_url(&self.config.host, u).map_err(BuildError::BaseUrl)?;
126        }
127        self.config.check().map_err(BuildError::Config)?;
128        let keys = Arc::new(KeyCache::default());
129        let foreign = Arc::new(Foreign::new(&self.config, self.store.clone(), keys.clone(), self.clock.clone()));
130        let mut b = Engine::builder(self.store.clone(), self.config.host.clone()).clock(self.clock.clone());
131        b = match (self.key, &self.key_file) {
132            (Some(k), _) => b.signing_key(k),
133            (None, Some(p)) => {
134                crate::config::read_secret_file(p).map_err(BuildError::Config)?;
135                b.signing_key_file(p.clone())
136            }
137            (None, None) => b,
138        };
139        let mut runtimes = self.runtimes;
140        if self.formula {
141            runtimes.push(Arc::new(FormulaRuntime::new(self.store.clone())));
142        }
143        for rt in runtimes {
144            b = b.runtime(Arc::new(CrossMesh::new(rt, foreign.clone())));
145        }
146        if let Some(f) = self.fuel {
147            b = b.fuel(f);
148        }
149        if let Some(l) = self.licence {
150            b = b.licence(l);
151        }
152        if let Some(n) = self.memo_capacity {
153            b = b.memo_capacity(n);
154        }
155        let engine = b.build().map_err(BuildError::Engine)?;
156        let config = self.config;
157        let inner = Inner {
158            pool: Arc::new(Pool::new(config.pool_size)),
159            jobs: Jobs::new(config.ttl.job, config.max_jobs),
160            limiter: Limiter::new(config.rate.clone()),
161            metrics: Metrics::default(),
162            engine: Arc::new(engine),
163            store: self.store,
164            clock: self.clock,
165            keys,
166            foreign,
167            descriptors: Mutex::new(HashMap::new()),
168            last_good: Mutex::new(HashMap::new()),
169            infos: (0..32).map(|_| Mutex::new(HashMap::new())).collect(),
170            by_hash: (0..32).map(|_| Mutex::new(HashMap::new())).collect(),
171            latest: Latest::new(),
172            targets: Targets::new(),
173            slices: Mutex::new(Vec::new()),
174            known: Mutex::new(crate::describe::Index::default()),
175            started: Instant::now(),
176            config,
177        };
178        Ok(Mesh { inner: Arc::new(inner) })
179    }
180}
181
182/// The last `ok` receipt served for a cell, for `stale` answers.
183struct LastGood {
184    info: Arc<ReceiptInfo>,
185    at: Instant,
186}
187
188/// What the mesh needs of a receipt it serves, kept by its bytes (content-addressed: never
189/// stale): its hash, `asof`, trust and its `ok` envelope.
190pub(crate) struct ReceiptInfo {
191    pub(crate) hash: String,
192    pub(crate) asof: String,
193    pub(crate) receipt: Vec<u8>,
194    pub(crate) parsed: Receipt,
195    pub(crate) trust: datumesh_core::TrustLabel,
196    /// The `ok` envelope, the function hash echoed.
197    pub(crate) ok: crate::envelope::Bytes,
198}
199
200pub(crate) struct Inner {
201    pub(crate) config: Config,
202    pub(crate) store: Arc<dyn Store + Send + Sync>,
203    pub(crate) engine: Arc<Engine>,
204    pub(crate) clock: Arc<dyn Clock>,
205    pub(crate) pool: Arc<Pool>,
206    pub(crate) jobs: Jobs,
207    pub(crate) limiter: Limiter,
208    pub(crate) metrics: Metrics,
209    pub(crate) keys: Arc<KeyCache>,
210    pub(crate) foreign: Arc<Foreign>,
211    descriptors: Mutex<HashMap<String, Arc<FunctionDescriptor>>>,
212    last_good: Mutex<HashMap<String, LastGood>>,
213    infos: Vec<Mutex<HashMap<u64, Arc<ReceiptInfo>>>>,
214    by_hash: Vec<Mutex<HashMap<String, Arc<ReceiptInfo>>>>,
215    latest: Latest,
216    targets: Targets,
217    #[allow(clippy::type_complexity)]
218    pub(crate) slices: Mutex<Vec<(String, String, Arc<Vec<datumesh_store::SliceValue>>)>>,
219    /// The index of the objects the mesh knows (describe, short ids).
220    pub(crate) known: Mutex<crate::describe::Index>,
221    pub(crate) started: Instant,
222}
223
224/// A Datumesh mesh: the engine behind the endpoints. Cheap to clone (shared).
225#[derive(Clone)]
226pub struct Mesh {
227    pub(crate) inner: Arc<Inner>,
228}
229
230impl std::fmt::Debug for Mesh {
231    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
232        f.debug_struct("Mesh").field("host", &self.inner.config.host).finish_non_exhaustive()
233    }
234}
235
236/// Bindings looked up once per name and asof within one batch.
237pub(crate) struct Memo<'a> {
238    inner: &'a Inner,
239    seen: std::borrow::Cow<'a, Seen>,
240}
241
242/// A binding a batch looks up: the lookup's result once one succeeded, and the lock held
243/// during a lookup, so the batch's chunks, which start together and ask for the same names,
244/// make one store round trip per name and asof, not one each.
245#[derive(Default)]
246struct SeenEntry {
247    found: std::sync::OnceLock<Option<Arc<Bound>>>,
248    lookup: Mutex<()>,
249}
250
251/// The bindings a batch has looked up (shared by its chunks), by name, then asof.
252#[derive(Default)]
253pub(crate) struct Seen(RwLock<HashMap<String, SeenAsofs>>);
254
255/// A name's entries in [`Seen`], by asof.
256type SeenAsofs = Vec<(String, Arc<SeenEntry>)>;
257
258impl Clone for Seen {
259    fn clone(&self) -> Seen {
260        let m = self.0.read().unwrap_or_else(|p| p.into_inner());
261        let copy = m
262            .iter()
263            .map(|(name, v)| {
264                let v = v
265                    .iter()
266                    .map(|(a, e)| (a.clone(), Arc::new(SeenEntry { found: e.found.clone(), lookup: Mutex::new(()) })))
267                    .collect();
268                (name.clone(), v)
269            })
270            .collect();
271        Seen(RwLock::new(copy))
272    }
273}
274
275/// What [`Seen`] has of a name as of an asof.
276enum Held {
277    Found(Option<Arc<Bound>>),
278    Entry(Arc<SeenEntry>),
279    Full,
280}
281
282impl Seen {
283    /// The binding of `fn_name` as of `asof` if found, else its entry (made if there is room:
284    /// 64 asofs per name).
285    fn held(&self, fn_name: &str, asof: &str) -> Held {
286        if let Some(v) = self.0.read().unwrap_or_else(|p| p.into_inner()).get(fn_name) {
287            if let Some((_, e)) = v.iter().find(|(a, _)| a == asof) {
288                return match e.found.get() {
289                    Some(b) => Held::Found(b.clone()),
290                    None => Held::Entry(e.clone()),
291                };
292            }
293        }
294        let mut m = self.0.write().unwrap_or_else(|p| p.into_inner());
295        let v = m.entry(fn_name.to_string()).or_default();
296        if let Some((_, e)) = v.iter().find(|(a, _)| a == asof) {
297            return Held::Entry(e.clone());
298        }
299        if v.len() >= 64 {
300            return Held::Full;
301        }
302        let e = Arc::new(SeenEntry::default());
303        v.push((asof.to_string(), e.clone()));
304        Held::Entry(e)
305    }
306
307    /// The binding of `fn_name` as of `asof`: as found before, else looked up by `look`, at
308    /// most one lookup at a time per name and asof (the others wait for its result). A failed
309    /// lookup is not kept: the next request looks the name up again.
310    pub(crate) fn lookup(
311        &self,
312        fn_name: &str,
313        asof: &str,
314        look: impl FnOnce() -> Result<Option<Arc<Bound>>, ErrorCode>,
315    ) -> Result<Option<Arc<Bound>>, ErrorCode> {
316        let e = match self.held(fn_name, asof) {
317            Held::Found(b) => return Ok(b),
318            Held::Full => return look(),
319            Held::Entry(e) => e,
320        };
321        let _looking = e.lookup.lock().unwrap_or_else(|p| p.into_inner());
322        if let Some(b) = e.found.get() {
323            return Ok(b.clone());
324        }
325        let b = look()?;
326        let _ = e.found.set(b.clone());
327        Ok(b)
328    }
329}
330
331impl<'a> Memo<'a> {
332    pub(crate) fn new(inner: &'a Inner) -> Memo<'a> {
333        Memo { inner, seen: std::borrow::Cow::Owned(Seen::default()) }
334    }
335
336    pub(crate) fn shared(inner: &'a Inner, seen: &'a Seen) -> Memo<'a> {
337        Memo { inner, seen: std::borrow::Cow::Borrowed(seen) }
338    }
339}
340
341impl Bindings for Memo<'_> {
342    fn pinned(&self, fn_hash: &str) -> Result<Option<Arc<Bound>>, ErrorCode> {
343        Bindings::pinned(self.inner, fn_hash)
344    }
345
346    fn alias(&self, alias: &str) -> Option<String> {
347        Bindings::alias(self.inner, alias)
348    }
349
350    fn class(&self, name: &str, asof: &str) -> Result<Option<Arc<call::BoundClass>>, ErrorCode> {
351        Bindings::class(self.inner, name, asof)
352    }
353
354    fn aliases_tx(&self) -> Option<String> {
355        Bindings::aliases_tx(self.inner)
356    }
357
358    fn lookup(&self, class: &str, label: &str, asof: &str) -> Result<Option<String>, ErrorCode> {
359        Bindings::lookup(self.inner, class, label, asof)
360    }
361
362    fn cached(&self, fn_hash: &str, rest: &str) -> Option<Arc<Target>> {
363        self.inner.targets.get(fn_hash, rest)
364    }
365
366    fn remember(&self, rest: &str, target: &Arc<Target>) {
367        self.inner.targets.put(rest, target);
368    }
369
370    fn binding(&self, fn_name: &str, asof: &str) -> Result<Option<Arc<Bound>>, ErrorCode> {
371        self.seen.lookup(fn_name, asof, || Bindings::binding(self.inner, fn_name, asof))
372    }
373}
374
375impl Bindings for Inner {
376    fn pinned(&self, fn_hash: &str) -> Result<Option<Arc<Bound>>, ErrorCode> {
377        match self.descriptor(fn_hash) {
378            Ok(d) => Ok(Some(Arc::new(Bound::new(fn_hash, "", d)))),
379            Err(ErrorCode::FnUnavailable) => Ok(None),
380            Err(c) => Err(c),
381        }
382    }
383
384    fn alias(&self, alias: &str) -> Option<String> {
385        self.config.aliases.get(alias).cloned()
386    }
387
388    fn class(&self, name: &str, asof: &str) -> Result<Option<Arc<call::BoundClass>>, ErrorCode> {
389        let c = self.class_binding(name, asof)?;
390        if c.is_some() {
391            self.hear_of_class(name);
392        }
393        Ok(c)
394    }
395
396    /// The mesh's configured alias map has no snapshot.
397    fn aliases_tx(&self) -> Option<String> {
398        None
399    }
400
401    fn lookup(&self, class: &str, label: &str, asof: &str) -> Result<Option<String>, ErrorCode> {
402        let Some(c) = Bindings::class(self, class, asof)? else { return Ok(None) };
403        let Some(method) = &c.descriptor.lookup else { return Ok(None) };
404        let name = format!("{class}/{method}");
405        let Some(b) = Bindings::binding(self, &name, asof)? else { return Ok(None) };
406        let (ns, fn_name) = name.rsplit_once('/').unwrap_or((&name, ""));
407        let mut args = datumesh_core::Args::new();
408        args.insert("label".into(), datumesh_core::Arg::Value(datumesh_core::Scalar::String(label.to_string())));
409        let cell = datumesh_core::Cell { ns: ns.into(), fn_name: fn_name.into(), fn_hash: b.fn_hash.clone(), args };
410        match self.engine.get_cell(&cell, Some(asof)) {
411            Ok(Answer::Receipt(bytes)) => match Receipt::from_json(&bytes).map(|r| r.value().clone()) {
412                Ok(datumesh_core::Scalar::String(k)) => Ok(Some(k)),
413                _ => Ok(None),
414            },
415            Err(EngineError::Store(_)) => Err(ErrorCode::InputUnavailable),
416            _ => Ok(None),
417        }
418    }
419
420    fn cached(&self, fn_hash: &str, rest: &str) -> Option<Arc<Target>> {
421        self.targets.get(fn_hash, rest)
422    }
423
424    fn remember(&self, rest: &str, target: &Arc<Target>) {
425        self.targets.put(rest, target);
426    }
427
428    fn binding(&self, fn_name: &str, asof: &str) -> Result<Option<Arc<Bound>>, ErrorCode> {
429        let mut failed = None;
430        if self.foreign.is_foreign(fn_name) {
431            if let Err(e) = self.foreign.ensure_name(fn_name) {
432                tracing::warn!(target: "datumesh_http", name = fn_name, detail = %e.detail, "cross-mesh binding");
433                // `Bindings::binding` answers a bare code: the detail of E_FOREIGN_UNAVAILABLE
434                // waits on this thread for `rejection`, which answers on the same thread.
435                FOREIGN_DETAIL.with(|d| d.set(e.foreign_detail()));
436                failed = Some(e.code);
437            }
438        }
439        let b = self.store.resolve_binding(fn_name, asof).map_err(|e| {
440            tracing::warn!(target: "datumesh_http", error = %e, "resolve_binding");
441            ErrorCode::InputUnavailable
442        })?;
443        // The other mesh is unreachable: a binding imported before still names the cell
444        // (whose answer is then stale or an error), else the name cannot be resolved.
445        if let (Some(code), None) = (failed, &b) {
446            return Err(code);
447        }
448        match b {
449            None => Ok(None),
450            Some(b) => {
451                let d = self.descriptor(&b.fn_hash)?;
452                Ok(Some(Arc::new(Bound::new(b.fn_hash, b.tx, d))))
453            }
454        }
455    }
456}
457
458thread_local! {
459    /// Why the other mesh could not be reached, from the last cross-mesh name resolution on
460    /// this thread (see `Inner::binding` and `Inner::rejection`).
461    static FOREIGN_DETAIL: std::cell::Cell<Option<datumesh_core::ForeignDetail>> = const { std::cell::Cell::new(None) };
462}
463
464/// Latest answers by key: the receipt, the cell id and the asof answered at.
465type LatestShard = RwLock<HashMap<String, (Arc<ReceiptInfo>, String, String)>>;
466
467/// The latest answers of local stored cells, as of when they were answered: such an answer
468/// stands for every later asof until a version of the cell is added, which the mesh is told
469/// of ([`Mesh::stored_version_added`]), as the engine's memo is. It saves the engine's work
470/// (the cell id, the memo) on the hottest path: warm gets of stored cells.
471struct Latest {
472    shards: Vec<LatestShard>,
473    by_cell: Mutex<HashMap<String, Vec<String>>>,
474}
475
476impl Latest {
477    fn new() -> Latest {
478        Latest { shards: (0..32).map(|_| RwLock::new(HashMap::new())).collect(), by_cell: Mutex::new(HashMap::new()) }
479    }
480
481    fn shard(&self, key: &str) -> &LatestShard {
482        use std::hash::{Hash, Hasher};
483        let mut h = std::collections::hash_map::DefaultHasher::new();
484        key.hash(&mut h);
485        &self.shards[(h.finish() % self.shards.len() as u64) as usize]
486    }
487
488    /// The answer for `key` as of `a`, if one answered as of `a` or earlier is held.
489    fn get(&self, key: &str, a: &str) -> Option<Arc<ReceiptInfo>> {
490        let m = self.shard(key).read().unwrap_or_else(|p| p.into_inner());
491        let (info, _, at) = m.get(key)?;
492        (a >= at.as_str()).then(|| info.clone())
493    }
494
495    fn put(&self, key: String, cell_id: String, info: Arc<ReceiptInfo>, at: String) {
496        {
497            let mut b = self.by_cell.lock().unwrap_or_else(|p| p.into_inner());
498            if b.len() > 200_000 {
499                b.clear();
500                for s in &self.shards {
501                    s.write().unwrap_or_else(|p| p.into_inner()).clear();
502                }
503            }
504            b.entry(cell_id.clone()).or_default().push(key.clone());
505        }
506        self.shard(&key).write().unwrap_or_else(|p| p.into_inner()).insert(key, (info, cell_id, at));
507    }
508
509    fn forget(&self, cell_id: &str) {
510        let keys = self.by_cell.lock().unwrap_or_else(|p| p.into_inner()).remove(cell_id).unwrap_or_default();
511        for k in keys {
512            self.shard(&k).write().unwrap_or_else(|p| p.into_inner()).remove(&k);
513        }
514    }
515
516    fn clear(&self) {
517        self.by_cell.lock().unwrap_or_else(|p| p.into_inner()).clear();
518        for s in &self.shards {
519            s.write().unwrap_or_else(|p| p.into_inner()).clear();
520        }
521    }
522}
523
524/// Cell URI rests already parsed, by function hash (parsing depends on the signature
525/// alone): resolving a hot cell costs a binding lookup and no parse.
526struct Targets {
527    #[allow(clippy::type_complexity)]
528    shards: Vec<RwLock<HashMap<String, HashMap<String, Arc<Target>>>>>,
529}
530
531impl Targets {
532    fn new() -> Targets {
533        Targets { shards: (0..32).map(|_| RwLock::new(HashMap::new())).collect() }
534    }
535
536    #[allow(clippy::type_complexity)]
537    fn shard(&self, rest: &str) -> &RwLock<HashMap<String, HashMap<String, Arc<Target>>>> {
538        use std::hash::{Hash, Hasher};
539        let mut h = std::collections::hash_map::DefaultHasher::new();
540        rest.hash(&mut h);
541        &self.shards[(h.finish() % self.shards.len() as u64) as usize]
542    }
543
544    fn get(&self, fn_hash: &str, rest: &str) -> Option<Arc<Target>> {
545        self.shard(rest).read().unwrap_or_else(|p| p.into_inner()).get(rest)?.get(fn_hash).cloned()
546    }
547
548    fn put(&self, rest: &str, t: &Arc<Target>) {
549        let mut m = self.shard(rest).write().unwrap_or_else(|p| p.into_inner());
550        if m.len() >= 4_096 {
551            m.clear();
552        }
553        let v = m.entry(rest.to_string()).or_default();
554        if v.len() >= 8 {
555            v.clear();
556        }
557        v.insert(t.bound.fn_hash.clone(), t.clone());
558    }
559}
560
561/// The key of a cell's last good answer: the function hash and the URI (without asof: the
562/// last good answer is kept for requests about now only).
563fn last_good_key(t: &Target) -> String {
564    t.cell_key().to_string()
565}
566
567/// The engine's error as an envelope code (the engine's table, "For the HTTP layer").
568fn engine_code(e: &EngineError) -> (bool, ErrorCode) {
569    match e {
570        EngineError::Invalid(e) if envelope::is_request_code(e.code()) => (true, e.code()),
571        EngineError::Invalid(e) if envelope::is_error_code(e.code()) => (false, e.code()),
572        EngineError::NameUnresolved { .. } => (false, ErrorCode::FnUnavailable),
573        EngineError::UndeclaredInput { .. } => (false, ErrorCode::InputUndeclared),
574        EngineError::Sign(e) if envelope::is_error_code(e.code()) => (false, e.code()),
575        EngineError::Store(_) => (false, ErrorCode::InputUnavailable),
576        _ => (false, ErrorCode::EvalUnavailable),
577    }
578}
579
580impl Inner {
581    pub(crate) fn now(&self) -> String {
582        self.clock.now()
583    }
584
585    /// A descriptor by hash (cached: content-addressed).
586    pub(crate) fn descriptor(&self, fn_hash: &str) -> Result<Arc<FunctionDescriptor>, ErrorCode> {
587        if let Some(d) = self.descriptors.lock().unwrap_or_else(|p| p.into_inner()).get(fn_hash) {
588            return Ok(d.clone());
589        }
590        let bytes = self.store.descriptor(fn_hash).ok_or(ErrorCode::FnUnavailable)?;
591        let d = Arc::new(FunctionDescriptor::from_json(&bytes).map_err(|_| ErrorCode::FnUnavailable)?);
592        let mut m = self.descriptors.lock().unwrap_or_else(|p| p.into_inner());
593        if m.len() > 10_000 {
594            m.clear();
595        }
596        m.insert(fn_hash.to_string(), d.clone());
597        Ok(d)
598    }
599
600    /// The `ok` reply with a receipt, remembered for `stale` answers.
601    fn ok_reply(
602        &self,
603        target: &Target,
604        info: Arc<ReceiptInfo>,
605        a: &str,
606        now: &str,
607        private: bool,
608        link: bool,
609    ) -> Reply {
610        let mut reply = Reply::json(200, info.ok.clone(), Cache::Immutable);
611        if target.asof().is_none() {
612            let mut lg = self.last_good.lock().unwrap_or_else(|p| p.into_inner());
613            if lg.len() > 100_000 {
614                lg.clear();
615            }
616            lg.insert(last_good_key(target), LastGood { info, at: Instant::now() });
617        }
618        self.cache_rules(&mut reply, target, a, now, private, link);
619        reply
620    }
621
622    /// Remembers the answer as of now `a` for a local stored cell, when it is the cell's
623    /// latest version (a version with a later `tx` would answer later asofs).
624    fn remember_latest(&self, target: &Target, info: &Arc<ReceiptInfo>, a: &str) {
625        match self.store.latest(target.cell_id()) {
626            Ok(Some(v)) if v.receipt_hash == info.hash => {
627                self.latest.put(
628                    target.cell_key().to_string(),
629                    target.cell_id().to_string(),
630                    info.clone(),
631                    a.to_string(),
632                );
633            }
634            _ => {}
635        }
636    }
637
638    /// A stored version was added for `cell_id`: the engine's memo, the latest answers and
639    /// the slice cache forget what rests on it.
640    pub(crate) fn version_added(&self, cell_id: &str) {
641        self.engine.stored_version_added(cell_id);
642        self.latest.forget(cell_id);
643        self.slices.lock().unwrap_or_else(|p| p.into_inner()).clear();
644        self.known.lock().unwrap_or_else(|p| p.into_inner()).announce(cell_id);
645    }
646
647    /// The receipt's hash, asof, trust and `ok` envelope (cached by its bytes).
648    fn receipt_info(&self, bytes: &[u8]) -> Option<Arc<ReceiptInfo>> {
649        use std::hash::{Hash, Hasher};
650        let mut h = std::collections::hash_map::DefaultHasher::new();
651        bytes.hash(&mut h);
652        let key = h.finish();
653        let shard = &self.infos[(key % self.infos.len() as u64) as usize];
654        if let Some(i) = shard.lock().unwrap_or_else(|p| p.into_inner()).get(&key) {
655            if i.receipt == bytes {
656                return Some(i.clone());
657            }
658        }
659        let r = Receipt::from_json(bytes).ok()?;
660        let trust = envelope::trust_label_of(&r, &self.config.host);
661        let ok = envelope::with_fn_hash(datumesh_core::Answer::ok(r.clone(), trust), Some(&r.cell().fn_hash)).to_json();
662        let info = Arc::new(ReceiptInfo {
663            hash: r.hash().to_string(),
664            asof: r.asof().to_string(),
665            receipt: bytes.to_vec(),
666            parsed: r,
667            trust,
668            ok: ok.into(),
669        });
670        let mut m = shard.lock().unwrap_or_else(|p| p.into_inner());
671        if m.len() >= 4_096 {
672            m.clear();
673        }
674        m.insert(key, info.clone());
675        Some(info)
676    }
677
678    /// A receipt's info by its hash: from the cache, else the store.
679    pub(crate) fn receipt_info_by_hash(&self, hash: &str) -> Option<Arc<ReceiptInfo>> {
680        use std::hash::{Hash, Hasher};
681        let mut h = std::collections::hash_map::DefaultHasher::new();
682        hash.hash(&mut h);
683        let shard = &self.by_hash[(h.finish() % self.by_hash.len() as u64) as usize];
684        if let Some(i) = shard.lock().unwrap_or_else(|p| p.into_inner()).get(hash) {
685            return Some(i.clone());
686        }
687        let bytes = self.store.receipt(hash)?;
688        let info = self.receipt_info(&bytes)?;
689        let mut m = shard.lock().unwrap_or_else(|p| p.into_inner());
690        if m.len() >= 2_048 {
691            m.clear();
692        }
693        m.insert(hash.to_string(), info.clone());
694        Some(info)
695    }
696
697    /// The reply to a request the call parser rejected.
698    pub(crate) fn rejection(&self, r: Rejection, asof: Option<&str>) -> Reply {
699        match r {
700            Rejection::BadRequest(c) => envelope::bad_request_reply(c),
701            Rejection::NotCovered => {
702                let _ = asof;
703                Reply::json(404, envelope::not_covered(None), Cache::Public(self.config.ttl.latest_max_age.as_secs()))
704            }
705            Rejection::Error(ErrorCode::NameUnbound) => {
706                envelope::name_unbound_reply(self.config.ttl.latest_max_age.as_secs())
707            }
708            Rejection::Error(ErrorCode::ForeignUnavailable) => {
709                // The other mesh could not be reached while resolving the name (spec-0.4.3).
710                let d = FOREIGN_DETAIL.with(|d| d.take()).unwrap_or(datumesh_core::ForeignDetail::Network);
711                envelope::answer_reply(&datumesh_core::Answer::foreign_unavailable(d), Cache::NoStore)
712            }
713            Rejection::Error(c) => envelope::error_reply(c),
714        }
715    }
716
717    /// The licence and payment rules for a target and principal: a refusal, and whether the
718    /// answer depends on who asks.
719    fn policy(&self, target: &Target, principal: Option<&Principal>) -> (Option<Reply>, bool) {
720        if self.config.policy.rules.is_empty() {
721            return (None, false);
722        }
723        match self.config.policy.rule(&target.fn_name()) {
724            None => (None, false),
725            Some(Rule::Principals(ps)) => {
726                if principal.is_some_and(|p| ps.contains(&p.id)) {
727                    (None, true)
728                } else {
729                    let a = envelope::with_fn_hash(datumesh_core::Answer::unlicensed(), Some(&target.bound.fn_hash));
730                    (Some(envelope::answer_reply(&a, Cache::Private)), true)
731                }
732            }
733            Some(Rule::Price { amount, currency }) => {
734                let authorise = format!("{}/pay/{}", self.config.origin(), target.cell_id());
735                let quote = datumesh_core::Quote { amount: amount.clone(), currency: currency.clone(), authorise };
736                let a =
737                    envelope::with_fn_hash(datumesh_core::Answer::payment_required(quote), Some(&target.bound.fn_hash));
738                (Some(envelope::answer_reply(&a, Cache::Private)), true)
739            }
740        }
741    }
742
743    /// Answers a `/cell` request (blocking; no budget: see [`Mesh::cell`]). `on_target` is
744    /// told the request description as soon as it is known (for `pending`).
745    pub(crate) fn answer(
746        &self,
747        rest: &str,
748        principal: Option<&Principal>,
749        bindings: &dyn Bindings,
750        now: &str,
751        on_target: &mut dyn FnMut(&Target),
752    ) -> Reply {
753        self.answer_with(rest, principal, bindings, now, on_target, true)
754    }
755
756    /// As [`Inner::answer`]; without the canonical link when `link` is false (a batch's
757    /// envelopes have no headers).
758    pub(crate) fn answer_with(
759        &self,
760        rest: &str,
761        principal: Option<&Principal>,
762        bindings: &dyn Bindings,
763        now: &str,
764        on_target: &mut dyn FnMut(&Target),
765        link: bool,
766    ) -> Reply {
767        let target = match call::resolve(rest, now, &self.config.aliases, bindings, false) {
768            Ok(t) => t,
769            Err(r) => return self.rejection(r, None),
770        };
771        on_target(&target);
772        let (refused, private) = self.policy(&target, principal);
773        let reply = match refused {
774            Some(r) => r,
775            None => self.answer_target(&target, now, private, link),
776        };
777        // What the request resolved is per request: the answers are built from cached bytes.
778        match &target.resolved {
779            Some(r) => envelope::with_resolved(reply, r),
780            None => reply,
781        }
782    }
783
784    /// Answers a resolved target as of its asof (or `now`).
785    pub(crate) fn answer_target(&self, target: &Target, now: &str, private: bool, link: bool) -> Reply {
786        let a = target.asof().unwrap_or(now);
787        let stored = target.bound.descriptor.lang == "stored";
788        let local = stored && !self.foreign.is_foreign(&target.cell.ns);
789        if local {
790            if let Some(info) = self.latest.get(target.cell_key(), a) {
791                let mut reply = Reply::json(200, info.ok.clone(), Cache::Immutable);
792                self.cache_rules(&mut reply, target, a, now, private, link);
793                return reply;
794            }
795        }
796        if let Err(e) = self.foreign.prepare(&target.cell, stored, target.asof()) {
797            return self.unavailable(target, e);
798        }
799        // Since 0.2.1: before computing another mesh's function, its publisher's key document
800        // (its declarations, SPEC 8.5), fetched again after its TTL.
801        if !stored {
802            if let Err(e) = self.foreign.ensure_publisher(&target.cell.ns) {
803                return self.unavailable(target, e);
804            }
805        }
806        let mut attempt = 0;
807        loop {
808            let r = self.engine.get_cell(&target.cell, Some(a));
809            let inval = self.foreign.take_invalidated();
810            for id in &inval {
811                self.version_added(id);
812            }
813            if !inval.is_empty() && attempt < 2 {
814                attempt += 1;
815                continue;
816            }
817            // A formula cell answered: the describe index learns of it (CONTRACT-1.8b H4).
818            if !stored && matches!(r, Ok(Answer::Receipt(_))) {
819                self.known.lock().unwrap_or_else(|p| p.into_inner()).note_computed(&target.cell);
820            }
821            return match r {
822                Ok(Answer::Receipt(bytes)) => {
823                    let Some(info) = self.receipt_info(&bytes) else {
824                        return envelope::error_answer_reply(ErrorCode::EvalUnavailable, Some(&target.bound.fn_hash));
825                    };
826                    if attempt < 2 {
827                        match self.foreign.refresh_deps(&info.hash, a) {
828                            Ok(true) => {
829                                for id in self.foreign.take_invalidated() {
830                                    self.version_added(&id);
831                                }
832                                attempt += 1;
833                                continue;
834                            }
835                            Ok(false) => {}
836                            Err(e) => return self.unavailable(target, e),
837                        }
838                    }
839                    if local && target.asof().is_none() {
840                        self.remember_latest(target, &info, a);
841                    }
842                    self.ok_reply(target, info, a, now, private, link)
843                }
844                Ok(Answer::NotCovered { fault }) => {
845                    let mut ans =
846                        envelope::with_fn_hash(datumesh_core::Answer::not_covered(), Some(&target.bound.fn_hash));
847                    if let Some(f) = fault {
848                        ans = ans.with_fault(f);
849                    }
850                    let mut reply = envelope::answer_reply(&ans, Cache::Public(0));
851                    self.cache_rules(&mut reply, target, a, now, private, link);
852                    if target.asof().is_some() {
853                        reply.cache = if private {
854                            Cache::Private
855                        } else {
856                            Cache::Public(self.config.ttl.latest_max_age.as_secs())
857                        };
858                    }
859                    reply
860                }
861                Ok(_) => envelope::error_answer_reply(ErrorCode::EvalUnavailable, Some(&target.bound.fn_hash)),
862                Err(EngineError::Unlicensed { cell_id, reason }) => {
863                    // Licence inheritance refuses the cell (SPEC 8.5, spec-0.4.3): `unlicensed`,
864                    // no new code. Not immutable: a declaration may come later.
865                    tracing::info!(target: "datumesh_http", cell_id = %cell_id, reason = reason.as_str(), "unlicensed");
866                    let a = envelope::with_fn_hash(datumesh_core::Answer::unlicensed(), Some(&target.bound.fn_hash));
867                    let cache =
868                        if private { Cache::Private } else { Cache::Public(self.config.ttl.latest_max_age.as_secs()) };
869                    envelope::answer_reply(&a, cache)
870                }
871                Err(e) => {
872                    let (bad, code) = engine_code(&e);
873                    tracing::info!(target: "datumesh_http", error = %e, code = code.as_str(), "engine");
874                    if code == ErrorCode::ForeignUnavailable {
875                        // A cross-mesh fetch inside the evaluation got no response (ForeignError::eval).
876                        let detail = match &e {
877                            EngineError::Invalid(c) => {
878                                c.detail().strip_prefix("cross-mesh: ").unwrap_or(c.detail()).to_string()
879                            }
880                            other => other.to_string(),
881                        };
882                        return self.unavailable(target, ForeignError { code, detail });
883                    }
884                    if bad {
885                        envelope::bad_request_reply(code)
886                    } else if code == ErrorCode::InputUnavailable {
887                        self.unavailable(target, ForeignError { code, detail: e.to_string() })
888                    } else {
889                        envelope::error_answer_reply(code, Some(&target.bound.fn_hash))
890                    }
891                }
892            };
893        }
894    }
895
896    fn cache_rules(&self, reply: &mut Reply, target: &Target, a: &str, now: &str, private: bool, link: bool) {
897        let latest = self.config.ttl.latest_max_age.as_secs();
898        reply.cache = if private {
899            Cache::Private
900        } else {
901            match target.asof() {
902                Some(x) if x <= now => Cache::Immutable,
903                Some(_) => Cache::Public(latest),
904                None => Cache::Public(latest),
905            }
906        };
907        if link && target.asof().is_none() {
908            reply.canonical = Some(format!("{}/cell/{}", self.config.origin(), target.rest_asof(a)));
909        }
910    }
911
912    /// The answer when something the mesh depends on failed: `stale` with the last receipt
913    /// it served for the cell, when it has one that answers the request; else `error`.
914    fn unavailable(&self, target: &Target, e: ForeignError) -> Reply {
915        tracing::info!(target: "datumesh_http", code = e.code.as_str(), detail = %e.detail, "unavailable");
916        // A suspended namespace (9.9, 5.5): the import is refused, so `not_covered` with its error,
917        // and not the last receipt served (a cell served before is served as before, not imported).
918        if e.code == crate::foreign::NAMESPACE_SUSPENDED {
919            if let Ok(a) = datumesh_core::Answer::not_covered().with_error(ErrorCode::NamespaceSuspended) {
920                return envelope::answer_reply(&envelope::with_fn_hash(a, Some(&target.bound.fn_hash)), Cache::NoStore);
921            }
922        }
923        let lg = self.last_good.lock().unwrap_or_else(|p| p.into_inner());
924        if let Some(g) = lg.get(&last_good_key(target)) {
925            if target.asof().is_none_or(|a| g.info.asof.as_str() <= a) {
926                let age = g.at.elapsed().as_secs();
927                let a = datumesh_core::Answer::stale(g.info.parsed.clone(), g.info.trust, age);
928                let a = envelope::with_fn_hash(a, Some(&g.info.parsed.cell().fn_hash));
929                return envelope::answer_reply(&a, Cache::NoStore);
930            }
931        }
932        if let Some(d) = e.foreign_detail() {
933            let a = envelope::with_fn_hash(datumesh_core::Answer::foreign_unavailable(d), Some(&target.bound.fn_hash));
934            return envelope::answer_reply(&a, Cache::NoStore);
935        }
936        envelope::error_answer_reply(e.code, Some(&target.bound.fn_hash))
937    }
938
939    /// The keys to verify `receipt` with: the documents of its signer and of the signers of
940    /// its inputs and slice members held in the store, from the cache or the store's
941    /// namespace records.
942    pub(crate) fn keys_for_receipt(&self, receipt: &[u8]) -> Keys {
943        let mut hosts = std::collections::BTreeSet::new();
944        if let Ok(v) = json::parse(receipt) {
945            if let Some(h) = v.get("computed_by").and_then(Value::as_str) {
946                hosts.insert(h.split('#').next().unwrap_or("").to_string());
947            }
948            if let Some(Value::Array(ins)) = v.get("inputs") {
949                let mut members = Vec::new();
950                for i in ins.iter().filter_map(Value::as_str).take(10_000) {
951                    if i.starts_with("slice:") {
952                        if let Some(m) =
953                            self.store.manifest(i).and_then(|m| datumesh_core::Manifest::from_json(&m).ok())
954                        {
955                            members.extend(m.members().iter().take(10_000).cloned());
956                        }
957                    } else {
958                        members.push(i.to_string());
959                    }
960                }
961                for h in members.iter().take(20_000) {
962                    if let Some(r) = self.store.receipt(h).and_then(|b| Receipt::from_json(&b).ok()) {
963                        hosts.insert(r.signer_host().to_string());
964                    }
965                }
966            }
967        }
968        let mut keys = Keys::new();
969        for h in hosts {
970            if let Some(r) = self.keys.result(&h) {
971                keys.insert_result(&h, r);
972            } else if let Some(doc) = self.key_doc(&h) {
973                keys.insert(doc);
974            }
975        }
976        keys
977    }
978
979    /// A host's key document: the cache's, else the store's namespace record.
980    fn key_doc(&self, host: &str) -> Option<KeyDoc> {
981        if let Some((d, _, _)) = self.keys.get(host) {
982            return Some(d);
983        }
984        let ns = self.store.namespace(host).ok()??;
985        keys_from_response(host, 200, Some(&ns.keydoc)).ok()
986    }
987}
988
989fn verified(r: datumesh_core::VerifyResult) -> Verified {
990    let s = |v: Option<&str>| v.map(|x| Value::String(x.to_string())).unwrap_or(Value::Null);
991    let body = Value::Object(vec![
992        ("blob_checked".into(), Value::Bool(r.blob_checked)),
993        ("code".into(), s(r.code.map(|c| c.as_str()))),
994        ("computed_by".into(), s(r.computed_by.as_deref())),
995        ("detail".into(), Value::String(r.detail.clone())),
996        ("hash".into(), s(r.hash.as_deref())),
997        ("level".into(), s(r.level.map(|l| l.as_str()))),
998        ("ok".into(), Value::Bool(r.ok)),
999        ("path".into(), Value::String(r.path.clone())),
1000    ]);
1001    Verified { body: body.to_jcs() }
1002}
1003
1004/// What `POST /verify` reports.
1005#[derive(Clone, Debug, PartialEq, Eq)]
1006pub struct Verified {
1007    /// The result as JSON (`ok`, `level`, `code`, `hash`, `computed_by`, `path`, `detail`).
1008    pub body: Vec<u8>,
1009}
1010
1011impl Mesh {
1012    /// A builder for a mesh on `store` with `config`.
1013    pub fn builder(config: Config, store: Arc<dyn Store + Send + Sync>) -> MeshBuilder {
1014        MeshBuilder {
1015            config,
1016            store,
1017            key: None,
1018            key_file: None,
1019            runtimes: Vec::new(),
1020            formula: true,
1021            clock: Arc::new(SystemClock),
1022            fuel: None,
1023            licence: None,
1024            memo_capacity: None,
1025        }
1026    }
1027
1028    /// The configuration.
1029    pub fn config(&self) -> &Config {
1030        &self.inner.config
1031    }
1032
1033    /// The engine.
1034    pub fn engine(&self) -> &Arc<Engine> {
1035        &self.inner.engine
1036    }
1037
1038    /// Forgets every memoised answer (the engine's memo and the mesh's), for a process that
1039    /// wrote versions without telling the mesh.
1040    pub fn clear_memo(&self) {
1041        self.inner.engine.clear_memo();
1042        self.inner.latest.clear();
1043        self.inner.slices.lock().unwrap_or_else(|p| p.into_inner()).clear();
1044    }
1045
1046    /// The cross-mesh resolver.
1047    pub fn foreign(&self) -> &Foreign {
1048        &self.inner.foreign
1049    }
1050
1051    /// The store.
1052    pub fn store(&self) -> &Arc<dyn Store + Send + Sync> {
1053        &self.inner.store
1054    }
1055
1056    /// The key documents the mesh holds for other hosts (fetched, or inserted here): what
1057    /// `POST /verify` verifies with, besides the store's namespace records.
1058    pub fn keys(&self) -> &KeyCache {
1059        &self.inner.keys
1060    }
1061
1062    /// Tells the engine that a stored version was added for `cell_id` outside the mesh.
1063    pub fn stored_version_added(&self, cell_id: &str) {
1064        self.inner.version_added(cell_id);
1065    }
1066
1067    /// The envelope for `rest` (a call or a cell URI's rest, query included, as received at
1068    /// `/cell/`), for `principal`. Blocking, and without a budget: what a `/cell` request
1069    /// gets when it finishes within its budget, or its job's result.
1070    pub fn cell(&self, rest: &str, principal: Option<&Principal>) -> Reply {
1071        let now = self.inner.now();
1072        self.inner.answer(rest, principal, &*self.inner, &now, &mut |_| {})
1073    }
1074
1075    /// The envelopes of a batch, in order (blocking, no budget).
1076    pub fn cells(&self, rests: &[String], principal: Option<&Principal>) -> Vec<Reply> {
1077        let now = self.inner.now();
1078        let memo = Memo::new(&self.inner);
1079        rests.iter().map(|r| self.inner.answer(r, principal, &memo, &now, &mut |_| {})).collect()
1080    }
1081
1082    /// Resolves a request to its cell, as `/cell` does (or to its slice, with `slice`).
1083    pub fn resolve(&self, rest: &str, slice: bool) -> Result<Arc<Target>, Rejection> {
1084        let now = self.inner.now();
1085        call::resolve(rest, &now, &self.inner.config.aliases, &*self.inner, slice)
1086    }
1087
1088    /// The describe answer (SPEC 16.8, 9.6) for `id`: a class name, an object's key encoding, an
1089    /// object id, a cell id or a short id (12 hex digits). A class or an object: the body is a
1090    /// `describe-class` or `describe-object` document, `200`; an id the mesh does not know, `404`;
1091    /// a short id naming more than one object or cell the mesh knows, `400` with
1092    /// `E_SHORT_ID_AMBIGUOUS`. A class hash is not an id (9.6). Blocking. Since 0.2.2.
1093    pub fn describe(&self, id: &str) -> Reply {
1094        self.inner.describe(id)
1095    }
1096
1097    /// Verifies a receipt (SPEC 10.1) with the mesh's keys; at level `recomputed` with the
1098    /// engine as the resolver unless `signed_only`; `blob` is content for step 7.7.
1099    pub fn verify(&self, receipt: &[u8], signed_only: bool, blob: Option<&[u8]>) -> Verified {
1100        let keys = self.inner.keys_for_receipt(receipt);
1101        let resolver: Option<&dyn datumesh_core::Resolver> =
1102            if signed_only { None } else { Some(&*self.inner.engine as &dyn datumesh_core::Resolver) };
1103        verified(verify(receipt, &keys, resolver, blob))
1104    }
1105
1106    /// Verifies a receipt with the mesh's keys and what the caller offers for step 7: a
1107    /// `recompute` object as SPEC 11 describes it (`descriptor`, `inputs`, `manifests`,
1108    /// `lineage`, `value`), the core's `MapResolver` over it. Without one, steps 1-6 only.
1109    pub fn verify_offered(&self, receipt: &[u8], recompute: Option<&Value>, blob: Option<&[u8]>) -> Verified {
1110        let mut keys = self.inner.keys_for_receipt(receipt);
1111        // The signers of the receipts offered for step 7 too.
1112        let mut hosts = std::collections::BTreeSet::new();
1113        for (_, r) in recompute.and_then(|rc| rc.get("inputs")).and_then(Value::as_object).unwrap_or(&[]) {
1114            if let Some(h) = r
1115                .as_str()
1116                .and_then(|t| json::parse(t.as_bytes()).ok())
1117                .and_then(|v| v.get("computed_by").and_then(Value::as_str).map(str::to_string))
1118            {
1119                hosts.insert(h.split('#').next().unwrap_or("").to_string());
1120            }
1121        }
1122        for h in hosts {
1123            if let Some(r) = self.inner.keys.result(&h) {
1124                keys.insert_result(&h, r);
1125            } else if let Some(doc) = self.inner.key_doc(&h) {
1126                keys.insert(doc);
1127            }
1128        }
1129        let Some(rc) = recompute else {
1130            return verified(verify(receipt, &keys, None, blob));
1131        };
1132        let mut m = datumesh_core::MapResolver::new();
1133        let cell = json::parse(receipt).ok().and_then(|r| r.get("cell").cloned());
1134        if let (Some(d), Some(h)) =
1135            (rc.get("descriptor"), cell.as_ref().and_then(|c| c.get("fn_hash")).and_then(Value::as_str))
1136        {
1137            m.insert_descriptor(h, d.to_jcs());
1138        }
1139        for (h, r) in rc.get("inputs").and_then(Value::as_object).unwrap_or(&[]) {
1140            m.insert_receipt(h.as_str(), r.as_str().unwrap_or("").as_bytes());
1141        }
1142        for (e, t) in rc.get("manifests").and_then(Value::as_object).unwrap_or(&[]) {
1143            m.insert_manifest(e.as_str(), t.as_str().unwrap_or("").as_bytes());
1144        }
1145        let value = rc.get("value").and_then(|v| datumesh_core::Scalar::from_json(&v.to_jcs()).ok());
1146        if let (Some(value), Some(c)) = (value, cell.as_ref().and_then(|c| datumesh_core::Cell::from_value(c).ok())) {
1147            m.insert_value(c.id(), value);
1148            if let Some(Value::Array(l)) = rc.get("lineage") {
1149                m.insert_lineage(c.id(), l.iter().filter_map(Value::as_str));
1150            }
1151        }
1152        verified(verify(receipt, &keys, Some(&m), blob))
1153    }
1154
1155    /// The mesh document (SPEC 9.6) this mesh serves: its URLs on the base URL when one is
1156    /// set ([`Config::base_url`]), else on `https://<host>`.
1157    pub fn mesh_document(&self) -> Vec<u8> {
1158        let o = self.inner.config.mesh_document_base();
1159        let ep: BTreeMap<&str, String> = [
1160            ("blob", format!("{o}/blob/{{sha256}}")),
1161            ("cell", format!("{o}/cell/{{cell}}")),
1162            ("cells", format!("{o}/cells")),
1163            ("describe", format!("{o}/describe/{{id}}")),
1164            ("descriptor", format!("{o}/descriptor/{{hash}}")),
1165            ("explain", format!("{o}/explain/{{cell}}")),
1166            ("find", format!("{o}/find")),
1167            ("jobs", format!("{o}/jobs/{{job}}")),
1168            ("manifest", format!("{o}/manifest/{{slice_id}}/{{members_hash}}")),
1169            ("receipt", format!("{o}/receipt/{{hash}}")),
1170            ("slice", format!("{o}/slice/{{cell}}")),
1171            ("verify", format!("{o}/verify")),
1172            ("versions", format!("{o}/versions/{{cell}}")),
1173        ]
1174        .into_iter()
1175        .collect();
1176        Value::Object(vec![
1177            ("bindings".into(), Value::String(format!("{o}/bindings"))),
1178            (
1179                "endpoints".into(),
1180                Value::Object(ep.into_iter().map(|(k, v)| (k.to_string(), Value::String(v))).collect()),
1181            ),
1182            ("host".into(), Value::String(self.inner.config.host.clone())),
1183            ("proto".into(), Value::String("datumesh/1".into())),
1184        ])
1185        .to_jcs()
1186    }
1187
1188    /// The key document this mesh serves: the store's namespace record for its host.
1189    pub fn key_document(&self) -> Option<Vec<u8>> {
1190        self.inner.store.namespace(&self.inner.config.host).ok().flatten().map(|n| n.keydoc)
1191    }
1192
1193    /// The Prometheus text of `/metrics`.
1194    pub fn metrics(&self) -> String {
1195        crate::http::metrics_text(&self.inner)
1196    }
1197
1198    /// The number of requests counted for a route template (e.g. `/cell/{cell}`).
1199    pub fn requests_of(&self, route: &str) -> u64 {
1200        self.inner.metrics.requests_of(route)
1201    }
1202
1203    /// The host of a function name (its first segment).
1204    pub fn host_of(name: &str) -> &str {
1205        host_of(name)
1206    }
1207
1208    /// How long the mesh has run.
1209    pub fn uptime(&self) -> Duration {
1210        self.inner.started.elapsed()
1211    }
1212}
1213
1214impl Inner {
1215    /// The class `name` is bound to as of `asof`, with its flattened descriptor (not noted for the
1216    /// describe index: see [`Bindings::class`]).
1217    pub(crate) fn class_binding(&self, name: &str, asof: &str) -> Result<Option<Arc<call::BoundClass>>, ErrorCode> {
1218        let store_failed = |e: datumesh_store::Error| {
1219            tracing::warn!(target: "datumesh_http", error = %e, "resolve_class_binding");
1220            ErrorCode::InputUnavailable
1221        };
1222        let Some(b) = self.store.resolve_class_binding(name, asof).map_err(store_failed)? else { return Ok(None) };
1223        let Some(bytes) = self.store.class(&b.class_hash).map_err(store_failed)? else {
1224            return Err(ErrorCode::InputUnavailable);
1225        };
1226        let d = datumesh_core::ClassDescriptor::from_json(&bytes).map_err(|_| ErrorCode::InputUnavailable)?;
1227        Ok(Some(Arc::new(call::BoundClass { class_hash: b.class_hash, since: b.tx, descriptor: Arc::new(d) })))
1228    }
1229}
1230
1231#[cfg(test)]
1232mod tests {
1233    use super::*;
1234    use std::sync::atomic::{AtomicUsize, Ordering};
1235
1236    /// A batch's chunks start together and ask for the same names: one store round trip per
1237    /// name and asof for the whole batch, not one per chunk.
1238    #[test]
1239    fn a_batch_looks_each_binding_up_once() {
1240        let seen = Seen::default();
1241        let lookups = AtomicUsize::new(0);
1242        let start = std::sync::Barrier::new(6);
1243        let look = || {
1244            lookups.fetch_add(1, Ordering::SeqCst);
1245            std::thread::sleep(Duration::from_millis(50));
1246            Ok(None)
1247        };
1248        std::thread::scope(|s| {
1249            for _ in 0..6 {
1250                s.spawn(|| {
1251                    start.wait();
1252                    assert!(matches!(seen.lookup("a.example/f", "2026-01-01T00:00:00Z", look), Ok(None)));
1253                });
1254            }
1255        });
1256        assert_eq!(lookups.load(Ordering::SeqCst), 1, "one lookup for six chunks");
1257        // Found: no lookup.
1258        assert!(matches!(seen.lookup("a.example/f", "2026-01-01T00:00:00Z", look), Ok(None)));
1259        assert_eq!(lookups.load(Ordering::SeqCst), 1);
1260        // Another asof, another name: looked up.
1261        assert!(matches!(seen.lookup("a.example/f", "2026-01-02T00:00:00Z", look), Ok(None)));
1262        assert!(matches!(seen.lookup("a.example/g", "2026-01-01T00:00:00Z", look), Ok(None)));
1263        assert_eq!(lookups.load(Ordering::SeqCst), 3);
1264        // A failed lookup is not kept.
1265        let fail = || Err(ErrorCode::InputUnavailable);
1266        assert!(matches!(seen.lookup("a.example/h", "2026-01-01T00:00:00Z", fail), Err(ErrorCode::InputUnavailable)));
1267        assert!(matches!(seen.lookup("a.example/h", "2026-01-01T00:00:00Z", look), Ok(None)));
1268        assert_eq!(lookups.load(Ordering::SeqCst), 4);
1269    }
1270}