Crate compression

Expand description

§compression-rs

Safe Rust bindings for Apple’s Compression and AppleArchive APIs on macOS.

compression-rs 0.2.2 uses a Swift bridge in front of the C-only Apple SDK surfaces. The default API is safe Rust over opaque Swift-owned handles, while the original compression.h FFI remains available behind the raw-ffi feature.

§Requirements

macOS
Xcode / Swift toolchain available on PATH (build.rs runs swift build)

§Installation

[dependencies]
compression-rs = "0.2"

Enable raw compression.h bindings when needed:

[dependencies]
compression-rs = { version = "0.2", features = ["raw-ffi"] }

§Covered areas

CompressionStream via CompressionStream, Encoder, and Decoder
one-shot CompressionEncode / CompressionDecode helpers
AAByteStream file, fd, temp-file, shared-buffer, compression, and random-access APIs
AAArchiveStream encode, decode, extract, convert, header, blob, and message-callback APIs
AAEntryACLBlob and AAEntryXATBlob helper APIs
custom AACustomByteStream and AACustomArchiveStream callback flows
AEAContext, AEAAuthData, and AEAStreams symmetric archive helpers
AAFieldKey / AAFieldKeySet
AAHeader
requested AAEntryStream coverage, mapped to PathList, EntryMessage, and EntryAttributes

See COVERAGE.md for the requested-area mapping and COVERAGE_AUDIT.md for the full audited SDK surface.

§Quick start

use compression::{compress, decompress, Algorithm};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = b"doom fish doom fish doom fish";
    let compressed = compress(input, Algorithm::Lzfse)?;
    let round_trip = decompress(&compressed, Algorithm::Lzfse)?;

    assert_eq!(round_trip, input);
    Ok(())
}

§API notes

Algorithm::ALL contains the stream-capable algorithms.
Algorithm::BUFFER_ALL additionally includes buffer-only algorithms such as Lz4Raw and Lzbitmap.
compress / decompress use stream APIs when available and automatically fall back to repeated one-shot buffer calls for buffer-only algorithms.
raw-ffi currently preserves the direct compression.h surface. AppleArchive stays behind the Swift bridge.
AppleArchive does not define a concrete AAEntryStream type; this crate uses the entry-level AAPathList, AAEntryMessage, and AAEntryAttributes APIs to cover that requested area.
Deprecated AppleArchive *Abort* compatibility shims remain available as deprecated Rust aliases for audited SDK parity; prefer the cancel APIs in new code.

§Examples

cargo run --example 01_roundtrip
cargo run --example 04_aa_archive_stream_roundtrip
cargo run --example 05_aa_byte_stream_pipeline
cargo run --example 09_aa_entry_blobs
cargo run --example 10_aea_roundtrip
cargo run --example 11_aa_custom_stream_callbacks

This release also includes examples and tests for all requested logical areas:

01_roundtrip
02_compression_encode_one_shot
03_compression_decode_one_shot
04_aa_archive_stream_roundtrip
05_aa_byte_stream_pipeline
06_aa_entry_stream_path_list
07_aa_field_key_set
08_aa_header_roundtrip
09_aa_entry_blobs
10_aea_roundtrip
11_aa_custom_stream_callbacks

§License

Licensed under either of:

MIT license (LICENSE-MIT)
Apache License, Version 2.0 (LICENSE-APACHE)

Modules§

raw_ffiraw-ffi: Wraps the raw compression.h and AppleArchive FFI surface.

Structs§

AccessControlEntry: Wraps an ACL entry used by AAEntryACLBlob.
AeaAuthData: Wraps an AEAAuthData handle.
AeaContext: Wraps an AEAContext handle.
AeaPadding: Wraps AEA padding constants.
ArchiveFlags: Wraps AppleArchive archive-processing flags.
ArchiveStream: Wraps an AAArchiveStream handle.
BlobDescription: Wraps blob descriptors returned by AAHeaderGetFieldBlob.
ByteStream: Wraps an AAByteStream handle.
CompressionStream: Wraps a compression_stream handle.
Decoder: Wraps compression_stream_process for decoding.
Encoder: Wraps compression_stream_process for encoding.
EntryAclBlob: Wraps an AAEntryACLBlob handle.
EntryAttributes: Wraps AppleArchive entry attribute values.
EntryMessageEvent: Wraps AAEntryMessageProc event data.
EntryXatBlob: Wraps an AAEntryXATBlob handle.
FieldKey: Wraps an AAFieldKey value.
FieldKeySet: Wraps an AAFieldKeySet handle.
HashValue: Wraps hash values returned by AAHeaderGetFieldHash.
Header: Wraps an AAHeader handle.
NamedBlobEntry: Wraps a named blob entry used by AAEntryXATBlob and AEAAuthData.
PathList: Wraps an AAPathList handle.
Timespec: Wraps timespec values stored in AAHeader fields.

Enums§

AceQualifierType: Wraps AppleArchive ACL qualifier type identifiers.
AeaChecksumMode: Wraps AEA checksum mode identifiers.
AeaCiphersuite: Wraps AEA ciphersuite identifiers.
AeaContextField: Wraps AEA context field identifiers.
AeaContextFieldRepresentation: Wraps AEA context field representation identifiers.
AeaEncryptionMode: Wraps AEA encryption mode identifiers.
AeaProfile: Wraps AEA profile identifiers.
AeaSignatureMode: Wraps AEA signature mode identifiers.
Algorithm: Wraps compression_algorithm values from compression.h.
ArchiveCompressionAlgorithm: Wraps AppleArchive compression algorithm identifiers.
CompressionError: Wraps failures returned by Compression and AppleArchive helpers.
EntryMessage: Wraps AppleArchive entry message identifiers.
EntryMessageData: Wraps payloads delivered through AAEntryMessageProc.
EntryType: Wraps AppleArchive entry type identifiers.
FieldType: Wraps AppleArchive header field type identifiers.
HashFunction: Wraps AppleArchive hash function identifiers.
HeaderFieldValue: Wraps typed AAHeader field values.
StreamOperation: Wraps compression_stream_operation values.

Constants§

DEFAULT_FILE_MODE: Wraps DEFAULT_FILE_MODE.
OPEN_CREATE: Wraps OPEN_CREATE.
OPEN_READ_ONLY: Wraps OPEN_READ_ONLY.
OPEN_READ_WRITE: Wraps OPEN_READ_WRITE.
OPEN_TRUNCATE: Wraps OPEN_TRUNCATE.
OPEN_WRITE_ONLY: Wraps OPEN_WRITE_ONLY.

Traits§

CustomArchiveStreamCallbacks: Wraps callbacks installed by AACustomArchiveStreamSet*Proc.
CustomByteStreamCallbacks: Wraps callbacks installed by AACustomByteStreamSet*Proc.
EntryMessageHandler: Wraps handlers installed through AAEntryMessageProc.

Functions§

compress: Wraps compression_encode_buffer.
compression_decode_buffer: Wraps compression_decode_buffer.
compression_decode_scratch_buffer_size: Wraps compression_decode_buffer.
compression_encode_buffer: Wraps compression_encode_buffer.
compression_encode_scratch_buffer_size: Wraps compression_encode_buffer.
decompress: Wraps compression_decode_buffer.

Type Aliases§

AceFlagSet: Wraps the AppleArchive ACL flag bitset type.
AcePermSet: Wraps the AppleArchive ACL permission bitset type.
AceTag: Wraps the AppleArchive ACL tag field type.
Result: Wraps crate results returned by Compression and AppleArchive helpers.