Skip to main content

datumesh_http/
foreign.rs

1//! Cross-mesh resolution (SPEC 9.6, 9.7), minimal form: names under hosts this mesh does not
2//! own.
3//!
4//! # How the engine sees foreign names
5//!
6//! The engine reads only its store, and the store holds only what verified on the way in. So
7//! foreign records are **imported into the store before the engine reads them**, through a
8//! read-through layer around every runtime ([`CrossMesh`]): when a function reads a name under
9//! a host this mesh does not own, the layer first
10//!
11//! 1. resolves that host (its key document and its mesh document, `resolve_mesh`, cached),
12//! 2. brings the name's bindings up to date from the host's bindings resource (9.7): the
13//!    binding answering now and, walking back by `since`, every earlier one the store lacks,
14//!    each with its descriptor (fetched by hash, checked by `put_descriptor`), appended with
15//!    `bind_name` in order;
16//! 3. for a **stored** function, brings the cell's versions up to date: from the host's
17//!    versions endpoint (9.8) when its mesh document lists one, every version the store lacks,
18//!    each receipt fetched by hash and checked; otherwise the host's envelope for the cell
19//!    now, then, walking back (as of just before each receipt's start), every earlier version
20//!    the store lacks. Everything is fetched and checked by the store-less
21//!    [`crate::client::Client`] (envelopes against the request, signatures against the
22//!    signer's key document, fetched from the signer's own host); each receipt is then stored
23//!    with `put_receipt` (which verifies it again against the key document stored for its
24//!    signer) and `put_version`, oldest first.
25//!
26//! A foreign function that is not stored (a formula on the other mesh) is evaluated by this
27//! mesh from its descriptor and its inputs, which are imported the same way: its value is
28//! recomputed, never taken on trust.
29//!
30//! Versions and bindings are append-only in the store, in transaction order; importing the
31//! full history back to the first version (or binding) the store lacks keeps them so, so the
32//! store answers every asof as the other mesh would. A history that does not extend what the
33//! store holds (the other mesh rewrote it) is refused with `E_INPUT_UNAVAILABLE`.
34//!
35//! Answers for asofs at or before the last confirmation never change; answers about "now"
36//! are confirmed again after [`Ttls::current`](crate::config::Ttls) (bindings after
37//! `Ttls::binding`). The memo is kept honest by [`Foreign::take_invalidated`]: every cell
38//! whose versions grew is reported to the engine (`stored_version_added`) after the request.
39//!
40//! # Caches and lifetimes
41//!
42//! | What | Where | Lifetime |
43//! |---|---|---|
44//! | key documents | memory ([`KeyCache`]) and the store's namespace record | 300 s; a key id the cached document lacks refetches it at once (at most every 10 s) |
45//! | mesh documents | memory | 300 s |
46//! | a name's bindings | the store | confirmed again after 60 s |
47//! | a cell's versions | the store | confirmed again after 60 s, for requests about now |
48//! | descriptors, receipts | the store | forever: content-addressed |
49//!
50//! Not in 0.1.x: slices over foreign functions (`E_INPUT_UNAVAILABLE`: the store would hold
51//! only the members read so far), cells of a foreign name's earlier bindings that were never
52//! imported while current, and `pending` answers from the other mesh (`E_INPUT_UNAVAILABLE`).
53
54use std::collections::{HashMap, HashSet};
55use std::sync::{Arc, Mutex};
56use std::time::{Duration, Instant};
57
58use datumesh_core::{
59    format_uri, keys_from_response, Args, Cell, CellRef, Error as CoreError, ErrorCode, FunctionDescriptor, KeyDoc,
60    MeshDoc, Receipt, Request, Scalar,
61};
62use datumesh_engine::{Budget, Clock, EvalError, FnBinding, Input, Inputs, Member, Runtime, SlicePattern};
63use datumesh_store::Store;
64
65use crate::client::{Client, ClientConfig};
66use crate::config::Config;
67
68/// A fetched version: the receipt bytes and the parsed receipt.
69type Version = (Vec<u8>, Box<Receipt>);
70
71/// The code of a cross-mesh import the store refused because the namespace is suspended
72/// (`datumesh_store::Error::NamespaceSuspended`: a write refusal, not a failure to reach the
73/// other mesh). It is `not_covered` with this `error` (9.9, 5.5), never an `error` envelope
74/// (since 0.2.2, spec-0.5.0).
75pub(crate) const NAMESPACE_SUSPENDED: ErrorCode = ErrorCode::NamespaceSuspended;
76
77/// A store's refusal of an import `op` as a cross-mesh failure: a suspended namespace is
78/// [`NAMESPACE_SUSPENDED`], anything else `E_INPUT_UNAVAILABLE`.
79fn store_refusal(op: &str, e: datumesh_store::Error) -> ForeignError {
80    let code = match e {
81        datumesh_store::Error::NamespaceSuspended { .. } => NAMESPACE_SUSPENDED,
82        _ => ErrorCode::InputUnavailable,
83    };
84    ForeignError::new(code, format!("{op}: {e}"))
85}
86
87/// The most versions or bindings one walk imports.
88const MAX_WALK: usize = 10_000;
89
90/// The latest instant: the store's latest binding or version is the one answering then.
91const END: &str = "9999-12-31T23:59:59.999999Z";
92
93/// Key documents this mesh has fetched or been given, by host: each the result of
94/// interpreting a retrieval (SPEC 9.3), a failure included.
95#[derive(Default)]
96pub struct KeyCache {
97    #[allow(clippy::type_complexity)]
98    docs: Mutex<HashMap<String, (Result<KeyDoc, CoreError>, Vec<u8>, Instant)>>,
99}
100
101impl std::fmt::Debug for KeyCache {
102    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
103        f.debug_struct("KeyCache").field("hosts", &self.docs.lock().map(|d| d.len()).unwrap_or(0)).finish()
104    }
105}
106
107impl KeyCache {
108    /// Adds (or replaces) `host`'s key document, checked as a 200 response for that host;
109    /// a document that fails the check is not added.
110    pub fn insert(&self, host: &str, doc: &[u8]) -> Result<(), CoreError> {
111        let kd = keys_from_response(host, 200, Some(doc))?;
112        self.docs
113            .lock()
114            .unwrap_or_else(|p| p.into_inner())
115            .insert(host.to_string(), (Ok(kd), doc.to_vec(), Instant::now()));
116        Ok(())
117    }
118
119    /// Records what retrieving `host`'s key document gave (status and body, as SPEC 9.3
120    /// interprets them): a document, or the failure (`E_KEY_UNAVAILABLE`, `E_KEY_DOC`).
121    pub fn insert_response(&self, host: &str, status: u16, body: Option<&[u8]>) {
122        let r = keys_from_response(host, status, body);
123        self.docs
124            .lock()
125            .unwrap_or_else(|p| p.into_inner())
126            .insert(host.to_string(), (r, body.unwrap_or_default().to_vec(), Instant::now()));
127    }
128
129    /// `host`'s document, its bytes and when it was fetched.
130    pub fn get(&self, host: &str) -> Option<(KeyDoc, Vec<u8>, Instant)> {
131        match self.docs.lock().unwrap_or_else(|p| p.into_inner()).get(host) {
132            Some((Ok(d), b, at)) => Some((d.clone(), b.clone(), *at)),
133            _ => None,
134        }
135    }
136
137    /// What is recorded for `host`: its document or the failure.
138    pub fn result(&self, host: &str) -> Option<Result<KeyDoc, CoreError>> {
139        self.docs.lock().unwrap_or_else(|p| p.into_inner()).get(host).map(|(r, _, _)| r.clone())
140    }
141
142    /// Forgets `host`'s document.
143    pub fn remove(&self, host: &str) {
144        self.docs.lock().unwrap_or_else(|p| p.into_inner()).remove(host);
145    }
146}
147
148/// The content of a hosted namespace's marker (see `Foreign::host`).
149pub(crate) fn hosted_marker(host: &str) -> Vec<u8> {
150    format!("datumesh hosted namespace 1\n{host}\n").into_bytes()
151}
152
153/// A failure of cross-mesh resolution: the client's error (its code is the `error`
154/// envelope's).
155pub type ForeignError = crate::client::ClientError;
156
157impl ForeignError {
158    /// As an evaluation error (the engine reports it as `EngineError::Invalid`, which the
159    /// mesh answers `error` with this code).
160    pub(crate) fn eval(self) -> EvalError {
161        EvalError::InvalidInput(CoreError::new(self.code, "$", format!("cross-mesh: {}", self.detail)))
162    }
163}
164
165/// Percent-encodes a value as SPEC 5.1 says (literal characters as themselves).
166pub fn pct(s: &str) -> String {
167    crate::client::pct(s)
168}
169
170/// One microsecond before `t`.
171fn before(t: &str) -> Option<String> {
172    let us = datumesh_formula::calendar::parse_instant(t)?;
173    datumesh_formula::calendar::instant_text(us - 1)
174}
175
176/// The host of a function name or namespace: its first segment.
177pub fn host_of(name: &str) -> &str {
178    name.split('/').next().unwrap_or(name)
179}
180
181struct Confirmed {
182    at: Instant,
183    /// The mesh's clock reading then: answers as of it or earlier never change.
184    instant: String,
185}
186
187/// The cross-mesh resolver of a mesh: the [`Client`]'s fetches and checks, then the import
188/// into the store.
189pub struct Foreign {
190    store: Arc<dyn Store + Send + Sync>,
191    client: Client,
192    clock: Arc<dyn Clock>,
193    owned: Vec<String>,
194    enabled: bool,
195    ttl_binding: Duration,
196    ttl_current: Duration,
197    names: Mutex<HashMap<String, Confirmed>>,
198    cells: Mutex<HashMap<String, Confirmed>>,
199    invalidated: Mutex<Vec<String>>,
200    /// Whether `invalidated` may be non-empty, and whether any cell was imported (checked
201    /// without a lock on every answer).
202    dirty: std::sync::atomic::AtomicBool,
203    any: std::sync::atomic::AtomicBool,
204    deps: Mutex<HashMap<String, Arc<Vec<Cell>>>>,
205    /// The namespaces this mesh hosts that it has seen (a hosted namespace never becomes foreign again).
206    hosted: Mutex<std::collections::HashSet<String>>,
207    /// Counters for /metrics.
208    pub(crate) fetches: std::sync::atomic::AtomicU64,
209    pub(crate) failures: std::sync::atomic::AtomicU64,
210    pub(crate) imported: std::sync::atomic::AtomicU64,
211}
212
213impl std::fmt::Debug for Foreign {
214    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
215        f.debug_struct("Foreign").field("owned", &self.owned).field("enabled", &self.enabled).finish_non_exhaustive()
216    }
217}
218
219enum Fetched {
220    Receipt(Vec<u8>, Box<Receipt>),
221    NotCovered,
222}
223
224impl Foreign {
225    pub(crate) fn new(
226        config: &Config,
227        store: Arc<dyn Store + Send + Sync>,
228        keys: Arc<KeyCache>,
229        clock: Arc<dyn Clock>,
230    ) -> Foreign {
231        let cc = ClientConfig {
232            peers: config.peers.clone(),
233            allowed: config.cross_mesh_hosts.clone(),
234            timeout: config.peer_timeout,
235            key_ttl: config.ttl.key_doc,
236            key_refetch: config.ttl.key_refetch,
237            mesh_ttl: config.ttl.mesh_doc,
238        };
239        Foreign {
240            store,
241            client: Client::with_keys(cc, keys),
242            clock,
243            owned: config.namespaces.clone(),
244            enabled: config.cross_mesh,
245            ttl_binding: config.ttl.binding,
246            ttl_current: config.ttl.current,
247            names: Mutex::new(HashMap::new()),
248            cells: Mutex::new(HashMap::new()),
249            invalidated: Mutex::new(Vec::new()),
250            dirty: Default::default(),
251            any: Default::default(),
252            deps: Mutex::new(HashMap::new()),
253            hosted: Mutex::new(Default::default()),
254            fetches: Default::default(),
255            failures: Default::default(),
256            imported: Default::default(),
257        }
258    }
259
260    /// The client it fetches and checks with.
261    pub fn client(&self) -> &Client {
262        &self.client
263    }
264
265    /// Whether `name` (a function name) is under a host this mesh does not own, and
266    /// cross-mesh resolution is on (and allows that host).
267    pub fn is_foreign(&self, name: &str) -> bool {
268        let host = host_of(name);
269        self.enabled && !self.owned.iter().any(|h| h == host) && self.client.allowed(host) && !self.is_hosted(host)
270    }
271
272    /// The store's record that `host` is hosted here (Build 2 Part 4, P1): a blob whose content is
273    /// [`hosted_marker`], so the mark needs no table of its own. Positive answers are kept in memory.
274    fn is_hosted(&self, host: &str) -> bool {
275        if self.hosted.lock().unwrap_or_else(|p| p.into_inner()).contains(host) {
276            return true;
277        }
278        let key = datumesh_core::sha256_hex(&hosted_marker(host));
279        let hosted = matches!(self.store.blob(&key), Ok(Some(_)));
280        if hosted {
281            self.hosted.lock().unwrap_or_else(|p| p.into_inner()).insert(host.to_string());
282        }
283        hosted
284    }
285
286    /// Makes `host` hosted on this mesh (Build 2 Part 4, P1): its names and cells are then the store's,
287    /// and this mesh never asks the publisher for them again. Called once an accepted bundle is written.
288    pub(crate) fn host(&self, host: &str) -> Result<(), String> {
289        self.store.put_blob(&hosted_marker(host)).map_err(|e| format!("hosted marker of {host}: {e}"))?;
290        self.hosted.lock().unwrap_or_else(|p| p.into_inner()).insert(host.to_string());
291        Ok(())
292    }
293
294    /// Whether any foreign cell was ever imported (lineage checks are skipped otherwise).
295    pub fn any_cells(&self) -> bool {
296        self.any.load(std::sync::atomic::Ordering::Acquire)
297    }
298
299    /// The cells whose versions grew since the last call: the caller reports each to the
300    /// engine (`stored_version_added`).
301    pub fn take_invalidated(&self) -> Vec<String> {
302        if !self.dirty.swap(false, std::sync::atomic::Ordering::AcqRel) {
303            return Vec::new();
304        }
305        std::mem::take(&mut *self.invalidated.lock().unwrap_or_else(|p| p.into_inner()))
306    }
307
308    fn counted<T>(&self, r: Result<T, ForeignError>) -> Result<T, ForeignError> {
309        self.fetches.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
310        if r.is_err() {
311            self.failures.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
312        }
313        r
314    }
315
316    /// The key document of `host` (see [`Client::key_document`]).
317    pub fn keys_for(&self, host: &str, refresh: bool) -> Result<KeyDoc, ForeignError> {
318        self.counted(self.client.key_document(host, refresh))
319    }
320
321    /// The mesh document of `host`, resolved with its key document (SPEC 9.6), cached.
322    pub fn mesh(&self, host: &str) -> Result<MeshDoc, ForeignError> {
323        self.counted(self.client.resolve(host))
324    }
325
326    /// Brings the bindings of a foreign `name` up to date (when not confirmed within the TTL).
327    pub fn ensure_name(&self, name: &str) -> Result<(), ForeignError> {
328        if !self.is_foreign(name) {
329            return Ok(());
330        }
331        if let Some(c) = self.names.lock().unwrap_or_else(|p| p.into_inner()).get(name) {
332            if c.at.elapsed() < self.ttl_binding {
333                return Ok(());
334            }
335        }
336        let now = self.clock.now();
337        let host = host_of(name);
338        let local = self
339            .store
340            .resolve_binding(name, END)
341            .map_err(|e| ForeignError::unavailable(format!("store: {e}")))?
342            .map(|b| (b.fn_hash, b.tx));
343        let mut chain = Vec::new();
344        let mut at: Option<String> = None;
345        while let Some(b) = self.counted(self.client.binding(host, name, at.as_deref()))? {
346            let b = (b.fn_hash, b.since);
347            if Some(&b) == local.as_ref() {
348                break;
349            }
350            if chain.len() >= MAX_WALK {
351                return Err(ForeignError::unavailable(format!("{name}: more than {MAX_WALK} bindings")));
352            }
353            at = Some(before(&b.1).ok_or_else(|| ForeignError::unavailable("a binding at the first instant"))?);
354            let stop = at.as_deref() < Some("0001-01-01T00:00:00.000000Z");
355            chain.push(b);
356            if stop {
357                break;
358            }
359        }
360        if let (Some(oldest), Some(l)) = (chain.last(), &local) {
361            if oldest.1 <= l.1 {
362                return Err(ForeignError::unavailable(format!("{name}: the other mesh's bindings do not extend ours")));
363            }
364        }
365        for (fn_hash, since) in chain.iter().rev() {
366            self.import_descriptor(host, fn_hash)?;
367            self.store.bind_name(name, fn_hash, since).map_err(|e| store_refusal(&format!("bind {name}"), e))?;
368        }
369        self.names
370            .lock()
371            .unwrap_or_else(|p| p.into_inner())
372            .insert(name.to_string(), Confirmed { at: Instant::now(), instant: now });
373        Ok(())
374    }
375
376    fn import_descriptor(&self, host: &str, fn_hash: &str) -> Result<(), ForeignError> {
377        if self.store.descriptor(fn_hash).is_some() {
378            return Ok(());
379        }
380        let body = self.counted(self.client.descriptor(host, fn_hash))?;
381        let h = self
382            .store
383            .put_descriptor(&body)
384            .map_err(|e| ForeignError::new(ErrorCode::FnHashMismatch, e.to_string()))?;
385        if h != fn_hash {
386            return Err(ForeignError::new(ErrorCode::FnHashMismatch, format!("{host} gave the descriptor {h}")));
387        }
388        Ok(())
389    }
390
391    /// The other mesh's answer for `cell` as of `asof` (now when `None`), checked as an
392    /// envelope against the request and the signer's key document.
393    fn fetch_cell(&self, cell: &Cell, asof: Option<&str>) -> Result<Fetched, ForeignError> {
394        let host = host_of(&cell.ns);
395        let reference = CellRef {
396            ns: cell.ns.clone(),
397            fn_name: cell.fn_name.clone(),
398            args: cell.args.clone(),
399            asof: asof.map(str::to_string),
400        };
401        let uri = format_uri(&reference);
402        let request = Request::new(&cell.id(), asof).map_err(|_| ForeignError::unavailable("request"))?;
403        let f = match self.counted(self.client.cell(host, &uri["cell://".len()..], &request)) {
404            Ok(f) => f,
405            Err(e) if e.code == ErrorCode::Envelope => return Err(ForeignError::unavailable(e.detail)),
406            Err(e) => return Err(e),
407        };
408        match (f.answer.outcome.as_str(), f.answer.receipt) {
409            ("ok" | "stale", Some(r)) => {
410                let bytes = datumesh_core::json::parse(&f.body)
411                    .ok()
412                    .and_then(|v| v.get("receipt").map(datumesh_core::json::Value::to_jcs))
413                    .ok_or_else(|| ForeignError::unavailable("receipt"))?;
414                Ok(Fetched::Receipt(bytes, Box::new(r)))
415            }
416            ("not_covered", _) => Ok(Fetched::NotCovered),
417            (o, _) => Err(ForeignError::unavailable(format!("{host}: {o}"))),
418        }
419    }
420
421    /// The versions of `cell` its mesh lists (9.8) after `after_tx`, with their receipts, when
422    /// its mesh document has the versions endpoint; `Ok(None)` when it has none.
423    fn listed_versions(&self, cell: &Cell, after_tx: Option<&str>) -> Result<Option<Vec<Version>>, ForeignError> {
424        let host = host_of(&cell.ns);
425        let mesh = self.mesh(host)?;
426        if !mesh.endpoints.contains_key("versions") {
427            return Ok(None);
428        }
429        let reference =
430            CellRef { ns: cell.ns.clone(), fn_name: cell.fn_name.clone(), args: cell.args.clone(), asof: None };
431        let uri = format_uri(&reference);
432        let mut rest = uri["cell://".len()..].to_string();
433        if let Some(t) = after_tx
434            .and_then(datumesh_formula::calendar::parse_instant)
435            .and_then(|us| datumesh_formula::calendar::instant_text(us + 1))
436        {
437            rest.push(if rest.contains('?') { '&' } else { '?' });
438            rest.push_str(&format!("from={t}"));
439        }
440        let mut page = self.counted(self.client.versions(host, &rest))?;
441        let mut out = Vec::new();
442        loop {
443            if page.cell.get("fn_hash").and_then(datumesh_core::json::Value::as_str) != Some(cell.fn_hash.as_str()) {
444                return Err(ForeignError::unavailable(format!("{host}: the versions of another function")));
445            }
446            for v in &page.versions {
447                let bytes = self.counted(self.client.receipt(host, &v.receipt))?;
448                let r = Receipt::from_json(&bytes).map_err(|e| ForeignError::new(e.code(), e.to_string()))?;
449                if r.cell().id() != cell.id() || r.tx() != v.tx {
450                    return Err(ForeignError::unavailable(format!("{host}: a version of another cell")));
451                }
452                out.push((bytes, Box::new(r)));
453                if out.len() > MAX_WALK {
454                    return Err(ForeignError::unavailable(format!("{host}: more than {MAX_WALK} versions")));
455                }
456            }
457            match page.next.clone() {
458                Some(n) => page = self.counted(self.client.versions_at(&n))?,
459                None => break,
460            }
461        }
462        Ok(Some(out))
463    }
464
465    /// Brings the versions of a foreign stored cell up to date (when not confirmed within the
466    /// TTL). `Ok(true)` when versions were added.
467    pub fn ensure_cell(&self, cell: &Cell) -> Result<bool, ForeignError> {
468        let id = cell.id();
469        if let Some(c) = self.cells.lock().unwrap_or_else(|p| p.into_inner()).get(&id) {
470            if c.at.elapsed() < self.ttl_current {
471                return Ok(false);
472            }
473        }
474        let now = self.clock.now();
475        let name = cell.function_name();
476        let current = self
477            .store
478            .resolve_binding(&name, &now)
479            .map_err(|e| ForeignError::unavailable(format!("store: {e}")))?
480            .map(|b| b.fn_hash);
481        if current.as_deref() != Some(cell.fn_hash.as_str()) {
482            if self.cells.lock().unwrap_or_else(|p| p.into_inner()).contains_key(&id) {
483                // A cell of an earlier binding, imported while current: its versions are final.
484                return Ok(false);
485            }
486            return Err(ForeignError::unavailable(format!(
487                "{name}: a cell of an earlier binding is not resolved in 0.1.x"
488            )));
489        }
490        let local = self.store.latest(&id).map_err(|e| ForeignError::unavailable(format!("store: {e}")))?;
491        // Oldest first.
492        let chain: Vec<(Vec<u8>, Box<Receipt>)> =
493            match self.listed_versions(cell, local.as_ref().map(|v| v.tx.as_str()))? {
494                Some(listed) => listed,
495                None => {
496                    let mut chain: Vec<(Vec<u8>, Box<Receipt>)> = Vec::new();
497                    let mut at: Option<String> = None;
498                    loop {
499                        match self.fetch_cell(cell, at.as_deref())? {
500                            Fetched::NotCovered => break,
501                            Fetched::Receipt(bytes, r) => {
502                                if local.as_ref().is_some_and(|v| v.receipt_hash == r.hash()) {
503                                    break;
504                                }
505                                if chain.iter().any(|(_, c)| c.hash() == r.hash()) || chain.len() >= MAX_WALK {
506                                    return Err(ForeignError::unavailable(format!(
507                                        "{name}: the other mesh's history does not end"
508                                    )));
509                                }
510                                let start = std::cmp::max(r.tx(), r.asof()).to_string();
511                                let next = before(&start);
512                                chain.push((bytes, r));
513                                match next {
514                                    Some(t) => at = Some(t),
515                                    None => break,
516                                }
517                            }
518                        }
519                    }
520                    chain.reverse();
521                    chain
522                }
523            };
524        if let (Some((_, oldest)), Some(l)) = (chain.first(), &local) {
525            if oldest.tx() <= l.tx.as_str() {
526                return Err(ForeignError::unavailable(format!("{name}: the other mesh's versions do not extend ours")));
527            }
528        }
529        let added = !chain.is_empty();
530        for (bytes, r) in &chain {
531            self.ensure_namespace(r.signer_host())?;
532            let h = self.store.put_receipt(bytes).map_err(|e| store_refusal("put_receipt", e))?;
533            self.store.put_version(&id, r.tx(), &h).map_err(|e| store_refusal("put_version", e))?;
534            self.imported.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
535        }
536        if added {
537            self.invalidated.lock().unwrap_or_else(|p| p.into_inner()).push(id.clone());
538            self.dirty.store(true, std::sync::atomic::Ordering::Release);
539        }
540        self.cells.lock().unwrap_or_else(|p| p.into_inner()).insert(id, Confirmed { at: Instant::now(), instant: now });
541        self.any.store(true, std::sync::atomic::Ordering::Release);
542        Ok(added)
543    }
544
545    /// Puts the signer host's key document (as cached, fetched from that host) in the store,
546    /// unless the store's is the same. Never for a host this mesh owns.
547    fn ensure_namespace(&self, host: &str) -> Result<(), ForeignError> {
548        if self.owned.iter().any(|h| h == host) {
549            return Ok(());
550        }
551        self.keys_for(host, false)?;
552        self.store_key_document(host)
553    }
554
555    /// Before this mesh computes a function under a host it does not own (a formula of
556    /// another mesh, evaluated here): the publisher's key document, as cached (fetched again
557    /// after its TTL), put in the store, where the engine reads its declarations (SPEC 8.5,
558    /// spec-0.4.3). No HTTP response from the host is `E_FOREIGN_UNAVAILABLE`, its detail
559    /// first in the error's `detail` ([`ForeignError::foreign_detail`]). Nothing for a
560    /// namespace this mesh owns, or with cross-mesh resolution off. Since 0.2.1.
561    pub fn ensure_publisher(&self, ns: &str) -> Result<(), ForeignError> {
562        if !self.is_foreign(ns) {
563            return Ok(());
564        }
565        let host = host_of(ns);
566        self.counted(self.client.publisher_key_document(host))?;
567        self.store_key_document(host)
568    }
569
570    /// The cached key document of `host`, put in the store unless the store's is the same.
571    fn store_key_document(&self, host: &str) -> Result<(), ForeignError> {
572        let bytes = self
573            .client
574            .key_document_bytes(host)
575            .ok_or_else(|| ForeignError::new(ErrorCode::KeyUnavailable, host.to_string()))?;
576        let stored = self.store.namespace(host).map_err(|e| ForeignError::unavailable(format!("store: {e}")))?;
577        if stored.as_ref().map(|n| n.keydoc.as_slice()) != Some(bytes.as_slice()) {
578            self.store
579                .put_namespace(host, &bytes, &self.clock.now())
580                .map_err(|e| ForeignError::new(ErrorCode::KeyDoc, format!("put_namespace {host}: {e}")))?;
581        }
582        Ok(())
583    }
584
585    /// The foreign stored cells a receipt rests on, through its lineage in the store
586    /// (bounded; cached by receipt hash).
587    fn foreign_deps(&self, receipt_hash: &str) -> Arc<Vec<Cell>> {
588        if let Some(d) = self.deps.lock().unwrap_or_else(|p| p.into_inner()).get(receipt_hash) {
589            return d.clone();
590        }
591        let mut out = Vec::new();
592        let mut seen = HashSet::new();
593        let mut todo = vec![receipt_hash.to_string()];
594        while let Some(h) = todo.pop() {
595            if !seen.insert(h.clone()) || seen.len() > 100_000 {
596                continue;
597            }
598            if h.starts_with("slice:") {
599                if let Some(m) = self.store.manifest(&h) {
600                    if let Ok(m) = datumesh_core::Manifest::from_json(&m) {
601                        todo.extend(m.members().iter().cloned());
602                    }
603                }
604                continue;
605            }
606            let Some(bytes) = self.store.receipt(&h) else {
607                continue;
608            };
609            let Ok(r) = Receipt::from_json(&bytes) else { continue };
610            if self.is_foreign(&r.cell().ns) && r.inputs().is_empty() {
611                out.push(r.cell().clone());
612            } else {
613                todo.extend(r.inputs().iter().cloned());
614            }
615        }
616        let d = Arc::new(out);
617        let mut deps = self.deps.lock().unwrap_or_else(|p| p.into_inner());
618        if deps.len() > 100_000 {
619            deps.clear();
620        }
621        deps.insert(receipt_hash.to_string(), d.clone());
622        d
623    }
624
625    /// Confirms the foreign cells an answer rests on, for an answer as of `asof`: those not
626    /// confirmed within the TTL and confirmed before `asof` are fetched again. `Ok(true)` when
627    /// versions were added (the caller answers again).
628    pub fn refresh_deps(&self, receipt_hash: &str, asof: &str) -> Result<bool, ForeignError> {
629        if !self.any_cells() {
630            return Ok(false);
631        }
632        let mut added = false;
633        for cell in self.foreign_deps(receipt_hash).iter() {
634            let stale = match self.cells.lock().unwrap_or_else(|p| p.into_inner()).get(&cell.id()) {
635                Some(c) => c.at.elapsed() >= self.ttl_current && asof > c.instant.as_str(),
636                None => true,
637            };
638            if stale {
639                added |= self.ensure_cell(cell)?;
640            }
641        }
642        Ok(added)
643    }
644
645    /// For a request about a foreign name as of `asof` (now when `None`): its bindings and,
646    /// for a stored function's cell, its versions, brought up to date when needed.
647    pub fn prepare(&self, cell: &Cell, stored: bool, asof: Option<&str>) -> Result<(), ForeignError> {
648        if !self.is_foreign(&cell.function_name()) || !stored {
649            return Ok(());
650        }
651        let fresh = match self.cells.lock().unwrap_or_else(|p| p.into_inner()).get(&cell.id()) {
652            Some(c) => c.at.elapsed() < self.ttl_current || asof.is_some_and(|a| a <= c.instant.as_str()),
653            None => false,
654        };
655        if !fresh {
656            self.ensure_cell(cell)?;
657        }
658        Ok(())
659    }
660}
661
662/// A runtime with cross-mesh reads in front of it (see the module documentation).
663pub struct CrossMesh {
664    inner: Arc<dyn Runtime>,
665    foreign: Arc<Foreign>,
666}
667
668impl CrossMesh {
669    /// `inner`, reading foreign names through `foreign`.
670    pub fn new(inner: Arc<dyn Runtime>, foreign: Arc<Foreign>) -> CrossMesh {
671        CrossMesh { inner, foreign }
672    }
673}
674
675impl Runtime for CrossMesh {
676    fn lang(&self) -> &str {
677        self.inner.lang()
678    }
679
680    fn evaluate(
681        &self,
682        descriptor: &FunctionDescriptor,
683        cell: &Cell,
684        inputs: &mut dyn Inputs,
685        budget: &mut Budget,
686    ) -> Result<Scalar, EvalError> {
687        // Since 0.2.1: the publisher's declarations, for licence inheritance (SPEC 8.5).
688        self.foreign.ensure_publisher(&cell.ns).map_err(ForeignError::eval)?;
689        for name in &descriptor.inputs {
690            self.foreign.ensure_name(name).map_err(ForeignError::eval)?;
691        }
692        let mut w = Through { inner: inputs, foreign: &self.foreign };
693        self.inner.evaluate(descriptor, cell, &mut w, budget)
694    }
695
696    fn asof_dependent(&self, descriptor: &FunctionDescriptor) -> bool {
697        self.inner.asof_dependent(descriptor)
698    }
699}
700
701/// The inputs of one evaluation, foreign reads imported first.
702struct Through<'a> {
703    inner: &'a mut dyn Inputs,
704    foreign: &'a Foreign,
705}
706
707impl Through<'_> {
708    fn pre(&mut self, name: &str, args: &Args, at: Option<&str>) -> Result<(), EvalError> {
709        if !self.foreign.is_foreign(name) {
710            return Ok(());
711        }
712        self.foreign.ensure_name(name).map_err(ForeignError::eval)?;
713        let Some(b) = self.inner.binding_peek(name, at)? else {
714            return Ok(());
715        };
716        if b.descriptor.lang != "stored" {
717            return Ok(());
718        }
719        let (ns, f) = name.rsplit_once('/').unwrap_or((name, ""));
720        let cell = Cell { ns: ns.to_string(), fn_name: f.to_string(), fn_hash: b.fn_hash.clone(), args: args.clone() };
721        self.foreign.ensure_cell(&cell).map_err(ForeignError::eval)?;
722        Ok(())
723    }
724}
725
726impl Inputs for Through<'_> {
727    fn read(&mut self, fn_name: &str, args: &Args) -> Result<Scalar, EvalError> {
728        self.pre(fn_name, args, None)?;
729        self.inner.read(fn_name, args)
730    }
731
732    fn read_cell(&mut self, fn_name: &str, args: &Args) -> Result<Input, EvalError> {
733        self.pre(fn_name, args, None)?;
734        self.inner.read_cell(fn_name, args)
735    }
736
737    fn read_asof(&mut self, fn_name: &str, args: &Args, t: &str) -> Result<Input, EvalError> {
738        self.pre(fn_name, args, Some(t))?;
739        self.inner.read_asof(fn_name, args, t)
740    }
741
742    fn read_slice(&mut self, fn_name: &str, pattern: &SlicePattern) -> Result<Vec<Member>, EvalError> {
743        if self.foreign.is_foreign(fn_name) {
744            self.foreign.ensure_name(fn_name).map_err(ForeignError::eval)?;
745            if let Some(b) = self.inner.binding_peek(fn_name, None)? {
746                if b.descriptor.lang == "stored" {
747                    return Err(ForeignError::unavailable(format!(
748                        "{fn_name}: slices of foreign stored functions are not read in 0.1.0"
749                    ))
750                    .eval());
751                }
752            }
753        }
754        self.inner.read_slice(fn_name, pattern)
755    }
756
757    fn read_versions(&mut self, fn_name: &str, args: &Args, from: &str, to: &str) -> Result<Vec<Input>, EvalError> {
758        self.pre(fn_name, args, None)?;
759        self.inner.read_versions(fn_name, args, from, to)
760    }
761
762    fn read_pinned(&mut self, fn_name: &str, fn_hash: &str, args: &Args) -> Result<Input, EvalError> {
763        // A pinned read (`super`, 16.3) resolves no name: nothing to fetch by name first. The cell it
764        // reads is the engine's own (a foreign mesh's cell is read through its own namespace).
765        self.inner.read_pinned(fn_name, fn_hash, args)
766    }
767
768    fn binding(&mut self, fn_name: &str, at: Option<&str>) -> Result<Option<FnBinding>, EvalError> {
769        self.foreign.ensure_name(fn_name).map_err(ForeignError::eval)?;
770        self.inner.binding(fn_name, at)
771    }
772
773    fn asof(&mut self) -> String {
774        self.inner.asof()
775    }
776
777    fn binding_peek(&mut self, fn_name: &str, at: Option<&str>) -> Result<Option<FnBinding>, EvalError> {
778        self.foreign.ensure_name(fn_name).map_err(ForeignError::eval)?;
779        self.inner.binding_peek(fn_name, at)
780    }
781
782    fn asof_compare(&mut self, t: &str) -> Result<std::cmp::Ordering, EvalError> {
783        self.inner.asof_compare(t)
784    }
785
786    fn read_blob(&mut self, sha256: &str, length: u64) -> Result<Vec<u8>, EvalError> {
787        self.inner.read_blob(sha256, length)
788    }
789}