Skip to main content

datumesh_http/
client.rs

1//! The store-less client of other meshes (for `datumesh-local` and for this mesh's cross-mesh
2//! reads): fetch a host's key document and mesh document, its bindings, a cell's envelope (by
3//! call, URI or pin), slice pages, batches, receipts, descriptors, manifests, blobs and
4//! versions, and **check** each with the core: the envelope against the request
5//! (`check_answer`, `check_slice_answer`, `check_batch`), every receipt's signature against
6//! its signer's key document (fetched from the signer's own host, never from the mesh that
7//! served it), and content-addressed bytes against their hash. Nothing is stored; the import
8//! into a store is [`crate::foreign::Foreign`]'s, a layer on top.
9//!
10//! **Blocking.** The client is synchronous (ureq, rustls with the Mozilla roots, no redirects,
11//! a time limit per request, bodies bounded): this mesh's engine reads foreign cells from
12//! inside an evaluation, which runs on a blocking thread, and `datumesh-local`'s CLI is
13//! synchronous too. An async caller runs it on `tokio::task::spawn_blocking`, as the mesh's
14//! own handlers do with the engine. [`Client`] is cheap to clone and shares its caches.
15//!
16//! **Caches.** Key documents (default 300 s; a key id the cached document lacks refetches it,
17//! at most every 10 s) and mesh documents (300 s), in memory. Nothing else is cached here.
18//!
19//! **Allowlist.** With [`ClientConfig::allowed`] set, only those hosts are fetched from
20//! (anything else is refused with `E_INPUT_UNAVAILABLE` before any request).
21
22use std::collections::{BTreeMap, BTreeSet, HashMap};
23use std::sync::{Arc, Mutex};
24use std::time::{Duration, Instant};
25
26use datumesh_core::json::{self, Value};
27use datumesh_core::{
28    check_answer, check_batch, check_slice_answer, format_reference, keys_from_response, lexical, parse_reference,
29    resolve_mesh, Answer, Batch, ErrorCode, ForeignDetail, FunctionDescriptor, KeyDoc, Keys, Manifest, MeshDoc,
30    Receipt, Reference, Request, Retrieval, Slice, SliceRequest,
31};
32
33use crate::foreign::KeyCache;
34
35/// The largest body read from another mesh.
36const MAX_BODY: u64 = 64 << 20;
37/// The largest key or mesh document read (SPEC 9.3's suggested bound).
38const MAX_DOC: u64 = 256 << 10;
39
40/// A failure of the client: the code of the `error` envelope a mesh would give for it, and why.
41#[derive(Clone, Debug)]
42pub struct ClientError {
43    /// `E_INPUT_UNAVAILABLE` (the other mesh is down, answered otherwise, or is not allowed),
44    /// `E_MESH_DOC`, `E_KEY_UNAVAILABLE` or `E_KEY_DOC` (resolving its host), `E_ENVELOPE` (an
45    /// answer that fails the check), or what checking a receipt gave.
46    pub code: ErrorCode,
47    /// Why.
48    pub detail: String,
49}
50
51impl ClientError {
52    pub(crate) fn new(code: ErrorCode, detail: impl Into<String>) -> ClientError {
53        ClientError { code, detail: detail.into() }
54    }
55    pub(crate) fn unavailable(detail: impl Into<String>) -> ClientError {
56        ClientError::new(ErrorCode::InputUnavailable, detail)
57    }
58
59    /// `E_FOREIGN_UNAVAILABLE` (spec-0.4.3): no HTTP response came back from the other mesh.
60    /// `detail` starts with the envelope's `detail` name, then `": "` and why.
61    pub(crate) fn foreign(detail: ForeignDetail, why: impl std::fmt::Display) -> ClientError {
62        ClientError::new(ErrorCode::ForeignUnavailable, format!("{}: {why}", detail.as_str()))
63    }
64
65    /// For `E_FOREIGN_UNAVAILABLE` (spec-0.4.3), the envelope's `detail` (`offline`, `network`,
66    /// `dns`, `tls`, `timeout`, `refused`): the start of [`ClientError::detail`]. `None` for
67    /// every other code. Since 0.2.1.
68    pub fn foreign_detail(&self) -> Option<ForeignDetail> {
69        if self.code != ErrorCode::ForeignUnavailable {
70            return None;
71        }
72        ForeignDetail::from_name(self.detail.split(':').next().unwrap_or(""))
73    }
74}
75
76/// Why no HTTP response came back (spec-0.4.3's `detail` of `E_FOREIGN_UNAVAILABLE`), when the
77/// failure is one of those; `None` for a failure after a response began, or of another kind.
78fn transport_detail(e: &ureq::Error) -> Option<ForeignDetail> {
79    use std::io::ErrorKind;
80    Some(match e {
81        ureq::Error::HostNotFound => ForeignDetail::Dns,
82        ureq::Error::Timeout(_) => ForeignDetail::Timeout,
83        // The system resolver's failure arrives as an I/O error, not `HostNotFound`.
84        ureq::Error::Io(io) if io.to_string().contains("failed to lookup address information") => ForeignDetail::Dns,
85        // Windows' resolver (CONTRACT-1.8b H3): WSAHOST_NOT_FOUND (11001) to WSANO_DATA (11004),
86        // or its text.
87        ureq::Error::Io(io)
88            if io.raw_os_error().is_some_and(|c| (11001..=11004).contains(&c))
89                || io.to_string().to_ascii_lowercase().contains("no such host is known") =>
90        {
91            ForeignDetail::Dns
92        }
93        ureq::Error::Io(io) => match io.kind() {
94            ErrorKind::ConnectionRefused => ForeignDetail::Refused,
95            ErrorKind::TimedOut => ForeignDetail::Timeout,
96            _ => ForeignDetail::Network,
97        },
98        ureq::Error::ConnectionFailed => ForeignDetail::Network,
99        ureq::Error::Tls(_) | ureq::Error::Rustls(_) | ureq::Error::Pem(_) | ureq::Error::TlsRequired => {
100            ForeignDetail::Tls
101        }
102        _ => return None,
103    })
104}
105
106impl std::fmt::Display for ClientError {
107    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
108        write!(f, "{}: {}", self.code.as_str(), self.detail)
109    }
110}
111
112impl std::error::Error for ClientError {}
113
114/// The client's configuration.
115#[non_exhaustive]
116#[derive(Clone, Debug)]
117pub struct ClientConfig {
118    /// Origins to use instead of `https://<host>` for some hosts (tests, private networks).
119    pub peers: BTreeMap<String, String>,
120    /// When set, the only hosts fetched from.
121    pub allowed: Option<Vec<String>>,
122    /// The time limit of one request (default 10 s).
123    pub timeout: Duration,
124    /// Key documents' lifetime in the cache (default 300 s).
125    pub key_ttl: Duration,
126    /// The shortest interval between two fetches of one host's key document (default 10 s).
127    pub key_refetch: Duration,
128    /// Mesh documents' lifetime in the cache (default 300 s).
129    pub mesh_ttl: Duration,
130}
131
132impl Default for ClientConfig {
133    fn default() -> Self {
134        ClientConfig {
135            peers: BTreeMap::new(),
136            allowed: None,
137            timeout: Duration::from_secs(10),
138            key_ttl: Duration::from_secs(300),
139            key_refetch: Duration::from_secs(10),
140            mesh_ttl: Duration::from_secs(300),
141        }
142    }
143}
144
145/// A binding another mesh states (SPEC 9.7).
146#[derive(Clone, Debug, PartialEq, Eq)]
147pub struct RemoteBinding {
148    /// The function hash.
149    pub fn_hash: String,
150    /// When the binding began.
151    pub since: String,
152}
153
154/// An answer fetched and checked: its HTTP status, its body as received, and the checked answer.
155#[derive(Clone, Debug)]
156pub struct Fetched {
157    /// The HTTP status.
158    pub status: u16,
159    /// The body.
160    pub body: Vec<u8>,
161    /// The answer, checked against the request.
162    pub answer: Answer,
163}
164
165/// One version a mesh lists (SPEC 9.8).
166#[derive(Clone, Debug, PartialEq, Eq)]
167pub struct VersionEntry {
168    /// The version's `tx`.
169    pub tx: String,
170    /// Its receipt's `asof`.
171    pub asof: String,
172    /// Its receipt hash.
173    pub receipt: String,
174}
175
176/// A page of the versions endpoint (SPEC 9.8).
177#[derive(Clone, Debug)]
178pub struct Versions {
179    /// The cell (4.4).
180    pub cell: Value,
181    /// The versions, ascending by `tx`.
182    pub versions: Vec<VersionEntry>,
183    /// The following page's URL.
184    pub next: Option<String>,
185}
186
187struct Inner {
188    agent: ureq::Agent,
189    cfg: ClientConfig,
190    keys: Arc<KeyCache>,
191    meshes: Mutex<HashMap<String, (MeshDoc, Instant)>>,
192}
193
194/// The client (see the module documentation).
195#[derive(Clone)]
196pub struct Client {
197    inner: Arc<Inner>,
198}
199
200impl std::fmt::Debug for Client {
201    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
202        f.debug_struct("Client").field("allowed", &self.inner.cfg.allowed).finish_non_exhaustive()
203    }
204}
205
206/// Percent-encodes a value as SPEC 5.1 says (literal characters as themselves).
207pub fn pct(s: &str) -> String {
208    let mut out = String::with_capacity(s.len());
209    for b in s.bytes() {
210        if b.is_ascii_alphanumeric() || matches!(b, b'-' | b'.' | b'_' | b'~' | b':') {
211            out.push(b as char);
212        } else {
213            out.push_str(&format!("%{b:02X}"));
214        }
215    }
216    out
217}
218
219fn host_of(name: &str) -> &str {
220    name.split('/').next().unwrap_or(name)
221}
222
223impl Client {
224    /// A client with this configuration.
225    pub fn new(cfg: ClientConfig) -> Client {
226        Client::with_keys(cfg, Arc::new(KeyCache::default()))
227    }
228
229    /// A client sharing a key cache (the mesh's, so `POST /verify` sees what it fetched).
230    pub fn with_keys(cfg: ClientConfig, keys: Arc<KeyCache>) -> Client {
231        let agent: ureq::Agent = ureq::Agent::config_builder()
232            .max_redirects(0)
233            .http_status_as_error(false)
234            .timeout_global(Some(cfg.timeout))
235            .user_agent(concat!("datumesh-http/", env!("CARGO_PKG_VERSION")))
236            .build()
237            .into();
238        Client { inner: Arc::new(Inner { agent, cfg, keys, meshes: Mutex::new(HashMap::new()) }) }
239    }
240
241    /// The key cache.
242    pub fn keys(&self) -> &Arc<KeyCache> {
243        &self.inner.keys
244    }
245
246    /// Whether `host` may be fetched from.
247    pub fn allowed(&self, host: &str) -> bool {
248        self.inner.cfg.allowed.as_ref().is_none_or(|a| a.iter().any(|h| h == host))
249    }
250
251    fn check_host(&self, host: &str) -> Result<(), ClientError> {
252        if lexical::check_dns_name(host, "$").is_err() {
253            return Err(ClientError::new(ErrorCode::KeyUnavailable, format!("{host:?} is not a DNS name")));
254        }
255        if !self.allowed(host) {
256            return Err(ClientError::unavailable(format!("{host} is not an allowed host")));
257        }
258        Ok(())
259    }
260
261    /// `GET url` (an `https://<host>/...` URL; the origin replaced for a configured peer):
262    /// status and body, at most `limit` bytes.
263    pub fn get(&self, url: &str, limit: u64) -> Result<(u16, Vec<u8>), String> {
264        self.request(url, None, limit)
265    }
266
267    fn request(&self, url: &str, post: Option<&[u8]>, limit: u64) -> Result<(u16, Vec<u8>), String> {
268        self.request_with_detail(url, post, limit).map_err(|(m, _)| m)
269    }
270
271    /// A request to another mesh whose failure is a [`ClientError`]: `E_FOREIGN_UNAVAILABLE`
272    /// (spec-0.4.3) with its detail (`offline`, `network`, `dns`, `tls`, `timeout`, `refused`)
273    /// when no HTTP response came back, `E_INPUT_UNAVAILABLE` for a failure after a response
274    /// began (a body that could not be read, a host not allowed). A mesh that answered, with
275    /// any status, is not this function's failure. Since the cross-mesh failure change.
276    fn fetch(&self, url: &str, post: Option<&[u8]>, limit: u64) -> Result<(u16, Vec<u8>), ClientError> {
277        self.request_with_detail(url, post, limit).map_err(|(m, d)| match d {
278            Some(d) => ClientError::foreign(d, m),
279            None => ClientError::unavailable(m),
280        })
281    }
282
283    /// [`request`](Client::request), its failure with the `E_FOREIGN_UNAVAILABLE` detail when no
284    /// HTTP response came back.
285    fn request_with_detail(
286        &self,
287        url: &str,
288        post: Option<&[u8]>,
289        limit: u64,
290    ) -> Result<(u16, Vec<u8>), (String, Option<ForeignDetail>)> {
291        let mut target = url.to_string();
292        if let Some(rest) = url.strip_prefix("https://") {
293            let host = rest.split(['/', '?']).next().unwrap_or("");
294            if !self.allowed(host) {
295                return Err((format!("{host} is not an allowed host"), None));
296            }
297            if let Some(origin) = self.inner.cfg.peers.get(host) {
298                target = format!("{origin}{}", &rest[host.len()..]);
299            }
300        }
301        let resp = match post {
302            None => self.inner.agent.get(&target).call(),
303            Some(b) => self.inner.agent.post(&target).header("content-type", "application/json").send(b),
304        };
305        let mut resp = resp.map_err(|e| (format!("{url}: {e}"), transport_detail(&e)))?;
306        let status = resp.status().as_u16();
307        let body =
308            resp.body_mut().with_config().limit(limit).read_to_vec().map_err(|e| (format!("{url}: {e}"), None))?;
309        Ok((status, body))
310    }
311
312    /// The key document of `host` (SPEC 9.3), from the cache while it is fresh, else fetched;
313    /// `refresh` fetches it again unless it was fetched within the refetch interval.
314    pub fn key_document(&self, host: &str, refresh: bool) -> Result<KeyDoc, ClientError> {
315        self.key_document_with(host, refresh)
316    }
317
318    /// [`key_document`](Client::key_document) of a function's publisher, before this mesh
319    /// computes the function (its declarations, SPEC 8.5): a fetch that got no HTTP response
320    /// is `E_FOREIGN_UNAVAILABLE` (spec-0.4.3), its detail first in
321    /// [`ClientError::detail`] ([`ClientError::foreign_detail`]). Since 0.2.1.
322    pub fn publisher_key_document(&self, host: &str) -> Result<KeyDoc, ClientError> {
323        self.key_document_with(host, false)
324    }
325
326    fn key_document_with(&self, host: &str, refresh: bool) -> Result<KeyDoc, ClientError> {
327        if let Some((doc, _, at)) = self.inner.keys.get(host) {
328            let age = at.elapsed();
329            if (!refresh && age < self.inner.cfg.key_ttl) || (refresh && age < self.inner.cfg.key_refetch) {
330                return Ok(doc);
331            }
332        }
333        self.check_host(host)?;
334        let url = format!("https://{host}/.well-known/datumesh.json");
335        let (status, body) = self.request_with_detail(&url, None, MAX_DOC).map_err(|(e, d)| match d {
336            Some(d) => ClientError::foreign(d, e),
337            None => ClientError::new(ErrorCode::KeyUnavailable, e),
338        })?;
339        let doc = keys_from_response(host, status, if status == 200 { Some(&body) } else { None })
340            .map_err(|e| ClientError::new(e.code(), e.to_string()))?;
341        self.inner.keys.insert(host, &body).map_err(|e| ClientError::new(e.code(), e.to_string()))?;
342        Ok(doc)
343    }
344
345    /// The bytes of `host`'s key document, fetched now (not from the cache) and given at most
346    /// `within` (the domain proof of `POST /bundles`, Build 2 Part 4, P1: 5 s). Nothing is cached.
347    /// A failure to get any HTTP answer, or a non-200 answer, is `E_KEY_UNAVAILABLE`.
348    pub fn key_document_live(&self, host: &str, within: Duration) -> Result<Vec<u8>, ClientError> {
349        self.check_host(host)?;
350        let url = format!("https://{host}/.well-known/datumesh.json");
351        let mut target = url.clone();
352        if let Some(origin) = self.inner.cfg.peers.get(host) {
353            target = format!("{origin}/.well-known/datumesh.json");
354        }
355        let resp = self
356            .inner
357            .agent
358            .get(&target)
359            .config()
360            .timeout_global(Some(within))
361            .build()
362            .call()
363            .map_err(|e| ClientError::new(ErrorCode::KeyUnavailable, format!("{url}: {e}")))?;
364        let mut resp = resp;
365        if resp.status().as_u16() != 200 {
366            return Err(ClientError::new(
367                ErrorCode::KeyUnavailable,
368                format!("{url}: status {}", resp.status().as_u16()),
369            ));
370        }
371        resp.body_mut()
372            .with_config()
373            .limit(MAX_DOC)
374            .read_to_vec()
375            .map_err(|e| ClientError::new(ErrorCode::KeyUnavailable, format!("{url}: {e}")))
376    }
377
378    /// The bytes of `host`'s key document as last fetched.
379    pub fn key_document_bytes(&self, host: &str) -> Option<Vec<u8>> {
380        self.inner.keys.get(host).map(|(_, b, _)| b)
381    }
382
383    /// The mesh document of `host`, resolved with its key document (SPEC 9.6), cached.
384    pub fn resolve(&self, host: &str) -> Result<MeshDoc, ClientError> {
385        if let Some((m, at)) = self.inner.meshes.lock().unwrap_or_else(|p| p.into_inner()).get(host) {
386            if at.elapsed() < self.inner.cfg.mesh_ttl {
387                return Ok(m.clone());
388            }
389        }
390        self.check_host(host)?;
391        type Got = Result<(u16, Vec<u8>), (String, Option<ForeignDetail>)>;
392        let get = |path: &str| -> Got {
393            let url = format!("https://{host}/.well-known/{path}");
394            self.request_with_detail(&url, None, MAX_DOC)
395        };
396        let keys: Got = get("datumesh.json");
397        let mesh: Got = match &keys {
398            Ok((200, _)) => get("datumesh-mesh.json"),
399            _ => Err((String::new(), None)),
400        };
401        fn ret(r: &Got) -> Retrieval<'_> {
402            match r {
403                Ok((s, b)) => Retrieval::Response { status: *s, body: Some(b.as_slice()) },
404                Err(_) => Retrieval::Failed,
405            }
406        }
407        let resolved = resolve_mesh(host, ret(&keys), ret(&mesh)).map_err(|e| {
408            // No response from the host: E_FOREIGN_UNAVAILABLE with why.
409            for r in [&keys, &mesh] {
410                if let Err((why, Some(d))) = r {
411                    return ClientError::foreign(*d, why);
412                }
413            }
414            let detail = match (&keys, &mesh) {
415                (Err((e, _)), _) | (_, Err((e, _))) if !e.is_empty() => e.clone(),
416                _ => e.to_string(),
417            };
418            ClientError::new(e.code(), detail)
419        })?;
420        if let Ok((_, body)) = &keys {
421            let _ = self.inner.keys.insert(host, body);
422        }
423        let m = resolved.mesh;
424        self.inner
425            .meshes
426            .lock()
427            .unwrap_or_else(|p| p.into_inner())
428            .insert(host.to_string(), (m.clone(), Instant::now()));
429        Ok(m)
430    }
431
432    fn endpoint(&self, host: &str, name: &str, values: &[(&str, &str)]) -> Result<String, ClientError> {
433        self.resolve(host)?
434            .url(name, values)
435            .ok_or_else(|| ClientError::new(ErrorCode::MeshDoc, format!("{host} has no {name} endpoint")))
436    }
437
438    /// The binding of `name` that `host`'s bindings resource states as of `asof` (now when
439    /// `None`), SPEC 9.7.
440    pub fn binding(&self, host: &str, name: &str, asof: Option<&str>) -> Result<Option<RemoteBinding>, ClientError> {
441        let mesh = self.resolve(host)?;
442        let mut url = format!("{}?name={}", mesh.bindings, pct(name));
443        if let Some(a) = asof {
444            url.push_str(&format!("&asof={}", pct(a)));
445        }
446        let (status, body) = self.fetch(&url, None, MAX_DOC)?;
447        if status != 200 {
448            return Err(ClientError::unavailable(format!("{url}: status {status}")));
449        }
450        let v = json::parse(&body).map_err(|e| ClientError::unavailable(format!("{url}: {e}")))?;
451        let Some(b) = v.get("bindings").and_then(|b| b.get(name)) else {
452            if v.get("bindings").and_then(Value::as_object).is_none() {
453                return Err(ClientError::unavailable(format!("{url}: no bindings object")));
454            }
455            return Ok(None);
456        };
457        let h = b.get("fn_hash").and_then(Value::as_str).unwrap_or("");
458        let since = b.get("since").and_then(Value::as_str).unwrap_or("");
459        if lexical::check_hex(h, 64, "$").is_err() || lexical::check_instant(since, "$").is_err() {
460            return Err(ClientError::unavailable(format!("{url}: malformed binding")));
461        }
462        if asof.is_some_and(|a| since > a) {
463            return Err(ClientError::unavailable(format!("{url}: a binding since after the asof")));
464        }
465        Ok(Some(RemoteBinding { fn_hash: h.to_string(), since: since.to_string() }))
466    }
467
468    /// The descriptor `fn_hash` names, from `host` (its hash checked).
469    pub fn descriptor(&self, host: &str, fn_hash: &str) -> Result<Vec<u8>, ClientError> {
470        let url = self.endpoint(host, "descriptor", &[("hash", fn_hash)])?;
471        let (status, body) = self.fetch(&url, None, MAX_BODY)?;
472        if status != 200 {
473            return Err(ClientError::new(ErrorCode::FnUnavailable, format!("{url}: status {status}")));
474        }
475        let d = FunctionDescriptor::from_json(&body).map_err(|e| ClientError::new(e.code(), e.to_string()))?;
476        if d.hash() != fn_hash {
477            return Err(ClientError::new(ErrorCode::FnHashMismatch, format!("{url} gave the descriptor {}", d.hash())));
478        }
479        Ok(body)
480    }
481
482    /// The keys of the signers named in a body (a receipt, an envelope, a page or a batch):
483    /// each signer's key document, from its own host.
484    pub fn keys_for_body(&self, body: &[u8]) -> Keys {
485        let mut hosts = BTreeSet::new();
486        fn walk(v: &Value, hosts: &mut BTreeSet<String>, depth: usize) {
487            if depth > 8 {
488                return;
489            }
490            match v {
491                Value::Object(m) => {
492                    for (k, x) in m {
493                        if k == "computed_by" {
494                            if let Some(s) = x.as_str() {
495                                hosts.insert(s.split('#').next().unwrap_or("").to_string());
496                            }
497                        } else {
498                            walk(x, hosts, depth + 1);
499                        }
500                    }
501                }
502                Value::Array(a) => a.iter().for_each(|x| walk(x, hosts, depth + 1)),
503                _ => {}
504            }
505        }
506        if let Ok(v) = json::parse(body) {
507            walk(&v, &mut hosts, 0);
508        }
509        let mut keys = Keys::new();
510        for h in hosts {
511            match self.key_document(&h, false) {
512                Ok(d) => keys.insert(d),
513                Err(e) => keys.insert_result(&h, Err(datumesh_core::Error::new(e.code, "$", e.detail))),
514            }
515        }
516        keys
517    }
518
519    /// Runs `check` with the signers' keys, fetching them again once when a key id is unknown
520    /// (a rotation).
521    fn checked<T>(&self, body: &[u8], check: impl Fn(&Keys) -> datumesh_core::Result<T>) -> Result<T, ClientError> {
522        let keys = self.keys_for_body(body);
523        match check(&keys) {
524            Err(e) if matches!(e.code(), ErrorCode::KeyUnknown | ErrorCode::KeyNotValid) => {
525                let mut hosts = BTreeSet::new();
526                if let Ok(v) = json::parse(body) {
527                    collect_signers(&v, &mut hosts);
528                }
529                for h in hosts {
530                    let _ = self.key_document(&h, true);
531                }
532                check(&self.keys_for_body(body)).map_err(|e| ClientError::new(e.code(), e.to_string()))
533            }
534            r => r.map_err(|e| ClientError::new(e.code(), e.to_string())),
535        }
536    }
537
538    /// A receipt by its hash from `host`: its hash checked and its signature verified (SPEC
539    /// 10.1 steps 1-6) against its signer's key document.
540    pub fn receipt(&self, host: &str, hash: &str) -> Result<Vec<u8>, ClientError> {
541        let url = self.endpoint(host, "receipt", &[("hash", hash)])?;
542        let (status, body) = self.fetch(&url, None, MAX_BODY)?;
543        if status != 200 {
544            return Err(ClientError::unavailable(format!("{url}: status {status}")));
545        }
546        let h = self.checked(&body, |keys| {
547            let r = datumesh_core::verify(&body, keys, None, None);
548            match r.error() {
549                Some(e) => Err(e),
550                None => Ok(r.hash.unwrap_or_default()),
551            }
552        })?;
553        if h != hash {
554            return Err(ClientError::unavailable(format!("{url} gave the receipt {h}")));
555        }
556        Ok(body)
557    }
558
559    /// A slice manifest from `host` (its entry checked).
560    pub fn manifest(&self, host: &str, slice_id: &str, members_hash: &str) -> Result<Vec<u8>, ClientError> {
561        let url = self.endpoint(host, "manifest", &[("slice_id", slice_id), ("members_hash", members_hash)])?;
562        let (status, body) = self.fetch(&url, None, MAX_BODY)?;
563        if status != 200 {
564            return Err(ClientError::unavailable(format!("{url}: status {status}")));
565        }
566        let m = Manifest::from_json(&body).map_err(|e| ClientError::new(e.code(), e.to_string()))?;
567        if m.entry() != format!("slice:{slice_id}:{members_hash}") {
568            return Err(ClientError::unavailable(format!("{url} gave the manifest {}", m.entry())));
569        }
570        Ok(body)
571    }
572
573    /// Blob content by SHA-256 from `host` (its hash checked).
574    pub fn blob(&self, host: &str, sha256: &str) -> Result<Vec<u8>, ClientError> {
575        let url = self.endpoint(host, "blob", &[("sha256", sha256)])?;
576        let (status, body) = self.fetch(&url, None, MAX_BODY)?;
577        if status != 200 {
578            return Err(ClientError::unavailable(format!("{url}: status {status}")));
579        }
580        if datumesh_core::sha256_hex(&body) != sha256 {
581            return Err(ClientError::new(ErrorCode::BlobMismatch, format!("{url}: content of another hash")));
582        }
583        Ok(body)
584    }
585
586    /// The envelope for `rest` (a cell URI's rest or a call, as the cell endpoint takes it)
587    /// from `host`, checked against `request` (5.5; the host asked is added to it).
588    pub fn cell(&self, host: &str, rest: &str, request: &Request) -> Result<Fetched, ClientError> {
589        let url = self.endpoint(host, "cell", &[("cell", rest)])?;
590        let (status, body) = self.fetch(&url, None, MAX_BODY)?;
591        let req =
592            request.clone().with_mesh(host).map_err(|e| ClientError::new(ErrorCode::Envelope, format!("{e:?}")))?;
593        let answer = self.checked(&body, |keys| check_answer(status, &body, keys, &req))?;
594        Ok(Fetched { status, body, answer })
595    }
596
597    /// The envelope of a reference (pinned or not) from `host`: its URI written by the core,
598    /// the request it describes made from it (the cell id needs the function hash: the pin,
599    /// else the binding `host` states as of the reference's asof).
600    pub fn reference(&self, host: &str, reference: &Reference) -> Result<Fetched, ClientError> {
601        let fn_hash = match &reference.fn_hash {
602            Some(h) => h.clone(),
603            None => {
604                let name = format!("{}/{}", reference.ns, reference.fn_name);
605                self.binding(host, &name, reference.asof.as_deref())?
606                    .ok_or_else(|| ClientError::new(ErrorCode::NameUnbound, name.clone()))?
607                    .fn_hash
608            }
609        };
610        let cell = reference.resolve(&fn_hash).map_err(|e| ClientError::new(e.code(), e.to_string()))?;
611        let mut request = Request::new(&cell.id(), reference.asof.as_deref())
612            .map_err(|e| ClientError::new(ErrorCode::Envelope, format!("{e:?}")))?;
613        if let Some(p) = &reference.fn_hash {
614            request = request.with_pin(p).map_err(|e| ClientError::new(ErrorCode::Envelope, format!("{e:?}")))?;
615        }
616        let uri = format_reference(reference);
617        self.cell(host, &uri["cell://".len()..], &request)
618    }
619
620    /// The slice a slice URI's rest denotes on `host`: the descriptor of its pin, or of the
621    /// name's binding (as of its asof), parsed against.
622    pub fn slice_of(&self, host: &str, rest: &str) -> Result<(Slice, Reference), ClientError> {
623        let uri = format!("cell://{rest}");
624        let path = rest.split('?').next().unwrap_or(rest);
625        let query = rest.split_once('?').map(|(_, q)| q).unwrap_or("");
626        let pin = query.split('&').find_map(|p| p.strip_prefix("fn_hash=")).map(str::to_string);
627        let asof = query.split('&').next_back().and_then(|p| p.strip_prefix("asof=")).map(str::to_string);
628        let fn_hash = match pin {
629            Some(p) => p,
630            None => {
631                self.binding(host, path, asof.as_deref())?
632                    .ok_or_else(|| ClientError::new(ErrorCode::NameUnbound, path.to_string()))?
633                    .fn_hash
634            }
635        };
636        let d = FunctionDescriptor::from_json(&self.descriptor(host, &fn_hash)?)
637            .map_err(|e| ClientError::new(e.code(), e.to_string()))?;
638        let r =
639            parse_reference(&uri, &d.signature.to_value()).map_err(|e| ClientError::new(e.code(), e.to_string()))?;
640        let cell = r.resolve(&fn_hash).map_err(|e| ClientError::new(e.code(), e.to_string()))?;
641        let slice = Slice::from_value(&cell.to_value()).map_err(|e| ClientError::new(e.code(), e.to_string()))?;
642        Ok((slice, r))
643    }
644
645    /// A page of a slice from `host` (5.6): the first page of `rest` (a slice URI's rest), or,
646    /// with `next`, the page that URL names (which must be on `host`), checked against the
647    /// slice `rest` denotes and, for a following page, the cursor `after`.
648    pub fn slice_page(
649        &self,
650        host: &str,
651        rest: &str,
652        next: Option<&str>,
653        after: Option<BTreeMap<String, datumesh_core::Scalar>>,
654    ) -> Result<Fetched, ClientError> {
655        let (slice, r) = self.slice_of(host, rest)?;
656        let url = match next {
657            Some(n) => {
658                if !n.starts_with(&format!("https://{host}/")) {
659                    return Err(ClientError::new(ErrorCode::Envelope, format!("{n} is not on {host}")));
660                }
661                n.to_string()
662            }
663            None => self.endpoint(host, "slice", &[("cell", rest)])?,
664        };
665        let (status, body) = self.fetch(&url, None, MAX_BODY)?;
666        let mut req = SliceRequest::new(slice.id(), r.asof.as_deref())
667            .and_then(|q| q.with_mesh(host))
668            .map_err(|e| ClientError::new(ErrorCode::Envelope, format!("{e:?}")))?;
669        if let Some(p) = &r.fn_hash {
670            req = req.with_pin(p).map_err(|e| ClientError::new(ErrorCode::Envelope, format!("{e:?}")))?;
671        }
672        if let Some(a) = after {
673            req = req.with_after(a);
674        }
675        let answer = self.checked(&body, |keys| check_slice_answer(status, &body, keys, &req))?;
676        Ok(Fetched { status, body, answer })
677    }
678
679    /// The first page of a slice (see [`Client::slice_page`]).
680    pub fn slice(&self, host: &str, rest: &str, next: Option<&str>) -> Result<Fetched, ClientError> {
681        self.slice_page(host, rest, next, None)
682    }
683
684    /// A batch (5.7) to `host`: the requests' rests and the request each describes, checked as
685    /// a whole and item by item.
686    pub fn batch(&self, host: &str, items: &[String], requests: &[Request]) -> Result<Batch, ClientError> {
687        let url = self.endpoint(host, "cells", &[])?;
688        let body = Value::Array(items.iter().map(|i| Value::String(i.clone())).collect()).to_jcs();
689        let (status, resp) = self.fetch(&url, Some(&body), MAX_BODY)?;
690        let reqs: Vec<Request> =
691            requests.iter().map(|r| r.clone().with_mesh(host).unwrap_or_else(|_| r.clone())).collect();
692        self.checked(&resp, |keys| check_batch(status, &resp, keys, &reqs))
693    }
694
695    /// The versions of a stored cell from `host` (9.8): `rest` is its URI's rest without asof.
696    pub fn versions(&self, host: &str, rest: &str) -> Result<Versions, ClientError> {
697        let url = self.endpoint(host, "versions", &[("cell", rest)])?;
698        self.versions_at(&url)
699    }
700
701    /// A page of the versions endpoint at `url` (a `next`).
702    pub fn versions_at(&self, url: &str) -> Result<Versions, ClientError> {
703        let (status, body) = self.fetch(url, None, MAX_BODY)?;
704        let v = json::parse(&body).map_err(|e| ClientError::unavailable(format!("{url}: {e}")))?;
705        if status != 200 {
706            let code = v
707                .get("error")
708                .and_then(Value::as_str)
709                .and_then(ErrorCode::from_code)
710                .unwrap_or(ErrorCode::InputUnavailable);
711            return Err(ClientError::new(code, format!("{url}: status {status}")));
712        }
713        let cell = v.get("cell").cloned().ok_or_else(|| ClientError::unavailable(format!("{url}: no cell")))?;
714        let mut versions = Vec::new();
715        if let Some(Value::Array(vs)) = v.get("versions") {
716            for x in vs {
717                let s = |k: &str| x.get(k).and_then(Value::as_str).map(str::to_string);
718                match (s("tx"), s("asof"), s("receipt")) {
719                    (Some(tx), Some(asof), Some(receipt)) => versions.push(VersionEntry { tx, asof, receipt }),
720                    _ => return Err(ClientError::unavailable(format!("{url}: a malformed version"))),
721                }
722            }
723        }
724        Ok(Versions { cell, versions, next: v.get("next").and_then(Value::as_str).map(str::to_string) })
725    }
726
727    /// A receipt fetched by the client, parsed.
728    pub fn parse_receipt(bytes: &[u8]) -> Result<Receipt, ClientError> {
729        Receipt::from_json(bytes).map_err(|e| ClientError::new(e.code(), e.to_string()))
730    }
731}
732
733fn collect_signers(v: &Value, hosts: &mut BTreeSet<String>) {
734    match v {
735        Value::Object(m) => {
736            for (k, x) in m {
737                if k == "computed_by" {
738                    if let Some(s) = x.as_str() {
739                        hosts.insert(s.split('#').next().unwrap_or("").to_string());
740                    }
741                } else {
742                    collect_signers(x, hosts);
743                }
744            }
745        }
746        Value::Array(a) => a.iter().for_each(|x| collect_signers(x, hosts)),
747        _ => {}
748    }
749}
750
751/// The host of a function name.
752pub fn name_host(name: &str) -> &str {
753    host_of(name)
754}
755
756#[cfg(test)]
757mod transport_detail_tests {
758    use super::*;
759    use std::io::{self, ErrorKind};
760
761    /// CONTRACT-1.8b H3, test 1: a Windows resolver error code (WSAHOST_NOT_FOUND, 11001) is `dns`.
762    #[test]
763    fn a_windows_resolver_code_is_dns() {
764        let e = ureq::Error::Io(io::Error::from_raw_os_error(11001));
765        assert_eq!(transport_detail(&e), Some(ForeignDetail::Dns));
766    }
767
768    /// CONTRACT-1.8b H3, test 2: the text "No such host is known" is `dns`.
769    #[test]
770    fn no_such_host_is_known_is_dns() {
771        let e = ureq::Error::Io(io::Error::other("No such host is known. (os error 11001)"));
772        assert_eq!(transport_detail(&e), Some(ForeignDetail::Dns));
773    }
774
775    /// CONTRACT-1.8b H3, test 3: everything else is unchanged.
776    #[test]
777    fn a_refused_connection_stays_refused() {
778        let e = ureq::Error::Io(io::Error::from(ErrorKind::ConnectionRefused));
779        assert_eq!(transport_detail(&e), Some(ForeignDetail::Refused));
780    }
781}