Crate libpna

Crate libpna 

Source
Expand description

A library for reading and writing PNA archives.

This library provides utilities necessary to manage PNA archives abstracted over a reader or writer. Great strides are taken to ensure that an archive is never required to be fully resident in memory, and all objects provide largely a streaming interface to read bytes from.

§Quick Start

§Creating an Archive

use libpna::{Archive, EntryBuilder, 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 = EntryBuilder::new_file(
        "hello.txt".into(),
        WriteOptions::builder().build(),
    )?;
    entry.write_all(b"Hello, world!")?;
    archive.add_entry(entry.build()?)?;

    // Add a directory entry
    let dir = EntryBuilder::new_dir("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::{WriteOptions, Compression, Encryption, CipherMode, HashAlgorithm};

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

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

§Solid Mode

Solid mode compresses multiple files together for better compression ratios:

use libpna::{Archive, EntryBuilder, 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 = EntryBuilder::new_file("file1.txt".into(), WriteOptions::store())?;
    file1.write_all(b"Content 1")?;
    solid.add_entry(file1.build()?)?;

    let mut file2 = EntryBuilder::new_file("file2.txt".into(), WriteOptions::store())?;
    file2.write_all(b"Content 2")?;
    solid.add_entry(file2.build()?)?;

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

§Key Types

§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§

prelude
PNA Prelude.

Structs§

Archive
An object providing access to a PNA file. An instance of an Archive can be read and/or written.
ChunkType
A 4-byte chunk type code.
CompressionLevel
Compression level of each algorithm.
Duration
A span of time with nanosecond precision.
EntryBuilder
A builder for creating a NormalEntry.
EntryDataReader
Reader for Entry data.
EntryHeader
Represents the entry information header that expressed in the FHED chunk.
EntryName
A UTF-8 encoded entry name.
EntryNameError
Error of invalid EntryName.
EntryPart
A structure representing the split Entry for archive splitting.
EntryReference
A UTF-8 encoded entry reference.
EntryReferenceError
Error of invalid EntryReference.
ExtendedAttribute
Represents a single extended attribute of a file entry.
HashAlgorithm
Password hash algorithm.
Metadata
Metadata information about an entry.
NormalEntry
A normal entry in a PNA archive.
Permission
Permission struct represents an owner, group, and permissions for an entry.
RawChunk
A raw chunk in a PNA archive.
ReadOptions
Options for reading an entry.
ReadOptionsBuilder
Builder for ReadOptions.
SolidArchive
An object that provides write access to solid mode PNA files.
SolidEntry
A solid mode entry in a PNA archive.
SolidEntryBuilder
A builder for creating a SolidEntry.
SolidHeader
Represents the entry information header that expressed in the SHED chunk.
UnknownValueError
Unknown value error.
WriteOptions
Options for writing entries to a PNA archive.
WriteOptionsBuilder
Builder for WriteOptions.

Enums§

ChunkTypeError
ChunkType validation error.
CipherAlgorithm
Cipher algorithm.
CipherMode
Cipher mode of encryption algorithm.
Compression
Compression method.
DataKind
Type of filesystem object represented by an entry.
Encryption
Encryption algorithm.
ReadEntry
A NormalEntry or SolidEntry read from an archive.

Constants§

MIN_CHUNK_BYTES_SIZE
The minimum size of a PNA chunk in bytes.
PNA_HEADER
The magic number of Portable-Network-Archive

Traits§

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

Functions§

read_as_chunks
Reads an archive as chunks from the given reader.
read_chunks_from_slice
Reads an archive as chunks from the given bytes.