Crate libpna

Expand description

A library for reading and writing PNA archives.

The APIs operate over readers and writers and support streaming archive data without loading an entire archive into memory.

§Quick Start

§Creating an Archive

use libpna::{Archive, DirEntryBuilder, FileEntryBuilder, WriteOptions};
use std::fs::File;
use std::io::{self, Write};

fn main() -> io::Result<()> {
    let file = File::create("archive.pna")?;
    let mut archive = Archive::write_header(file)?;

    // Add a file entry
    let mut entry = FileEntryBuilder::new_with_options(
        "hello.txt".into(),
        WriteOptions::builder().build(),
    )?;
    entry.write_all(b"Hello, world!")?;
    archive.add_entry(entry.build()?)?;

    // Add a directory entry
    let dir = DirEntryBuilder::new("my_folder/".into());
    archive.add_entry(dir.build()?)?;

    archive.finalize()?;
    Ok(())
}

§Reading an Archive

use libpna::{Archive, ReadEntry, ReadOptions};
use std::fs::File;
use std::io::{self, Read};

fn main() -> io::Result<()> {
    let file = File::open("archive.pna")?;
    let mut archive = Archive::read_header(file)?;

    for entry in archive.entries().skip_solid() {
        let entry = entry?;
        println!("Entry: {}", entry.header().path().as_path().display());

        // Read file contents
        let mut reader = entry.reader(ReadOptions::builder().build())?;
        let mut contents = Vec::new();
        reader.read_to_end(&mut contents)?;
    }
    Ok(())
}

§Compression and Encryption

PNA supports multiple compression algorithms and encryption options:

use libpna::{CipherMode, Compression, Encryption, HashAlgorithm, WriteOptions};

// Compressed entry (Zstandard)
let compressed = WriteOptions::builder()
    .compression(Compression::ZSTANDARD)
    .build();

// Encrypted entry (AES-256-GCM with Argon2id key derivation)
let encrypted = WriteOptions::builder()
    .compression(Compression::ZSTANDARD)
    .encryption(Encryption::AES)
    .cipher_mode(CipherMode::GCM)
    .hash_algorithm(HashAlgorithm::argon2id())
    .password(Some("secure_password"))
    .build();

§Solid Mode

Solid mode compresses multiple files together for better compression ratios:

use libpna::{Archive, FileEntryBuilder, SolidEntryBuilder, WriteOptions};
use std::io::{self, Write};

fn main() -> io::Result<()> {
    let mut archive = Archive::write_header(Vec::new())?;

    // Create a solid entry containing multiple files
    let mut solid = SolidEntryBuilder::new(WriteOptions::builder().build())?;

    let mut file1 = FileEntryBuilder::new("file1.txt".into())?;
    file1.write_all(b"Content 1")?;
    solid.add_entry(file1.build()?)?;

    let mut file2 = FileEntryBuilder::new("file2.txt".into())?;
    file2.write_all(b"Content 2")?;
    solid.add_entry(file2.build()?)?;

    archive.add_entry(solid.build()?)?;
    archive.finalize()?;
    Ok(())
}

§Key Types

Archive - Main entry point for reading and writing archives
FileEntryBuilder / DirEntryBuilder / SymlinkEntryBuilder / HardLinkEntryBuilder - Kind-specific entry builders
OpaqueEntryBuilder - Escape-hatch builder for entry kinds without a dedicated builder
SolidEntryBuilder - Builder for creating solid (multi-file) entries
EntryWriteAttributes - Metadata and extra chunks for streaming entry writes
WriteOptions - Configuration for compression and encryption when writing
ReadOptions - Configuration (password) for reading encrypted entries
NormalEntry / SolidEntry / ReadEntry - Entry types for reading
Chunk / ChunkType - Low-level chunk primitives

§Feature Flags

zlib-ng - Use zlib-ng for improved deflate compression performance
unstable-async - Enable async I/O support via futures-io (unstable API)

Modules§

bytes: Byte-slice primitives for parsing PNA archives.
io: I/O primitives for reading and writing PNA archives.
prelude: PNA Prelude.

Structs§

