macula_content (macula v0.20.3)

Public API facade for Macula content-addressed storage system.

Provides a simple, high-level interface for content operations: - Publishing: Store content and announce to mesh - Fetching: Download content from mesh peers - Verification: Ensure content integrity via Merkle proofs

Quick Start

   %% Publish content (returns manifest MCID)
   {ok, MCID} = macula_content:publish("/path/to/release.tar.gz").
  
   %% Fetch content by MCID
   {ok, FilePath} = macula_content:fetch(MCID, #{output_dir => "/tmp"}).
  
   %% Check if content is available locally
   true = macula_content:is_local(MCID).

MCID Format

MCIDs are 34-byte content identifiers: - Version (1 byte): Protocol version - Codec (1 byte): Content type (0x55 = raw, 0x56 = manifest) - Hash (32 bytes): BLAKE3 or SHA256 content hash

Summary

Types

chunk_info/0

manifest/0

mcid/0

34 bytes

Functions

create_manifest(Data)

Create manifest from binary data.

create_manifest(Data, Opts)

Create manifest from binary data with options. Options: - name: Content name (default: "unnamed") - chunk_size: Chunk size in bytes (default: 262144 / 256KB) - hash_algorithm: blake3 | sha256 (default: blake3)

fetch(MCID)

Fetch content by MCID. If available locally, returns immediately. Otherwise, discovers providers and downloads.

fetch(MCID, Opts)

Fetch content with options. Options: - verify: Verify Merkle root after download (default: true) - timeout: Download timeout in ms (default: 300000 / 5 min)

get_chunks(_)

Get list of chunks from manifest.

is_local(MCID)

Check if content is available locally.

mcid(Data)

Create MCID from binary data using default algorithm (BLAKE3).

mcid(Data, Opts)

Create MCID from binary data with options. Options: - hash_algorithm: blake3 | sha256 (default: blake3)

mcid_from_string(Str)

Parse MCID from string representation.

mcid_to_string(MCID)

Convert MCID to human-readable string. Format: mcid1-{codec}-{algorithm}-{hash_hex}

missing_chunks(Manifest)

Get list of chunks not yet stored locally.

status()

Get content system status.

store(Data)

Store binary content locally. Creates manifest, chunks data, stores blocks.

store(Data, Opts)

Store binary content with options.

verify_manifest(Manifest, Data)

Verify data against manifest. Returns true if data matches manifest's root hash.