nimbus_vault/lib.rs
1#![warn(missing_docs)]
2//! A generic sync abstraction: a tree of [`object::Object`]s (a [`vault::Vault`]) whose
3//! actual storage lives behind a pluggable [`origin::Origin`] — a local directory, an HTTP
4//! API, a shell command, or another vault. Syncing "a folder on disk" and "objects behind a
5//! REST API" run through the exact same code path, because both are just implementations of
6//! one `Origin` trait.
7//!
8//! # The model
9//!
10//! - [`object::Object`] — a node in the tree: `Leaf` (has content), `Branch` (has children),
11//! or `Root`. Objects only ever carry metadata (name, id, size, content type, modified time,
12//! plus a free-form `extra` map) — never raw bytes — so listing a tree never materializes
13//! its contents into memory.
14//! - [`object::ObjectId`] — a newtype around `String`, opaque and origin-specific (a relative
15//! path for the filesystem origin, an arbitrary id for HTTP/command origins).
16//! - [`origin::Origin`] — the trait every backend implements: `fetch`, `list`, `get`, `put`,
17//! `send`, `delete`. `fetch`/`send` are streaming
18//! ([`origin::ByteStream`] = `BoxStream<'static, VaultResult<Bytes>>`) — content moves in
19//! chunks, it's never buffered whole into RAM. `put(object, destination)` writes `object`
20//! under `destination` and returns the `Object` as it now exists at the origin —
21//! implementations may, but aren't required to, rename `object` in place, so callers should
22//! always act on the returned value rather than assuming `object` itself changed.
23//! - [`vault::Vault`] — owns one `Origin` plus an in-memory metadata cache. `get`/`list`
24//! populate the cache; `list` always re-hits the origin (it's the source of truth) while
25//! refreshing the cache. `find` resolves a `/`-separated path to an `ObjectId` by walking
26//! the tree one `list` call per component. `put` only updates the cache on success, and
27//! caches the `Object` `put` returned. `pull`/`push` recursively sync a subtree between the
28//! vault's own origin and any other `&dyn Origin`, threading `put`'s return value through to
29//! the following `send`.
30//!
31//! Four built-in origins ship in this crate:
32//!
33//! - [`origin::fs::OriginFileSystem`] (`type = "fs"`) — a directory on disk, via `tokio::fs`.
34//! - [`origin::http::OriginHTTP`] (`type = "http"`) — any REST-ish API, with a
35//! `{id}`-templated URL per operation.
36//! - [`origin::command::OriginCommand`] (`type = "command"`) — a shell command per operation;
37//! the universal escape hatch for anything that isn't a plain filesystem or HTTP API.
38//! - [`origin::vault::OriginVault`] (`type = "vault"`) — another [`vault::Vault`], wrapped so
39//! it can act as an origin in its own right, letting two vaults sync directly with `push`/
40//! `pull` without either side needing to know the other is a `Vault` rather than a plain
41//! origin.
42//!
43//! # Configuration
44//!
45//! A vault is fully described by a TOML file, deserialized into [`config::VaultConfig`] /
46//! [`config::OriginConfig`]:
47//!
48//! ```toml
49//! # vault.toml — backed by a local directory
50//! name = "my-vault"
51//!
52//! [origin_config]
53//! type = "fs"
54//! root = "/srv/data"
55//! ```
56//!
57//! ```no_run
58//! use nimbus_vault::vault::Vault;
59//!
60//! # async fn example() -> nimbus_vault::VaultResult<()> {
61//! let vault = Vault::new("vault.toml".into())?;
62//! let root = vault.find("/".into()).await?;
63//! let children = vault.list(root).await?;
64//! # Ok(())
65//! # }
66//! ```
67//!
68//! An `origin_config` can also be built standalone, without a `name`/`root_id`/`Vault`
69//! wrapper, via [`config::OriginConfig::from_file`] — useful for tooling that talks to an
70//! origin directly, or for building the `remote` argument to
71//! [`vault::Vault::pull`]/[`vault::Vault::push`].
72//!
73//! A config file can live anywhere, but [`config::VaultConfig::default_path`] gives the
74//! conventional home for one — `vaults/<name>.toml` under [`config_home`] — which is where
75//! nimbus's own tooling writes new vaults so they can be found again later.
76//!
77//! # Quick start
78//!
79//! A fully self-contained, end-to-end example — writing a vault config, creating an object,
80//! reading it back, and listing its parent:
81//!
82//! ```
83//! use std::fs;
84//! use futures::StreamExt;
85//! use nimbus_vault::{object::{Metadata, Object, ObjectId}, vault::Vault};
86//!
87//! # #[tokio::main]
88//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
89//! let dir = tempfile::tempdir()?;
90//! let data_dir = dir.path().join("data");
91//! fs::create_dir_all(&data_dir)?;
92//!
93//! let config_path = dir.path().join("vault.toml");
94//! fs::write(
95//! &config_path,
96//! format!(
97//! "name = \"my-vault\"\n\n[origin_config]\ntype = \"fs\"\nroot = \"{}\"\n",
98//! data_dir.display(),
99//! ),
100//! )?;
101//!
102//! let vault = Vault::new(config_path)?;
103//!
104//! // create an object
105//! let mut notes = Object::Leaf {
106//! name: "notes.txt".to_string(),
107//! id: ObjectId::from("notes.txt"),
108//! meta: Metadata::new(),
109//! };
110//! vault.put(&mut notes, &ObjectId::from("")).await?;
111//! vault.send(¬es, Box::pin(futures::stream::once(async {
112//! Ok(bytes::Bytes::from_static(b"hello vault"))
113//! }))).await?;
114//!
115//! // read it back
116//! let mut stream = vault.fetch("notes.txt").await?;
117//! let mut bytes = Vec::new();
118//! while let Some(chunk) = stream.next().await {
119//! bytes.extend_from_slice(&chunk?);
120//! }
121//! assert_eq!(&bytes, b"hello vault");
122//!
123//! // list the vault's root
124//! let names: Vec<String> = vault.list("").await?.iter().map(Object::get_name).collect();
125//! assert_eq!(names, vec!["notes.txt".to_string()]);
126//! # Ok(())
127//! # }
128//! ```
129//!
130//! # Syncing
131//!
132//! [`vault::Vault::pull`]/[`vault::Vault::push`] sync a subtree between the vault's own origin
133//! and any other `&dyn Origin` — another config-defined origin, or another vault wrapped in
134//! [`origin::vault::OriginVault`]:
135//!
136//! ```no_run
137//! use nimbus_vault::{config::OriginConfig, vault::Vault};
138//!
139//! # async fn example() -> nimbus_vault::VaultResult<()> {
140//! let vault = Vault::new("vault.toml".into())?;
141//! let remote = OriginConfig::from_file("remote.toml".into())?;
142//! let root = vault.find("".into()).await?;
143//!
144//! vault.pull(&root, remote.as_ref()).await?; // bring local up to date with remote
145//! vault.push(&root, remote.as_ref()).await?; // push local changes back out
146//! # Ok(())
147//! # }
148//! ```
149//!
150//! # Errors
151//!
152//! Every fallible operation in this crate returns [`VaultResult`], an alias for
153//! `Result<T, `[`error::VaultError`]`>`.
154//!
155//! # Constants
156//!
157//! The `{placeholder}` keys, `OriginConfig::Command` field names, and root id/name
158//! conventions shared across [`object`] and the [`origin::command`]/[`origin::http`]
159//! implementations are defined once here (e.g. [`ROOT_ID`], [`PLACEHOLDER_ID`],
160//! [`FETCH_CMD_FIELD`]) rather than being hardcoded independently in each module.
161
162/// On-disk (TOML) configuration for a [`vault::Vault`] and the [`origin::Origin`] it wraps.
163pub mod config;
164/// The crate's error type, [`error::VaultError`], and the [`VaultResult`] alias built from it.
165pub mod error;
166/// The tree node type, [`object::Object`], along with [`object::ObjectId`] and
167/// [`object::Metadata`].
168pub mod object;
169/// The [`origin::Origin`] trait and its built-in implementations (`fs`, `http`, `command`,
170/// `vault`).
171pub mod origin;
172/// [`vault::Vault`], the tree-like view over an `Origin` that ties everything together.
173pub mod vault;
174
175/// The result type used throughout this crate, shorthand for `Result<T, `[`error::VaultError`]`>`.
176pub type VaultResult<T> = Result<T, error::VaultError>;
177
178/// Conventional root [`object::ObjectId`] value, used by [`object::ObjectId::default`] and
179/// [`object::Object::root`].
180pub const ROOT_ID: &str = "/";
181/// Display name reported by [`object::Object::get_name`] for the `Root` variant, which has no
182/// real name of its own.
183pub const ROOT_NAME: &str = "##ROOT##";
184
185/// Template placeholder key substituted with an object's id in
186/// [`origin::command::OriginCommand`]/[`origin::http::OriginHTTP`] templates (rendered as
187/// `{id}`).
188pub const PLACEHOLDER_ID: &str = "id";
189/// Template placeholder key substituted with an object's name in
190/// [`origin::command::OriginCommand`] templates (rendered as `{name}`).
191pub const PLACEHOLDER_NAME: &str = "name";
192/// Template placeholder key substituted with an object's payload size in
193/// [`origin::command::OriginCommand`] templates (rendered as `{size}`).
194pub const PLACEHOLDER_SIZE: &str = "size";
195/// Template placeholder key substituted with an object's content type in
196/// [`origin::command::OriginCommand`] templates (rendered as `{content_type}`).
197pub const PLACEHOLDER_CONTENT_TYPE: &str = "content_type";
198/// Template placeholder key substituted with an object's modified timestamp in
199/// [`origin::command::OriginCommand`] templates (rendered as `{modified}`).
200pub const PLACEHOLDER_MODIFIED: &str = "modified";
201/// `extra_vars` key [`origin::command::OriginCommand`]'s `put` uses to expose its
202/// `destination` argument to the `put_cmd` template (rendered as `{destination}`). Refreshed
203/// on every `put`.
204pub const PLACEHOLDER_DESTINATION: &str = "destination";
205/// Template placeholder key substituted with an object's kind in
206/// [`origin::command::OriginCommand`] templates (rendered as `{kind}`), taking the value
207/// [`OBJECT_KIND_LEAF`] or [`OBJECT_KIND_BRANCH`]. Without it a `put_cmd` has no way to tell
208/// whether it is being asked to create a file or a directory.
209pub const PLACEHOLDER_KIND: &str = "kind";
210/// Value substituted for [`PLACEHOLDER_KIND`] when putting a file.
211pub const OBJECT_KIND_LEAF: &str = "leaf";
212/// Value substituted for [`PLACEHOLDER_KIND`] when putting a directory.
213pub const OBJECT_KIND_BRANCH: &str = "branch";
214/// Fallback content type substituted into command templates when an object's metadata doesn't
215/// specify one.
216pub const UNKNOWN_CONTENT_TYPE: &str = "unknown";
217
218/// [`config::OriginConfig::Command`]/[`origin::command::CmdType`] field name for the fetch
219/// command template.
220pub const FETCH_CMD_FIELD: &str = "fetch_cmd";
221/// [`config::OriginConfig::Command`]/[`origin::command::CmdType`] field name for the list
222/// command template.
223pub const LIST_CMD_FIELD: &str = "list_cmd";
224/// [`config::OriginConfig::Command`]/[`origin::command::CmdType`] field name for the get
225/// command template.
226pub const GET_CMD_FIELD: &str = "get_cmd";
227/// [`config::OriginConfig::Command`]/[`origin::command::CmdType`] field name for the put
228/// command template.
229pub const PUT_CMD_FIELD: &str = "put_cmd";
230/// [`config::OriginConfig::Command`]/[`origin::command::CmdType`] field name for the send
231/// command template.
232pub const SEND_CMD_FIELD: &str = "send_cmd";
233/// [`config::OriginConfig::Command`]/[`origin::command::CmdType`] field name for the delete
234/// command template.
235pub const DELETE_CMD_FIELD: &str = "delete_cmd";
236
237/// Directory nimbus keeps its own configuration in: `.nimbus` under the platform config
238/// directory (`$XDG_CONFIG_HOME` on Linux), falling back to the temp directory when there
239/// isn't one.
240///
241/// Defined here rather than in each binary so the CLI's own config and the vault configs
242/// written by the creator wizard can't drift apart.
243///
244/// # Examples
245///
246/// ```
247/// let home = nimbus_vault::config_home();
248/// assert!(home.ends_with(".nimbus"));
249/// ```
250pub fn config_home() -> std::path::PathBuf {
251 dirs::config_dir()
252 .unwrap_or_else(std::env::temp_dir)
253 .join(".nimbus")
254}