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/// A failure of cross-mesh resolution: the client's error (its code is the `error`
149/// envelope's).
150pub type ForeignError = crate::client::ClientError;
151
152impl ForeignError {
153    /// As an evaluation error (the engine reports it as `EngineError::Invalid`, which the
154    /// mesh answers `error` with this code).
155    pub(crate) fn eval(self) -> EvalError {
156        EvalError::InvalidInput(CoreError::new(self.code, "$", format!("cross-mesh: {}", self.detail)))
157    }
158}
159
160/// Percent-encodes a value as SPEC 5.1 says (literal characters as themselves).
161pub fn pct(s: &str) -> String {
162    crate::client::pct(s)
163}
164
165/// One microsecond before `t`.
166fn before(t: &str) -> Option<String> {
167    let us = datumesh_formula::calendar::parse_instant(t)?;
168    datumesh_formula::calendar::instant_text(us - 1)
169}
170
171/// The host of a function name or namespace: its first segment.
172pub fn host_of(name: &str) -> &str {
173    name.split('/').next().unwrap_or(name)
174}
175
176struct Confirmed {
177    at: Instant,
178    /// The mesh's clock reading then: answers as of it or earlier never change.
179    instant: String,
180}
181
182/// The cross-mesh resolver of a mesh: the [`Client`]'s fetches and checks, then the import
183/// into the store.
184pub struct Foreign {
185    store: Arc<dyn Store + Send + Sync>,
186    client: Client,
187    clock: Arc<dyn Clock>,
188    owned: Vec<String>,
189    enabled: bool,
190    ttl_binding: Duration,
191    ttl_current: Duration,
192    names: Mutex<HashMap<String, Confirmed>>,
193    cells: Mutex<HashMap<String, Confirmed>>,
194    invalidated: Mutex<Vec<String>>,
195    /// Whether `invalidated` may be non-empty, and whether any cell was imported (checked
196    /// without a lock on every answer).
197    dirty: std::sync::atomic::AtomicBool,
198    any: std::sync::atomic::AtomicBool,
199    deps: Mutex<HashMap<String, Arc<Vec<Cell>>>>,
200    /// Counters for /metrics.
201    pub(crate) fetches: std::sync::atomic::AtomicU64,
202    pub(crate) failures: std::sync::atomic::AtomicU64,
203    pub(crate) imported: std::sync::atomic::AtomicU64,
204}
205
206impl std::fmt::Debug for Foreign {
207    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
208        f.debug_struct("Foreign").field("owned", &self.owned).field("enabled", &self.enabled).finish_non_exhaustive()
209    }
210}
211
212enum Fetched {
213    Receipt(Vec<u8>, Box<Receipt>),
214    NotCovered,
215}
216
217impl Foreign {
218    pub(crate) fn new(
219        config: &Config,
220        store: Arc<dyn Store + Send + Sync>,
221        keys: Arc<KeyCache>,
222        clock: Arc<dyn Clock>,
223    ) -> Foreign {
224        let cc = ClientConfig {
225            peers: config.peers.clone(),
226            allowed: config.cross_mesh_hosts.clone(),
227            timeout: config.peer_timeout,
228            key_ttl: config.ttl.key_doc,
229            key_refetch: config.ttl.key_refetch,
230            mesh_ttl: config.ttl.mesh_doc,
231        };
232        Foreign {
233            store,
234            client: Client::with_keys(cc, keys),
235            clock,
236            owned: config.namespaces.clone(),
237            enabled: config.cross_mesh,
238            ttl_binding: config.ttl.binding,
239            ttl_current: config.ttl.current,
240            names: Mutex::new(HashMap::new()),
241            cells: Mutex::new(HashMap::new()),
242            invalidated: Mutex::new(Vec::new()),
243            dirty: Default::default(),
244            any: Default::default(),
245            deps: Mutex::new(HashMap::new()),
246            fetches: Default::default(),
247            failures: Default::default(),
248            imported: Default::default(),
249        }
250    }
251
252    /// The client it fetches and checks with.
253    pub fn client(&self) -> &Client {
254        &self.client
255    }
256
257    /// Whether `name` (a function name) is under a host this mesh does not own, and
258    /// cross-mesh resolution is on (and allows that host).
259    pub fn is_foreign(&self, name: &str) -> bool {
260        let host = host_of(name);
261        self.enabled && !self.owned.iter().any(|h| h == host) && self.client.allowed(host)
262    }
263
264    /// Whether any foreign cell was ever imported (lineage checks are skipped otherwise).
265    pub fn any_cells(&self) -> bool {
266        self.any.load(std::sync::atomic::Ordering::Acquire)
267    }
268
269    /// The cells whose versions grew since the last call: the caller reports each to the
270    /// engine (`stored_version_added`).
271    pub fn take_invalidated(&self) -> Vec<String> {
272        if !self.dirty.swap(false, std::sync::atomic::Ordering::AcqRel) {
273            return Vec::new();
274        }
275        std::mem::take(&mut *self.invalidated.lock().unwrap_or_else(|p| p.into_inner()))
276    }
277
278    fn counted<T>(&self, r: Result<T, ForeignError>) -> Result<T, ForeignError> {
279        self.fetches.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
280        if r.is_err() {
281            self.failures.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
282        }
283        r
284    }
285
286    /// The key document of `host` (see [`Client::key_document`]).
287    pub fn keys_for(&self, host: &str, refresh: bool) -> Result<KeyDoc, ForeignError> {
288        self.counted(self.client.key_document(host, refresh))
289    }
290
291    /// The mesh document of `host`, resolved with its key document (SPEC 9.6), cached.
292    pub fn mesh(&self, host: &str) -> Result<MeshDoc, ForeignError> {
293        self.counted(self.client.resolve(host))
294    }
295
296    /// Brings the bindings of a foreign `name` up to date (when not confirmed within the TTL).
297    pub fn ensure_name(&self, name: &str) -> Result<(), ForeignError> {
298        if !self.is_foreign(name) {
299            return Ok(());
300        }
301        if let Some(c) = self.names.lock().unwrap_or_else(|p| p.into_inner()).get(name) {
302            if c.at.elapsed() < self.ttl_binding {
303                return Ok(());
304            }
305        }
306        let now = self.clock.now();
307        let host = host_of(name);
308        let local = self
309            .store
310            .resolve_binding(name, END)
311            .map_err(|e| ForeignError::unavailable(format!("store: {e}")))?
312            .map(|b| (b.fn_hash, b.tx));
313        let mut chain = Vec::new();
314        let mut at: Option<String> = None;
315        while let Some(b) = self.counted(self.client.binding(host, name, at.as_deref()))? {
316            let b = (b.fn_hash, b.since);
317            if Some(&b) == local.as_ref() {
318                break;
319            }
320            if chain.len() >= MAX_WALK {
321                return Err(ForeignError::unavailable(format!("{name}: more than {MAX_WALK} bindings")));
322            }
323            at = Some(before(&b.1).ok_or_else(|| ForeignError::unavailable("a binding at the first instant"))?);
324            let stop = at.as_deref() < Some("0001-01-01T00:00:00.000000Z");
325            chain.push(b);
326            if stop {
327                break;
328            }
329        }
330        if let (Some(oldest), Some(l)) = (chain.last(), &local) {
331            if oldest.1 <= l.1 {
332                return Err(ForeignError::unavailable(format!("{name}: the other mesh's bindings do not extend ours")));
333            }
334        }
335        for (fn_hash, since) in chain.iter().rev() {
336            self.import_descriptor(host, fn_hash)?;
337            self.store.bind_name(name, fn_hash, since).map_err(|e| store_refusal(&format!("bind {name}"), e))?;
338        }
339        self.names
340            .lock()
341            .unwrap_or_else(|p| p.into_inner())
342            .insert(name.to_string(), Confirmed { at: Instant::now(), instant: now });
343        Ok(())
344    }
345
346    fn import_descriptor(&self, host: &str, fn_hash: &str) -> Result<(), ForeignError> {
347        if self.store.descriptor(fn_hash).is_some() {
348            return Ok(());
349        }
350        let body = self.counted(self.client.descriptor(host, fn_hash))?;
351        let h = self
352            .store
353            .put_descriptor(&body)
354            .map_err(|e| ForeignError::new(ErrorCode::FnHashMismatch, e.to_string()))?;
355        if h != fn_hash {
356            return Err(ForeignError::new(ErrorCode::FnHashMismatch, format!("{host} gave the descriptor {h}")));
357        }
358        Ok(())
359    }
360
361    /// The other mesh's answer for `cell` as of `asof` (now when `None`), checked as an
362    /// envelope against the request and the signer's key document.
363    fn fetch_cell(&self, cell: &Cell, asof: Option<&str>) -> Result<Fetched, ForeignError> {
364        let host = host_of(&cell.ns);
365        let reference = CellRef {
366            ns: cell.ns.clone(),
367            fn_name: cell.fn_name.clone(),
368            args: cell.args.clone(),
369            asof: asof.map(str::to_string),
370        };
371        let uri = format_uri(&reference);
372        let request = Request::new(&cell.id(), asof).map_err(|_| ForeignError::unavailable("request"))?;
373        let f = match self.counted(self.client.cell(host, &uri["cell://".len()..], &request)) {
374            Ok(f) => f,
375            Err(e) if e.code == ErrorCode::Envelope => return Err(ForeignError::unavailable(e.detail)),
376            Err(e) => return Err(e),
377        };
378        match (f.answer.outcome.as_str(), f.answer.receipt) {
379            ("ok" | "stale", Some(r)) => {
380                let bytes = datumesh_core::json::parse(&f.body)
381                    .ok()
382                    .and_then(|v| v.get("receipt").map(datumesh_core::json::Value::to_jcs))
383                    .ok_or_else(|| ForeignError::unavailable("receipt"))?;
384                Ok(Fetched::Receipt(bytes, Box::new(r)))
385            }
386            ("not_covered", _) => Ok(Fetched::NotCovered),
387            (o, _) => Err(ForeignError::unavailable(format!("{host}: {o}"))),
388        }
389    }
390
391    /// The versions of `cell` its mesh lists (9.8) after `after_tx`, with their receipts, when
392    /// its mesh document has the versions endpoint; `Ok(None)` when it has none.
393    fn listed_versions(&self, cell: &Cell, after_tx: Option<&str>) -> Result<Option<Vec<Version>>, ForeignError> {
394        let host = host_of(&cell.ns);
395        let mesh = self.mesh(host)?;
396        if !mesh.endpoints.contains_key("versions") {
397            return Ok(None);
398        }
399        let reference =
400            CellRef { ns: cell.ns.clone(), fn_name: cell.fn_name.clone(), args: cell.args.clone(), asof: None };
401        let uri = format_uri(&reference);
402        let mut rest = uri["cell://".len()..].to_string();
403        if let Some(t) = after_tx
404            .and_then(datumesh_formula::calendar::parse_instant)
405            .and_then(|us| datumesh_formula::calendar::instant_text(us + 1))
406        {
407            rest.push(if rest.contains('?') { '&' } else { '?' });
408            rest.push_str(&format!("from={t}"));
409        }
410        let mut page = self.counted(self.client.versions(host, &rest))?;
411        let mut out = Vec::new();
412        loop {
413            if page.cell.get("fn_hash").and_then(datumesh_core::json::Value::as_str) != Some(cell.fn_hash.as_str()) {
414                return Err(ForeignError::unavailable(format!("{host}: the versions of another function")));
415            }
416            for v in &page.versions {
417                let bytes = self.counted(self.client.receipt(host, &v.receipt))?;
418                let r = Receipt::from_json(&bytes).map_err(|e| ForeignError::new(e.code(), e.to_string()))?;
419                if r.cell().id() != cell.id() || r.tx() != v.tx {
420                    return Err(ForeignError::unavailable(format!("{host}: a version of another cell")));
421                }
422                out.push((bytes, Box::new(r)));
423                if out.len() > MAX_WALK {
424                    return Err(ForeignError::unavailable(format!("{host}: more than {MAX_WALK} versions")));
425                }
426            }
427            match page.next.clone() {
428                Some(n) => page = self.counted(self.client.versions_at(&n))?,
429                None => break,
430            }
431        }
432        Ok(Some(out))
433    }
434
435    /// Brings the versions of a foreign stored cell up to date (when not confirmed within the
436    /// TTL). `Ok(true)` when versions were added.
437    pub fn ensure_cell(&self, cell: &Cell) -> Result<bool, ForeignError> {
438        let id = cell.id();
439        if let Some(c) = self.cells.lock().unwrap_or_else(|p| p.into_inner()).get(&id) {
440            if c.at.elapsed() < self.ttl_current {
441                return Ok(false);
442            }
443        }
444        let now = self.clock.now();
445        let name = cell.function_name();
446        let current = self
447            .store
448            .resolve_binding(&name, &now)
449            .map_err(|e| ForeignError::unavailable(format!("store: {e}")))?
450            .map(|b| b.fn_hash);
451        if current.as_deref() != Some(cell.fn_hash.as_str()) {
452            if self.cells.lock().unwrap_or_else(|p| p.into_inner()).contains_key(&id) {
453                // A cell of an earlier binding, imported while current: its versions are final.
454                return Ok(false);
455            }
456            return Err(ForeignError::unavailable(format!(
457                "{name}: a cell of an earlier binding is not resolved in 0.1.x"
458            )));
459        }
460        let local = self.store.latest(&id).map_err(|e| ForeignError::unavailable(format!("store: {e}")))?;
461        // Oldest first.
462        let chain: Vec<(Vec<u8>, Box<Receipt>)> =
463            match self.listed_versions(cell, local.as_ref().map(|v| v.tx.as_str()))? {
464                Some(listed) => listed,
465                None => {
466                    let mut chain: Vec<(Vec<u8>, Box<Receipt>)> = Vec::new();
467                    let mut at: Option<String> = None;
468                    loop {
469                        match self.fetch_cell(cell, at.as_deref())? {
470                            Fetched::NotCovered => break,
471                            Fetched::Receipt(bytes, r) => {
472                                if local.as_ref().is_some_and(|v| v.receipt_hash == r.hash()) {
473                                    break;
474                                }
475                                if chain.iter().any(|(_, c)| c.hash() == r.hash()) || chain.len() >= MAX_WALK {
476                                    return Err(ForeignError::unavailable(format!(
477                                        "{name}: the other mesh's history does not end"
478                                    )));
479                                }
480                                let start = std::cmp::max(r.tx(), r.asof()).to_string();
481                                let next = before(&start);
482                                chain.push((bytes, r));
483                                match next {
484                                    Some(t) => at = Some(t),
485                                    None => break,
486                                }
487                            }
488                        }
489                    }
490                    chain.reverse();
491                    chain
492                }
493            };
494        if let (Some((_, oldest)), Some(l)) = (chain.first(), &local) {
495            if oldest.tx() <= l.tx.as_str() {
496                return Err(ForeignError::unavailable(format!("{name}: the other mesh's versions do not extend ours")));
497            }
498        }
499        let added = !chain.is_empty();
500        for (bytes, r) in &chain {
501            self.ensure_namespace(r.signer_host())?;
502            let h = self.store.put_receipt(bytes).map_err(|e| store_refusal("put_receipt", e))?;
503            self.store.put_version(&id, r.tx(), &h).map_err(|e| store_refusal("put_version", e))?;
504            self.imported.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
505        }
506        if added {
507            self.invalidated.lock().unwrap_or_else(|p| p.into_inner()).push(id.clone());
508            self.dirty.store(true, std::sync::atomic::Ordering::Release);
509        }
510        self.cells.lock().unwrap_or_else(|p| p.into_inner()).insert(id, Confirmed { at: Instant::now(), instant: now });
511        self.any.store(true, std::sync::atomic::Ordering::Release);
512        Ok(added)
513    }
514
515    /// Puts the signer host's key document (as cached, fetched from that host) in the store,
516    /// unless the store's is the same. Never for a host this mesh owns.
517    fn ensure_namespace(&self, host: &str) -> Result<(), ForeignError> {
518        if self.owned.iter().any(|h| h == host) {
519            return Ok(());
520        }
521        self.keys_for(host, false)?;
522        self.store_key_document(host)
523    }
524
525    /// Before this mesh computes a function under a host it does not own (a formula of
526    /// another mesh, evaluated here): the publisher's key document, as cached (fetched again
527    /// after its TTL), put in the store, where the engine reads its declarations (SPEC 8.5,
528    /// spec-0.4.3). No HTTP response from the host is `E_FOREIGN_UNAVAILABLE`, its detail
529    /// first in the error's `detail` ([`ForeignError::foreign_detail`]). Nothing for a
530    /// namespace this mesh owns, or with cross-mesh resolution off. Since 0.2.1.
531    pub fn ensure_publisher(&self, ns: &str) -> Result<(), ForeignError> {
532        if !self.is_foreign(ns) {
533            return Ok(());
534        }
535        let host = host_of(ns);
536        self.counted(self.client.publisher_key_document(host))?;
537        self.store_key_document(host)
538    }
539
540    /// The cached key document of `host`, put in the store unless the store's is the same.
541    fn store_key_document(&self, host: &str) -> Result<(), ForeignError> {
542        let bytes = self
543            .client
544            .key_document_bytes(host)
545            .ok_or_else(|| ForeignError::new(ErrorCode::KeyUnavailable, host.to_string()))?;
546        let stored = self.store.namespace(host).map_err(|e| ForeignError::unavailable(format!("store: {e}")))?;
547        if stored.as_ref().map(|n| n.keydoc.as_slice()) != Some(bytes.as_slice()) {
548            self.store
549                .put_namespace(host, &bytes, &self.clock.now())
550                .map_err(|e| ForeignError::new(ErrorCode::KeyDoc, format!("put_namespace {host}: {e}")))?;
551        }
552        Ok(())
553    }
554
555    /// The foreign stored cells a receipt rests on, through its lineage in the store
556    /// (bounded; cached by receipt hash).
557    fn foreign_deps(&self, receipt_hash: &str) -> Arc<Vec<Cell>> {
558        if let Some(d) = self.deps.lock().unwrap_or_else(|p| p.into_inner()).get(receipt_hash) {
559            return d.clone();
560        }
561        let mut out = Vec::new();
562        let mut seen = HashSet::new();
563        let mut todo = vec![receipt_hash.to_string()];
564        while let Some(h) = todo.pop() {
565            if !seen.insert(h.clone()) || seen.len() > 100_000 {
566                continue;
567            }
568            if h.starts_with("slice:") {
569                if let Some(m) = self.store.manifest(&h) {
570                    if let Ok(m) = datumesh_core::Manifest::from_json(&m) {
571                        todo.extend(m.members().iter().cloned());
572                    }
573                }
574                continue;
575            }
576            let Some(bytes) = self.store.receipt(&h) else {
577                continue;
578            };
579            let Ok(r) = Receipt::from_json(&bytes) else { continue };
580            if self.is_foreign(&r.cell().ns) && r.inputs().is_empty() {
581                out.push(r.cell().clone());
582            } else {
583                todo.extend(r.inputs().iter().cloned());
584            }
585        }
586        let d = Arc::new(out);
587        let mut deps = self.deps.lock().unwrap_or_else(|p| p.into_inner());
588        if deps.len() > 100_000 {
589            deps.clear();
590        }
591        deps.insert(receipt_hash.to_string(), d.clone());
592        d
593    }
594
595    /// Confirms the foreign cells an answer rests on, for an answer as of `asof`: those not
596    /// confirmed within the TTL and confirmed before `asof` are fetched again. `Ok(true)` when
597    /// versions were added (the caller answers again).
598    pub fn refresh_deps(&self, receipt_hash: &str, asof: &str) -> Result<bool, ForeignError> {
599        if !self.any_cells() {
600            return Ok(false);
601        }
602        let mut added = false;
603        for cell in self.foreign_deps(receipt_hash).iter() {
604            let stale = match self.cells.lock().unwrap_or_else(|p| p.into_inner()).get(&cell.id()) {
605                Some(c) => c.at.elapsed() >= self.ttl_current && asof > c.instant.as_str(),
606                None => true,
607            };
608            if stale {
609                added |= self.ensure_cell(cell)?;
610            }
611        }
612        Ok(added)
613    }
614
615    /// For a request about a foreign name as of `asof` (now when `None`): its bindings and,
616    /// for a stored function's cell, its versions, brought up to date when needed.
617    pub fn prepare(&self, cell: &Cell, stored: bool, asof: Option<&str>) -> Result<(), ForeignError> {
618        if !self.is_foreign(&cell.function_name()) || !stored {
619            return Ok(());
620        }
621        let fresh = match self.cells.lock().unwrap_or_else(|p| p.into_inner()).get(&cell.id()) {
622            Some(c) => c.at.elapsed() < self.ttl_current || asof.is_some_and(|a| a <= c.instant.as_str()),
623            None => false,
624        };
625        if !fresh {
626            self.ensure_cell(cell)?;
627        }
628        Ok(())
629    }
630}
631
632/// A runtime with cross-mesh reads in front of it (see the module documentation).
633pub struct CrossMesh {
634    inner: Arc<dyn Runtime>,
635    foreign: Arc<Foreign>,
636}
637
638impl CrossMesh {
639    /// `inner`, reading foreign names through `foreign`.
640    pub fn new(inner: Arc<dyn Runtime>, foreign: Arc<Foreign>) -> CrossMesh {
641        CrossMesh { inner, foreign }
642    }
643}
644
645impl Runtime for CrossMesh {
646    fn lang(&self) -> &str {
647        self.inner.lang()
648    }
649
650    fn evaluate(
651        &self,
652        descriptor: &FunctionDescriptor,
653        cell: &Cell,
654        inputs: &mut dyn Inputs,
655        budget: &mut Budget,
656    ) -> Result<Scalar, EvalError> {
657        // Since 0.2.1: the publisher's declarations, for licence inheritance (SPEC 8.5).
658        self.foreign.ensure_publisher(&cell.ns).map_err(ForeignError::eval)?;
659        for name in &descriptor.inputs {
660            self.foreign.ensure_name(name).map_err(ForeignError::eval)?;
661        }
662        let mut w = Through { inner: inputs, foreign: &self.foreign };
663        self.inner.evaluate(descriptor, cell, &mut w, budget)
664    }
665
666    fn asof_dependent(&self, descriptor: &FunctionDescriptor) -> bool {
667        self.inner.asof_dependent(descriptor)
668    }
669}
670
671/// The inputs of one evaluation, foreign reads imported first.
672struct Through<'a> {
673    inner: &'a mut dyn Inputs,
674    foreign: &'a Foreign,
675}
676
677impl Through<'_> {
678    fn pre(&mut self, name: &str, args: &Args, at: Option<&str>) -> Result<(), EvalError> {
679        if !self.foreign.is_foreign(name) {
680            return Ok(());
681        }
682        self.foreign.ensure_name(name).map_err(ForeignError::eval)?;
683        let Some(b) = self.inner.binding_peek(name, at)? else {
684            return Ok(());
685        };
686        if b.descriptor.lang != "stored" {
687            return Ok(());
688        }
689        let (ns, f) = name.rsplit_once('/').unwrap_or((name, ""));
690        let cell = Cell { ns: ns.to_string(), fn_name: f.to_string(), fn_hash: b.fn_hash.clone(), args: args.clone() };
691        self.foreign.ensure_cell(&cell).map_err(ForeignError::eval)?;
692        Ok(())
693    }
694}
695
696impl Inputs for Through<'_> {
697    fn read(&mut self, fn_name: &str, args: &Args) -> Result<Scalar, EvalError> {
698        self.pre(fn_name, args, None)?;
699        self.inner.read(fn_name, args)
700    }
701
702    fn read_cell(&mut self, fn_name: &str, args: &Args) -> Result<Input, EvalError> {
703        self.pre(fn_name, args, None)?;
704        self.inner.read_cell(fn_name, args)
705    }
706
707    fn read_asof(&mut self, fn_name: &str, args: &Args, t: &str) -> Result<Input, EvalError> {
708        self.pre(fn_name, args, Some(t))?;
709        self.inner.read_asof(fn_name, args, t)
710    }
711
712    fn read_slice(&mut self, fn_name: &str, pattern: &SlicePattern) -> Result<Vec<Member>, EvalError> {
713        if self.foreign.is_foreign(fn_name) {
714            self.foreign.ensure_name(fn_name).map_err(ForeignError::eval)?;
715            if let Some(b) = self.inner.binding_peek(fn_name, None)? {
716                if b.descriptor.lang == "stored" {
717                    return Err(ForeignError::unavailable(format!(
718                        "{fn_name}: slices of foreign stored functions are not read in 0.1.0"
719                    ))
720                    .eval());
721                }
722            }
723        }
724        self.inner.read_slice(fn_name, pattern)
725    }
726
727    fn read_versions(&mut self, fn_name: &str, args: &Args, from: &str, to: &str) -> Result<Vec<Input>, EvalError> {
728        self.pre(fn_name, args, None)?;
729        self.inner.read_versions(fn_name, args, from, to)
730    }
731
732    fn read_pinned(&mut self, fn_name: &str, fn_hash: &str, args: &Args) -> Result<Input, EvalError> {
733        // A pinned read (`super`, 16.3) resolves no name: nothing to fetch by name first. The cell it
734        // reads is the engine's own (a foreign mesh's cell is read through its own namespace).
735        self.inner.read_pinned(fn_name, fn_hash, args)
736    }
737
738    fn binding(&mut self, fn_name: &str, at: Option<&str>) -> Result<Option<FnBinding>, EvalError> {
739        self.foreign.ensure_name(fn_name).map_err(ForeignError::eval)?;
740        self.inner.binding(fn_name, at)
741    }
742
743    fn asof(&mut self) -> String {
744        self.inner.asof()
745    }
746
747    fn binding_peek(&mut self, fn_name: &str, at: Option<&str>) -> Result<Option<FnBinding>, EvalError> {
748        self.foreign.ensure_name(fn_name).map_err(ForeignError::eval)?;
749        self.inner.binding_peek(fn_name, at)
750    }
751
752    fn asof_compare(&mut self, t: &str) -> Result<std::cmp::Ordering, EvalError> {
753        self.inner.asof_compare(t)
754    }
755
756    fn read_blob(&mut self, sha256: &str, length: u64) -> Result<Vec<u8>, EvalError> {
757        self.inner.read_blob(sha256, length)
758    }
759}