astrs_node_api/node/
extension.rs1use 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 pub fn ext_store(&self, key: &ExtensionKey, value: Vec<u8>) -> Result<()> {
45 self.ext_store_inner(key, value, None)
46 }
47
48 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 pub fn ext_load(&self, key: &ExtensionKey) -> Result<Option<Vec<u8>>> {
69 self.ext_load_timeout(key, Self::reply_timeout())
70 }
71
72 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 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 Ok(Err(_)) => Err(NodeError::DaemonGone),
98 Err(_) => Err(NodeError::Timeout {
99 operation: "Node::ext_load",
100 millis,
101 }),
102 }
103 }
104
105 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 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 pub fn ext_drop(&self, key: &ExtensionKey) -> Result<()> {
146 self.session()
147 .send_request(NodeRequest::ExtDrop { key: key.clone() })
148 }
149
150 pub fn ext_key(name: impl Into<String>) -> Result<ExtensionKey> {
156 Ok(ExtensionKey::user(name)?)
157 }
158
159 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#[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 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}