Skip to main content

plexus_core/plexus/
view.rs

1//! AUTH-4 — **the caller's view**: what a caller can discover of a gated service
2//! is exactly what it can use.
3//!
4//! A service with a gate ([`DynamicHub::with_gate`](super::DynamicHub::with_gate))
5//! answers `_info`, its own `schema` / `hash` / `hashes`, and every
6//! `<activation>.schema` from the caller's [`View`]:
7//!
8//! - **anonymous** (no principal): only the `public` methods — the auth
9//!   activation's door (`auth.providers`, `auth.login`, `auth.signup`);
10//! - **caller** (signed in): only the methods whose grant some role the
11//!   caller holds lists (within its session's ceiling), each with `held_on`
12//!   — where it is held; plus the public methods, and the methods every
13//!   signed-in caller reaches (the auth activation's `whoami`, `logout`,
14//!   `requires`). A method the caller cannot use is **absent**, not marked;
15//!   an activation left with none is absent too.
16//!
17//! The service's own methods (`call`, `hash`, `hashes`, `schema`) are in every
18//! view: they are how a client reaches anything at all. Each activation's
19//! `schema` entry stays beside its visible methods (introspection is open).
20//! An activation's declared `roles` are left out of a gated view (they name
21//! methods the caller may not see); `auth.roles` answers them to whoever
22//! holds it.
23//!
24//! **Hashes.** Every schema in a view carries a hash of what *it* shows —
25//! its methods (with `held_on`) and, for the service, its children's view
26//! hashes — so two callers with identical holdings share a view hash, and
27//! a client's schema cache (synapse keeps IR by hash) never mixes two
28//! callers' views. The service's view hash is `v-anon-<hex>` for the anonymous
29//! view and `v-<hex>` for a caller's. PERF-21: the service lists its children
30//! by namespace, so a view hash is the same at every start of the same build,
31//! and a cache keeps its schema across a restart.
32//!
33//! A service **without a gate** never builds a view on the wire: `_info` and
34//! every schema answer exactly as before. [`DynamicHub::view`](super::DynamicHub::view)
35//! there returns the whole service as a [`ViewKind::Caller`] view whose hash is
36//! the service's own.
37//!
38//! **Kept, not rebuilt** (PERF-15). Building a view asks every activation for
39//! its schema and the gate for every method — 150–520 ms on menger, on every
40//! `_info`, `hash` and `schema`. A service keeps instead ([`Cache`]): what its
41//! schemas show whoever asks ([`Described`]), built once per *schema
42//! generation* — moved by every change to the service while it is built (a
43//! mount) and by [`DynamicHub::schema_moved`](super::DynamicHub::schema_moved)
44//! after; and each view of it ([`Shaped`]), built once per *view key* — the
45//! caller's grants' [`Fingerprint`], or anonymous — and *grants generation*,
46//! which every write that could change one of the gate's answers moves
47//! (BIDIR-8). Callers holding the same share one view. A view is kept as what
48//! it decided — which methods, each `held_on`, and the hashes — not as copies
49//! of the schemas, and is rebuilt from [`Described`] exactly as it was built.
50//! A caller's sign-in is asked whether it still stands on every ask (AUTH-11):
51//! one that ended is anonymous at once.
52
53use std::collections::{BTreeMap, BTreeSet, HashMap};
54use std::hash::{Hash, Hasher};
55use std::sync::atomic::{AtomicU64, Ordering};
56use std::sync::{Arc, Mutex, OnceLock};
57
58use plexus_auth_core::grants::{Fingerprint, Gate, Grant};
59use serde_json::Value;
60
61use super::context::PlexusContext;
62use super::schema::{ChildHashes, ChildSummary, MethodRole, MethodSchema, PluginHashes, PluginSchema, ViewKind};
63use super::types::{PlexusStreamItem, StreamMetadata};
64
65/// The service as one caller may see it (AUTH-4).
66#[derive(Debug, Clone)]
67pub struct View {
68    /// Anonymous (the door only) or the caller's own.
69    pub kind: ViewKind,
70    /// The service's own schema in this view: its methods, and a child summary
71    /// for each activation the view keeps, carrying that activation's view
72    /// hash. `hash` is the view's hash.
73    pub schema: PluginSchema,
74    /// The view's hash: deterministic over what the view shows.
75    pub hash: String,
76    /// Each activation the view keeps, by namespace, as its
77    /// `<ns>.schema` answers in this view.
78    pub activations: BTreeMap<String, PluginSchema>,
79}
80
81impl View {
82    /// The schema `<ns>.schema` answers in this view: the service's own for its
83    /// namespace, else the activation's — `None` when the view does not
84    /// show it.
85    pub fn schema_of(&self, ns: &str) -> Option<&PluginSchema> {
86        if ns == self.schema.namespace {
87            Some(&self.schema)
88        } else {
89            self.activations.get(ns)
90        }
91    }
92
93    /// The grants of the `public` methods this view shows, activation by
94    /// activation (in namespace order), each in declaration order —
95    /// `_info`'s `auth.methods` for an anonymous caller.
96    pub fn public_methods(&self) -> Vec<String> {
97        self.activations
98            .values()
99            .flat_map(|s| {
100                let ns = s.namespace.clone();
101                s.methods.iter().filter(|m| m.public).map(move |m| m.grant_or(&ns)).collect::<Vec<_>>()
102            })
103            .collect()
104    }
105
106    /// The service's `hashes` answer in this view.
107    pub fn hashes(&self) -> PluginHashes {
108        hashes_of(&self.schema)
109    }
110}
111
112/// The service's `hashes` answer, from its schema.
113#[allow(deprecated)]
114fn hashes_of(service: &PluginSchema) -> PluginHashes {
115    PluginHashes {
116        namespace: service.namespace.clone(),
117        self_hash: service.self_hash.clone(),
118        children_hash: service.children_hash.clone(),
119        hash: service.hash.clone(),
120        children: service
121            .children
122            .as_ref()
123            .map(|kids| kids.iter().map(|c| ChildHashes { namespace: c.namespace.clone(), hash: c.hash.clone() }).collect()),
124    }
125}
126
127/// A stable 64-bit digest of `value`'s JSON, as 16 hex digits. The JSON of
128/// a schema is deterministic (struct fields in order; maps sorted), so equal
129/// views digest equally.
130fn digest(value: &impl serde::Serialize) -> String {
131    let text = serde_json::to_string(value).unwrap_or_default();
132    let mut h = std::collections::hash_map::DefaultHasher::new();
133    text.hash(&mut h);
134    format!("{:016x}", h.finish())
135}
136
137/// What the gate needs to say about one caller, computed once per view.
138struct Asker<'a> {
139    gate: &'a Gate,
140    /// The caller's grants ([`Gate::fingerprint`]); `None` when anonymous.
141    who: Option<&'a Fingerprint>,
142    /// Grants every signed-in caller reaches (the auth activation's
143    /// `whoami`, `logout`, `requires`), whatever its roles or ceiling.
144    signed_in_grants: &'a BTreeSet<String>,
145}
146
147impl Asker<'_> {
148    /// Whether the view keeps a method, and its `held_on` there.
149    fn keep(&self, grant: &str, public: bool) -> Option<Option<Vec<String>>> {
150        let Some(who) = self.who else {
151            return public.then_some(None);
152        };
153        let held: Vec<String> = self.gate.held_on_by(who, &Grant::new(grant)).iter().map(|s| s.as_str().to_string()).collect();
154        if !held.is_empty() {
155            return Some(Some(held));
156        }
157        (public || self.signed_in_grants.contains(grant)).then_some(None)
158    }
159}
160
161/// What a service's schemas show whoever asks: its own schema, every registered
162/// activation's and every static child's (MACRO-20) — built once per schema
163/// generation, and every view of the service is decided over it.
164pub(crate) struct Described {
165    /// The service's own schema ([`Activation::plugin_schema`](super::Activation::plugin_schema)).
166    pub(crate) service: PluginSchema,
167    /// Each registered activation's schema, in namespace order (PERF-21).
168    pub(crate) activations: Vec<PluginSchema>,
169    /// The static children, by their whole path — what a view reads of them.
170    below: Vec<Below>,
171    /// Each activation's schema without its methods — what a view's schema
172    /// is rebuilt from, beside the methods it keeps.
173    hollow: Vec<PluginSchema>,
174    /// Introspection answers' envelopes, by method and params ([`Shell`]).
175    shells: Mutex<HashMap<String, Arc<Shell>>>,
176}
177
178/// A static child (MACRO-20) as a view reads it: its whole path, and the
179/// grant of each method it answers, `public` or not — not its schema, which
180/// on menger is as large as `tickets.schema` itself.
181struct Below {
182    namespace: String,
183    grants: Vec<(String, bool)>,
184}
185
186impl Below {
187    fn of(child: &PluginSchema) -> Self {
188        let grants = child
189            .methods
190            .iter()
191            .filter(|m| matches!(m.role, MethodRole::Rpc) && !m.is_auto_schema())
192            .map(|m| (m.grant_or(&child.namespace), m.public))
193            .collect();
194        Below { namespace: child.namespace.clone(), grants }
195    }
196}
197
198/// At most this many envelopes are kept; past it each new one is routed
199/// every time, as before PERF-15.
200const SHELLS: usize = 256;
201
202impl Described {
203    pub(crate) fn new(service: PluginSchema, activations: Vec<PluginSchema>, children: Vec<PluginSchema>) -> Self {
204        let hollow = activations
205            .iter()
206            .map(|s| {
207                let mut h = s.clone();
208                h.methods = Vec::new();
209                h
210            })
211            .collect();
212        let below = children.iter().map(Below::of).collect();
213        Self { service, activations, below, hollow, shells: Mutex::new(HashMap::new()) }
214    }
215
216    /// The view of a service without a gate: everything, as today.
217    pub(crate) fn whole(&self) -> View {
218        View {
219            kind: ViewKind::Caller,
220            schema: self.service.clone(),
221            hash: self.service.hash.clone(),
222            activations: self.activations.iter().map(|s| (s.namespace.clone(), s.clone())).collect(),
223        }
224    }
225
226    /// RETURNS-40: every static child's whole path (`tickets.commits`), as
227    /// the service describes it — what `ir` may be asked for below an
228    /// activation.
229    pub(crate) fn nested(&self) -> impl Iterator<Item = &str> {
230        self.below.iter().map(|b| b.namespace.as_str())
231    }
232
233    /// The envelope kept for an introspection answer (`key`: its method and params).
234    pub(crate) fn shell(&self, key: &str) -> Option<Arc<Shell>> {
235        self.shells.lock().unwrap_or_else(|p| p.into_inner()).get(key).cloned()
236    }
237
238    /// Keep `shell` for `key` — while there is room.
239    pub(crate) fn keep_shell(&self, key: String, shell: Shell) {
240        let mut shells = self.shells.lock().unwrap_or_else(|p| p.into_inner());
241        if shells.len() < SHELLS {
242            shells.insert(key, Arc::new(shell));
243        }
244    }
245}
246
247/// One caller's view, kept as what it decided over [`Described`]: the service's
248/// own schema in the view (small: its methods and the kept activations'
249/// summaries), and for each activation it keeps which of its methods, in the
250/// order shown, each with its `held_on`, and its hashes — not a copy of the
251/// schemas. [`Shaped::view`] rebuilds exactly the [`View`] it decided.
252pub(crate) struct Shaped {
253    pub(crate) kind: ViewKind,
254    /// The view's hash ([`View::hash`]).
255    pub(crate) hash: String,
256    /// The service's own schema in this view ([`View::schema`]).
257    pub(crate) service: PluginSchema,
258    kept: BTreeMap<String, Kept>,
259    /// `_info`'s content for this view, once asked.
260    pub(crate) info: OnceLock<Value>,
261}
262
263/// One activation as a view keeps it.
264struct Kept {
265    /// Where it is in [`Described::activations`].
266    at: usize,
267    /// The methods shown, in order: each one's index in the activation's
268    /// methods, and the `held_on` the view gives it.
269    methods: Vec<(usize, Option<Vec<String>>)>,
270    /// The child summaries kept (`None`: the activation lists none).
271    children: Option<Vec<ChildSummary>>,
272    self_hash: String,
273    children_hash: Option<String>,
274    hash: String,
275}
276
277impl Kept {
278    /// The activation's schema as the view shows it.
279    fn schema(&self, base: &Described, kind: ViewKind) -> PluginSchema {
280        let source = &base.activations[self.at];
281        let mut s = base.hollow[self.at].clone();
282        s.methods = self.methods.iter().map(|(i, held)| Self::shown(source, *i, held)).collect();
283        #[allow(deprecated)]
284        {
285            s.children = self.children.clone();
286        }
287        s.roles = BTreeMap::new();
288        s.view = Some(kind);
289        s.self_hash = self.self_hash.clone();
290        s.children_hash = self.children_hash.clone();
291        s.hash = self.hash.clone();
292        s
293    }
294
295    /// The method named `name` as the view shows it, if it does.
296    fn method(&self, base: &Described, name: &str) -> Option<MethodSchema> {
297        let source = &base.activations[self.at];
298        self.methods.iter().find(|(i, _)| source.methods[*i].name == name).map(|(i, held)| Self::shown(source, *i, held))
299    }
300
301    fn shown(source: &PluginSchema, i: usize, held: &Option<Vec<String>>) -> MethodSchema {
302        let mut m = source.methods[i].clone();
303        m.held_on = held.clone();
304        m
305    }
306}
307
308impl Shaped {
309    /// The view, whole.
310    pub(crate) fn view(&self, base: &Described) -> View {
311        View {
312            kind: self.kind,
313            schema: self.service.clone(),
314            hash: self.hash.clone(),
315            activations: self.kept.iter().map(|(ns, k)| (ns.clone(), k.schema(base, self.kind))).collect(),
316        }
317    }
318
319    /// Whether the view shows `ns`: the service's own namespace, or an activation it keeps.
320    pub(crate) fn shows(&self, ns: &str) -> bool {
321        ns == self.service.namespace || self.kept.contains_key(ns)
322    }
323
324    /// [`View::schema_of`]: the schema `<ns>.schema` answers in this view.
325    pub(crate) fn schema_of(&self, base: &Described, ns: &str) -> Option<PluginSchema> {
326        if ns == self.service.namespace {
327            Some(self.service.clone())
328        } else {
329            self.kept.get(ns).map(|k| k.schema(base, self.kind))
330        }
331    }
332
333    /// The method `name` of `ns`'s schema in this view, as it shows it.
334    pub(crate) fn method_of(&self, base: &Described, ns: &str, name: &str) -> Option<MethodSchema> {
335        if ns == self.service.namespace {
336            self.service.methods.iter().find(|m| m.name == name).cloned()
337        } else {
338            self.kept.get(ns)?.method(base, name)
339        }
340    }
341
342    /// [`View::public_methods`].
343    pub(crate) fn public_methods(&self, base: &Described) -> Vec<String> {
344        self.kept
345            .values()
346            .flat_map(|k| {
347                let source = &base.activations[k.at];
348                k.methods.iter().map(|(i, _)| &source.methods[*i]).filter(|m| m.public).map(|m| m.grant_or(&source.namespace))
349            })
350            .collect()
351    }
352
353    /// [`View::hashes`].
354    pub(crate) fn hashes(&self) -> PluginHashes {
355        hashes_of(&self.service)
356    }
357}
358
359/// One activation as the view keeps it, or `None` when it keeps no method
360/// of it.
361fn activation_view(asker: &Asker<'_>, kind: ViewKind, base: &Described, at: usize) -> Option<Kept> {
362    let schema = &base.activations[at];
363    let ns = &schema.namespace;
364    let mut kept = Vec::new();
365    let mut schema_entry = None;
366    for (i, m) in schema.methods.iter().enumerate() {
367        let is_schema_entry = m.is_auto_schema();
368        if is_schema_entry {
369            schema_entry = Some((i, m.held_on.clone()));
370            continue;
371        }
372        // MACRO-20: a static child's entry (`tickets.commits`) names no
373        // method of its own; it stays when the caller can use a method
374        // somewhere below it (`tickets.commits.link`), so the caller can
375        // navigate to what it holds.
376        // A child that describes nothing (a hand-written router) is
377        // decided as before, by the entry's own grant.
378        if matches!(m.role, MethodRole::StaticChild) {
379            if let Some(reached) = reaches_below(asker, &format!("{ns}.{}", m.name), &base.below) {
380                if reached {
381                    kept.push((i, None));
382                }
383                continue;
384            }
385        }
386        let grant = m.grant_or(ns);
387        if let Some(held) = asker.keep(&grant, m.public) {
388            kept.push((i, held));
389        }
390    }
391    if kept.is_empty() {
392        return None;
393    }
394    kept.extend(schema_entry);
395    // A child summary names a nested router; it stays only when the
396    // method that reaches it does.
397    let names: BTreeSet<&str> = kept.iter().map(|(i, _)| schema.methods[*i].name.as_str()).collect();
398    #[allow(deprecated)]
399    let children = schema
400        .children
401        .as_ref()
402        .map(|kids| kids.iter().filter(|c| names.contains(c.namespace.as_str())).cloned().collect());
403    let mut k = Kept { at, methods: kept, children, self_hash: String::new(), children_hash: None, hash: String::new() };
404    let mut shown = k.schema(base, kind);
405    rehash(&mut shown, None);
406    (k.self_hash, k.children_hash, k.hash) = (shown.self_hash, shown.children_hash, shown.hash);
407    Some(k)
408}
409
410/// MACRO-20: whether the caller can use a method of a static child at
411/// `path` or of one below it (`children`: the service's qualified static
412/// children, [`super::children`], as [`Below`]).
413/// `None` when no child at `path` describes itself.
414fn reaches_below(asker: &Asker<'_>, path: &str, children: &[Below]) -> Option<bool> {
415    let below = format!("{path}.");
416    let mut known = children.iter().filter(|c| c.namespace == path || c.namespace.starts_with(&below)).peekable();
417    known.peek()?;
418    Some(known.flat_map(|c| c.grants.iter()).any(|(grant, public)| asker.keep(grant, *public).is_some()))
419}
420
421/// Recompute `self_hash`, `children_hash` and `hash` over what the schema
422/// shows. `prefix` marks the service's view hash.
423#[allow(deprecated)]
424fn rehash(schema: &mut PluginSchema, prefix: Option<&str>) {
425    schema.self_hash = String::new();
426    schema.children_hash = None;
427    schema.hash = String::new();
428    let self_hash = digest(&(&schema.namespace, &schema.methods, &schema.view));
429    let children_hash = schema.children.as_ref().map(|kids| digest(kids));
430    let composite = digest(&(&self_hash, &children_hash, &*schema));
431    schema.self_hash = self_hash;
432    schema.children_hash = children_hash;
433    schema.hash = match prefix {
434        Some(p) => format!("{p}{composite}"),
435        None => composite,
436    };
437}
438
439/// Decide the view of a gated service for whoever has `who` (`None`:
440/// anonymous) over what the service describes.
441pub(crate) fn shape(gate: &Gate, signed_in_grants: &BTreeSet<String>, who: Option<&Fingerprint>, base: &Described) -> Shaped {
442    let kind = if who.is_some() { ViewKind::Caller } else { ViewKind::Anonymous };
443    let asker = Asker { gate, who, signed_in_grants };
444
445    let kept: BTreeMap<String, Kept> = (0..base.activations.len())
446        .filter_map(|at| activation_view(&asker, kind, base, at))
447        .map(|k| (base.activations[k.at].namespace.clone(), k))
448        .collect();
449
450    let mut service = base.service.clone();
451    #[allow(deprecated)]
452    {
453        let mut children: Vec<ChildSummary> = service.children.take().unwrap_or_default();
454        children.retain(|c| kept.contains_key(&c.namespace));
455        for c in children.iter_mut() {
456            c.hash = kept[&c.namespace].hash.clone();
457        }
458        service.children = Some(children);
459    }
460    // The service's own methods are how a client reaches anything: in every view.
461    for m in service.methods.iter_mut() {
462        m.held_on = None;
463    }
464    service.roles = BTreeMap::new();
465    service.view = Some(kind);
466    rehash(&mut service, Some(if who.is_some() { "v-" } else { "v-anon-" }));
467    let hash = service.hash.clone();
468    Shaped { kind, hash, service, kept, info: OnceLock::new() }
469}
470
471// ---------------------------------------------------------------------------
472// PERF-15: the cache
473// ---------------------------------------------------------------------------
474
475/// At most this many views are kept at once; past it the kept views are
476/// dropped and built again as they are asked.
477const VIEWS: usize = 1024;
478
479/// A service's self-description cache: what its schemas show ([`Described`]),
480/// kept for the schema generation it was built at, and each view of it
481/// ([`Shaped`]), kept for its key — the caller's [`Fingerprint`], or `None`
482/// for anonymous — and the grants generation it was decided at. A
483/// generation that moves drops what was kept for the one before; a reader
484/// that read a generation older than the cache's builds its own and keeps
485/// nothing. Each entry is built once, by its first asker.
486#[derive(Default)]
487pub(crate) struct Cache {
488    /// Moved by [`Cache::schema_moved`]: something the service describes changed.
489    schema_generation: AtomicU64,
490    state: Mutex<State>,
491}
492
493type Cell<T> = Arc<OnceLock<Arc<T>>>;
494
495#[derive(Default)]
496struct State {
497    /// The schema generation `base` and `views` are for.
498    schema_at: u64,
499    /// The grants generation `views` are for.
500    grants_at: u64,
501    base: Cell<Described>,
502    views: HashMap<Option<Fingerprint>, Cell<Shaped>>,
503}
504
505impl Cache {
506    /// The schema generation now.
507    pub(crate) fn schema_generation(&self) -> u64 {
508        self.schema_generation.load(Ordering::Acquire)
509    }
510
511    /// Something the service describes changed: what was kept is dropped at the next ask.
512    pub(crate) fn schema_moved(&self) {
513        self.schema_generation.fetch_add(1, Ordering::AcqRel);
514    }
515
516    /// The service is changed while it is built: nothing kept stands.
517    pub(crate) fn reset(&mut self) {
518        let next = self.schema_generation.get_mut().wrapping_add(1);
519        *self = Cache { schema_generation: AtomicU64::new(next), state: Mutex::new(State { schema_at: next, ..State::default() }) };
520    }
521
522    fn state(&self) -> std::sync::MutexGuard<'_, State> {
523        self.state.lock().unwrap_or_else(|p| p.into_inner())
524    }
525
526    /// The cell for what the service describes at `schema_at`; `None` for a
527    /// stale reader.
528    pub(crate) fn base(&self, schema_at: u64) -> Option<Cell<Described>> {
529        let mut st = self.state();
530        if schema_at < st.schema_at {
531            return None;
532        }
533        if schema_at > st.schema_at {
534            *st = State { schema_at, grants_at: st.grants_at, ..State::default() };
535        }
536        Some(st.base.clone())
537    }
538
539    /// The cells for what the service describes at `schema_at` and for `who`'s
540    /// view of it at `grants_at`; `None` for a stale reader.
541    pub(crate) fn view(&self, schema_at: u64, grants_at: u64, who: &Option<Fingerprint>) -> Option<(Cell<Described>, Cell<Shaped>)> {
542        let mut st = self.state();
543        if schema_at < st.schema_at || grants_at < st.grants_at {
544            return None;
545        }
546        if schema_at > st.schema_at {
547            *st = State { schema_at, grants_at, ..State::default() };
548        } else if grants_at > st.grants_at {
549            st.grants_at = grants_at;
550            st.views.clear();
551        }
552        let cell = match st.views.get(who) {
553            Some(cell) => cell.clone(),
554            None => {
555                if st.views.len() >= VIEWS {
556                    st.views.clear();
557                }
558                st.views.entry(who.clone()).or_default().clone()
559            }
560        };
561        Some((st.base.clone(), cell))
562    }
563}
564
565// ---------------------------------------------------------------------------
566// PERF-15: an introspection answer's envelope
567// ---------------------------------------------------------------------------
568
569/// Everything an introspection answer carries but its content and its
570/// clock: each item's kind, provenance, `plexus_hash` and content type —
571/// learned from the one answer routed for its method and params, and
572/// carrying the view's content after. Only an answer of `data` and `done`
573/// items has one; any other is routed every time, as before.
574pub(crate) struct Shell(Vec<ShellItem>);
575
576enum ShellItem {
577    Data { provenance: Vec<String>, plexus_hash: HashOf, content_type: std::borrow::Cow<'static, str> },
578    Done { provenance: Vec<String>, plexus_hash: HashOf },
579}
580
581/// An item's `plexus_hash`: the process's own ([`PlexusContext::hash`], read
582/// when the answer is made, as the item read it), or another it carried.
583enum HashOf {
584    Context,
585    Carried(String),
586}
587
588impl HashOf {
589    fn of(carried: &str, context: &str) -> Self {
590        if carried == context {
591            HashOf::Context
592        } else {
593            HashOf::Carried(carried.to_string())
594        }
595    }
596
597    fn now(&self, context: &str) -> String {
598        match self {
599            HashOf::Context => context.to_string(),
600            HashOf::Carried(h) => h.clone(),
601        }
602    }
603}
604
605impl Shell {
606    /// The envelope of `items`, a routed answer; `None` unless every item
607    /// is `data` or `done`.
608    pub(crate) fn of(items: &[PlexusStreamItem]) -> Option<Self> {
609        let context = PlexusContext::hash();
610        items
611            .iter()
612            .map(|item| match item {
613                PlexusStreamItem::Data { metadata, content_type, .. } => Some(ShellItem::Data {
614                    provenance: metadata.provenance.clone(),
615                    plexus_hash: HashOf::of(&metadata.plexus_hash, &context),
616                    content_type: content_type.clone(),
617                }),
618                PlexusStreamItem::Done { metadata } => Some(ShellItem::Done {
619                    provenance: metadata.provenance.clone(),
620                    plexus_hash: HashOf::of(&metadata.plexus_hash, &context),
621                }),
622                _ => None,
623            })
624            .collect::<Option<Vec<_>>>()
625            .map(Shell)
626    }
627
628    /// The answer: these items, `content` in each `data` one (moved into the
629    /// last, cloned for any before it), stamped now.
630    pub(crate) fn answer(&self, content: Value) -> Vec<PlexusStreamItem> {
631        let (context, timestamp) = (PlexusContext::hash(), chrono::Utc::now().timestamp());
632        let meta = |provenance: &Vec<String>, hash: &HashOf| StreamMetadata {
633            provenance: provenance.clone(),
634            plexus_hash: hash.now(&context),
635            timestamp,
636        };
637        let last = self.0.iter().rposition(|item| matches!(item, ShellItem::Data { .. }));
638        let mut content = Some(content);
639        self.0
640            .iter()
641            .enumerate()
642            .map(|(at, item)| match item {
643                ShellItem::Data { provenance, plexus_hash, content_type } => PlexusStreamItem::Data {
644                    metadata: meta(provenance, plexus_hash).into(),
645                    content_type: content_type.clone(),
646                    content: if Some(at) == last { content.take() } else { content.clone() }.unwrap_or_default().into(),
647                },
648                ShellItem::Done { provenance, plexus_hash } => PlexusStreamItem::Done { metadata: meta(provenance, plexus_hash) },
649            })
650            .collect()
651    }
652}