Skip to main content

astrs_node_api/node/
extension.rs

1//! The extension table client (blueprint §9.1's `ext_store/load/drop`, §7.3).
2//!
3//! A small key/value store the daemon keeps on a node's behalf, and the seam
4//! through which pinned host buffers and accelerator IPC handles will reach a
5//! node in 0.2 (§7.3 "extension & pinned-memory"). What makes it worth having
6//! now is what it survives: an entry outlives the node that stored it, so a
7//! restarted node can pick up a calibration, a warm cache or a device handle
8//! that its previous incarnation left behind.
9//!
10//! # Namespacing
11//!
12//! [`ExtensionKey`] is `namespace/name`, and a node may only write the `user`
13//! namespace ([`ExtensionKey::is_writable_by_node`]). The reserved ones are
14//! the daemon's to fill: a node *reads* the pinned buffer it was granted, it
15//! does not invent one. [`Node::ext_store`] refuses a reserved key locally
16//! rather than making a round trip to be told no.
17//!
18//! # Time to live
19//!
20//! [`Node::ext_store_with_ttl`] sets one. Without it a crashed node's handles
21//! accumulate, which is the whole reason the wire carries a `ttl` field.
22//!
23//! # Reads are a round trip
24//!
25//! `ExtLoad` is answered by an `ExtValue` event, which the session dispatcher
26//! routes to the caller rather than to the node's stream. That makes
27//! [`Node::ext_load`] a blocking call with a deadline — and gives it an async
28//! twin for a node whose loop is already asynchronous.
29
30use std::time::Duration;
31
32use astrs_wire::{DurationMs, ExtensionKey, ExtensionNamespace, NodeRequest};
33
34use crate::error::{NodeError, Result};
35use crate::node::Node;
36
37impl Node {
38    /// Stores `value` under `key` (§7.3 `ExtStore`).
39    ///
40    /// # Errors
41    ///
42    /// [`NodeError::Pattern`] for a key in a namespace a node may not write,
43    /// and [`NodeError::DaemonGone`] once the session has ended.
44    pub fn ext_store(&self, key: &ExtensionKey, value: Vec<u8>) -> Result<()> {
45        self.ext_store_inner(key, value, None)
46    }
47
48    /// Stores `value` under `key`, to be reclaimed after `ttl`.
49    ///
50    /// # Errors
51    ///
52    /// As [`Node::ext_store`].
53    pub fn ext_store_with_ttl(
54        &self,
55        key: &ExtensionKey,
56        value: Vec<u8>,
57        ttl: Duration,
58    ) -> Result<()> {
59        self.ext_store_inner(key, value, Some(DurationMs::from_duration(ttl)))
60    }
61
62    /// Reads `key` back, waiting up to the session's default timeout.
63    ///
64    /// # Errors
65    ///
66    /// [`NodeError::Timeout`] when the daemon does not answer,
67    /// [`NodeError::DaemonGone`] once the session has ended.
68    pub fn ext_load(&self, key: &ExtensionKey) -> Result<Option<Vec<u8>>> {
69        self.ext_load_timeout(key, Self::reply_timeout())
70    }
71
72    /// Reads `key` back, waiting up to `timeout`.
73    ///
74    /// # Errors
75    ///
76    /// As [`Node::ext_load`], plus [`NodeError::BlockingInAsync`] when the
77    /// caller may not block.
78    pub fn ext_load_timeout(
79        &self,
80        key: &ExtensionKey,
81        timeout: Duration,
82    ) -> Result<Option<Vec<u8>>> {
83        let session = self.session();
84        let receiver = session.watch_extension(key);
85        session.send_request(NodeRequest::ExtLoad { key: key.clone() })?;
86        let runtime = session.runtime.clone();
87        let millis = u64::try_from(timeout.as_millis()).unwrap_or(u64::MAX);
88        // The timeout future is built *inside* the async block: constructing a
89        // `Sleep` needs a reactor, and outside a runtime there is none until
90        // `block_on` enters one.
91        let answer = runtime.block_on("Node::ext_load", "Node::ext_load_async", async move {
92            tokio::time::timeout(timeout, receiver).await
93        })?;
94        match answer {
95            Ok(Ok(value)) => Ok(value),
96            // The sender was dropped: the session closed under us.
97            Ok(Err(_)) => Err(NodeError::DaemonGone),
98            Err(_) => Err(NodeError::Timeout {
99                operation: "Node::ext_load",
100                millis,
101            }),
102        }
103    }
104
105    /// The async twin of [`Node::ext_load`].
106    ///
107    /// # Errors
108    ///
109    /// As [`Node::ext_load`].
110    pub async fn ext_load_async(&self, key: &ExtensionKey) -> Result<Option<Vec<u8>>> {
111        self.ext_load_async_timeout(key, Self::reply_timeout())
112            .await
113    }
114
115    /// The async twin of [`Node::ext_load_timeout`].
116    ///
117    /// # Errors
118    ///
119    /// As [`Node::ext_load`].
120    pub async fn ext_load_async_timeout(
121        &self,
122        key: &ExtensionKey,
123        timeout: Duration,
124    ) -> Result<Option<Vec<u8>>> {
125        let session = self.session();
126        let receiver = session.watch_extension(key);
127        session
128            .send_request_async(NodeRequest::ExtLoad { key: key.clone() })
129            .await?;
130        match tokio::time::timeout(timeout, receiver).await {
131            Ok(Ok(value)) => Ok(value),
132            Ok(Err(_)) => Err(NodeError::DaemonGone),
133            Err(_) => Err(NodeError::Timeout {
134                operation: "Node::ext_load_async",
135                millis: u64::try_from(timeout.as_millis()).unwrap_or(u64::MAX),
136            }),
137        }
138    }
139
140    /// Drops `key` from the table (§7.3 `ExtDrop`).
141    ///
142    /// # Errors
143    ///
144    /// [`NodeError::DaemonGone`] once the session has ended.
145    pub fn ext_drop(&self, key: &ExtensionKey) -> Result<()> {
146        self.session()
147            .send_request(NodeRequest::ExtDrop { key: key.clone() })
148    }
149
150    /// A validated key in the `user` namespace.
151    ///
152    /// # Errors
153    ///
154    /// [`NodeError::Id`] when the name fails the identifier grammar.
155    pub fn ext_key(name: impl Into<String>) -> Result<ExtensionKey> {
156        Ok(ExtensionKey::user(name)?)
157    }
158
159    /// The shared implementation of the two store forms.
160    fn ext_store_inner(
161        &self,
162        key: &ExtensionKey,
163        value: Vec<u8>,
164        ttl: Option<DurationMs>,
165    ) -> Result<()> {
166        if !key.is_writable_by_node() {
167            return Err(NodeError::Pattern(format!(
168                "the `{}` extension namespace is the daemon's to write, not a node's",
169                key.namespace
170            )));
171        }
172        self.session().send_request(NodeRequest::ExtStore {
173            key: key.clone(),
174            value,
175            ttl,
176        })
177    }
178}
179
180/// Whether a namespace is one a node may write (§7.3).
181///
182/// A convenience for a caller building keys dynamically; the store methods
183/// apply it themselves.
184#[must_use]
185pub const fn is_writable(namespace: ExtensionNamespace) -> bool {
186    !namespace.is_reserved()
187}
188
189#[cfg(test)]
190mod tests {
191    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
192
193    use super::*;
194    use crate::testing::TestHarness;
195
196    #[test]
197    fn a_stored_value_reads_back() {
198        let harness = TestHarness::start().unwrap();
199        let key = Node::ext_key("calibration").unwrap();
200        harness.node.ext_store(&key, vec![1, 2, 3]).unwrap();
201        assert_eq!(harness.node.ext_load(&key).unwrap(), Some(vec![1, 2, 3]));
202        assert_eq!(harness.daemon.extension(&key), Some(vec![1, 2, 3]));
203    }
204
205    #[test]
206    fn an_unset_key_reads_back_as_none() {
207        let harness = TestHarness::start().unwrap();
208        let key = Node::ext_key("absent").unwrap();
209        assert_eq!(harness.node.ext_load(&key).unwrap(), None);
210    }
211
212    #[test]
213    fn dropping_a_key_removes_it() {
214        let harness = TestHarness::start().unwrap();
215        let key = Node::ext_key("temporary").unwrap();
216        harness.node.ext_store(&key, vec![7]).unwrap();
217        assert_eq!(harness.node.ext_load(&key).unwrap(), Some(vec![7]));
218        harness.node.ext_drop(&key).unwrap();
219        assert_eq!(harness.node.ext_load(&key).unwrap(), None);
220    }
221
222    #[test]
223    fn a_time_to_live_is_carried_on_the_wire() {
224        let harness = TestHarness::start().unwrap();
225        let key = Node::ext_key("expiring").unwrap();
226        harness
227            .node
228            .ext_store_with_ttl(&key, vec![1], Duration::from_secs(60))
229            .unwrap();
230        harness
231            .daemon
232            .wait_for(Duration::from_secs(5), |requests| {
233                requests.iter().any(|entry| {
234                    matches!(
235                        &entry.request,
236                        NodeRequest::ExtStore { ttl: Some(ttl), .. }
237                            if ttl.as_millis() == 60_000
238                    )
239                })
240            })
241            .unwrap();
242    }
243
244    #[test]
245    fn a_reserved_namespace_is_refused_locally() {
246        let harness = TestHarness::start().unwrap();
247        let key = ExtensionKey::new(ExtensionNamespace::PinnedMemory, "pool").unwrap();
248        let error = harness.node.ext_store(&key, vec![1]).unwrap_err();
249        assert!(matches!(error, NodeError::Pattern(_)), "{error}");
250        assert!(!is_writable(ExtensionNamespace::PinnedMemory));
251        assert!(is_writable(ExtensionNamespace::User));
252
253        // No round trip was made.
254        assert!(
255            !harness
256                .daemon
257                .requests()
258                .iter()
259                .any(|entry| matches!(entry.request, NodeRequest::ExtStore { .. }))
260        );
261    }
262
263    #[test]
264    fn a_load_after_shutdown_reports_the_daemon_is_gone() {
265        let mut harness = TestHarness::start().unwrap();
266        let key = Node::ext_key("gone").unwrap();
267        harness.node.shutdown().unwrap();
268        assert!(matches!(
269            harness.node.ext_load(&key),
270            Err(NodeError::DaemonGone)
271        ));
272        assert!(matches!(
273            harness.node.ext_store(&key, vec![1]),
274            Err(NodeError::DaemonGone)
275        ));
276        assert!(matches!(
277            harness.node.ext_drop(&key),
278            Err(NodeError::DaemonGone)
279        ));
280    }
281}