Search documentation of macula

# macula_mri (macula v0.44.2)

View Source

Macula Resource Identifier (MRI) - Core Module

Provides parsing, validation, formatting, and manipulation of MRIs. MRI format: `mri:{type}:{realm}/{path}`

Example: {ok, Parsed} = macula_mri:parse(MRI), app = macula_mri:type(Parsed), Realm = macula_mri:realm(Parsed), Path = macula_mri:path(Parsed).

# Summary

## Types

mri/0
mri_map/0
mri_type/0
path_segment/0
realm/0

## Functions

ancestors(MRI)

Get all ancestors of an MRI, from immediate parent to root.

append_segment(MRI, Segment)

Append a segment to an MRI's path.

depth(MRI)

Get the depth of an MRI (0 for realm, 1 for org, etc).

derive_procedure(InstanceMRI, DeclaredProcedure)

Derive a DHT procedure from an instance MRI and a declared procedure name.

derive_topic(InstanceMRI, DeclaredTopic)

Derive a DHT topic from an instance MRI and a declared topic name.

format(_)

Format an MRI map back to binary.

is_ancestor(PotentialAncestor, MRI)

Check if PotentialAncestor is an ancestor of MRI.

is_valid(MRI)

Check if an MRI is valid.

join_path(Segments)

Join path segments with slashes.

new(Opts)

Create a new MRI from a map.

new(Type, Realm, Path)

Create a new MRI from type, realm, and path.

new_app(Realm, Org, App)

Create an app MRI.

new_instance(Realm, Org, Device, InstanceName)

Create an instance MRI (running installation of an artifact). Instance path: {org}/{device}/{instance_name} Example: mri:instance:io.macula/acme/edge-01/counter

new_instance_qualified(Realm, Org, Device, ArtifactName, Qualifier)

Create an instance MRI with qualifier (environment or replica index). Example: mri:instance:io.macula/acme/edge-01/counter.prod

new_org(Realm, Org)

Create an org MRI.

new_realm(Realm)

Create a realm MRI.

new_service(Realm, Org, App, Service)

Create a service MRI.

new_user(Realm, Org, User)

Create a user MRI.

parent(MRI)

Get the parent MRI, or undefined for realm-level MRIs.

parent_type(_)

Get the parent type for a given type.

parse(MRI)

Parse an MRI binary into a map.

path(MRI)

Get the path segments from an MRI.

path_string(MRI)

Get the path as a single joined string.

realm(MRI)

Get the realm from an MRI.

split_path(PathBin)

Split a path string into segments.

to_topic_prefix(MRI)

Convert an MRI to a topic/procedure prefix (realm/path segments).

type(MRI)

Get the type from an MRI (binary or parsed).

validate(MRI)

Validate an MRI, returning ok or error with reason.

# Types

# mri/0

    -type mri() :: binary().

# mri_map/0

    -type mri_map() :: #{type := mri_type(), realm := realm(), path := [path_segment()]}.

# mri_type/0

    -type mri_type() :: atom() | {custom, binary()}.

# path_segment/0

    -type path_segment() :: binary().

# realm/0

    -type realm() :: binary().

# Functions

# ancestors(MRI)

    -spec ancestors(mri() | mri_map()) -> [mri()].

Get all ancestors of an MRI, from immediate parent to root.

# append_segment(MRI, Segment)

    -spec append_segment(mri() | mri_map(), path_segment()) -> mri().

Append a segment to an MRI's path.

# depth(MRI)

    -spec depth(mri() | mri_map()) -> non_neg_integer().

Get the depth of an MRI (0 for realm, 1 for org, etc).

# derive_procedure(InstanceMRI, DeclaredProcedure)

    -spec derive_procedure(mri(), binary()) -> binary().

Derive a DHT procedure from an instance MRI and a declared procedure name.

Takes an instance MRI and a declared procedure name, returns the full DHT procedure. The instance path becomes a prefix: realm/org/device/instance.declared_procedure

Example: InstanceMRI = "mri:instance:io.macula/acme/edge-01/counter.prod" DeclaredProcedure = "place_order" Result = "io.macula/acme/edge-01/counter.prod.place_order"

