macula_content_manifest (macula v0.20.5)

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.