cacache_sync/
lib.rs

1//! cacache is a Rust library for managing local key and content address
2//! caches. It's really fast, really good at concurrency, and it will never
3//! give you corrupted data, even if cache files get corrupted or manipulated.
4//!
5//! ## API Layout
6//!
7//! The cacache API is organized roughly similar to `std::fs`; most of the
8//! toplevel functionality is available as free functions directly in the
9//! `cacache` module, with some additional functionality available through
10//! returned objects, as well as `WriteOpts`, which is analogous to
11//! `OpenOpts`, but is only able to write.
12//!
13//! ### Suffixes
14//!
15//! You may notice various suffixes associated with otherwise familiar
16//! functions:
17//!
18//! * `_hash` - Since cacache is a content-addressable cache, the `_hash`
19//!   suffix means you're interacting directly with content data, skipping the
20//!   index and its metadata. These functions use an `Integrity` to look up
21//!   data, instead of a string key.
22//!
23//! ## Examples
24//!
25//! ```no_run
26//! fn main() -> cacache_sync::Result<()> {
27//!   // Data goes in...
28//!   cacache_sync::write("./my-cache", "key", b"hello")?;
29//!
30//!   // ...data comes out!
31//!   let data = cacache_sync::read("./my-cache", "key")?;
32//!   assert_eq!(data, b"hello");
33//!
34//!   Ok(())
35//! }
36//! ```
37//!
38//! ### Lookup by hash
39//!
40//! What makes `cacache` content addressable, though, is its ability to fetch
41//! data by its "content address", which in our case is a ["subresource
42//! integrity" hash](https://crates.io/crates/ssri), which `cacache_sync::put`
43//! conveniently returns for us. Fetching data by hash is significantly faster
44//! than doing key lookups:
45//!
46//! ```no_run
47//! fn main() -> cacache_sync::Result<()> {
48//!   // Data goes in...
49//!   let sri = cacache_sync::write("./my-cache", "key", b"hello")?;
50//!
51//!   // ...data gets looked up by `sri` ("Subresource Integrity").
52//!   let data = cacache_sync::read_hash("./my-cache", &sri)?;
53//!   assert_eq!(data, b"hello");
54//!
55//!   Ok(())
56//! }
57//! ```
58//!
59//! ### Large file support
60//!
61//! `cacache-sync` supports large file reads, through an API reminiscent of
62//! `std::fs::OpenOptions`:
63//!
64//! ```no_run
65//! use std::io::{Read, Write};
66//!
67//! fn main() -> cacache_sync::Result<()> {
68//!   let mut fd = cacache_sync::Writer::create("./my-cache", "key")?;
69//!   for _ in 0..10 {
70//!     fd.write_all(b"very large data").expect("Failed to write to cache");
71//!   }
72//!   // Data is only committed to the cache after you do `fd.commit()`!
73//!   let sri = fd.commit()?;
74//!   println!("integrity: {}", &sri);
75//!
76//!   let mut fd = cacache_sync::Reader::open("./my-cache", "key")?;
77//!   let mut buf = String::new();
78//!   fd.read_to_string(&mut buf).expect("Failed to read to string");
79//!
80//!   // Make sure to call `.check()` when you're done! It makes sure that what
81//!   // you just read is actually valid. `cacache` always verifies the data
82//!   // you get out is what it's supposed to be. The check is very cheap!
83//!   fd.check()?;
84//!
85//!   Ok(())
86//! }
87//! ```
88
89pub use serde_json::Value;
90pub use ssri::Algorithm;
91
92mod content;
93mod errors;
94mod index;
95
96mod get;
97mod ls;
98mod put;
99mod rm;
100
101pub use errors::{Error, Result};
102pub use index::Metadata;
103
104pub use get::*;
105pub use ls::*;
106pub use put::*;
107pub use rm::*;
cacache_sync/lib.rs

cacache_sync/
lib.rs