# derive_topic(InstanceMRI, DeclaredTopic)

    -spec derive_topic(mri(), binary()) -> binary().

Derive a DHT topic from an instance MRI and a declared topic name.

Takes an instance MRI and a declared topic name, returns the full DHT topic. The instance path becomes a prefix: realm/org/device/instance.declared_topic

Example: InstanceMRI = "mri:instance:io.macula/acme/edge-01/counter.prod" DeclaredTopic = "orders.created" Result = "io.macula/acme/edge-01/counter.prod.orders.created"

# format(_)

    -spec format(mri_map()) -> mri().

Format an MRI map back to binary.

# is_ancestor(PotentialAncestor, MRI)

    -spec is_ancestor(mri(), mri()) -> boolean().

Check if PotentialAncestor is an ancestor of MRI.

# is_valid(MRI)

    -spec is_valid(mri() | mri_map()) -> boolean().

Check if an MRI is valid.

# join_path(Segments)

    -spec join_path([path_segment()]) -> binary().

Join path segments with slashes.

# new(Opts)

    -spec new(map()) -> {ok, mri()} | {error, term()}.

Create a new MRI from a map.

# new(Type, Realm, Path)

    -spec new(mri_type(), realm(), [path_segment()]) -> {ok, mri()} | {error, term()}.

Create a new MRI from type, realm, and path.

# new_app(Realm, Org, App)

    -spec new_app(realm(), binary(), binary()) -> mri().

Create an app MRI.

# new_instance(Realm, Org, Device, InstanceName)

    -spec new_instance(realm(), binary(), binary(), binary()) -> mri().

Create an instance MRI (running installation of an artifact). Instance path: {org}/{device}/{instance_name} Example: mri:instance:io.macula/acme/edge-01/counter

# new_instance_qualified(Realm, Org, Device, ArtifactName, Qualifier)

    -spec new_instance_qualified(realm(), binary(), binary(), binary(), binary()) -> mri().

Create an instance MRI with qualifier (environment or replica index). Example: mri:instance:io.macula/acme/edge-01/counter.prod

# new_org(Realm, Org)

    -spec new_org(realm(), binary()) -> mri().

Create an org MRI.

# new_realm(Realm)

    -spec new_realm(realm()) -> mri().

Create a realm MRI.

# new_service(Realm, Org, App, Service)

    -spec new_service(realm(), binary(), binary(), binary()) -> mri().

Create a service MRI.

# new_user(Realm, Org, User)

    -spec new_user(realm(), binary(), binary()) -> mri().

Create a user MRI.

# parent(MRI)

    -spec parent(mri() | mri_map()) -> mri() | undefined.

Get the parent MRI, or undefined for realm-level MRIs.

# parent_type(_)

    -spec parent_type(mri_type()) -> mri_type() | undefined.

Get the parent type for a given type.

# parse(MRI)

    -spec parse(mri()) -> {ok, mri_map()} | {error, term()}.

Parse an MRI binary into a map.

# path(MRI)

    -spec path(mri() | mri_map()) -> [path_segment()].

Get the path segments from an MRI.

# path_string(MRI)

    -spec path_string(mri() | mri_map()) -> binary().

Get the path as a single joined string.

# realm(MRI)

    -spec realm(mri() | mri_map()) -> realm().

Get the realm from an MRI.

# split_path(PathBin)

    -spec split_path(binary()) -> [path_segment()].

Split a path string into segments.

# to_topic_prefix(MRI)

    -spec to_topic_prefix(mri()) -> binary().

Convert an MRI to a topic/procedure prefix (realm/path segments).

Takes any MRI and extracts the realm and path as a topic-compatible prefix. Format: realm/path_segment1/path_segment2/...

Example: MRI = "mri:instance:io.macula/acme/edge-01/counter.prod" Result = "io.macula/acme/edge-01/counter.prod"

# type(MRI)

    -spec type(mri() | mri_map()) -> mri_type().

Get the type from an MRI (binary or parsed).

# validate(MRI)

    -spec validate(mri() | mri_map()) -> ok | {error, term()}.

Validate an MRI, returning ok or error with reason.