Skip to main content

datumesh_http/
call.rs

1//! What a request names: a cell URI's `<rest>` (SPEC 5.3) or a call (SPEC 5.8), resolved to
2//! one canonical reference, pinned to a function hash or not (spec-0.4.2).
3//!
4//! # The forms `/cell` accepts
5//!
6//! * **A cell URI's rest**, byte for byte (SPEC 5.3):
7//!   `/cell/ecb.europa.eu/fx_rate?base=EUR&date=2024-03-15&quote=USD`, then optionally
8//!   `&fn_hash=<64 hex digits>` (a pin, 5.1) and `&asof=<instant>`. It is parsed by the core's
9//!   `parse_reference` against the signature of the function the pin names, or else the one
10//!   the name is bound to as of that asof (or now), so every code of SPEC 5.4 is reported as it
11//!   defines.
12//! * **A call** (5.8), percent-encoded as any URL path is
13//!   (`/cell/rates.example.org/fx_rate(%22EUR%22,%20%22USD%22,%202024-03-15)`), with an optional
14//!   query `?asof=<instant>` and nothing else: a read of the formula dialect whose arguments
15//!   are literals, the callee a full name or an `@alias` of the configured map, optionally
16//!   pinned (`name@<fn_hash>(...)`). It is parsed by the formula crate's
17//!   `datumesh_formula::call::parse_call` in 5.8's order and codes, written as its cell URI and
18//!   resolved as above: a call and its URI are one request.
19//!
20//!   Since 0.2.2 (spec-0.5.0, 5.8, 16.3, 16.7) the call is also a **method call**
21//!   (`N(keys).m(args)`, the same request as the plain read `N/m(keys, args)`), takes **unquoted
22//!   values** by the position's type, **labels** (`N[label]`, through the class's `lookup`), the
23//!   `asof` **default** (the call's `asof`, or the mesh's now, in the cell URI) and a **bare name**
24//!   through the alias map. What it resolved is [`Target::resolved`], the answer's `resolved`
25//!   (5.5). A key not canonical under its normalisation is `E_KEY_NORMALISATION`, a malformed
26//!   encoding `E_KEY_ENCODING` (both `bad_request`). Not accepted: expressions, ranges or units
27//!   (`E_PARSE_URI`).
28//!
29//! An unbound name (or alias) is `not_covered` with `E_NAME_UNBOUND`
30//! ([`Rejection::Error`]`(ErrorCode::NameUnbound)`, which the mesh answers so); a pin no
31//! descriptor of the mesh has is a plain `not_covered` ([`Rejection::NotCovered`]); a slice
32//! marker at `/cell` is `E_SLICE_AT_CELL`.
33
34use std::collections::BTreeMap;
35use std::sync::Arc;
36
37use datumesh_core::json::Value;
38use datumesh_core::{
39    format_reference, lexical, parse_reference, Arg, Cell, CellRef, ClassDescriptor, ErrorCode, FunctionDescriptor,
40    Reference, Resolved,
41};
42
43/// A function bound to a name as of an instant.
44#[derive(Clone, Debug)]
45pub struct Bound {
46    /// The function hash.
47    pub fn_hash: String,
48    /// When the binding began.
49    pub since: String,
50    /// The descriptor.
51    pub descriptor: Arc<FunctionDescriptor>,
52    /// The descriptor's signature as JSON (what `parse_uri` reads).
53    pub signature: Arc<Value>,
54}
55
56impl Bound {
57    /// A binding of `fn_hash` since `since` to `descriptor`.
58    pub fn new(fn_hash: impl Into<String>, since: impl Into<String>, descriptor: Arc<FunctionDescriptor>) -> Bound {
59        let signature = Arc::new(descriptor.signature.to_value());
60        Bound { fn_hash: fn_hash.into(), since: since.into(), descriptor, signature }
61    }
62}
63
64/// A class name's binding as of an instant (spec-0.5.0, 9.7): the class hash and the
65/// flattened descriptor.
66#[derive(Clone, Debug)]
67pub struct BoundClass {
68    /// The class hash.
69    pub class_hash: String,
70    /// When the binding began.
71    pub since: String,
72    /// The flattened class descriptor.
73    pub descriptor: Arc<ClassDescriptor>,
74}
75
76/// Where names are looked up: the mesh's store (and, for names under other hosts, the
77/// cross-mesh resolver in front of it).
78pub trait Bindings {
79    /// The binding of `fn_name` as of `asof`; `Ok(None)` when it has none. An `Err` is the
80    /// code of an `error` envelope (the store or another mesh failed).
81    fn binding(&self, fn_name: &str, asof: &str) -> Result<Option<Arc<Bound>>, ErrorCode>;
82
83    /// A target resolved before for the cell URI rest `rest` under function hash `fn_hash`
84    /// (parsing depends on nothing else). Provided: none.
85    fn cached(&self, fn_hash: &str, rest: &str) -> Option<Arc<Target>> {
86        let _ = (fn_hash, rest);
87        None
88    }
89
90    /// Remembers a resolved target for [`Bindings::cached`]. Provided: nothing.
91    fn remember(&self, rest: &str, target: &Arc<Target>) {
92        let _ = (rest, target);
93    }
94
95    /// The descriptor whose function hash is `fn_hash` (a pin, spec-0.4.2), as a binding of
96    /// no time (`since` empty); `Ok(None)` when the mesh has none. Provided: none.
97    fn pinned(&self, fn_hash: &str) -> Result<Option<Arc<Bound>>, ErrorCode> {
98        let _ = fn_hash;
99        Ok(None)
100    }
101
102    /// The fully qualified name an alias (without `@`) stands for. Provided: none.
103    fn alias(&self, alias: &str) -> Option<String> {
104        let _ = alias;
105        None
106    }
107
108    /// The class `name` is bound to as of `asof` (spec-0.5.0, 9.7, 16.3); `Ok(None)` when it is
109    /// not a class (a function name, or unbound). Provided: none.
110    fn class(&self, name: &str, asof: &str) -> Result<Option<Arc<BoundClass>>, ErrorCode> {
111        let _ = (name, asof);
112        Ok(None)
113    }
114
115    /// The instant of the alias snapshot [`Bindings::alias`] answers from, for `resolved.aliases_tx`
116    /// (16.7); `None` when there is none (the configured map has no snapshot). Provided: none.
117    fn aliases_tx(&self) -> Option<String> {
118        None
119    }
120
121    /// The key encoding the lookup method of class `class` maps `label` to as of `asof`
122    /// (16.7, D93): the value of the cell `<class>/<lookup>(label: ...)`. `Ok(None)` when the
123    /// class has no lookup or the cell has no value. Provided: none.
124    fn lookup(&self, class: &str, label: &str, asof: &str) -> Result<Option<String>, ErrorCode> {
125        let _ = (class, label, asof);
126        Ok(None)
127    }
128}
129
130/// A request resolved to its cell (or slice, at `/slice`).
131#[derive(Clone, Debug)]
132pub struct Target {
133    /// The canonical cell URI, `asof` included when the request had one.
134    pub uri: String,
135    /// The reference (`asof` included).
136    pub reference: CellRef,
137    /// The cell, with the function hash the name is bound to as of the asof.
138    pub cell: Cell,
139    id: std::sync::OnceLock<String>,
140    key: std::sync::OnceLock<String>,
141    /// The binding (for a pinned request, the pinned descriptor).
142    pub bound: Arc<Bound>,
143    /// The pin (spec-0.4.2): the function hash the request named, if it named one.
144    pub pin: Option<String>,
145    /// What the request resolved (spec-0.5.0, 5.5, 16.7): an alias, a method, a default or a
146    /// label; none for a plain or pinned call of a full name and for a cell URI.
147    pub resolved: Option<Resolved>,
148}
149
150impl Target {
151    /// The function's fully qualified name.
152    pub fn fn_name(&self) -> String {
153        format!("{}/{}", self.reference.ns, self.reference.fn_name)
154    }
155
156    /// The cell's id (SPEC 4.4), computed once.
157    pub fn cell_id(&self) -> &str {
158        self.id.get_or_init(|| self.cell.id())
159    }
160
161    /// The cell's key: its function hash and its URI without `asof` (computed once).
162    pub fn cell_key(&self) -> &str {
163        self.key.get_or_init(|| {
164            let rest = self.rest();
165            let base = match self.asof() {
166                Some(a) => &rest[..rest.len() - a.len() - "asof=".len() - 1],
167                None => rest,
168            };
169            format!("{} {}", self.bound.fn_hash, base)
170        })
171    }
172
173    /// The reference with its pin (spec-0.4.2): what the request denotes.
174    pub fn pinned_reference(&self) -> Reference {
175        let mut r = Reference::from(self.reference.clone());
176        r.fn_hash = self.pin.clone();
177        r
178    }
179
180    /// The requested asof, if any.
181    pub fn asof(&self) -> Option<&str> {
182        self.reference.asof.as_deref()
183    }
184
185    /// The cell URI's `<rest>` (SPEC 5.3), without `cell://`.
186    pub fn rest(&self) -> &str {
187        &self.uri["cell://".len()..]
188    }
189
190    /// The rest with `asof` set to `asof` (replacing one there).
191    pub fn rest_asof(&self, asof: &str) -> String {
192        let rest = self.rest();
193        let base = match self.reference.asof.as_deref() {
194            // `asof` is the last parameter of a canonical URI.
195            Some(a) => &rest[..rest.len() - a.len() - "asof=".len() - 1],
196            None => rest,
197        };
198        let sep = if base.contains('?') { '&' } else { '?' };
199        format!("{base}{sep}asof={asof}")
200    }
201}
202
203/// Why a request names no cell.
204#[derive(Clone, Copy, Debug, PartialEq, Eq)]
205pub enum Rejection {
206    /// `bad_request` with this code.
207    BadRequest(ErrorCode),
208    /// `not_covered`: the mesh does not serve the function (a pin no descriptor of it has).
209    NotCovered,
210    /// `error` with this code: looking the name up failed. `ErrorCode::NameUnbound` stands
211    /// for an unbound name, answered `not_covered` with that code (spec-0.4.2; this enum is
212    /// exhaustive, so 0.1.1 gives that case no variant of its own).
213    Error(ErrorCode),
214}
215
216/// Whether `rest` (the text after `/cell/`, query included, as received) is a call rather
217/// than a cell URI's rest: its path (before the first `?`) has a `(` or a `%`, or starts with
218/// `@`, none of which a cell URI's path (namespace and name) has.
219pub fn is_call(rest: &str) -> bool {
220    let path = rest.split('?').next().unwrap_or("");
221    path.contains('(') || path.contains('%') || path.starts_with('@')
222}
223
224/// Resolves a request: a call or a cell URI's rest (see the module documentation). `now` is
225/// the asof used to look the name up when the request has none. `slice` allows `*` (and
226/// requires one).
227pub fn resolve(
228    rest: &str,
229    now: &str,
230    aliases: &BTreeMap<String, String>,
231    bindings: &dyn Bindings,
232    slice: bool,
233) -> Result<Arc<Target>, Rejection> {
234    if is_call(rest) {
235        resolve_call(rest, now, aliases, bindings, slice)
236    } else {
237        resolve_uri(rest, now, bindings, slice)
238    }
239}
240
241/// The parameters of a URI's query, split leniently (for the asof, the pin and a synthetic
242/// signature; `parse_reference` checks them properly).
243fn params(query: &str) -> Vec<(&str, &str)> {
244    if query.is_empty() {
245        return vec![];
246    }
247    query.split('&').map(|p| p.split_once('=').unwrap_or((p, ""))).collect()
248}
249
250/// The codes `parse_reference` reports before it reads the signature, or independently of
251/// the arguments' types: what a URI whose function the mesh does not know can still be
252/// refused with.
253fn structural(code: ErrorCode) -> bool {
254    matches!(
255        code,
256        ErrorCode::ParseUri
257            | ErrorCode::CanonName
258            | ErrorCode::CanonArgName
259            | ErrorCode::CanonArgDuplicate
260            | ErrorCode::CanonArgOrder
261            | ErrorCode::CanonPercent
262            | ErrorCode::CanonInstant
263            | ErrorCode::CanonHex
264    )
265}
266
267/// Resolves a cell URI's rest.
268pub fn resolve_uri(rest: &str, now: &str, bindings: &dyn Bindings, slice: bool) -> Result<Arc<Target>, Rejection> {
269    let (path, query) = match rest.split_once('?') {
270        Some((p, q)) => (p, Some(q)),
271        None => (rest, None),
272    };
273    let ps = params(query.unwrap_or(""));
274    // The asof the name is looked up at: the last parameter's, when it is an instant; the pin,
275    // the last remaining one's when it is named fn_hash and is 64 lowercase hex digits.
276    let mut rest_ps: &[(&str, &str)] = &ps;
277    let mut asof = now;
278    if let Some((("asof", v), before)) = rest_ps.split_last() {
279        if lexical::check_instant(v, "$").is_ok() {
280            asof = v;
281        }
282        rest_ps = before;
283    }
284    let pin = match rest_ps.last() {
285        Some(("fn_hash", v)) if lexical::check_hex(v, 64, "$").is_ok() => Some(v.to_string()),
286        _ => None,
287    };
288    let name_ok = lexical::check_function_name(path, "$").is_ok() && !path.contains('#');
289    let bound = match (&pin, name_ok) {
290        (Some(p), true) => bindings.pinned(p).map_err(Rejection::Error)?,
291        (None, true) => bindings.binding(path, asof).map_err(Rejection::Error)?,
292        (_, false) => None,
293    };
294    if let Some(b) = &bound {
295        if let Some(t) = bindings.cached(&b.fn_hash, rest) {
296            if t.reference.args.values().any(|a| matches!(a, Arg::Slice)) == slice {
297                return Ok(t);
298            }
299        }
300    }
301    let uri = format!("cell://{rest}");
302    let Some(bound) = bound else {
303        // No function to parse against: report what the URI's form alone shows (every
304        // argument read as a string), else not_covered: the name unbound, or the pin unknown.
305        let mut sig = Vec::new();
306        for (name, _) in &ps {
307            if *name != "asof" && *name != "fn_hash" {
308                sig.push((name.to_string(), Value::Object(vec![("type".into(), Value::String("string".into()))])));
309            }
310        }
311        let signature = Value::Object(vec![("args".into(), Value::Object(sig))]);
312        // A function name core refuses (2.2, 2.3: a segment or the whole name over its limit, a name
313        // that is not canonical) is answered with core's canonical code (spec-0.6.1, 5.4).
314        let name_error = if path.contains('#') { None } else { lexical::check_function_name(path, "$").err() };
315        return match parse_reference(&uri, &signature) {
316            Err(e) if structural(e.code()) => Err(Rejection::BadRequest(e.code())),
317            _ if name_error.is_some() => {
318                Err(Rejection::BadRequest(name_error.map_or(ErrorCode::CanonName, |e| e.code())))
319            }
320            _ if pin.is_some() || !name_ok => Err(Rejection::NotCovered),
321            _ => Err(Rejection::Error(ErrorCode::NameUnbound)),
322        };
323    };
324    let reference = parse_reference(&uri, &bound.signature).map_err(|e| {
325        if crate::envelope::is_request_code(e.code()) {
326            Rejection::BadRequest(e.code())
327        } else {
328            Rejection::Error(ErrorCode::EvalUnavailable)
329        }
330    })?;
331    let has_slice = reference.args.values().any(|a| matches!(a, Arg::Slice));
332    if has_slice && !slice {
333        return Err(Rejection::BadRequest(ErrorCode::SliceAtCell));
334    }
335    if !has_slice && slice {
336        // A cell at the slice endpoint: the request names no slice.
337        return Err(Rejection::BadRequest(ErrorCode::ParseUri));
338    }
339    let cell = Cell {
340        ns: reference.ns.clone(),
341        fn_name: reference.fn_name.clone(),
342        fn_hash: bound.fn_hash.clone(),
343        args: reference.args.clone(),
344    };
345    let pin = reference.fn_hash.clone();
346    let cell_ref = CellRef { ns: reference.ns, fn_name: reference.fn_name, args: reference.args, asof: reference.asof };
347    // format(parse(uri)) = uri (SPEC 5.4): the accepted URI is the canonical one.
348    let t = Arc::new(Target {
349        uri,
350        reference: cell_ref,
351        cell,
352        id: std::sync::OnceLock::new(),
353        key: std::sync::OnceLock::new(),
354        bound,
355        pin,
356        resolved: None,
357    });
358    bindings.remember(rest, &t);
359    Ok(t)
360}
361
362/// Percent-decodes a URL path (any `%XX`, either case; the result must be UTF-8).
363pub(crate) fn url_decode(s: &str) -> Option<String> {
364    let b = s.as_bytes();
365    let mut out = Vec::with_capacity(b.len());
366    let mut i = 0;
367    while i < b.len() {
368        if b[i] == b'%' {
369            let h = std::str::from_utf8(b.get(i + 1..i + 3)?).ok()?;
370            out.push(u8::from_str_radix(h, 16).ok()?);
371            i += 3;
372        } else {
373            out.push(b[i]);
374            i += 1;
375        }
376    }
377    String::from_utf8(out).ok()
378}
379
380/// [`Bindings`] as the formula crate's call environment: aliases from the mesh's map, names as
381/// of the call's asof (or now), descriptors by pin.
382struct Env<'a> {
383    bindings: &'a dyn Bindings,
384    aliases: &'a BTreeMap<String, String>,
385    now: &'a str,
386}
387
388impl datumesh_formula::call::CallEnv for Env<'_> {
389    fn alias(&self, alias: &str) -> Result<Option<String>, String> {
390        Ok(self.aliases.get(alias).cloned().or_else(|| self.bindings.alias(alias)))
391    }
392    fn bound(&self, name: &str, asof: Option<&str>) -> Result<Option<FunctionDescriptor>, String> {
393        match self.bindings.binding(name, asof.unwrap_or(self.now)) {
394            Ok(b) => Ok(b.map(|b| (*b.descriptor).clone())),
395            Err(c) => Err(c.as_str().to_string()),
396        }
397    }
398    fn pinned(&self, fn_hash: &str) -> Result<Option<FunctionDescriptor>, String> {
399        match self.bindings.pinned(fn_hash) {
400            Ok(b) => Ok(b.map(|b| (*b.descriptor).clone())),
401            Err(c) => Err(c.as_str().to_string()),
402        }
403    }
404    fn bound_class(&self, name: &str, asof: Option<&str>) -> Result<Option<ClassDescriptor>, String> {
405        match self.bindings.class(name, asof.unwrap_or(self.now)) {
406            Ok(c) => Ok(c.map(|c| (*c.descriptor).clone())),
407            Err(c) => Err(c.as_str().to_string()),
408        }
409    }
410    fn aliases_tx(&self) -> Result<Option<String>, String> {
411        Ok(self.bindings.aliases_tx())
412    }
413    fn now(&self) -> Result<Option<String>, String> {
414        Ok(Some(self.now.to_string()))
415    }
416    fn lookup(&self, class: &str, label: &str, asof: &str) -> Result<Option<String>, String> {
417        self.bindings.lookup(class, label, asof).map_err(|c| c.as_str().to_string())
418    }
419}
420
421/// Resolves a call (SPEC 5.8).
422pub fn resolve_call(
423    rest: &str,
424    now: &str,
425    aliases: &BTreeMap<String, String>,
426    bindings: &dyn Bindings,
427    slice: bool,
428) -> Result<Arc<Target>, Rejection> {
429    let (path, query) = match rest.split_once('?') {
430        Some((p, q)) => (p, Some(q)),
431        None => (rest, None),
432    };
433    let mut text = url_decode(path).ok_or(Rejection::BadRequest(ErrorCode::CanonPercent))?;
434    if let Some(q) = query {
435        text.push('?');
436        text.push_str(q);
437    }
438    let env = Env { bindings, aliases, now };
439    let call = datumesh_formula::call::parse_call(text.trim_start(), &env).map_err(|e| match e {
440        datumesh_formula::call::CallError::Code(c, _) => match ErrorCode::from_code(c) {
441            Some(ErrorCode::NameUnbound) => Rejection::Error(ErrorCode::NameUnbound),
442            Some(ErrorCode::FnUnavailable) => Rejection::NotCovered,
443            Some(code) if crate::envelope::is_request_code(code) => Rejection::BadRequest(code),
444            _ => Rejection::BadRequest(ErrorCode::ParseUri),
445        },
446        datumesh_formula::call::CallError::Env(m) => {
447            Rejection::Error(ErrorCode::from_code(&m).unwrap_or(ErrorCode::InputUnavailable))
448        }
449        _ => Rejection::Error(ErrorCode::EvalUnavailable),
450    })?;
451    let uri = call.uri();
452    if !slice && call.cell.args.values().any(|a| matches!(a, Arg::Slice)) {
453        return Err(Rejection::BadRequest(ErrorCode::SliceAtCell));
454    }
455    let target = resolve_uri(&uri["cell://".len()..], now, bindings, slice)?;
456    match call.resolved {
457        // The target may come from the cache: the clone carries what this request resolved, and is
458        // not cached.
459        Some(r) => {
460            let mut t = (*target).clone();
461            t.resolved = Some(r);
462            Ok(Arc::new(t))
463        }
464        None => Ok(target),
465    }
466}
467
468/// The URI of a reference with its pin (core's `format_reference`).
469pub fn format_pinned(reference: &Reference) -> String {
470    format_reference(reference)
471}