1/*
 2 * SPDX-FileCopyrightText: 2026 Copyright (c) Contributors to the Eclipse Foundation
 3 *
 4 * See the NOTICE file(s) distributed with this work for additional
 5 * information regarding copyright ownership.
 6 *
 7 * This program and the accompanying materials are made available under the
 8 * terms of the Apache License Version 2.0 which is available at
 9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * SPDX-License-Identifier: Apache-2.0
12 */
13
14//! Local filesystem storage backend for the CDA Storage Access API.
15//!
16//! This crate provides [`LocalStorage`], a crash-safe, transactional storage implementation
17//! backed by the local filesystem. It implements the traits defined in
18//! [`cda_interfaces::storage_api`].
19//!
20//! ## Directory layout
21//!
22//! ```text
23//! {root}/
24//! \-- collections/
25//! \   \-- diagnostic_database/
26//! \   \   \-- key_a
27//! \   \   \-- key_b
28//! \   \-- diagnostic_database_backup/
29//! \-- journal/
30//!     \-- transaction.wal
31//!     \-- staging/
32//!         \-- {uuid}.tmp
33//! ```
34//!
35//! ## Usage
36//!
37//! ```rust,no_run
38//! use cda_interfaces::storage_api::{Collection as _, CollectionName, Storage};
39//! use cda_storage::LocalStorage;
40//!
41//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
42//! let storage = LocalStorage::new("/tmp/cda-storage")?;
43//!
44//! // Read access -> no transaction needed.
45//! let collection = storage.get_or_create_collection(&CollectionName::DiagnosticDatabase).await?;
46//! let keys = collection.list().await?;
47//!
48//! // Write access -> requires a transaction.
49//! let mut tx = storage.begin_transaction()?;
50//! let mut data: &[u8] = b"hello world";
51//! collection.write(&mut tx, "my_key", &mut data).await?;
52//! tx.commit().await?;
53//! # Ok(())
54//! # }
55//! ```
56
57mod io;
58mod local_collection;
59mod local_storage;
60mod paths;
61pub(crate) mod recovery;
62pub mod storage_seed;
63/// Write-ahead log utilities. Exposed publicly for use in recovery tests.
[docs]64/// [[ dimpl~storage-wal-journaling, Write-ahead log with checksum-verified one-phase commit, dimpl ]]
65pub mod wal;
66
67pub use local_collection::LocalCollection;
68pub use local_storage::LocalStorage;