Skip to main content

plexus_core/plexus/ir/
serve.rs

1//! What a service's `ir` method answers ([`DynamicHub::service_ir`]): the
2//! IR of the walks from the namespaces asked for, or why not — and what the
3//! service keeps of it.
4//!
5//! [`DynamicHub::service_ir`]: crate::plexus::DynamicHub::service_ir
6
7use std::borrow::Cow;
8use std::collections::{BTreeMap, HashMap};
9use std::sync::atomic::{AtomicUsize, Ordering};
10use std::sync::{Arc, Mutex};
11
12use tokio::sync::OnceCell;
13
14use schemars::{json_schema, JsonSchema, Schema, SchemaGenerator};
15use serde::{Deserialize, Serialize};
16use serde_json::value::RawValue;
17use serde_json::Value;
18
19use super::build::{build, IrBuildError};
20
21/// A service's IR, as `<service>.ir` answers it: IR 3.1 — the document
22/// synapse's `buildIRFromSchemas` builds from the same schemas (its
23/// `irBackend` the service's namespace, its `irMetadata` `null`). Kept as
24/// its JSON, written once.
25#[derive(Debug, Clone, Serialize, Deserialize)]
26#[serde(transparent)]
27pub struct ServiceIr(pub Arc<RawValue>);
28
29impl ServiceIr {
30    /// The IR as a JSON value.
31    pub fn to_value(&self) -> Value {
32        serde_json::from_str(self.0.get()).unwrap_or(Value::Null)
33    }
34}
35
36impl PartialEq for ServiceIr {
37    fn eq(&self, other: &Self) -> bool {
38        self.0.get() == other.0.get()
39    }
40}
41
42impl JsonSchema for ServiceIr {
43    fn schema_name() -> Cow<'static, str> {
44        "ServiceIr".into()
45    }
46
47    fn inline_schema() -> bool {
48        true
49    }
50
51    fn json_schema(_: &mut SchemaGenerator) -> Schema {
52        json_schema!({
53            "description": "The service's IR 3.1: every type once (irTypes), each method referring to them (irMethods) — as synapse's buildIRFromSchemas builds it from the same schemas"
54        })
55    }
56}
57
58/// Why a service writes no IR for what was asked. (A title collision is no
59/// reason: the walk refuses that activation into the IR's `irRefusals`.)
60#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
61#[serde(tag = "type", rename_all = "snake_case")]
62pub enum IrError {
63    /// A namespace asked for is not one the caller's view of the service shows.
64    NotFound { namespace: String, message: String },
65    /// A schema the service answered is one synapse could not read.
66    Unreadable { namespace: String, message: String },
67}
68
69impl std::fmt::Display for IrError {
70    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
71        match self {
72            IrError::NotFound { message, .. } | IrError::Unreadable { message, .. } => f.write_str(message),
73        }
74    }
75}
76
77impl std::error::Error for IrError {}
78
79/// The walks' roots for `namespaces` (dotted paths; none, `""` or the
80/// service's own namespace: the root): sorted, each once, and none under
81/// another named one — its walk reads it already. Sorted, an ancestor comes
82/// before everything under it, and only names under it come between: one
83/// pass against the last root kept (RETURNS-40 review #1: linear, not a
84/// comparison of every pair).
85pub fn roots(service: &str, namespaces: &[String]) -> Vec<Vec<String>> {
86    let mut paths: Vec<Vec<String>> = namespaces
87        .iter()
88        .map(|n| if n.is_empty() || n == service { vec![] } else { n.split('.').map(str::to_string).collect() })
89        .collect();
90    if paths.is_empty() {
91        return vec![vec![]];
92    }
93    paths.sort();
94    paths.dedup();
95    let mut kept: Vec<Vec<String>> = Vec::with_capacity(paths.len());
96    for p in paths {
97        if kept.last().is_some_and(|q| p.starts_with(q)) {
98            continue;
99        }
100        kept.push(p);
101    }
102    kept
103}
104
105fn dotted(path: &[String]) -> String {
106    path.join(".")
107}
108
109/// The answer for `roots` over `schemas` (every `<path>.schema` the walks
110/// read, by path): the IR, or why not.
111pub fn answer(service: &str, roots: &[Vec<String>], schemas: &BTreeMap<Vec<String>, Value>) -> Result<ServiceIr, IrError> {
112    match build(service, roots, schemas) {
113        Ok(ir) => {
114            let text = serde_json::to_string(&ir.to_json()).expect("an IR serializes");
115            Ok(ServiceIr(Arc::from(RawValue::from_string(text).expect("JSON"))))
116        }
117        Err(e) => {
118            let message = e.to_string();
119            Err(match e {
120                // the walk refuses a title collision into the IR (synapse's
121                // pluginIRRefusing): build() never fails so
122                IrBuildError::TitleCollision { namespace, .. } => IrError::Unreadable { namespace, message },
123                IrBuildError::MissingSchema { path } => IrError::NotFound {
124                    message: format!("no namespace {} in this service", if path.is_empty() { service.to_string() } else { dotted(&path) }),
125                    namespace: dotted(&path),
126                },
127                IrBuildError::Unreadable { path, .. } => IrError::Unreadable { namespace: dotted(&path), message },
128            })
129        }
130    }
131}
132
133/// What one kept answer is kept by: the hash of the view it was built from
134/// (the service's, or the caller's view's under the grant gate), the roots
135/// asked, and — under the R-5 scope gate — the namespaces whose schema the
136/// caller's own calls are answered, so a caller is never answered what was
137/// built for another (RETURNS-40 review #2, #3).
138#[derive(Debug, Clone, PartialEq, Eq, Hash)]
139pub struct IrKey {
140    pub view: String,
141    pub roots: Vec<Vec<String>>,
142    pub permitted: Option<Vec<String>>,
143}
144
145/// At most this many answers are kept.
146pub const IR_CACHE_ENTRIES: usize = 128;
147/// At most this many bytes of answers are kept (64 MiB: a hundred of
148/// menger's whole-service IR, 565 KB).
149pub const IR_CACHE_BYTES: usize = 64 << 20;
150
151/// What a service keeps of its `ir` answers (RETURNS-40 review #4, re-review
152/// #1, #2): one build per key at a time — a later asker of a key waits for
153/// the build under way, and when the asker building it goes the next waiter
154/// takes the build over; bounded at the ask — a slot being built counts
155/// toward the entries, and an ask with no room (every slot building) builds
156/// without keeping; a slot whose every asker has gone before it was built
157/// is removed (a blocking build under way then finishes and its answer is
158/// dropped); built answers kept least recently used out, by entries and by
159/// bytes, an answer past the byte bound never kept, a slot being built
160/// never evicted; a refusal never kept. The lock is held for O(log n) work
161/// alone.
162pub struct IrCache {
163    state: Mutex<CacheState>,
164    builds: AtomicUsize,
165    max_entries: usize,
166    max_bytes: usize,
167}
168
169#[derive(Default)]
170struct CacheState {
171    slots: HashMap<IrKey, Slot>,
172    /// The built slots, by when each was last used: the least recently
173    /// used first. A slot being built is not here, so never evicted.
174    lru: BTreeMap<u64, IrKey>,
175    tick: u64,
176    bytes: usize,
177    next_id: u64,
178}
179
180struct Slot {
181    /// Which slot this is: a key removed and asked again is another.
182    id: u64,
183    cell: Arc<OnceCell<ServiceIr>>,
184    /// The asks waiting on it.
185    waiters: usize,
186    /// Once built and kept: when it was last used, and its bytes.
187    built: Option<(u64, usize)>,
188}
189
190impl Default for IrCache {
191    fn default() -> Self {
192        IrCache::with_limits(IR_CACHE_ENTRIES, IR_CACHE_BYTES)
193    }
194}
195
196/// One ask waiting on a slot; gone (finished or cancelled), it says so.
197struct Waiter<'a> {
198    cache: &'a IrCache,
199    key: &'a IrKey,
200    id: u64,
201}
202
203impl Drop for Waiter<'_> {
204    fn drop(&mut self) {
205        let mut st = self.cache.state();
206        let gone = match st.slots.get_mut(self.key) {
207            Some(slot) if slot.id == self.id => {
208                slot.waiters -= 1;
209                slot.waiters == 0 && slot.built.is_none()
210            }
211            _ => false,
212        };
213        if gone {
214            st.slots.remove(self.key);
215        }
216    }
217}
218
219impl IrCache {
220    pub fn with_limits(max_entries: usize, max_bytes: usize) -> Self {
221        IrCache { state: Mutex::new(CacheState::default()), builds: AtomicUsize::new(0), max_entries: max_entries.max(1), max_bytes }
222    }
223
224    fn state(&self) -> std::sync::MutexGuard<'_, CacheState> {
225        self.state.lock().unwrap_or_else(|p| p.into_inner())
226    }
227
228    /// The answer kept for `key`, or `build`'s — run once for every asker
229    /// of `key` while it runs. An `Err` is answered and not kept.
230    pub async fn get_or_build<F, Fut>(&self, key: IrKey, build: F) -> Result<ServiceIr, IrError>
231    where
232        F: FnOnce() -> Fut,
233        Fut: std::future::Future<Output = Result<ServiceIr, IrError>>,
234    {
235        let joined = self.join(&key);
236        let Some((id, cell)) = joined else {
237            // no room beside the slots being built: built, not kept
238            self.builds.fetch_add(1, Ordering::SeqCst);
239            return build().await;
240        };
241        let _waiting = Waiter { cache: self, key: &key, id };
242        let answer = cell
243            .get_or_try_init(|| {
244                self.builds.fetch_add(1, Ordering::SeqCst);
245                build()
246            })
247            .await
248            .cloned();
249        if let Ok(ir) = &answer {
250            self.settle(&key, id, ir.0.get().len());
251        }
252        answer
253    }
254
255    /// Wait on `key`'s slot — made when there is room — counted as one of
256    /// its askers; `None` when every slot is being built.
257    fn join(&self, key: &IrKey) -> Option<(u64, Arc<OnceCell<ServiceIr>>)> {
258        let mut st = self.state();
259        st.tick += 1;
260        let tick = st.tick;
261        if let Some(slot) = st.slots.get_mut(key) {
262            slot.waiters += 1;
263            let used = slot.built.map(|(used, _)| used);
264            if let Some((_, bytes)) = slot.built {
265                slot.built = Some((tick, bytes));
266            }
267            let joined = (slot.id, slot.cell.clone());
268            if let Some(used) = used {
269                st.lru.remove(&used);
270                st.lru.insert(tick, key.clone());
271            }
272            return Some(joined);
273        }
274        while st.slots.len() >= self.max_entries {
275            let Some((_, oldest)) = st.lru.pop_first() else { return None };
276            if let Some(gone) = st.slots.remove(&oldest) {
277                st.bytes -= gone.built.map_or(0, |(_, b)| b);
278            }
279        }
280        st.next_id += 1;
281        let id = st.next_id;
282        let cell = Arc::new(OnceCell::new());
283        st.slots.insert(key.clone(), Slot { id, cell: cell.clone(), waiters: 1, built: None });
284        Some((id, cell))
285    }
286
287    /// Keep a built answer — unless it is past the byte bound — then drop
288    /// the least recently used others while past it.
289    fn settle(&self, key: &IrKey, id: u64, bytes: usize) {
290        let mut st = self.state();
291        let fresh = matches!(st.slots.get(key), Some(slot) if slot.id == id && slot.built.is_none());
292        if !fresh {
293            return;
294        }
295        if bytes > self.max_bytes {
296            st.slots.remove(key);
297            return;
298        }
299        st.tick += 1;
300        let tick = st.tick;
301        if let Some(slot) = st.slots.get_mut(key) {
302            slot.built = Some((tick, bytes));
303        }
304        st.lru.insert(tick, key.clone());
305        st.bytes += bytes;
306        while st.bytes > self.max_bytes {
307            let Some((_, oldest)) = st.lru.pop_first() else { break };
308            if let Some(gone) = st.slots.remove(&oldest) {
309                st.bytes -= gone.built.map_or(0, |(_, b)| b);
310            }
311        }
312    }
313
314    /// How many slots there are: answers kept, and answers being built.
315    pub fn len(&self) -> usize {
316        self.state().slots.len()
317    }
318
319    pub fn is_empty(&self) -> bool {
320        self.len() == 0
321    }
322
323    /// The bytes of the answers kept.
324    pub fn bytes(&self) -> usize {
325        self.state().bytes
326    }
327
328    /// How many builds have run.
329    pub fn builds(&self) -> usize {
330        self.builds.load(Ordering::SeqCst)
331    }
332}
333
334#[cfg(test)]
335mod tests {
336    use super::*;
337
338    fn p(s: &[&str]) -> Vec<String> {
339        s.iter().map(|x| x.to_string()).collect()
340    }
341
342    fn key(n: usize) -> IrKey {
343        IrKey { view: format!("h{n}"), roots: vec![vec![]], permitted: None }
344    }
345
346    fn ir_of(bytes: usize) -> ServiceIr {
347        ServiceIr(Arc::from(RawValue::from_string(format!("\"{}\"", "x".repeat(bytes - 2))).unwrap()))
348    }
349
350    #[tokio::test]
351    async fn the_cache_keeps_the_most_recently_used_within_both_bounds() {
352        let cache = IrCache::with_limits(3, 250);
353        for n in 0..3 {
354            cache.get_or_build(key(n), || async { Ok(ir_of(50)) }).await.unwrap();
355        }
356        assert_eq!((cache.len(), cache.bytes(), cache.builds()), (3, 150, 3));
357        // 0 is used again; 3 comes in: 1, the least recently used, goes
358        cache.get_or_build(key(0), || async { Ok(ir_of(50)) }).await.unwrap();
359        cache.get_or_build(key(3), || async { Ok(ir_of(50)) }).await.unwrap();
360        assert_eq!((cache.len(), cache.builds()), (3, 4));
361        cache.get_or_build(key(1), || async { Ok(ir_of(50)) }).await.unwrap();
362        assert_eq!(cache.builds(), 5, "1 was dropped, so built again");
363        // a large answer: the others go one by one, oldest first, until it fits — never all at once
364        cache.get_or_build(key(9), || async { Ok(ir_of(150)) }).await.unwrap();
365        assert!(cache.bytes() <= 250, "{}", cache.bytes());
366        assert_eq!(cache.len(), 3, "9 and the two most recently used");
367        cache.get_or_build(key(1), || async { Ok(ir_of(50)) }).await.unwrap();
368        assert_eq!(cache.builds(), 6, "1 was kept");
369    }
370
371    #[tokio::test]
372    async fn a_refusal_is_not_kept() {
373        let cache = IrCache::default();
374        let refused = || async { Err(IrError::NotFound { namespace: "x".into(), message: "no".into() }) };
375        assert!(cache.get_or_build(key(0), refused).await.is_err());
376        assert!(cache.get_or_build(key(0), refused).await.is_err());
377        assert_eq!((cache.builds(), cache.len()), (2, 0));
378    }
379
380    #[test]
381    fn roots_of_what_is_asked() {
382        assert_eq!(roots("svc", &[]), vec![p(&[])]);
383        assert_eq!(roots("svc", &p(&["svc"])), vec![p(&[])]);
384        assert_eq!(roots("svc", &p(&["beta", "alpha", "beta"])), vec![p(&["alpha"]), p(&["beta"])]);
385        assert_eq!(roots("svc", &p(&["alpha.gamma", "alpha"])), vec![p(&["alpha"])]);
386        assert_eq!(roots("svc", &p(&["alpha", ""])), vec![p(&[])]);
387        assert_eq!(roots("svc", &p(&["alphabet", "alpha"])), vec![p(&["alpha"]), p(&["alphabet"])]);
388        assert_eq!(roots("svc", &p(&["a.b.c", "a.x", "a.b", "b"])), vec![p(&["a", "b"]), p(&["a", "x"]), p(&["b"])]);
389    }
390}