Crate cacache_sync

cacache is a Rust library for managing local key and content address caches. It’s really fast, really good at concurrency, and it will never give you corrupted data, even if cache files get corrupted or manipulated.

API Layout

The cacache API is organized roughly similar to std::fs; most of the toplevel functionality is available as free functions directly in the cacache module, with some additional functionality available through returned objects, as well as WriteOpts, which is analogous to OpenOpts, but is only able to write.

Suffixes

You may notice various suffixes associated with otherwise familiar functions:

• _hash - Since cacache is a content-addressable cache, the _hash suffix means you’re interacting directly with content data, skipping the index and its metadata. These functions use an Integrity to look up data, instead of a string key.

Examples

fn main() -> cacache_sync::Result<()> {
  // Data goes in...
  cacache_sync::write("./my-cache", "key", b"hello")?;

  // ...data comes out!
  let data = cacache_sync::read("./my-cache", "key")?;
  assert_eq!(data, b"hello");

  Ok(())
}

Lookup by hash

What makes cacache content addressable, though, is its ability to fetch data by its “content address”, which in our case is a “subresource integrity” hash, which cacache_sync::put conveniently returns for us. Fetching data by hash is significantly faster than doing key lookups:

fn main() -> cacache_sync::Result<()> {
  // Data goes in...
  let sri = cacache_sync::write("./my-cache", "key", b"hello")?;

  // ...data gets looked up by `sri` ("Subresource Integrity").
  let data = cacache_sync::read_hash("./my-cache", &sri)?;
  assert_eq!(data, b"hello");

  Ok(())
}

Large file support

cacache-sync supports large file reads, through an API reminiscent of std::fs::OpenOptions:

use std::io::{Read, Write};

fn main() -> cacache_sync::Result<()> {
  let mut fd = cacache_sync::Writer::create("./my-cache", "key")?;
  for _ in 0..10 {
    fd.write_all(b"very large data").expect("Failed to write to cache");
  }
  // Data is only committed to the cache after you do `fd.commit()`!
  let sri = fd.commit()?;
  println!("integrity: {}", &sri);

  let mut fd = cacache_sync::Reader::open("./my-cache", "key")?;
  let mut buf = String::new();
  fd.read_to_string(&mut buf).expect("Failed to read to string");

  // Make sure to call `.check()` when you're done! It makes sure that what
  // you just read is actually valid. `cacache` always verifies the data
  // you get out is what it's supposed to be. The check is very cheap!
  fd.check()?;

  Ok(())
}

Structs

Metadata

Represents a cache index entry, which points to content.

Reader

File handle for reading data synchronously.

WriteOpts

Builder for options and flags for opening a new cache file to write data into.

Writer

A reference to an open file writing to the cache.

Enums

Algorithm

Valid algorithms for integrity strings.

Error

Error type returned by all API calls.

Value

Represents any valid JSON value.

Functions

clear

Removes entire contents of the cache synchronously, including temporary files, the entry index, and all content data.

copy

Copies a cache entry by key to a specified location. Returns the number of bytes copied.

copy_hash

Copies a cache entry by integrity address to a specified location. Returns the number of bytes copied.

exists

Returns true if the given hash exists in the cache.

list

Returns a synchronous iterator that lists all cache index entries.

metadata

Gets metadata for a certain key.

read

Reads the entire contents of a cache file synchronously into a bytes vector, looking the data up by key.

read_hash

Reads the entire contents of a cache file synchronously into a bytes vector, looking the data up by its content address.

remove

Removes an individual index entry synchronously. The associated content will be left in the cache.

remove_hash

Removes an individual content entry synchronously. Any index entries pointing to this content will become invalidated.

write

Writes data to the cache synchronously, indexing it under key.

write_hash

Writes data to the cache synchronously, skipping associating a key with it.

Type Definitions

Result

The result type returned by calls to this library