Module hb_opts.erl

A module for interacting with local and global options inside HyperBEAM.

Description

Options are set globally, but can also be overridden using an an optional local Opts map argument. Many functions across the HyperBEAM environment accept an Opts argument, which can be used to customize behavior.

Options set in an Opts map must never change the behavior of a function that should otherwise be deterministic. Doing so may lead to loss of funds by the HyperBEAM node operator, as the results of their executions will be different than those of other node operators. If they are economically staked on the correctness of these results, they may experience punishments for non-verifiable behavior. Instead, if a local node setting makes deterministic behavior impossible, the caller should fail the execution with a refusal to execute.

Function Index

as/2	Find a given identity from the identities map, and return the options merged with the sub-options for that identity.
cached_os_env/2*	Cache the result of os:getenv/1 in the process dictionary, as it never changes during the lifetime of a node.
check_required_opts/2	Utility function to check for required options in a list.
config_lookup/3*	An abstraction for looking up configuration variables.
default_message/0	The default configuration options of the hyperbeam node.
ensure_node_history/2	Ensures all items in a node history meet required configuration options.
get/1	Get an option from the global options, optionally overriding with a local Opts map if prefer or only is set to local.
get/2
get/3
global_get/3*	Get an environment variable or configuration key.
identities/1	Find all known IDs and their sub-options from the priv_ids map.
identities/2*
load/1	Parse a flat@1.0 encoded file into a map, matching the types of the keys to those in the default message.
load/2
load_bin/2
mimic_default_types/3	Mimic the types of the default message for a given map.
normalize_default/1*	Get an option from environment variables, optionally consulting the hb_features of the node if a conditional default tuple is provided.

Function Details

as/2

as(Identity, Opts) -> any()

Find a given identity from the identities map, and return the options merged with the sub-options for that identity.

cached_os_env/2 *

cached_os_env(Key, DefaultValue) -> any()

Cache the result of os:getenv/1 in the process dictionary, as it never changes during the lifetime of a node.

check_required_opts/2

check_required_opts(KeyValuePairs::[{binary(), term()}], Opts::map()) -> {ok, map()} | {error, binary()}

KeyValuePairs: A list of {Name, Value} pairs to check.
Opts: The original options map to return if validation succeeds.

returns: {ok, Opts} if all required options are present, or {error, <<"Missing required parameters: ", MissingOptsStr/binary>>} where MissingOptsStr is a comma-separated list of missing option names.

Utility function to check for required options in a list. Takes a list of {Name, Value} pairs and returns: - {ok, Opts} when all required options are present (Value =/= not_found) - {error, ErrorMsg} with a message listing all missing options when any are not_found

config_lookup/3 *

config_lookup(Key, Default, Opts) -> any()

An abstraction for looking up configuration variables. In the future, this is the function that we will want to change to support a more dynamic configuration system.

default_message/0

default_message() -> any()

The default configuration options of the hyperbeam node.

ensure_node_history/2

ensure_node_history(NodeHistory::list() | term(), RequiredOpts::map()) -> {ok, binary()} | {error, binary()}

RequiredOpts: A map of options that must be present and unchanging

returns: {ok, <<"valid">>} when validation passes {error, <<"missing_keys">>} when required keys are missing from first item {error, <<"invalid_values">>} when first item values don't match requirements {error, <<"modified_required_key">>} when history items modify required keys {error, <<"validation_failed">>} when other validation errors occur

Ensures all items in a node history meet required configuration options.

This function verifies that the first item (complete opts) contains all required configuration options and that their values match the expected format. Then it validates that subsequent history items (which represent differences) never modify any of the required keys from the first item.

Validation is performed in two steps: 1. Checks that the first item has all required keys and valid values 2. Verifies that subsequent items don't modify any required keys from the first item

get/1

get(Key) -> any()

Get an option from the global options, optionally overriding with a local Opts map if prefer or only is set to local. If the only option is provided in the local map, only keys found in the corresponding (local or global) map will be returned. This function also offers users a way to specify a default value to return if the option is not set.

prefer defaults to local.

get/2

get(Key, Default) -> any()

get/3

get(Key, Default, Opts) -> any()

global_get/3 *

global_get(Key, Default, Opts) -> any()

Get an environment variable or configuration key.

identities/1

identities(Opts) -> any()

Find all known IDs and their sub-options from the priv_ids map. Allows the identities to be named, or based on addresses. The results are normalized such that the map returned by this function contains both mechanisms for finding an identity and its sub-options. Additionally, sub-options are also normalized such that the address property is present and accurate for all given identities.

identities/2 *

identities(Default, Opts) -> any()

load/1

load(Path) -> any()

Parse a flat@1.0 encoded file into a map, matching the types of the keys to those in the default message.

load/2

load(Path, Opts) -> any()

load_bin/2

load_bin(Bin, Opts) -> any()

mimic_default_types/3

mimic_default_types(Map, Mode, Opts) -> any()

Mimic the types of the default message for a given map.

normalize_default/1 *

normalize_default(Default) -> any()

Get an option from environment variables, optionally consulting the hb_features of the node if a conditional default tuple is provided.