Skip to main content

datumesh_http/
publish.rs

1//! Publishing stored cells as the mesh (`datumesh-mesh publish-stored`): a JSON lines file of
2//! stored functions and their cells, signed with the mesh's key, put in the store.
3//!
4//! Each line is one of:
5//!
6//! * a function: `{"function": "<ns>/<name>", "signature": {...}, "bound": "<instant>"}`: the
7//!   descriptor `{"code": {"body": "", "lang": "stored"}, "inputs": [], "signature": ...}`
8//!   is put and the name bound to it from `bound` (unless it already is);
9//! * a formula function: `{"formula": "<ns>/<name>", "source": "<formula>", "signature":
10//!   {...}, "bound": "<instant>"}`: defined with `datumesh_formula::definition::define_function`
11//!   (its callees as bound at `bound`) and published (`put_descriptor`, `bind_name` from
12//!   `bound`) unless the name is already bound to that function; its cells are evaluated on
13//!   demand by the mesh;
14//! * a cell: `{"cell": {"fn": "<ns>/<name>", "args": {<name>: <typed scalar>}}, "value": <typed
15//!   scalar> or {"blob": "<file>", "media_type": "<type>"}, "tx", "asof", "issued"?, "licence",
16//!   "summary"}`: a blob's file (relative to the JSON lines file) is put with `put_blob` and the
17//!   value is `<sha256>:<length>:<media type>`; the receipt is signed with the mesh's key
18//!   (`computed_by` the mesh host, `publisher` the cell's namespace, `valid` its valid-time
19//!   arguments; `issued` defaults to the later of `asof` and the key's start) and stored with
20//!   `put_receipt` and `put_version`.
21//!
22//! The function of a cell is the one its name is bound to as of the cell's `tx`. Re-running a
23//! file changes nothing: descriptors and blobs are content-addressed, signing is deterministic
24//! (the same receipt, the same hash), and a version already there is skipped. The key is never
25//! logged.
26
27use std::io::BufRead;
28use std::path::Path;
29
30use datumesh_core::json::{self, Value};
31use datumesh_core::{Arg, Args, Cell, FunctionDescriptor, ReceiptBuilder, Scalar, SigningKey, Type};
32use datumesh_store::Store;
33
34/// What a run put.
35#[non_exhaustive]
36#[derive(Clone, Debug, Default, PartialEq, Eq)]
37pub struct Published {
38    /// Functions newly bound (stored and formula).
39    pub functions: usize,
40    /// Cell lines read.
41    pub cells: usize,
42    /// Receipts stored (new or already there).
43    pub receipts: usize,
44    /// Versions newly added.
45    pub versions: usize,
46    /// Blobs put (new or already there).
47    pub blobs: usize,
48    /// Blob bytes put.
49    pub blob_bytes: u64,
50}
51
52/// Why a run stopped: the line and what was wrong.
53#[derive(Clone, Debug, PartialEq, Eq)]
54pub struct PublishError {
55    /// The line number (1-based; 0 for the file).
56    pub line: usize,
57    /// Why.
58    pub detail: String,
59}
60
61impl std::fmt::Display for PublishError {
62    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
63        write!(f, "line {}: {}", self.line, self.detail)
64    }
65}
66
67impl std::error::Error for PublishError {}
68
69fn s(v: &str) -> Value {
70    Value::String(v.to_string())
71}
72
73/// A store as the callees of a definition: a name's binding as of an instant, with its
74/// descriptor.
75struct StoreCallees<'a, S: Store + ?Sized>(&'a S);
76
77impl<S: Store + ?Sized> datumesh_formula::definition::Callees for StoreCallees<'_, S> {
78    fn callee(&self, name: &str, at: &str) -> Result<Option<datumesh_formula::definition::Callee>, String> {
79        let Some(b) = self.0.resolve_binding(name, at).map_err(|e| e.to_string())? else { return Ok(None) };
80        let bytes = self.0.descriptor(&b.fn_hash).ok_or_else(|| format!("descriptor {} is not stored", b.fn_hash))?;
81        let descriptor = json::parse(&bytes).map_err(|e| e.to_string())?;
82        Ok(Some(datumesh_formula::definition::Callee { fn_hash: b.fn_hash, start: b.tx, descriptor }))
83    }
84}
85
86/// The receipt JSON of a signed receipt: its payload's members and `sig`.
87pub fn receipt_json(r: &datumesh_core::Receipt) -> Vec<u8> {
88    let mut members = vec![("sig".to_string(), Value::String(r.sig().to_string()))];
89    if let Ok(Value::Object(m)) = json::parse(r.payload()) {
90        members.extend(m);
91    }
92    Value::Object(members).to_jcs()
93}
94
95/// Publishes the file at `path` into `store` as the mesh `host` signing with `key` (see the
96/// module documentation).
97pub fn publish_stored<S: Store + ?Sized>(
98    store: &S,
99    key: &SigningKey,
100    host: &str,
101    path: &Path,
102) -> Result<Published, PublishError> {
103    let file =
104        std::fs::File::open(path).map_err(|e| PublishError { line: 0, detail: format!("{}: {e}", path.display()) })?;
105    let base = path.parent().unwrap_or(Path::new("."));
106    let mut out = Published::default();
107    // The key's start: the earliest `issued`.
108    let key_from = store
109        .namespace(host)
110        .ok()
111        .flatten()
112        .and_then(|n| json::parse(&n.keydoc).ok())
113        .and_then(|d| match d.get("keys") {
114            Some(Value::Array(ks)) => ks
115                .iter()
116                .find(|k| k.get("id").and_then(Value::as_str) == Some(key.key_id()))
117                .and_then(|k| k.get("valid_from").and_then(Value::as_str).map(str::to_string)),
118            _ => None,
119        })
120        .ok_or_else(|| PublishError {
121            line: 0,
122            detail: format!("the key {} is not in {host}'s key document in the store", key.key_id()),
123        })?;
124    for (i, line) in std::io::BufReader::new(file).lines().enumerate() {
125        let n = i + 1;
126        let err = |d: String| PublishError { line: n, detail: d };
127        let line = line.map_err(|e| err(e.to_string()))?;
128        if line.trim().is_empty() {
129            continue;
130        }
131        let v = json::parse(line.as_bytes()).map_err(|e| err(e.to_string()))?;
132        if let Some(name) = v.get("function").and_then(Value::as_str) {
133            let sig = v.get("signature").ok_or_else(|| err("a function without a signature".into()))?;
134            let bound = v.get("bound").and_then(Value::as_str).ok_or_else(|| err("a function without bound".into()))?;
135            let d = Value::Object(vec![
136                ("code".into(), Value::Object(vec![("body".into(), s("")), ("lang".into(), s("stored"))])),
137                ("inputs".into(), Value::Array(vec![])),
138                ("signature".into(), sig.clone()),
139            ]);
140            let fd = FunctionDescriptor::from_value(&d).map_err(|e| err(e.to_string()))?;
141            let h = store.put_descriptor(&fd.canonical()).map_err(|e| err(e.to_string()))?;
142            match store.resolve_binding(name, "9999-12-31T23:59:59.999999Z").map_err(|e| err(e.to_string()))? {
143                Some(b) if b.fn_hash == h => {}
144                _ => {
145                    store.bind_name(name, &h, bound).map_err(|e| err(format!("bind {name}: {e}")))?;
146                    out.functions += 1;
147                }
148            }
149            continue;
150        }
151        if let Some(name) = v.get("formula").and_then(Value::as_str) {
152            let source =
153                v.get("source").and_then(Value::as_str).ok_or_else(|| err("a formula without source".into()))?;
154            let sig = v.get("signature").ok_or_else(|| err("a formula without a signature".into()))?;
155            let bound = v.get("bound").and_then(Value::as_str).ok_or_else(|| err("a formula without bound".into()))?;
156            let def = datumesh_formula::definition::define_function(
157                name,
158                source,
159                sig,
160                &Default::default(),
161                &StoreCallees(store),
162                bound,
163            )
164            .map_err(|e| err(format!("define {name}: {e}")))?;
165            let h = store.put_descriptor(&def.bytes).map_err(|e| err(e.to_string()))?;
166            match store.resolve_binding(name, "9999-12-31T23:59:59.999999Z").map_err(|e| err(e.to_string()))? {
167                Some(b) if b.fn_hash == h => {}
168                _ => {
169                    store.bind_name(name, &h, bound).map_err(|e| err(format!("bind {name}: {e}")))?;
170                    out.functions += 1;
171                }
172            }
173            continue;
174        }
175        let cell_v = v.get("cell").ok_or_else(|| err("neither a function nor a cell".into()))?;
176        let name = cell_v.get("fn").and_then(Value::as_str).ok_or_else(|| err("a cell without fn".into()))?;
177        let (ns, f) = name.rsplit_once('/').ok_or_else(|| err(format!("{name}: not a function name")))?;
178        let field =
179            |k: &str| v.get(k).and_then(Value::as_str).map(str::to_string).ok_or_else(|| err(format!("no {k}")));
180        let (tx, asof, licence, summary) = (field("tx")?, field("asof")?, field("licence")?, field("summary")?);
181        let issued = v
182            .get("issued")
183            .and_then(Value::as_str)
184            .map(str::to_string)
185            .unwrap_or_else(|| std::cmp::max(asof.clone(), key_from.clone()));
186        let fn_hash = store
187            .resolve_name(name, &tx)
188            .map_err(|e| err(e.to_string()))?
189            .ok_or_else(|| err(format!("{name} is not bound as of {tx}")))?;
190        let d = store.descriptor(&fn_hash).ok_or_else(|| err(format!("no descriptor {fn_hash}")))?;
191        let d = FunctionDescriptor::from_json(&d).map_err(|e| err(e.to_string()))?;
192        let mut args = Args::new();
193        for (k, a) in cell_v.get("args").and_then(Value::as_object).ok_or_else(|| err("a cell without args".into()))? {
194            args.insert(k.clone(), Arg::Value(Scalar::from_json(&a.to_jcs()).map_err(|e| err(format!("{k}: {e}")))?));
195        }
196        let valid: Args = args
197            .iter()
198            .filter(|(k, _)| d.signature.args.get(*k).is_some_and(|x| x.valid))
199            .map(|(k, a)| (k.clone(), a.clone()))
200            .collect();
201        let value_v = v.get("value").ok_or_else(|| err("a cell without value".into()))?;
202        let value = match value_v.get("blob").and_then(Value::as_str) {
203            Some(file) => {
204                let media = value_v.get("media_type").and_then(Value::as_str).unwrap_or("application/octet-stream");
205                let bytes = std::fs::read(base.join(file)).map_err(|e| err(format!("{file}: {e}")))?;
206                let sha = store.put_blob(&bytes).map_err(|e| err(e.to_string()))?;
207                out.blobs += 1;
208                out.blob_bytes += bytes.len() as u64;
209                Scalar::from_lexical(Type::Blob, &format!("{sha}:{}:{media}", bytes.len()))
210                    .map_err(|e| err(e.to_string()))?
211            }
212            None => Scalar::from_json(&value_v.to_jcs()).map_err(|e| err(e.to_string()))?,
213        };
214        let cell = Cell { ns: ns.to_string(), fn_name: f.to_string(), fn_hash, args };
215        let r = ReceiptBuilder::new()
216            .cell(cell.clone())
217            .value(value)
218            .valid(valid)
219            .asof(asof.as_str())
220            .tx(tx.as_str())
221            .issued(issued.as_str())
222            .publisher(ns)
223            .signer_host(host)
224            .licence(licence.as_str())
225            .summary(summary.as_str())
226            .sign(key)
227            .map_err(|e| err(e.to_string()))?;
228        let h = store.put_receipt(&receipt_json(&r)).map_err(|e| err(e.to_string()))?;
229        out.cells += 1;
230        out.receipts += 1;
231        let id = cell.id();
232        match store.latest(&id).map_err(|e| err(e.to_string()))? {
233            Some(l) if l.tx.as_str() >= tx.as_str() => {
234                if store.version_asof(&id, &tx).ok().flatten().is_none_or(|v| v.receipt_hash != h) {
235                    return Err(err(format!("{id} has a version at or after {tx} that is not this receipt")));
236                }
237            }
238            _ => {
239                store.put_version(&id, &tx, &h).map_err(|e| err(e.to_string()))?;
240                out.versions += 1;
241            }
242        }
243    }
244    Ok(out)
245}