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        return match parse_reference(&uri, &signature) {
313            Err(e) if structural(e.code()) => Err(Rejection::BadRequest(e.code())),
314            _ if pin.is_some() || !name_ok => Err(Rejection::NotCovered),
315            _ => Err(Rejection::Error(ErrorCode::NameUnbound)),
316        };
317    };
318    let reference = parse_reference(&uri, &bound.signature).map_err(|e| {
319        if crate::envelope::is_request_code(e.code()) {
320            Rejection::BadRequest(e.code())
321        } else {
322            Rejection::Error(ErrorCode::EvalUnavailable)
323        }
324    })?;
325    let has_slice = reference.args.values().any(|a| matches!(a, Arg::Slice));
326    if has_slice && !slice {
327        return Err(Rejection::BadRequest(ErrorCode::SliceAtCell));
328    }
329    if !has_slice && slice {
330        // A cell at the slice endpoint: the request names no slice.
331        return Err(Rejection::BadRequest(ErrorCode::ParseUri));
332    }
333    let cell = Cell {
334        ns: reference.ns.clone(),
335        fn_name: reference.fn_name.clone(),
336        fn_hash: bound.fn_hash.clone(),
337        args: reference.args.clone(),
338    };
339    let pin = reference.fn_hash.clone();
340    let cell_ref = CellRef { ns: reference.ns, fn_name: reference.fn_name, args: reference.args, asof: reference.asof };
341    // format(parse(uri)) = uri (SPEC 5.4): the accepted URI is the canonical one.
342    let t = Arc::new(Target {
343        uri,
344        reference: cell_ref,
345        cell,
346        id: std::sync::OnceLock::new(),
347        key: std::sync::OnceLock::new(),
348        bound,
349        pin,
350        resolved: None,
351    });
352    bindings.remember(rest, &t);
353    Ok(t)
354}
355
356/// Percent-decodes a URL path (any `%XX`, either case; the result must be UTF-8).
357pub(crate) fn url_decode(s: &str) -> Option<String> {
358    let b = s.as_bytes();
359    let mut out = Vec::with_capacity(b.len());
360    let mut i = 0;
361    while i < b.len() {
362        if b[i] == b'%' {
363            let h = std::str::from_utf8(b.get(i + 1..i + 3)?).ok()?;
364            out.push(u8::from_str_radix(h, 16).ok()?);
365            i += 3;
366        } else {
367            out.push(b[i]);
368            i += 1;
369        }
370    }
371    String::from_utf8(out).ok()
372}
373
374/// [`Bindings`] as the formula crate's call environment: aliases from the mesh's map, names as
375/// of the call's asof (or now), descriptors by pin.
376struct Env<'a> {
377    bindings: &'a dyn Bindings,
378    aliases: &'a BTreeMap<String, String>,
379    now: &'a str,
380}
381
382impl datumesh_formula::call::CallEnv for Env<'_> {
383    fn alias(&self, alias: &str) -> Result<Option<String>, String> {
384        Ok(self.aliases.get(alias).cloned().or_else(|| self.bindings.alias(alias)))
385    }
386    fn bound(&self, name: &str, asof: Option<&str>) -> Result<Option<FunctionDescriptor>, String> {
387        match self.bindings.binding(name, asof.unwrap_or(self.now)) {
388            Ok(b) => Ok(b.map(|b| (*b.descriptor).clone())),
389            Err(c) => Err(c.as_str().to_string()),
390        }
391    }
392    fn pinned(&self, fn_hash: &str) -> Result<Option<FunctionDescriptor>, String> {
393        match self.bindings.pinned(fn_hash) {
394            Ok(b) => Ok(b.map(|b| (*b.descriptor).clone())),
395            Err(c) => Err(c.as_str().to_string()),
396        }
397    }
398    fn bound_class(&self, name: &str, asof: Option<&str>) -> Result<Option<ClassDescriptor>, String> {
399        match self.bindings.class(name, asof.unwrap_or(self.now)) {
400            Ok(c) => Ok(c.map(|c| (*c.descriptor).clone())),
401            Err(c) => Err(c.as_str().to_string()),
402        }
403    }
404    fn aliases_tx(&self) -> Result<Option<String>, String> {
405        Ok(self.bindings.aliases_tx())
406    }
407    fn now(&self) -> Result<Option<String>, String> {
408        Ok(Some(self.now.to_string()))
409    }
410    fn lookup(&self, class: &str, label: &str, asof: &str) -> Result<Option<String>, String> {
411        self.bindings.lookup(class, label, asof).map_err(|c| c.as_str().to_string())
412    }
413}
414
415/// Resolves a call (SPEC 5.8).
416pub fn resolve_call(
417    rest: &str,
418    now: &str,
419    aliases: &BTreeMap<String, String>,
420    bindings: &dyn Bindings,
421    slice: bool,
422) -> Result<Arc<Target>, Rejection> {
423    let (path, query) = match rest.split_once('?') {
424        Some((p, q)) => (p, Some(q)),
425        None => (rest, None),
426    };
427    let mut text = url_decode(path).ok_or(Rejection::BadRequest(ErrorCode::CanonPercent))?;
428    if let Some(q) = query {
429        text.push('?');
430        text.push_str(q);
431    }
432    let env = Env { bindings, aliases, now };
433    let call = datumesh_formula::call::parse_call(text.trim_start(), &env).map_err(|e| match e {
434        datumesh_formula::call::CallError::Code(c, _) => match ErrorCode::from_code(c) {
435            Some(ErrorCode::NameUnbound) => Rejection::Error(ErrorCode::NameUnbound),
436            Some(ErrorCode::FnUnavailable) => Rejection::NotCovered,
437            Some(code) if crate::envelope::is_request_code(code) => Rejection::BadRequest(code),
438            _ => Rejection::BadRequest(ErrorCode::ParseUri),
439        },
440        datumesh_formula::call::CallError::Env(m) => {
441            Rejection::Error(ErrorCode::from_code(&m).unwrap_or(ErrorCode::InputUnavailable))
442        }
443        _ => Rejection::Error(ErrorCode::EvalUnavailable),
444    })?;
445    let uri = call.uri();
446    if !slice && call.cell.args.values().any(|a| matches!(a, Arg::Slice)) {
447        return Err(Rejection::BadRequest(ErrorCode::SliceAtCell));
448    }
449    let target = resolve_uri(&uri["cell://".len()..], now, bindings, slice)?;
450    match call.resolved {
451        // The target may come from the cache: the clone carries what this request resolved, and is
452        // not cached.
453        Some(r) => {
454            let mut t = (*target).clone();
455            t.resolved = Some(r);
456            Ok(Arc::new(t))
457        }
458        None => Ok(target),
459    }
460}
461
462/// The URI of a reference with its pin (core's `format_reference`).
463pub fn format_pinned(reference: &Reference) -> String {
464    format_reference(reference)
465}