1#![forbid(unsafe_code)]
27#![cfg_attr(test, allow(clippy::unwrap_used))]
28#![cfg_attr(
29 test,
30 allow(
31 clippy::disallowed_methods,
32 clippy::disallowed_types,
33 reason = "tests spawn, join and drain freely; production sites carry their own expectation"
34 )
35)]
36use parking_lot::{Mutex, MutexGuard};
37use std::{
38 collections::{BTreeMap, BTreeSet},
39 fmt,
40 fs::File,
41 path::{Component, Path, PathBuf},
42 sync::Arc,
43 time::{Duration, Instant},
44};
45
46use dekopon_capability::{StorageAccess, StorageInterface, StorageScope};
47use dekopon_core::{AgentId, CapabilityId, InvocationId, ProviderId, Subject};
48use serde::{Deserialize, Serialize};
49use thiserror::Error;
50
51mod config;
52mod handle;
53mod jsonl;
54mod key;
55mod layout;
56mod namespace;
57mod quota;
58mod sweep;
59mod vfs;
60
61pub use config::{StorageConfigError, StorageLimits};
62pub use handle::StorageHandle;
63pub use jsonl::JsonlChunk;
64pub use sweep::{RetentionPolicies, SweepSummary};
65pub use vfs::{Durability, FileStat, OpenOptions};
66
67use key::{
68 DOMAIN_AUDIT_SCOPE, DOMAIN_CONTENT, DOMAIN_DECISION_EVIDENCE, DOMAIN_NAMESPACE_PATH,
69 DOMAIN_RECORD_ID, commitment, random_bytes, token,
70};
71use layout::{Layout, scan_root_usage, scan_usage, usage_with_directory_entry};
72use namespace::{ContinuityOutcome, Namespace, NamespacePlan, Reset, deadline_after};
73use quota::QuotaLedger;
74
75#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
76#[serde(rename_all = "kebab-case")]
77pub enum ContinuityPolicy {
78 Relaxed,
79 #[default]
80 Paranoid,
81}
82
83#[derive(Clone, Copy, Debug, Eq, PartialEq)]
84pub enum ContinuityCheck {
85 Absent,
86 DigestMismatch,
87 SpaceBound,
88 RoutingDependent,
89 IdOnlySubject,
90 NoCandidate,
91}
92
93impl ContinuityCheck {
94 #[must_use]
95 pub const fn label(self) -> &'static str {
96 match self {
97 Self::Absent => "absent",
98 Self::DigestMismatch => "digest-mismatch",
99 Self::SpaceBound => "space-bound",
100 Self::RoutingDependent => "routing-dependent",
101 Self::IdOnlySubject => "id-only-subject",
102 Self::NoCandidate => "no-candidate",
103 }
104 }
105}
106
107#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
108#[serde(rename_all = "kebab-case")]
109pub enum UnprovenDisposition {
110 #[default]
111 Refuse,
112 FreshEpoch,
113}
114
115pub enum LegacyContinuity {
116 Unproven(ContinuityCheck),
117 Candidates(Vec<Vec<u8>>),
118}
119
120pub enum MemoryContinuity {
121 Relaxed,
122 Paranoid {
123 surface: Vec<u8>,
124 legacy: LegacyContinuity,
125 on_unproven: UnprovenDisposition,
126 },
127}
128
129pub(crate) enum Comparison {
130 Provider {
131 policy: ContinuityPolicy,
132 surface: Vec<u8>,
133 },
134 Memory(MemoryContinuity),
135}
136
137#[derive(Clone, Eq, PartialEq, Serialize, Deserialize)]
138#[serde(transparent)]
139pub struct StorageScopeCommitment(String);
140
141impl StorageScopeCommitment {
142 #[must_use]
143 pub fn as_str(&self) -> &str {
144 &self.0
145 }
146}
147
148impl fmt::Debug for StorageScopeCommitment {
149 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
150 formatter.write_str("StorageScopeCommitment([REDACTED])")
151 }
152}
153
154#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
155#[serde(deny_unknown_fields, rename_all = "camelCase")]
156pub struct StorageEvidence {
157 pub operations: u64,
158 pub syncs: u64,
159 pub quota_denials: u64,
160 pub read_bytes: u64,
161 pub write_bytes: u64,
162 pub evidence_commitment: String,
163}
164
165pub struct StorageGrantRequest {
166 invocation: InvocationId,
167 capability: CapabilityId,
168 provider: ProviderId,
169 interface: StorageInterface,
170 access: StorageAccess,
171 scope: StorageScope,
172 agent: AgentId,
173 subject: Subject,
174 transport_kind: String,
175 transport: String,
176 channel: String,
177 conversation: String,
178 comparison: Comparison,
179 shared_namespace: Option<ProviderId>,
180 space_key: Option<dekopon_core::SpaceKey>,
181}
182
183impl fmt::Debug for StorageGrantRequest {
184 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
185 formatter.write_str("StorageGrantRequest([REDACTED])")
186 }
187}
188
189impl StorageGrantRequest {
190 #[expect(
191 clippy::too_many_arguments,
192 reason = "reshaped by the unit that next rewrites this"
193 )]
194 pub fn new(
195 invocation: InvocationId,
196 capability: CapabilityId,
197 provider: ProviderId,
198 interface: StorageInterface,
199 access: StorageAccess,
200 scope: StorageScope,
201 agent: AgentId,
202 subject: Subject,
203 transport_kind: impl Into<String>,
204 transport: impl Into<String>,
205 channel: impl Into<String>,
206 conversation: impl Into<String>,
207 continuity_policy: ContinuityPolicy,
208 authority_surface: Vec<u8>,
209 ) -> Self {
210 Self {
211 invocation,
212 capability,
213 provider,
214 interface,
215 access,
216 scope,
217 agent,
218 subject,
219 transport_kind: transport_kind.into(),
220 transport: transport.into(),
221 channel: channel.into(),
222 conversation: conversation.into(),
223 comparison: Comparison::Provider {
224 policy: continuity_policy,
225 surface: authority_surface,
226 },
227 shared_namespace: None,
228 space_key: None,
229 }
230 }
231
232 #[must_use]
233 pub fn with_shared_namespace(mut self, namespace: Option<ProviderId>) -> Self {
234 self.shared_namespace = namespace;
235 self
236 }
237
238 #[must_use]
239 pub fn with_memory_continuity(mut self, continuity: MemoryContinuity) -> Self {
240 self.comparison = Comparison::Memory(continuity);
241 self
242 }
243
244 #[must_use]
245 pub fn with_space_key(mut self, key: Option<dekopon_core::SpaceKey>) -> Self {
246 self.space_key = key;
247 self
248 }
249
250 pub(crate) fn scope_values(&self) -> Vec<String> {
251 let provider = self
252 .shared_namespace
253 .as_ref()
254 .unwrap_or(&self.provider)
255 .to_string();
256 let agent = self.agent.to_string();
257 match self.scope {
258 StorageScope::PrivateConversation => vec![
259 provider,
260 agent,
261 self.subject.canonical(),
262 self.transport_kind.clone(),
263 self.transport.clone(),
264 self.channel.clone(),
265 self.conversation.clone(),
266 ],
267 StorageScope::SharedConversation => vec![
268 "shared-conversation-v1".to_owned(),
269 provider,
270 agent,
271 self.transport_kind.clone(),
272 self.transport.clone(),
273 self.channel.clone(),
274 self.conversation.clone(),
275 ],
276 StorageScope::Agent => vec!["agent-v1".to_owned(), provider, agent],
277 StorageScope::Space => vec![
278 "space-v1".to_owned(),
279 provider,
280 self.space_key.as_ref().map_or_else(String::new, |key| {
281 key.encode()
282 .iter()
283 .map(|byte| format!("{byte:02x}"))
284 .collect()
285 }),
286 ],
287 }
288 }
289 pub(crate) fn scope(&self) -> StorageScope {
290 self.scope
291 }
292 pub(crate) const fn comparison(&self) -> &Comparison {
293 &self.comparison
294 }
295}
296
297pub struct StorageGrantPreparation {
298 host: StorageHost,
299 request: StorageGrantRequest,
300 base_token: String,
301 scope_commitment: StorageScopeCommitment,
302}
303
304impl fmt::Debug for StorageGrantPreparation {
305 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
306 formatter.write_str("StorageGrantPreparation([REDACTED])")
307 }
308}
309
310impl StorageGrantPreparation {
311 #[must_use]
312 pub fn scope_commitment(&self) -> StorageScopeCommitment {
313 self.scope_commitment.clone()
314 }
315
316 #[must_use]
317 pub fn namespace(&self) -> &str {
318 &self.base_token
319 }
320
321 #[must_use]
322 pub fn record_id(&self, delivery: &[u8]) -> String {
323 record_id(&self.base_token, delivery)
324 }
325
326 #[must_use]
327 pub fn evidence_commitment(&self, label: &str, bytes: &[u8]) -> String {
328 commitment(
329 DOMAIN_DECISION_EVIDENCE,
330 &[self.base_token.as_bytes(), label.as_bytes(), bytes],
331 )
332 }
333
334 #[must_use]
335 pub fn content_commitment(&self, user: &str, assistant: &str) -> String {
336 content_commitment(&self.base_token, user, assistant)
337 }
338
339 pub fn materialize(self) -> Result<StorageGrant, StorageHostError> {
340 self.host.materialize_grant(self.request, self.base_token)
341 }
342}
343
344pub struct StorageGrant {
345 host_id: [u8; 32],
346 invocation: InvocationId,
347 capability: CapabilityId,
348 provider: ProviderId,
349 shared_namespace: Option<ProviderId>,
350 interface: StorageInterface,
351 access: StorageAccess,
352 scope_kind: StorageScope,
353 namespace: Namespace,
354 limits: StorageLimits,
355}
356
357impl fmt::Debug for StorageGrant {
358 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
359 formatter.write_str("StorageGrant([REDACTED])")
360 }
361}
362
363impl StorageGrant {
364 #[must_use]
365 pub fn invocation(&self) -> &InvocationId {
366 &self.invocation
367 }
368 #[must_use]
369 pub fn capability(&self) -> &CapabilityId {
370 &self.capability
371 }
372 #[must_use]
373 pub fn provider(&self) -> &ProviderId {
374 &self.provider
375 }
376 #[must_use]
377 pub fn shared_namespace(&self) -> Option<&ProviderId> {
378 self.shared_namespace.as_ref()
379 }
380 #[must_use]
381 pub const fn interface(&self) -> StorageInterface {
382 self.interface
383 }
384 #[must_use]
385 pub const fn access(&self) -> StorageAccess {
386 self.access
387 }
388 #[must_use]
389 pub const fn scope(&self) -> StorageScope {
390 self.scope_kind
391 }
392 #[must_use]
393 pub fn scope_commitment(&self) -> StorageScopeCommitment {
394 StorageScopeCommitment(self.namespace.scope_commitment.clone())
395 }
396 #[must_use]
397 pub fn record_id(&self, delivery: &[u8]) -> String {
398 record_id(&self.namespace.base_token, delivery)
399 }
400 #[must_use]
401 pub fn evidence_commitment(&self, label: &str, bytes: &[u8]) -> String {
402 commitment(
403 DOMAIN_DECISION_EVIDENCE,
404 &[
405 self.namespace.base_token.as_bytes(),
406 label.as_bytes(),
407 bytes,
408 ],
409 )
410 }
411
412 #[must_use]
413 pub fn content_commitment(&self, user: &str, assistant: &str) -> String {
414 content_commitment(&self.namespace.base_token, user, assistant)
415 }
416}
417
418fn record_id(base_token: &str, delivery: &[u8]) -> String {
419 commitment(DOMAIN_RECORD_ID, &[base_token.as_bytes(), delivery])
420}
421
422fn content_commitment(base_token: &str, user: &str, assistant: &str) -> String {
423 commitment(
424 DOMAIN_CONTENT,
425 &[base_token.as_bytes(), user.as_bytes(), assistant.as_bytes()],
426 )
427}
428
429#[derive(Debug)]
430struct HostInner {
431 id: [u8; 32],
432 layout: Layout,
433 ledger: Arc<QuotaLedger>,
434 limits: StorageLimits,
435 namespace_locks: Mutex<BTreeMap<String, Arc<Mutex<()>>>>,
436 namespace_observation_lock: Mutex<()>,
437}
438
439#[derive(Clone)]
440pub struct StorageHost {
441 inner: Arc<HostInner>,
442}
443
444impl fmt::Debug for StorageHost {
445 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
446 formatter.write_str("StorageHost([REDACTED])")
447 }
448}
449
450impl StorageHost {
451 pub fn open(root: impl AsRef<Path>, limits: StorageLimits) -> Result<Self, StorageHostError> {
452 limits.validate()?;
453 let root = resolve_storage_root_path(root.as_ref())?;
454 let minimum = Layout::minimum_usage(&root)?;
455 if minimum.bytes > limits.max_root_bytes || minimum.entries > limits.startup_max_entries {
456 return Err(StorageHostError::QuotaExceeded);
457 }
458 let layout = Layout::open(&root)?;
459 let (usage, namespace_count) = scan_root_usage(&layout, limits.startup_max_entries)?;
460 if usage.bytes > limits.max_root_bytes {
461 return Err(StorageHostError::QuotaExceeded);
462 }
463 tracing::info!(
464 event = "storage_namespace_capacity",
465 storage.namespace.count = namespace_count,
466 storage.namespace.limit = limits.max_namespaces,
467 "storage.namespace.capacity"
468 );
469 let ledger = QuotaLedger::new(limits.clone(), usage);
470 #[allow(
471 clippy::map_err_ignore,
472 reason = "the discarded value is the rejected raw-entropy Vec<u8> itself, whose only \
473 reportable property is the length EntropyLength already names"
474 )]
475 let id: [u8; 32] = random_bytes(32)?
476 .try_into()
477 .map_err(|_| StorageHostError::EntropyLength)?;
478 Ok(Self {
479 inner: Arc::new(HostInner {
480 id,
481 layout,
482 ledger,
483 limits,
484 namespace_locks: Mutex::new(BTreeMap::new()),
485 namespace_observation_lock: Mutex::new(()),
486 }),
487 })
488 }
489
490 #[must_use]
491 pub fn evidence_commitment(&self, label: &str, bytes: &[u8]) -> String {
492 commitment(
493 DOMAIN_DECISION_EVIDENCE,
494 &[b"denied-storage", label.as_bytes(), bytes],
495 )
496 }
497
498 pub fn prepare_grant(
499 &self,
500 request: StorageGrantRequest,
501 ) -> Result<StorageGrantPreparation, StorageHostError> {
502 if request.scope == StorageScope::Space
503 && !request
504 .space_key
505 .as_ref()
506 .is_some_and(|key| key.agent == request.agent)
507 {
508 return Err(StorageHostError::InvalidArgument);
509 }
510 let values = request.scope_values();
511 let fields = values.iter().map(String::as_bytes).collect::<Vec<_>>();
512 Ok(StorageGrantPreparation {
513 host: self.clone(),
514 base_token: token(DOMAIN_NAMESPACE_PATH, &fields),
515 scope_commitment: StorageScopeCommitment(commitment(DOMAIN_AUDIT_SCOPE, &fields)),
516 request,
517 })
518 }
519
520 pub fn grant(&self, request: StorageGrantRequest) -> Result<StorageGrant, StorageHostError> {
521 self.prepare_grant(request)?.materialize()
522 }
523
524 fn materialize_grant(
525 &self,
526 request: StorageGrantRequest,
527 base: String,
528 ) -> Result<StorageGrant, StorageHostError> {
529 debug_assert_eq!(
530 base,
531 token(
532 DOMAIN_NAMESPACE_PATH,
533 &request
534 .scope_values()
535 .iter()
536 .map(String::as_bytes)
537 .collect::<Vec<_>>()
538 )
539 );
540 let deadline = deadline_after(self.inner.limits.lock_timeout_ms)?;
543 let namespace_lock = namespace_lock(&self.inner.namespace_locks, &base);
544 let _namespace = lock_before(&namespace_lock, deadline)?;
545 let mut namespace_reservation = Some({
546 let _observation = self.inner.namespace_observation_lock.lock();
549 let observed_namespaces = self
550 .inner
551 .layout
552 .namespaces()
553 .entries_bounded(self.inner.limits.startup_max_entries)?
554 .into_iter()
555 .collect::<BTreeSet<_>>();
556 self.inner
557 .ledger
558 .reserve_namespace(base.clone(), observed_namespaces)?
559 });
560 let mut plan = NamespacePlan::prepare(
563 self.inner.layout.namespaces(),
564 &request,
565 deadline,
566 self.inner.limits.startup_max_entries,
567 )?;
568 let reset = plan.take_reset();
569 let continuity = plan.take_continuity();
570 if plan.maximum_generation_peak_bytes() > self.inner.limits.max_namespace_bytes {
571 return Err(StorageHostError::QuotaExceeded);
572 }
573 let before_namespace = plan.before_usage();
574 let housekeeping_reservation = self
575 .inner
576 .ledger
577 .reserve_root(plan.reserved_bytes(), plan.reserved_entries())?;
578 let _observation = self.inner.namespace_observation_lock.lock();
581 self.inner.ledger.observe_namespaces(
582 self.inner
583 .layout
584 .namespaces()
585 .entries_bounded(self.inner.limits.startup_max_entries)?,
586 );
587 let namespace = match plan.apply(self.inner.layout.namespaces(), deadline) {
588 Ok(namespace) => namespace,
589 Err(error) => {
590 if self.inner.layout.namespaces().exists(&base).unwrap_or(true) {
593 namespace_reservation
594 .take()
595 .expect("namespace reservation")
596 .commit();
597 }
598 housekeeping_reservation.retain();
599 return Err(error);
600 }
601 };
602 let base_directory = match self.inner.layout.namespaces().open_directory(&base) {
603 Ok(directory) => directory,
604 Err(error) => {
605 namespace_reservation
606 .take()
607 .expect("namespace reservation")
608 .commit();
609 housekeeping_reservation.retain();
610 return Err(error);
611 }
612 };
613 let scanned = match scan_usage(&base_directory, self.inner.limits.startup_max_entries) {
614 Ok(usage) => usage,
615 Err(error) => {
616 namespace_reservation
617 .take()
618 .expect("namespace reservation")
619 .commit();
620 housekeeping_reservation.retain();
621 return Err(error);
622 }
623 };
624 let after_namespace = match usage_with_directory_entry(scanned) {
625 Ok(usage) => usage,
626 Err(error) => {
627 namespace_reservation
628 .take()
629 .expect("namespace reservation")
630 .commit();
631 housekeeping_reservation.retain();
632 return Err(error);
633 }
634 };
635 if let Err(error) = housekeeping_reservation.commit(before_namespace, after_namespace) {
636 namespace_reservation
637 .take()
638 .expect("namespace reservation")
639 .commit();
640 return Err(error);
641 }
642 namespace_reservation
643 .take()
644 .expect("namespace reservation")
645 .commit();
646 if let Some(cause) = reset {
647 return Err(report_namespace_reset(cause, &namespace));
648 }
649 match continuity {
650 Some(ContinuityOutcome::Migrated) => tracing::info!(
651 event = "storage_continuity_migrated",
652 category = "storage",
653 storage.namespace = %namespace.base_token,
654 storage.generation = %namespace.generation_token,
655 "storage.continuity.migrated"
656 ),
657 Some(ContinuityOutcome::FreshEpoch { check }) => tracing::warn!(
658 event = "storage_continuity_fresh_epoch",
659 category = "storage",
660 storage.namespace = %namespace.base_token,
661 storage.generation = %namespace.generation_token,
662 storage.continuity.check = check.label(),
663 "storage.continuity.fresh_epoch"
664 ),
665 None => {}
666 }
667 Ok(StorageGrant {
668 host_id: self.inner.id,
669 invocation: request.invocation,
670 capability: request.capability,
671 provider: request.provider,
672 shared_namespace: request.shared_namespace,
673 interface: request.interface,
674 access: request.access,
675 scope_kind: request.scope,
676 namespace,
677 limits: self.inner.limits.clone(),
678 })
679 }
680
681 pub fn begin(&self, grant: StorageGrant) -> Result<StorageHandle, StorageHostError> {
682 if grant.host_id != self.inner.id {
683 return Err(StorageHostError::GrantHostMismatch);
684 }
685 StorageHandle::begin(grant, Arc::clone(&self.inner.ledger))
686 }
687
688 #[must_use]
689 pub fn limits(&self) -> &StorageLimits {
690 &self.inner.limits
691 }
692}
693
694fn lock_before(
695 lock: &Mutex<()>,
696 deadline: Instant,
697) -> Result<MutexGuard<'_, ()>, StorageHostError> {
698 loop {
699 match lock.try_lock() {
700 Some(guard) => return Ok(guard),
701 None if Instant::now() < deadline => {
702 std::thread::sleep(Duration::from_millis(5));
703 }
704 None => return Err(StorageHostError::Timeout),
705 }
706 }
707}
708
709fn namespace_lock(
710 registry: &Mutex<BTreeMap<String, Arc<Mutex<()>>>>,
711 base: &str,
712) -> Arc<Mutex<()>> {
713 let mut locks = registry.lock();
714 locks.retain(|_, lock| Arc::strong_count(lock) > 1);
715 Arc::clone(
716 locks
717 .entry(base.to_owned())
718 .or_insert_with(|| Arc::new(Mutex::new(()))),
719 )
720}
721
722pub fn resolve_storage_root_path(path: &Path) -> Result<PathBuf, StorageHostError> {
723 let io_error = |path: &Path, source: std::io::Error| StorageHostError::RootIo {
724 path: path.to_path_buf(),
725 source,
726 };
727 let unsafe_path = |path: &Path| StorageHostError::UnsafeRoot {
728 path: path.to_path_buf(),
729 };
730 let absolute = if path.is_absolute() {
731 path.to_path_buf()
732 } else {
733 std::env::current_dir()
734 .map_err(|source| io_error(path, source))?
735 .join(path)
736 };
737 let mut components = Vec::new();
738 for component in absolute.components() {
739 match component {
740 Component::RootDir | Component::CurDir => {}
741 Component::Normal(component) => components.push(component.to_os_string()),
742 Component::ParentDir | Component::Prefix(_) => return Err(unsafe_path(&absolute)),
743 }
744 }
745 if components.is_empty() {
746 return Err(unsafe_path(&absolute));
747 }
748
749 let root_fd = rustix::fs::open(
750 "/",
751 rustix::fs::OFlags::RDONLY
752 | rustix::fs::OFlags::DIRECTORY
753 | rustix::fs::OFlags::NOFOLLOW
754 | rustix::fs::OFlags::CLOEXEC,
755 rustix::fs::Mode::empty(),
756 )
757 .map_err(|source| io_error(Path::new("/"), std::io::Error::from(source)))?;
758 let mut directory = File::from(root_fd);
759 let mut traversed = PathBuf::from("/");
760 for component in &components[..components.len() - 1] {
761 traversed.push(component);
762 let fd = rustix::fs::openat(
763 &directory,
764 component,
765 rustix::fs::OFlags::RDONLY
766 | rustix::fs::OFlags::DIRECTORY
767 | rustix::fs::OFlags::NOFOLLOW
768 | rustix::fs::OFlags::CLOEXEC,
769 rustix::fs::Mode::empty(),
770 )
771 .map_err(|source| io_error(&traversed, std::io::Error::from(source)))?;
772 directory = File::from(fd);
773 }
774 traversed.push(components.last().expect("non-empty path components"));
775 Ok(traversed)
776}
777
778fn report_namespace_reset(reset: Reset, fresh: &Namespace) -> StorageHostError {
779 tracing::error!(
780 event = "storage_namespace_reset",
781 category = "storage",
782 storage.namespace = %fresh.base_token,
783 storage.generation = %fresh.generation_token,
784 storage.previous_generation = reset.previous_generation.as_deref(),
785 storage.check = reset.check,
786 storage.path = reset
787 .path
788 .as_deref()
789 .map(|path| tracing::field::display(path.display())),
790 "storage.namespace.reset"
791 );
792 StorageHostError::Corrupt {
793 scope: reset.check,
794 site: Some(Box::new(CorruptionSite {
795 namespace: Some(fresh.base_token.clone()),
796 generation: reset.previous_generation,
797 path: reset.path,
798 reset: Some(fresh.generation_token.clone()),
799 })),
800 }
801}
802
803pub(crate) fn report_decode_failure(document: &'static str, error: &serde_json::Error) {
804 tracing::warn!(
805 event = "storage_document_decode_failed",
806 category = "storage",
807 storage.document = document,
808 decode.class = ?error.classify(),
809 decode.line = error.line(),
810 decode.column = error.column(),
811 "storage.document.decode.failed"
812 );
813}
814
815#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
816pub enum StorageFailureClass {
817 Quota,
818 Timeout,
819 Corrupt,
820 Denied,
821 Io,
822}
823
824impl StorageFailureClass {
825 #[must_use]
826 pub const fn label(self) -> &'static str {
827 match self {
828 Self::Quota => "quota",
829 Self::Timeout => "timeout",
830 Self::Corrupt => "corrupt",
831 Self::Denied => "denied",
832 Self::Io => "io",
833 }
834 }
835}
836
837impl std::fmt::Display for StorageFailureClass {
838 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
839 formatter.write_str(self.label())
840 }
841}
842
843#[derive(Debug, Error)]
844pub enum StorageHostError {
845 #[error(transparent)]
846 Configuration(#[from] StorageConfigError),
847 #[error("storage root input/output failed at {}", path.display())]
848 RootIo {
849 path: PathBuf,
850 #[source]
851 source: std::io::Error,
852 },
853 #[error("storage root or ancestor is unsafe: {}", path.display())]
854 UnsafeRoot { path: PathBuf },
855 #[error("another conforming storage writer holds the root")]
856 SecondWriter,
857 #[error("storage layout is corrupt: {}", path.display())]
858 CorruptLayout { path: PathBuf },
859 #[error("storage corruption detected: {scope}{}", SiteSuffix(.site))]
860 Corrupt {
861 scope: &'static str,
862 site: Option<Box<CorruptionSite>>,
863 },
864 #[error("storage quota exceeded")]
865 QuotaExceeded,
866 #[error("storage resource is busy")]
867 Busy,
868 #[error("storage operation timed out")]
869 Timeout,
870 #[error("storage permission denied")]
871 PermissionDenied,
872 #[error("storage logical name is invalid")]
873 InvalidName,
874 #[error("storage argument is invalid")]
875 InvalidArgument,
876 #[error("storage object was not found")]
877 NotFound,
878 #[error("storage object already exists")]
879 AlreadyExists,
880 #[error("storage operation is unsupported")]
881 Unsupported,
882 #[error("storage input/output failed")]
883 Io,
884 #[error("storage arithmetic overflowed")]
885 Arithmetic,
886 #[error("storage entropy failed")]
887 Entropy {
888 #[source]
889 source: std::io::Error,
890 },
891 #[error("storage entropy returned an invalid length")]
892 EntropyLength,
893 #[error("storage clock failed")]
894 Clock,
895 #[error("storage startup scan saw {count} entries, above {maximum}")]
896 StartupEntryLimit { count: u64, maximum: u64 },
897 #[error("storage grant belongs to another host instance")]
898 GrantHostMismatch,
899 #[error("broker memory continuity could not be proved: {}", check.label())]
900 ContinuityUnproven { check: ContinuityCheck },
901}
902
903#[derive(Clone, Debug, Default, Eq, PartialEq)]
904pub struct CorruptionSite {
905 pub namespace: Option<String>,
906 pub generation: Option<String>,
907 pub path: Option<PathBuf>,
908 pub reset: Option<String>,
909}
910
911struct SiteSuffix<'a>(&'a Option<Box<CorruptionSite>>);
912
913impl fmt::Display for SiteSuffix<'_> {
914 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
915 let Some(site) = self.0 else {
916 return Ok(());
917 };
918 if let Some(namespace) = &site.namespace {
919 write!(formatter, " in namespace {namespace}")?;
920 }
921 if let Some(generation) = &site.generation {
922 write!(formatter, " generation {generation}")?;
923 }
924 if let Some(path) = &site.path {
925 write!(formatter, " at {}", path.display())?;
926 }
927 if let Some(reset) = &site.reset {
928 write!(formatter, "; reset to generation {reset}")?;
929 }
930 Ok(())
931 }
932}
933
934impl StorageHostError {
935 #[must_use]
936 pub const fn corrupt(scope: &'static str) -> Self {
937 Self::Corrupt { scope, site: None }
938 }
939
940 #[expect(
941 clippy::wildcard_enum_match_arm,
942 reason = "reshaped by the unit that next rewrites this"
943 )]
944 fn site_mut(&mut self) -> Option<&mut CorruptionSite> {
945 match self {
946 Self::Corrupt { site, .. } => Some(site.get_or_insert_with(Box::default)),
947 _ => None,
948 }
949 }
950
951 pub(crate) fn at(mut self, entry: PathBuf) -> Self {
952 if let Some(site) = self.site_mut() {
953 site.path.get_or_insert(entry);
954 }
955 self
956 }
957
958 pub(crate) fn in_namespace(mut self, base: &str, generation_token: Option<&str>) -> Self {
959 if let Some(site) = self.site_mut() {
960 site.namespace.get_or_insert_with(|| base.to_owned());
961 if let Some(token) = generation_token {
962 site.generation.get_or_insert_with(|| token.to_owned());
963 }
964 }
965 self
966 }
967
968 #[must_use]
969 pub fn namespace_reset(&self) -> bool {
970 matches!(self, Self::Corrupt { site: Some(site), .. } if site.reset.is_some())
971 }
972
973 #[must_use]
974 #[expect(
975 clippy::wildcard_enum_match_arm,
976 reason = "reshaped by the unit that next rewrites this"
977 )]
978 pub const fn class(&self) -> StorageFailureClass {
979 match self {
980 Self::QuotaExceeded | Self::Arithmetic => StorageFailureClass::Quota,
981 Self::Timeout => StorageFailureClass::Timeout,
982 Self::Corrupt { .. } | Self::CorruptLayout { .. } => StorageFailureClass::Corrupt,
983 Self::PermissionDenied | Self::GrantHostMismatch | Self::ContinuityUnproven { .. } => {
984 StorageFailureClass::Denied
985 }
986 _ => StorageFailureClass::Io,
987 }
988 }
989}