Search documentation of macula

# macula_mri_nif (macula v4.4.9)

View Source

MRI (Macula Resource Identifier) operations for Macula mesh.

This module provides high-performance MRI parsing, validation, and hierarchy queries. It uses Rust NIFs when available, falling back to pure Erlang implementations otherwise.

### NIF vs Erlang

The Rust NIFs provide significant performance improvements: - Parsing: ~3-5x faster (single-pass parsing) - Validation: ~4-6x faster (avoids binary_to_list conversion) - Path joining: ~5-10x faster (single allocation) - Hierarchy queries: ~10-20x faster (efficient prefix matching)

### Trie Index for Million-Scale Deployments

For large-scale deployments (millions of MRIs), use the persistent index:

      %% Build index once (O(n))
      {ok, Index} = macula_mri_nif:build_path_index(AllMRIs),

      %% Fast O(d) queries instead of O(n)
      {ok, Children} = macula_mri_nif:index_find_children(Index, Realm, Path),
      {ok, Descendants} = macula_mri_nif:index_find_descendants(Index, Realm, Path),

      %% Dynamic updates for device churn
      ok = macula_mri_nif:index_insert(Index, Realm, Path, MRI),
      ok = macula_mri_nif:index_remove(Index, Realm, Path).

The pure Erlang fallbacks ensure the module works even when NIFs cannot be loaded (e.g., different architecture, missing Rust toolchain).

### MRI Format

MRIs follow the format: mri:type:realm or mri:type:realm/path

Examples: mri:realm:io.macula — A realm mri:app:io.macula/counter — An app in the io.macula realm mri:service:io.macula/counter/api — A service endpoint

# Summary

## Functions

build_path_index(MRIs)

Build a trie index from a list of MRIs.

find_children(ParentRealm, ParentPath, AllMRIs)

Find children of a parent MRI from a list of MRIs.

find_descendants(ParentRealm, ParentPath, AllMRIs)

Find descendants of a parent MRI from a list of MRIs.

format_mri(Type, Realm, Path)

Format MRI components into an MRI string.

index_find_children(Index, Realm, Path)

Find direct children using a trie index.

index_find_descendants(Index, Realm, Path)

Find all descendants using a trie index.

index_insert(Index, Realm, Path, MRI)

Insert a single MRI into an existing index.

index_remove(Index, Realm, Path)

Remove a single MRI from an existing index.

index_size(Index)

Get the number of MRIs in an index.

is_builtin_type(Type)

Check if a type is a builtin MRI type.

is_nif_loaded()

Check if the NIF is loaded.

join_path_segments(Segments)

Join path segments into a single path binary.

nif_build_path_index(MRIs)
nif_find_children(ParentRealm, ParentPath, AllMRIs)
nif_find_descendants(ParentRealm, ParentPath, AllMRIs)
nif_format_mri(Type, Realm, Path)
nif_index_find_children(Index, Realm, Path)
nif_index_find_descendants(Index, Realm, Path)
nif_index_insert(Index, Realm, Path, MRI)
nif_index_remove(Index, Realm, Path)
nif_index_size(Index)
nif_is_builtin_type(Type)
nif_join_path_segments(Segments)
nif_parse_mri(MRI)
nif_validate_realm_format(Realm)
nif_validate_segment_chars(Segment)
parse_mri(MRI)

Parse an MRI string into its components.

validate_realm_format(Realm)

Validate realm format.

validate_segment_chars(Segment)

Validate segment characters.

# Functions

# build_path_index(MRIs)

    -spec build_path_index(MRIs :: [{binary(), [binary()], binary()}]) -> {ok, reference() | map()}.

Build a trie index from a list of MRIs.

Creates a persistent trie index that enables O(d) queries where d is the path depth. For million-scale deployments, this is orders of magnitude faster than O(n) list scanning.

When NIFs are loaded, returns an opaque reference to the Rust trie. When using Erlang fallback, returns a map-based index (slower but functional).

