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