Module archive 

The archive payload format for directory trees, carried inside an encrypted file’s content stream. The shadow archive payload format: a directory tree serialized as one byte stream.

An archive travels as the content of an encrypted file whose metadata envelope marks it as crate::file::ContentKind::Archive, so it inherits the container format’s encryption, authentication, and streaming. This module defines only the plaintext payload layout and is deliberately independent of the format versions: the layout carries its own magic and version byte and can be reused by future container versions unchanged.

Layout (all integers little endian):

magic: "SHDWARC" + version byte 1        (8 bytes)
entries, each:
  entry_type: u8                          (1 = file, 2 = directory, 0 = end)
  for file/directory entries:
    path_len: u16, path: UTF-8            ('/'-separated relative path)
    flags: u8                             (bit 0 mtime, bit 1 mode)
    mtime_secs: i64, mtime_nanos: u32     (if flag)
    mode: u32                             (if flag)
  for file entries:
    content_len: u64, content bytes
terminator: entry_type 0; nothing may follow

Directory entries appear before their contents. Paths are validated on both encode and parse: relative, ‘/’-separated, no .. or . or empty components, no backslashes.

Encoding is a set of pure functions producing header bytes (the caller interleaves raw file content); parsing is the incremental [ArchiveParser], fed arbitrary byte pieces and drained of [ArchiveEvent]s, so neither side ever needs the whole archive in memory.

Structs

ArchiveParser

Incremental archive parser: ArchiveParser::feed it byte pieces of any size, then drain ArchiveParser::next_event until it returns None (more input needed). Call ArchiveParser::finish after the last feed to catch truncated streams. Buffered bytes are zeroized on drop.

Enums

ArchiveError

Errors from encoding or parsing an archive stream.

ArchiveEvent

One parsed element of an archive stream, in stream order.

Constants

MAGIC

MAX_PATH_LEN

Upper bound on an entry path, matching common filesystem limits.

Functions

encode_directory

Header bytes for a directory entry. metadata.filename() is the directory’s relative path.

encode_end

The archive terminator entry.

encode_file

Header bytes for a file entry; exactly content_len raw content bytes must follow. metadata.filename() is the file’s relative path.

validate_path

Validates a ‘/’-separated relative entry path.