Search documentation of macula

# macula_content (macula v0.44.2)

View Source

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.

# Types

# chunk_info/0

    -type chunk_info() :: map().

# manifest/0

    -type manifest() :: map().

# mcid/0

    -type mcid() :: <<_:272>>.

34 bytes

# Functions

# create_manifest(Data)

    -spec create_manifest(binary()) -> {ok, manifest()}.

Create manifest from binary data.

# create_manifest(Data, Opts)

    -spec create_manifest(binary(), map()) -> {ok, manifest()}.

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)

    -spec fetch(mcid()) -> {ok, binary()} | {error, term()}.

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

# fetch(MCID, Opts)

    -spec fetch(mcid(), map()) -> {ok, binary()} | {error, term()}.

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

# get_chunks(_)

    -spec get_chunks(manifest()) -> [chunk_info()].

Get list of chunks from manifest.

# is_local(MCID)

    -spec is_local(mcid()) -> boolean().

Check if content is available locally.

# mcid(Data)

    -spec mcid(binary()) -> mcid().

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

# mcid(Data, Opts)

    -spec mcid(binary(), map()) -> mcid().

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

# mcid_from_string(Str)

    -spec mcid_from_string(binary()) -> {ok, mcid()} | {error, invalid_mcid}.

Parse MCID from string representation.

# mcid_to_string(MCID)

    -spec mcid_to_string(mcid()) -> binary().

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

# missing_chunks(Manifest)

    -spec missing_chunks(manifest()) -> [chunk_info()].

Get list of chunks not yet stored locally.

# status()

    -spec status() -> map().

Get content system status.

# store(Data)

    -spec store(binary()) -> {ok, manifest()} | {error, term()}.

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

# store(Data, Opts)

    -spec store(binary(), map()) -> {ok, manifest()} | {error, term()}.

Store binary content with options.

# verify_manifest(Manifest, Data)

    -spec verify_manifest(manifest(), binary()) -> boolean().

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