rtb_assets/lib.rs
1//! Embedded-asset + overlay filesystem abstraction.
2//!
3//! Tools built on RTB ship assets from three places: compiled into the
4//! binary via [`rust_embed`], on the user's disk (per-user overrides),
5//! and in-memory (tests, scaffolders). [`Assets`] unifies these behind
6//! a single read-only API.
7//!
8//! # Semantics
9//!
10//! * **Binary reads** ([`Assets::open`], [`Assets::open_text`],
11//! [`Assets::exists`]) follow last-wins shadowing. The
12//! highest-priority layer that provides the path supplies the bytes.
13//! * **Directory listing** ([`Assets::list_dir`]) unions entries across
14//! layers, deduplicated and sorted.
15//! * **Structured merge** ([`Assets::load_merged_yaml`],
16//! [`Assets::load_merged_json`]) reads the file from every layer that
17//! has it and deep-merges via RFC-7396 merge-patch semantics — nested
18//! maps merge recursively; scalars replace wholesale.
19//!
20//! # Construction
21//!
22//! ```
23//! use rtb_assets::Assets;
24//! use std::collections::HashMap;
25//!
26//! let assets = Assets::builder()
27//! .memory(
28//! "defaults",
29//! HashMap::from([("greeting.txt".into(), b"hello".to_vec())]),
30//! )
31//! .build();
32//!
33//! assert_eq!(assets.open_text("greeting.txt").unwrap(), "hello");
34//! ```
35//!
36//! See `docs/development/specs/2026-04-22-rtb-assets-v0.1.md` for the
37//! authoritative contract.
38
39#![forbid(unsafe_code)]
40
41pub mod assets;
42pub mod error;
43pub mod source;
44
45pub use assets::{Assets, AssetsBuilder};
46pub use error::AssetError;
47pub use source::{AssetSource, DirectorySource, EmbeddedSource, MemorySource};