sfa

SFA (simple file archive) is a minimal, flat file archive encoding/decoding library for Rust.

The file can be segmented into multiple sections (similar to a zip file), and individual sections accessed as a std::io::Read or (offset, len) tuples.

Sponsors

Basic usage

cargo add sfa

use sfa::{Writer, Reader};
use std::{
  fs::File,
  io::{BufWriter, Read, Write}
};

let file = File::create(&path)?;
let mut file = BufWriter::new(file);
let mut writer = Writer::from_writer(&mut file);

writer.start("Section 1")?;
writer.write_all(b"Hello world!\n")?;

writer.finish()?;
file.get_mut().sync_all()?;
drop(file);
// If on Unix, you probably want to fsync the directory here

let reader = Reader::new(&path)?;
let toc = reader.toc();
assert_eq!(toc.len(), 1);
assert_eq!(toc[0].name(), b"Section 1");
assert_eq!(toc[0].len(), 13);

let reader = toc[0].buf_reader(&path).unwrap();
assert_eq!(b"Hello world!\n", &*reader.bytes().collect::<Result<Vec<_>, _>>()?);

Stable disk format

The disk format will be stable as of 1.0.0.

Future breaking changes will result in a major version bump.

??? (header content)
[section1]
  ??? (section1 content)
[section2]
  ??? (section2 content)
[toc]
[magic, 4 bytes]
[len, 4 bytes]
  <section pos, 8 bytes>
  <section len, 8 bytes>
  <section name, len = N, 2 bytes>
  <section name, N bytes>
...
[trailer]
[magic, 4 bytes]
[version, 1 byte, 0x1]
[checksum type, 1 byte, always 0x0]
[toc checksum, 16 bytes]
[toc pos, 8 bytes]
[toc len, 8 bytes]

All integers are little-endian encoded.

License

All source code is licensed under MIT OR Apache-2.0.

All contributions are to be licensed as MIT OR Apache-2.0.