Archive: A reader or writer for a PNA archive.
ChunkType: A 4-byte chunk type code.
CipherMode: Cipher mode of encryption algorithm.
Compression: Compression method.
CompressionLevel: A compression level interpreted by the selected algorithm.
DataKind: Type of filesystem object represented by an entry.
DirEntryBuilder: A builder for creating a directory NormalEntry.
EncodedDataReader: Reader for encoded entry data.
Encryption: Encryption algorithm.
EntryDataReader: A reader over decoded entry data.
EntryHeader: Represents the entry information header expressed in the FHED chunk.
EntryName: A UTF-8 encoded entry name.
EntryNameError: An error returned when an EntryName cannot be constructed from invalid input.
EntryPartDeprecated: A structure representing the split Entry for archive splitting.
EntryReference: A UTF-8 encoded entry reference.
EntryReferenceError: An error returned when an EntryReference cannot be constructed from invalid input.
EntryWriteAttributes: Attributes known before streaming an entry payload.
ExtendedAttribute: Represents a single extended attribute of a file entry.
FileEntryBuilder: A builder for creating a regular file NormalEntry.
HardLinkEntryBuilder: A builder for creating a hard link NormalEntry.
HashAlgorithm: Password hash algorithm.
LengthExceeded: Error returned when a value exceeds the byte-length bound of a bounded owned string or byte slice.
Metadata: Metadata information about an entry.
NormalEntry: A normal entry in a PNA archive.
OpaqueEntryBuilder: A builder for an opaque NormalEntry with a specified DataKind.
OwnerGid: Owner group id (fGId).
OwnerGroupName: Owner group name (fGNm).
OwnerGroupSid: Owner group SID (fGSi).
OwnerUid: Owner user id (fUId).
OwnerUserName: Owner user name (fONm).
OwnerUserSid: Owner user SID (fOSi).
PermissionMode: POSIX permission mode (fMOd). Reserved bits outside 0o7777 (the rwx + setuid/setgid/sticky bits) are masked to 0 on construction.
RawChunk: A PNA chunk containing its length, type, data, and CRC32 checksum.
ReadOptions: Options for reading an entry.
ReadOptionsBuilder: Builder for ReadOptions.
SolidArchive: A writer for a PNA archive containing a single SolidEntry.
SolidEntry: A solid mode entry in a PNA archive.
SolidEntryBuilder: A builder for creating a SolidEntry.
SolidHeader: Represents the entry information header expressed in the SHED chunk.
SplitParts: A writer that splits archive chunks into parts of a bounded size.
SymlinkEntryBuilder: A builder for creating a symbolic link NormalEntry.
UnknownValueError: Unknown value error.
WriteOptions: Options for compressing and encrypting archive entries.
WriteOptionsBuilder: Builder for WriteOptions.
XattrName: Extended-attribute name identifier.
XattrValue: Extended-attribute value (arbitrary bytes).

Enums§

ChunkTypeError: ChunkType validation error.
CipherAlgorithm: Cipher algorithm.
EntryContent: Decoded content of a NormalEntry, interpreted according to its DataKind.
LinkTargetType: Link target type for link entries.
ReadEntry: A NormalEntry or SolidEntry read from an archive.

Constants§

MIN_CHUNK_BYTES_SIZE: The minimum size of a PNA chunk in bytes.
MIN_SPLIT_PART_BYTES: Minimum accepted value for max_part_bytes (framing plus one minimal chunk).
PNA_HEADERDeprecated: Alias of PNA_SIGNATURE.
PNA_SIGNATURE: The signature at the beginning of every PNA archive.

Traits§

Chunk: A chunk in a PNA archive.
Entry: A trait representing an entry in a PNA archive.

Functions§

read_as_chunks: Returns an iterator over the chunks of a PNA archive.
read_chunks_from_slice: Returns an iterator over the chunks of a PNA archive in a byte slice.

Type Aliases§

Duration: A SignedDuration under its original name.

Crate libpna

Crate libpna Copy item path

§Quick Start

§Creating an Archive

§Reading an Archive

§Compression and Encryption

§Solid Mode

§Key Types

§Feature Flags

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate libpna