Module dev_meta.erl

The hyperbeam meta device, which is the default entry point for all messages processed by the machine.

Description

This device executes a AO-Core singleton request, after first applying the node's pre-processor, if set. The pre-processor can halt the request by returning an error, or return a modified version if it deems necessary -- the result of the pre-processor is used as the request for the AO-Core resolver. Additionally, a post-processor can be set, which is executed after the AO-Core resolver has returned a result.

Function Index

add_dynamic_keys/1*	Add dynamic keys to the node message.
add_identity_addresses/1*
adopt_node_message/2	Attempt to adopt changes to a node message.
authorized_set_node_msg_succeeds_test/0*	Test that we can set the node message if the request is signed by the owner of the node.
build/3	Emits the version number and commit hash of the HyperBEAM node source, if available.
buildinfo_test/0*	Test that version information is available and returned correctly.
claim_node_test/0*	Test that we can claim the node correctly and set the node message after.
config_test/0*	Test that we can get the node message.
embed_status/2*	Wrap the result of a device call in a status.
filter_node_msg/2*	Remove items from the node message that are not encodable into a message.
halt_request_test/0*	Test that we can halt a request if the hook returns an error.
handle/2	Normalize and route messages downstream based on their path.
handle_initialize/2*
handle_resolve/3*	Handle an AO-Core request, which is a list of messages.
info/1	Ensure that the helper function adopt_node_message/2 is not exported.
info/3	Get/set the node message.
is/2	Check if the request in question is signed by a given role on the node.
is/3
is_operator/2	Utility function for determining if a request is from the operator of the node.
maybe_sign/2*	Sign the result of a device call if the node is configured to do so.
message_to_status/2*	Get the HTTP status code from a transaction (if it exists).
modify_request_test/0*	Test that a hook can modify a request.
permanent_node_message_test/0*	Test that a permanent node message cannot be changed.
priv_inaccessible_test/0*	Test that we can't get the node message if the requested key is private.
request_response_hooks_test/0*
resolve_hook/4*	Execute a hook from the node message upon the user's request.
status_code/2*	Calculate the appropriate HTTP status code for an AO-Core result.
unauthorized_set_node_msg_fails_test/0*	Test that we can't set the node message if the request is not signed by the owner of the node.
uninitialized_node_test/0*	Test that an uninitialized node will not run computation.
update_node_message/2*	Validate that the request is signed by the operator of the node, then allow them to update the node message.

Function Details

add_dynamic_keys/1 *

add_dynamic_keys(NodeMsg) -> any()

Add dynamic keys to the node message.

add_identity_addresses/1 *

add_identity_addresses(NodeMsg) -> any()

adopt_node_message/2

adopt_node_message(Request, NodeMsg) -> any()

Attempt to adopt changes to a node message.

authorized_set_node_msg_succeeds_test/0 *

authorized_set_node_msg_succeeds_test() -> any()

Test that we can set the node message if the request is signed by the owner of the node.

build/3

build(X1, X2, NodeMsg) -> any()

Emits the version number and commit hash of the HyperBEAM node source, if available.

We include the short hash separately, as the length of this hash may change in the future, depending on the git version/config used to build the node. Subsequently, rather than embedding the git-short-hash-length, for the avoidance of doubt, we include the short hash separately, as well as its long hash.

buildinfo_test/0 *

buildinfo_test() -> any()

Test that version information is available and returned correctly.

claim_node_test/0 *

claim_node_test() -> any()

Test that we can claim the node correctly and set the node message after.

config_test/0 *

config_test() -> any()

Test that we can get the node message.

embed_status/2 *

embed_status(X1, NodeMsg) -> any()

Wrap the result of a device call in a status.

filter_node_msg/2 *

filter_node_msg(Msg, NodeMsg) -> any()

Remove items from the node message that are not encodable into a message.

halt_request_test/0 *

halt_request_test() -> any()

Test that we can halt a request if the hook returns an error.

handle/2

handle(NodeMsg, RawRequest) -> any()

Normalize and route messages downstream based on their path. Messages with a Meta key are routed to the handle_meta/2 function, while all other messages are routed to the handle_resolve/2 function.

handle_initialize/2 *

handle_initialize(Rest, NodeMsg) -> any()

handle_resolve/3 *

handle_resolve(Req, Msgs, NodeMsg) -> any()

Handle an AO-Core request, which is a list of messages. We apply the node's pre-processor to the request first, and then resolve the request using the node's AO-Core implementation if its response was ok. After execution, we run the node's response hook on the result of the request before returning the result it grants back to the user.

info/1

info(X1) -> any()

Ensure that the helper function adopt_node_message/2 is not exported. The naming of this method carefully avoids a clash with the exported info/3 function. We would like the node information to be easily accessible via the info endpoint, but AO-Core also uses info as the name of the function that grants device information. The device call takes two or fewer arguments, so we are safe to use the name for both purposes in this case, as the user info call will match the three-argument version of the function. If in the future the request is added as an argument to AO-Core's internal info function, we will need to find a different approach.

info/3

info(X1, Request, NodeMsg) -> any()

Get/set the node message. If the request is a POST, we check that the request is signed by the owner of the node. If not, we return the node message as-is, aside all keys that are private (according to hb_private).

is/2

is(Request, NodeMsg) -> any()

Check if the request in question is signed by a given role on the node. The role can be one of operator or initiator.

is/3

is(X1, Request, NodeMsg) -> any()

is_operator/2

is_operator(Request, NodeMsg) -> any()

Utility function for determining if a request is from the operator of the node.

maybe_sign/2 *

maybe_sign(Res, NodeMsg) -> any()

Sign the result of a device call if the node is configured to do so.

message_to_status/2 *

message_to_status(Item, NodeMsg) -> any()

Get the HTTP status code from a transaction (if it exists).

modify_request_test/0 *

modify_request_test() -> any()

Test that a hook can modify a request.

permanent_node_message_test/0 *

permanent_node_message_test() -> any()

Test that a permanent node message cannot be changed.

priv_inaccessible_test/0 *

priv_inaccessible_test() -> any()

Test that we can't get the node message if the requested key is private.

request_response_hooks_test/0 *

request_response_hooks_test() -> any()

resolve_hook/4 *

resolve_hook(HookName, InitiatingRequest, Body, NodeMsg) -> any()

Execute a hook from the node message upon the user's request. The invocation of the hook provides a request of the following form:

       /path => request | response
       /request => the original request singleton
       /body => parsed sequence of messages to process | the execution result

status_code/2 *

status_code(X1, NodeMsg) -> any()

Calculate the appropriate HTTP status code for an AO-Core result. The order of precedence is: 1. The status code from the message. 2. The HTTP representation of the status code. 3. The default status code.

unauthorized_set_node_msg_fails_test/0 *

unauthorized_set_node_msg_fails_test() -> any()

Test that we can't set the node message if the request is not signed by the owner of the node.

uninitialized_node_test/0 *

uninitialized_node_test() -> any()

Test that an uninitialized node will not run computation.

update_node_message/2 *

update_node_message(Request, NodeMsg) -> any()

Validate that the request is signed by the operator of the node, then allow them to update the node message.