Example:

      AllMRIs = [
          {&lt;&lt;"io.macula"&gt;&gt;, [&lt;&lt;"apps"&gt;&gt;], &lt;&lt;"mri:app:io.macula/apps"&gt;&gt;},
          {&lt;&lt;"io.macula"&gt;&gt;, [&lt;&lt;"apps"&gt;&gt;, &lt;&lt;"counter"&gt;&gt;], &lt;&lt;"mri:app:io.macula/apps/counter"&gt;&gt;}
      ],
      {ok, Index} = macula_mri_nif:build_path_index(AllMRIs).

# find_children(ParentRealm, ParentPath, AllMRIs)

    -spec find_children(ParentRealm :: binary(),
                        ParentPath :: [binary()],
                        AllMRIs :: [{binary(), [binary()], binary()}]) ->
                           [binary()].

Find children of a parent MRI from a list of MRIs.

Children are MRIs that have the same realm, path starts with parent's path, and have exactly one more path segment.

The `AllMRIs` parameter is a list of `{Realm, PathSegments, FullMRI}` tuples.

Example:

      AllMRIs = [
          {&lt;&lt;"io.macula"&gt;&gt;, [&lt;&lt;"apps"&gt;&gt;], &lt;&lt;"mri:app:io.macula/apps"&gt;&gt;},
          {&lt;&lt;"io.macula"&gt;&gt;, [&lt;&lt;"apps"&gt;&gt;, &lt;&lt;"counter"&gt;&gt;], &lt;&lt;"mri:app:io.macula/apps/counter"&gt;&gt;}
      ],
      [&lt;&lt;"mri:app:io.macula/apps/counter"&gt;&gt;] =
          macula_mri_nif:find_children(&lt;&lt;"io.macula"&gt;&gt;, [&lt;&lt;"apps"&gt;&gt;], AllMRIs).

# find_descendants(ParentRealm, ParentPath, AllMRIs)

    -spec find_descendants(ParentRealm :: binary(),
                           ParentPath :: [binary()],
                           AllMRIs :: [{binary(), [binary()], binary()}]) ->
                              [binary()].

Find descendants of a parent MRI from a list of MRIs.

Descendants are MRIs that have the same realm, path starts with parent's path, and have at least one more path segment.

The `AllMRIs` parameter is a list of `{Realm, PathSegments, FullMRI}` tuples.

# format_mri(Type, Realm, Path)

    -spec format_mri(Type :: binary(), Realm :: binary(), Path :: [binary()]) ->
                        {ok, binary()} | {error, invalid_type | invalid_realm}.

Format MRI components into an MRI string.

Example:

      {ok, &lt;&lt;"mri:app:io.macula/counter"&gt;&gt;} =
          macula_mri_nif:format_mri(&lt;&lt;"app"&gt;&gt;, &lt;&lt;"io.macula"&gt;&gt;, [&lt;&lt;"counter"&gt;&gt;]).

# index_find_children(Index, Realm, Path)

    -spec index_find_children(Index :: reference() | map(), Realm :: binary(), Path :: [binary()]) ->
                                 {ok, [binary()]} | {error, invalid_realm}.

Find direct children using a trie index.

O(d) complexity where d is the path depth, vs O(n) for list scanning.

Example:

      {ok, Index} = macula_mri_nif:build_path_index(AllMRIs),
      {ok, [&lt;&lt;"mri:app:io.macula/apps/counter"&gt;&gt;]} =
          macula_mri_nif:index_find_children(Index, &lt;&lt;"io.macula"&gt;&gt;, [&lt;&lt;"apps"&gt;&gt;]).

# index_find_descendants(Index, Realm, Path)

    -spec index_find_descendants(Index :: reference() | map(), Realm :: binary(), Path :: [binary()]) ->
                                    {ok, [binary()]} | {error, invalid_realm}.

