Search documentation of macula

# macula_content_manifest (macula v0.44.2)

View Source

Content manifest module for Macula content-addressed storage.

Manifests describe content: name, size, chunk information, and Merkle root hash for verification. They are identified by an MCID (Macula Content Identifier) which is a self-describing hash.

### MCID Format

MCIDs are 34-byte binary values: - Byte 0: Version (currently 0x01) - Byte 1: Codec (0x55=raw, 0x56=manifest) - Bytes 2-33: 32-byte hash (BLAKE3 or SHA256)

### String Representation

MCIDs can be converted to human-readable strings: `mcid1-manifest-blake3-5d41402abc4b2a76b9719d911017c592`

### Example Usage

       %% Create manifest from binary data
       {ok, Manifest} = macula_content_manifest:create(Data, #{
           name => <<"my_app-1.0.0.tar.gz"/utf8>>,
           chunk_size => 262144
       }).

       %% Get MCID as string
       MCIDString = macula_content_manifest:mcid_to_string(maps:get(mcid, Manifest)).

       %% Verify data matches manifest
       ok = macula_content_manifest:verify(Manifest, Data).

# Summary

## Types

manifest/0
mcid/0

34 bytes

## Functions

create(Data, Opts)

Create a manifest from binary data.

decode(Binary)

Decode manifest from binary.

encode(Manifest)

Encode manifest to binary (MessagePack).

get_chunk_mcid(Manifest, Index)

Get MCID for a specific chunk.

mcid_from_string(String)

Parse MCID from string.

mcid_to_string(_)

Convert MCID to human-readable string.

verify(Manifest, Data)

Verify that data matches the manifest.

version()

Return the current manifest version.

# Types

# manifest/0

    -type manifest() ::
              #{mcid := mcid(),
                version := pos_integer(),
                name := binary(),
                size := non_neg_integer(),
                created := pos_integer(),
                chunk_size := pos_integer(),
                chunk_count := non_neg_integer(),
                hash_algorithm := macula_content_hasher:algorithm(),
                root_hash := binary(),
                chunks := [macula_content_chunker:chunk_info()],
                signature => binary(),
                publisher_did => binary()}.

# mcid/0

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

34 bytes

# Functions

# create(Data, Opts)

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

Create a manifest from binary data.

Options:

- `name` - binary() - Content name (default: "unnamed")
- `chunk_size` - pos_integer() - Chunk size (default: 262144)
- `hash_algorithm` - blake3 | sha256 - Hash algorithm (default: blake3)

# decode(Binary)

    -spec decode(binary()) -> {ok, manifest()} | {error, invalid_manifest}.

Decode manifest from binary.

# encode(Manifest)

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

Encode manifest to binary (MessagePack).

# get_chunk_mcid(Manifest, Index)

    -spec get_chunk_mcid(manifest(), non_neg_integer()) -> {ok, mcid()} | {error, invalid_index}.

Get MCID for a specific chunk.

# mcid_from_string(String)

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

Parse MCID from string.

# mcid_to_string(_)

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

Convert MCID to human-readable string.

# verify(Manifest, Data)

    -spec verify(manifest(), binary()) -> ok | {error, size_mismatch | root_hash_mismatch}.

Verify that data matches the manifest.

# version()

    -spec version() -> pos_integer().

Return the current manifest version.