Find all descendants using a trie index.

O(d + m) complexity where d is path depth and m is number of descendants, vs O(n) for list scanning where n is total MRIs.

# index_insert(Index, Realm, Path, MRI)

    -spec index_insert(Index :: reference() | map(), Realm :: binary(), Path :: [binary()], MRI :: binary()) ->
                          ok | {error, invalid_realm}.

Insert a single MRI into an existing index.

Use this for dynamic updates when devices connect.

Example:

      ok = macula_mri_nif:index_insert(Index, &lt;&lt;"io.macula"&gt;&gt;, [&lt;&lt;"devices"&gt;&gt;, &lt;&lt;"sensor1"&gt;&gt;],
                                        &lt;&lt;"mri:device:io.macula/devices/sensor1"&gt;&gt;).

# index_remove(Index, Realm, Path)

    -spec index_remove(Index :: reference() | map(), Realm :: binary(), Path :: [binary()]) ->
                          ok | {error, not_found | invalid_realm}.

Remove a single MRI from an existing index.

Use this for dynamic updates when devices disconnect.

# index_size(Index)

    -spec index_size(Index :: reference() | map()) -> {ok, non_neg_integer()}.

Get the number of MRIs in an index.

# is_builtin_type(Type)

    -spec is_builtin_type(Type :: binary()) -> boolean().

Check if a type is a builtin MRI type.

Builtin types: realm, org, user, app, service, artifact, license, cert, key, topic, proc, content, device, cluster, location, zone, network, model, dataset, config, class, taxonomy.

# is_nif_loaded()

    -spec is_nif_loaded() -> boolean().

Check if the NIF is loaded.

# join_path_segments(Segments)

    -spec join_path_segments(Segments :: [binary()]) -> binary().

Join path segments into a single path binary.

Example:

      &lt;&lt;"foo/bar/baz"&gt;&gt; = macula_mri_nif:join_path_segments([&lt;&lt;"foo"&gt;&gt;, &lt;&lt;"bar"&gt;&gt;, &lt;&lt;"baz"&gt;&gt;]).

# nif_build_path_index(MRIs)

# nif_find_children(ParentRealm, ParentPath, AllMRIs)

# nif_find_descendants(ParentRealm, ParentPath, AllMRIs)

# nif_format_mri(Type, Realm, Path)

# nif_index_find_children(Index, Realm, Path)

# nif_index_find_descendants(Index, Realm, Path)

# nif_index_insert(Index, Realm, Path, MRI)

# nif_index_remove(Index, Realm, Path)

# nif_index_size(Index)

# nif_is_builtin_type(Type)

# nif_join_path_segments(Segments)

# nif_parse_mri(MRI)

# nif_validate_realm_format(Realm)

# nif_validate_segment_chars(Segment)

# parse_mri(MRI)

    -spec parse_mri(MRI :: binary()) ->
                       {ok, #{type := binary(), realm := binary(), path := [binary()]}} |
                       {error, invalid_format | invalid_realm | invalid_segment}.

Parse an MRI string into its components.

Returns a map with `type`, `realm`, and `path` keys.

Example:

      {ok, #{type := &lt;&lt;"app"&gt;&gt;, realm := &lt;&lt;"io.macula"&gt;&gt;, path := [&lt;&lt;"counter"&gt;&gt;]}} =
          macula_mri_nif:parse_mri(&lt;&lt;"mri:app:io.macula/counter"&gt;&gt;).

# validate_realm_format(Realm)

    -spec validate_realm_format(Realm :: binary()) -> boolean().

Validate realm format.

Valid realm: reverse domain notation (e.g., "io.macula.example") Must contain at least one dot and only lowercase letters, digits, and dots.

# validate_segment_chars(Segment)

    -spec validate_segment_chars(Segment :: binary()) -> boolean().

Validate segment characters.

Valid segment: a-z, 0-9, hyphen (-), underscore (_)