From 2917ed542ef12f81dbb77049e12b73bc70df4d2b Mon Sep 17 00:00:00 2001 From: Tyler Hall Date: Mon, 10 Feb 2025 17:09:33 -0500 Subject: [PATCH 1/7] docs(core): correct edoc syntax errors --- src/dev_codec_ans104.erl | 8 ++++---- src/dev_codec_httpsig.erl | 8 ++++---- src/dev_codec_httpsig_conv.erl | 22 +++++----------------- src/dev_codec_structured.erl | 4 ++-- src/dev_compute_lite.erl | 2 +- src/dev_dedup.erl | 8 ++++---- src/dev_lookup.erl | 2 +- src/dev_message.erl | 20 ++++++++++---------- src/dev_meta.erl | 12 ++++++------ src/dev_p4.erl | 30 +++++++++++++++--------------- src/dev_process.erl | 8 ++++---- src/dev_relay.erl | 28 ++++++++++++++-------------- src/dev_router.erl | 28 ++++++++++++++-------------- src/dev_scheduler.erl | 28 ++++++++++++++-------------- src/dev_snp.erl | 18 +++++++++--------- src/dev_test.erl | 6 +++--- src/dev_wasm.erl | 14 +++++++------- src/hb.erl | 6 +++--- src/hb_cache.erl | 2 +- src/hb_cache_control.erl | 28 ++++++++++++++-------------- src/hb_converge.erl | 27 ++++++++++++++------------- src/hb_converge_test_vectors.erl | 14 +++++++------- src/hb_http_server.erl | 6 +++--- src/hb_path.erl | 9 +++++---- src/hb_singleton.erl | 10 +++++----- src/hb_test_utils.erl | 6 +++--- src/hb_util.erl | 2 +- 27 files changed, 173 insertions(+), 183 deletions(-) diff --git a/src/dev_codec_ans104.erl b/src/dev_codec_ans104.erl index 17e062ba..c0ccfa70 100644 --- a/src/dev_codec_ans104.erl +++ b/src/dev_codec_ans104.erl @@ -1,4 +1,4 @@ -%%% @doc Codec for managing transformations from `ar_bundles`-style Arweave TX +%%% @doc Codec for managing transformations from `ar_bundles'-style Arweave TX %%% records to and from TABMs. -module(dev_codec_ans104). -export([to/1, from/1, attest/3, verify/3]). @@ -25,7 +25,7 @@ ] ). -%% @doc Sign a message using the `priv_wallet` key in the options. +%% @doc Sign a message using the `priv_wallet' key in the options. attest(Msg, _Req, Opts) -> Signed = ar_bundles:sign_item( to(Msg), @@ -137,9 +137,9 @@ to(Binary) when is_binary(Binary) -> to(TX) when is_record(TX, tx) -> TX; to(RawTABM) when is_map(RawTABM) -> % The path is a special case so we normalized it first. It may have been - % modified by `hb_converge` in order to set it to the current key that is + % modified by `hb_converge' in order to set it to the current key that is % being executed. We should check whether the path is in the - % `priv/Converge/Original-Path` field, and if so, use that instead of the + % `priv/Converge/Original-Path' field, and if so, use that instead of the % stated path. This normalizes the path, such that the signed message will % continue to validate correctly. TABM = hb_converge:normalize_keys(RawTABM), diff --git a/src/dev_codec_httpsig.erl b/src/dev_codec_httpsig.erl index 57a98cbb..fb2e9307 100644 --- a/src/dev_codec_httpsig.erl +++ b/src/dev_codec_httpsig.erl @@ -137,10 +137,10 @@ attest(MsgToSign, _Req, Opts) -> Authority = authority(lists:sort(maps:keys(Enc)), #{}, Wallet), {ok, {SignatureInput, Signature}} = sign_auth(Authority, #{}, Enc), [ParsedSignatureInput] = dev_codec_structured_conv:parse_list(SignatureInput), - % Set the name as `http-sig-[hex encoding of the first 8 bytes of the public key]` + % Set the name as `http-sig-[hex encoding of the first 8 bytes of the public key]' Attestor = hb_util:human_id(Address = ar_wallet:to_address(Wallet)), SigName = address_to_sig_name(Address), - % Calculate the id and place the signature into the `attestations` key of the message. + % Calculate the id and place the signature into the `attestations' key of the message. Attestation = #{ <<"id">> => crypto:hash(sha256, Signature), @@ -168,7 +168,7 @@ attest(MsgToSign, _Req, Opts) -> MsgWithoutHP = maps:without([<<"hashpath">>], MsgToSign), reset_hmac(MsgWithoutHP#{ <<"attestations">> => NewAttestations }). -%% @doc If the `body` key is present, replace it with a content-digest. +%% @doc If the `body' key is present, replace it with a content-digest. add_content_digest(Msg) -> case maps:get(<<"body">>, Msg, not_found) of not_found -> Msg; @@ -292,7 +292,7 @@ hmac(Msg) -> HMacValue = crypto:mac(hmac, sha256, <<"ao">>, SignatureBase), {ok, HMacValue}. -%% @doc Verify different forms of httpsig attested messages. `dev_message:verify` +%% @doc Verify different forms of httpsig attested messages. `dev_message:verify' %% already places the keys from the attestation message into the root of the %% message. verify(MsgToVerify, #{ <<"attestor">> := <<"hmac-sha256">> }, _Opts) -> diff --git a/src/dev_codec_httpsig_conv.erl b/src/dev_codec_httpsig_conv.erl index e144b650..c5f08f8b 100644 --- a/src/dev_codec_httpsig_conv.erl +++ b/src/dev_codec_httpsig_conv.erl @@ -2,22 +2,10 @@ %%% @doc A codec for the that marshals TABM encoded messages to and from the %%% "HTTP" message structure. %%% -%%% The HTTP Message is an Erlang Map with the following shape: -%%% #{ -%%% headers => [ -%%% {<<"example-header">>, <<"value">>} -%%% ], -%%% body: <<"some body">> -%%% } -%%% %%% Every HTTP message is an HTTP multipart message. %%% See https://datatracker.ietf.org/doc/html/rfc7578 %%% %%% For each TABM Key: -%%% -%%% The TABM Key will be ignored if: -%%% - The field is private (according to hb_private:is_private/1) -%%% - The field is one of ?REGEN_KEYS %%% %%% The Key/Value Pair will be encoded according to the following rules: %%% "signatures" -> {SignatureInput, Signature} header Tuples, each encoded @@ -192,7 +180,7 @@ from_body_parts(TABM, [Part | Rest]) -> from_body_parts(maps:put(PartName, ParsedPart, TABM), Rest) end. -%% @doc Populate the `/attestations` key on the TABM with the dictionary of +%% @doc Populate the `/attestations' key on the TABM with the dictionary of %% signatures and their corresponding inputs. attestations_from_signature(Map, _HPs, not_found, _RawSigInput) -> ?event({no_sigs_found_in_from, {msg, Map}}), @@ -337,8 +325,8 @@ to(TABM, Opts) when is_map(TABM) -> <<"body">> => <> } end, - % Add the content-digest to the HTTP message. `generate_content_digest/1` - % will return a map with the `content-digest` key set, but the body removed, + % Add the content-digest to the HTTP message. `generate_content_digest/1' + % will return a map with the `content-digest' key set, but the body removed, % so we merge the two maps together to maintain the body and the content-digest. Enc2 = maps:merge( @@ -389,8 +377,8 @@ hashpaths_from_message(Msg) -> maps:get(<<"attestations">>, Msg, #{}) ). -%% @doc Extract all keys labelled `hashpath*` from the attestations, and add them -%% to the HTTP message as `hashpath*` keys. +%% @doc Extract all keys labelled `hashpath*' from the attestations, and add them +%% to the HTTP message as `hashpath*' keys. extract_hashpaths(Map) -> maps:filter( fun (<<"hashpath", _/binary>>, _) -> true; diff --git a/src/dev_codec_structured.erl b/src/dev_codec_structured.erl index db142c2b..1ed81794 100644 --- a/src/dev_codec_structured.erl +++ b/src/dev_codec_structured.erl @@ -5,7 +5,7 @@ %%% compound type depths, as well as limited floating point representations. %%% %%% As with all Converge codecs, its target format (the format it expects to -%%% receive in the `to/1` function, and give in `from/1`) is TABM. +%%% receive in the `to/1' function, and give in `from/1') is TABM. %%% %%% For more details, see the HTTP Structured Fields (RFC-9651) specification. -module(dev_codec_structured). @@ -71,7 +71,7 @@ from(Other) -> hb_path:to_binary(Other). %% @doc Convert a TABM into a native HyperBEAM message. to(Bin) when is_binary(Bin) -> Bin; to(TABM0) -> - % First, handle special cases of empty items, which `ar_bundles` cannot + % First, handle special cases of empty items, which `ar_bundles' cannot % handle. Needs to be transformed into a list (unfortunately) so that we % can also remove the "Converge-Type-" prefix from the key. TABM1 = diff --git a/src/dev_compute_lite.erl b/src/dev_compute_lite.erl index 6e2d95a5..9c677b7f 100644 --- a/src/dev_compute_lite.erl +++ b/src/dev_compute_lite.erl @@ -1,6 +1,6 @@ %%% @doc Simple wrapper module that enables compute on remote machines, %%% implementing the JSON-Iface. This can be used either as a standalone, to -%%% bring trusted results into the local node, or as the `Execution-Device` of +%%% bring trusted results into the local node, or as the `Execution-Device' of %%% an AO process. -module(dev_compute_lite). -export([compute/3]). diff --git a/src/dev_dedup.erl b/src/dev_dedup.erl index bdec90d5..736a3833 100644 --- a/src/dev_dedup.erl +++ b/src/dev_dedup.erl @@ -1,5 +1,5 @@ -%%% @moduledoc A device that deduplicates messages send to a process. -%%% Only runs on the first pass of the `compute` key call if executed +%%% @doc A device that deduplicates messages send to a process. +%%% Only runs on the first pass of the `compute' key call if executed %%% in a stack. Currently the device stores its list of already seen %%% items in memory, but at some point it will likely make sense to %%% drop them in the cache. @@ -49,7 +49,7 @@ handle(Key, M1, M2, Opts) -> dedup_test() -> hb:init(), % Create a stack with a dedup device and 2 devices that will append to a - % `Result` key. + % `Result' key. Msg = #{ <<"device">> => <<"Stack@1.0">>, <<"device-stack">> => @@ -78,7 +78,7 @@ dedup_test() -> dedup_with_multipass_test() -> % Create a stack with a dedup device and 2 devices that will append to a - % `Result` key and a `Multipass` device that will repeat the message for + % `Result' key and a `Multipass' device that will repeat the message for % an additional pass. We want to ensure that Multipass is not hindered by % the dedup device. Msg = #{ diff --git a/src/dev_lookup.erl b/src/dev_lookup.erl index 56d12437..fc46e6ee 100644 --- a/src/dev_lookup.erl +++ b/src/dev_lookup.erl @@ -1,5 +1,5 @@ %%% @doc A device that looks up an ID from a local store and returns it, honoring -%%% the `accept` key to return the correct format. +%%% the `accept' key to return the correct format. -module(dev_lookup). -export([read/3]). -include("include/hb.hrl"). diff --git a/src/dev_message.erl b/src/dev_message.erl index 34466172..b30e537d 100644 --- a/src/dev_message.erl +++ b/src/dev_message.erl @@ -35,15 +35,15 @@ info() -> %exports => ?DEVICE_KEYS }. -%% @doc Return the ID of a message, using the `attestors` list if it exists. -%% If the `attestors` key is `all`, return the ID including all known -%% attestations -- `none` yields the ID without any attestations. If the -%% `attestors` key is a list/map, return the ID including only the specified +%% @doc Return the ID of a message, using the `attestors' list if it exists. +%% If the `attestors' key is `all', return the ID including all known +%% attestations -- `none' yields the ID without any attestations. If the +%% `attestors' key is a list/map, return the ID including only the specified %% attestations. %% -%% The `id-device` key in the message can be used to specify the device that +%% The `id-device' key in the message can be used to specify the device that %% should be used to calculate the ID. If it is not set, the default device -%% (`httpsig@1.0`) is used. +%% (`httpsig@1.0') is used. %% %% Note: This function _does not_ use Converge's `get/3' function, as it %% as it would require significant computation. We may want to change this @@ -95,7 +95,7 @@ id(Base, Req, NodeOpts) -> ); Mod -> Mod end, - % Apply the function's `id` function with the appropriate arguments. If it + % Apply the function's `id' function with the appropriate arguments. If it % doesn't exist, error. case hb_converge:find_exported_function(ModBase, DevMod, id, 3, NodeOpts) of {ok, Fun} -> apply(Fun, [ModBase, Req, NodeOpts]); @@ -145,8 +145,8 @@ attest(Self, Req, Opts) -> #{ <<"hashpath">> := Hashpath } -> Base#{ <<"hashpath">> => Hashpath }; _ -> Base end, - % We _do not_ set the `device` key in the message, as the device will be - % part of the attestation. Instead, we find the device module's `attest` + % We _do not_ set the `device' key in the message, as the device will be + % part of the attestation. Instead, we find the device module's `attest' % function and apply it. AttMod = hb_converge:message_to_device(#{ <<"device">> => AttDev }, Opts), {ok, AttFun} = hb_converge:find_exported_function(Base, AttMod, attest, 3, Opts), @@ -197,7 +197,7 @@ verify(Self, Req, Opts) -> {ok, Res}. %% @doc Verify a single attestation in the context of its parent message. -%% Note: Assumes that the `attestations` key has already been removed from the +%% Note: Assumes that the `attestations' key has already been removed from the %% message. verify_attestation(Base, Attestation, Req, Opts) -> AttestionMessage = diff --git a/src/dev_meta.erl b/src/dev_meta.erl index c93974be..f0e0377e 100644 --- a/src/dev_meta.erl +++ b/src/dev_meta.erl @@ -14,8 +14,8 @@ -include_lib("eunit/include/eunit.hrl"). %% @doc 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_converge/2` function. +%% with a `Meta' key are routed to the `handle_meta/2' function, while all +%% other messages are routed to the `handle_converge/2' function. handle(NodeMsg, RawRequest) -> ?event({singleton_request, RawRequest}), NormRequest = hb_singleton:from(RawRequest), @@ -42,9 +42,9 @@ handle_initialize([_|Rest], NodeMsg) -> handle_initialize([], _NodeMsg) -> {error, <<"Node must be initialized before use.">>}. -%% @doc Get/set the node message. If the request is a `POST`, we check that the +%% @doc 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`). +%% as-is, aside all keys that are private (according to `hb_private'). info(_, Request, NodeMsg) -> case hb_converge:get(<<"method">>, Request, NodeMsg) of <<"GET">> -> @@ -122,8 +122,8 @@ update_node_message(Request, NodeMsg) -> %% @doc Handle a Converge 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 Converge implementation if its response was `ok`. -%% After execution, we run the node's `postprocessor` message on the result of +%% using the node's Converge implementation if its response was `ok'. +%% After execution, we run the node's `postprocessor' message on the result of %% the request before returning the result it grants back to the user. handle_converge(Req, Msgs, NodeMsg) -> % Apply the pre-processor to the request. diff --git a/src/dev_p4.erl b/src/dev_p4.erl index dce164d8..1b7bc7a9 100644 --- a/src/dev_p4.erl +++ b/src/dev_p4.erl @@ -5,31 +5,31 @@ %%% %%% The device requires the following node message settings in order to function: %%% -%%% - `p4_pricing_device`: The device that will estimate the cost of a request. -%%% - `p4_ledger_device`: The device that will act as a payment ledger. +%%% - `p4_pricing_device': The device that will estimate the cost of a request. +%%% - `p4_ledger_device': The device that will act as a payment ledger. %%% %%% The pricing device should implement the following keys: %%% ``` %%% GET /estimate?type=pre|post&body=[...]&request=RequestMessage %%% GET /price?type=pre|post&body=[...]&request=RequestMessage -%%% ``` +%%% ''' %%% -%%% The `body` key is used to pass either the request or response messages to the -%%% device. The `type` key is used to specify whether the inquiry is for a request +%%% The `body' key is used to pass either the request or response messages to the +%%% device. The `type' key is used to specify whether the inquiry is for a request %%% (pre) or a response (post) object. Requests carry lists of messages that will -%%% be executed, while responses carry the results of the execution. The `price` -%%% key may return `infinity` if the node will not serve a user under any -%%% circumstances. Else, the value returned by the `price` key will be passed to -%%% the ledger device as the `amount` key. +%%% be executed, while responses carry the results of the execution. The `price' +%%% key may return `infinity' if the node will not serve a user under any +%%% circumstances. Else, the value returned by the `price' key will be passed to +%%% the ledger device as the `amount' key. %%% %%% The ledger device should implement the following keys: %%% ``` %%% POST /credit?message=PaymentMessage&request=RequestMessage %%% POST /debit?amount=PriceMessage&type=pre|post&request=RequestMessage -%%% ``` +%%% ''' %%% -%%% The `type` key is optional and defaults to `pre`. If `type` is set to `post`, -%%% the debit must be applied to the ledger, whereas the `pre` type is used to +%%% The `type' key is optional and defaults to `pre'. If `type' is set to `post', +%%% the debit must be applied to the ledger, whereas the `pre' type is used to %%% check whether the debit would succeed before execution. -module(dev_p4). -export([preprocess/3, postprocess/3, balance/3]). @@ -43,7 +43,7 @@ ]). %% @doc Estimate the cost of a transaction and decide whether to proceed with -%% a request. The default behavior if `pricing_device` or `p4_balances` are +%% a request. The default behavior if `pricing_device' or `p4_balances' are %% not set is to proceed, so it is important that a user initialize them. preprocess(State, Raw, NodeMsg) -> PricingDevice = hb_converge:get(<<"pricing_device">>, State, false, NodeMsg), @@ -197,7 +197,7 @@ balance(_, Req, NodeMsg) -> end. %% @doc The node operator may elect to make certain routes non-chargable, using -%% the `routes` syntax also used to declare routes in `router@1.0`. +%% the `routes' syntax also used to declare routes in `router@1.0'. is_chargable_req(Req, NodeMsg) -> NonChargableRoutes = hb_opts:get( @@ -237,7 +237,7 @@ test_opts(Opts, PricingDev, LedgerDev) -> postprocessor => ProcessorMsg }. -%% @doc Simple test of p4's capabilities with the `faff@1.0` device. +%% @doc Simple test of p4's capabilities with the `faff@1.0' device. faff_test() -> GoodWallet = ar_wallet:new(), BadWallet = ar_wallet:new(), diff --git a/src/dev_process.erl b/src/dev_process.erl index d064ad0a..e509ebcd 100644 --- a/src/dev_process.erl +++ b/src/dev_process.erl @@ -57,7 +57,7 @@ -include_lib("include/hb.hrl"). %% The frequency at which the process state should be cached. Can be overridden -%% with the `cache_frequency` option. +%% with the `cache_frequency' option. -define(DEFAULT_CACHE_FREQ, 10). %% @doc When the info key is called, we should return the process exports. @@ -182,7 +182,7 @@ do_compute(ProcID, Msg1, Msg2, TargetSlot, Opts) -> ToProcess, Opts ), - % Cache the `Memory` key every `Cache-Frequency` slots. + % Cache the `Memory' key every `Cache-Frequency' slots. Freq = hb_opts:get( process_cache_frequency, @@ -401,13 +401,13 @@ run_as(Key, Msg1, Msg2, Opts) -> end. %% @doc Change the message to for that has the device set as this module. -%% In situations where the key that is `run_as` returns a message with a +%% In situations where the key that is `run_as' returns a message with a %% transformed device, this is useful. as_process(Msg1, Opts) -> {ok, Proc} = dev_message:set(Msg1, #{ <<"device">> => <<"Process@1.0">> }, Opts), Proc. -%% @doc Helper function to store a copy of the `process` key in the message. +%% @doc Helper function to store a copy of the `process' key in the message. ensure_process_key(Msg1, Opts) -> case hb_converge:get(<<"process">>, {as, dev_message, Msg1}, Opts) of not_found -> diff --git a/src/dev_relay.erl b/src/dev_relay.erl index 0a3c8ffa..032782e6 100644 --- a/src/dev_relay.erl +++ b/src/dev_relay.erl @@ -1,30 +1,30 @@ %%% @doc This module implements the relay device, which is responsible for %%% relaying messages between nodes and other HTTP(S) endpoints. %%% -%%% It can be called in either `call` or `cast` mode. In `call` mode, it -%%% returns a `{ok, Result}` tuple, where `Result` is the response from the -%%% remote peer to the message sent. In `cast` mode, the invocation returns +%%% It can be called in either `call' or `cast' mode. In `call' mode, it +%%% returns a `{ok, Result}' tuple, where `Result' is the response from the +%%% remote peer to the message sent. In `cast' mode, the invocation returns %%% immediately, and the message is relayed asynchronously. No response is given -%%% and the device returns `{ok, <<"OK">>}`. +%%% and the device returns `{ok, <<"OK">>}'. %%% %%% Example usage: %%% %%% ``` %%% curl /~relay@.1.0/call?method=GET?0.path=https://www.arweave.net/ -%%% ``` +%%% ''' -module(dev_relay). -export([call/3, cast/3]). -include("include/hb.hrl"). -include_lib("eunit/include/eunit.hrl"). -%% @doc Execute a `call` request using a node's routes. +%% @doc Execute a `call' request using a node's routes. %% %% Supports the following options: -%% - `target`: The target message to relay. Defaults to the original message. -%% - `relay-path`: The path to relay the message to. Defaults to the original path. -%% - `method`: The method to use for the request. Defaults to the original method. -%% - `requires-sign`: Whether the request requires signing before dispatching. -%% Defaults to `false`. +%% - `target': The target message to relay. Defaults to the original message. +%% - `relay-path': The path to relay the message to. Defaults to the original path. +%% - `method': The method to use for the request. Defaults to the original method. +%% - `requires-sign': Whether the request requires signing before dispatching. +%% Defaults to `false'. call(M1, RawM2, Opts) -> {ok, BaseTarget} = hb_message:find_target(M1, RawM2, Opts), RelayPath = @@ -53,11 +53,11 @@ call(M1, RawM2, Opts) -> RequestedClient -> RequestedClient end, ?event({relaying_message, TargetMod2}), - % Let `hb_http:request/2` handle finding the peer and dispatching the request. + % Let `hb_http:request/2' handle finding the peer and dispatching the request. hb_http:request(TargetMod2, Opts#{ http_client => Client }). -%% @doc Execute a request in the same way as `call/3`, but asynchronously. Always -%% returns <<"OK">>. +%% @doc Execute a request in the same way as `call/3', but asynchronously. Always +%% returns `<<"OK">>'. cast(M1, M2, Opts) -> spawn(fun() -> call(M1, M2, Opts) end), {ok, <<"OK">>}. diff --git a/src/dev_router.erl b/src/dev_router.erl index 255d2bce..6a579aff 100644 --- a/src/dev_router.erl +++ b/src/dev_router.erl @@ -3,16 +3,16 @@ %%% routed to a single process per node, which then load-balances them %%% between downstream workers that perform the actual requests. %%% -%%% The routes for the router are defined in the `routes` key of the `Opts`, +%%% The routes for the router are defined in the `routes' key of the `Opts', %%% as a precidence-ordered list of maps. The first map that matches the %%% message will be used to determine the route. %%% %%% Multiple nodes can be specified as viable for a single route, with the -%%% `Choose` key determining how many nodes to choose from the list (defaulting -%%% to 1). The `Strategy` key determines the load distribution strategy, -%%% which can be one of `Random`, `By-Base`, or `Nearest`. The route may also +%%% `Choose' key determining how many nodes to choose from the list (defaulting +%%% to 1). The `Strategy' key determines the load distribution strategy, +%%% which can be one of `Random', `By-Base', or `Nearest'. The route may also %%% define additional parallel execution parameters, which are used by the -%%% `hb_http` module to manage control of requests. +%%% `hb_http' module to manage control of requests. %%% %%% The structure of the routes should be as follows: %%% ``` @@ -75,13 +75,13 @@ routes(M1, M2, Opts) -> %% Nearest: According to the distance of the node's wallet address to the %% base message's hashpath. %% ''' -%% `By-Base` will ensure that all traffic for the same hashpath is routed to the -%% same node, minimizing work duplication, while `Random` ensures a more even +%% `By-Base' will ensure that all traffic for the same hashpath is routed to the +%% same node, minimizing work duplication, while `Random' ensures a more even %% distribution of the requests. %% -%% Can operate as a `Router/1.0` device, which will ignore the base message, +%% Can operate as a `Router/1.0' device, which will ignore the base message, %% routing based on the Opts and request message provided, or as a standalone -%% function, taking only the request message and the `Opts` map. +%% function, taking only the request message and the `Opts' map. route(Msg, Opts) -> route(undefined, Msg, Opts). route(_, Msg, Opts) -> Routes = hb_opts:get(routes, [], Opts), @@ -111,9 +111,9 @@ route(_, Msg, Opts) -> %% @doc Apply a node map's rules for transforming the path of the message. %% Supports the following keys: -%% - `prefix`: The prefix to add to the path. -%% - `suffix`: The suffix to add to the path. -%% - `replace`: A regex to replace in the path. +%% - `prefix': The prefix to add to the path. +%% - `suffix': The suffix to add to the path. +%% - `replace': A regex to replace in the path. apply_node(#{ <<"path">> := Path }, #{ <<"prefix">> := Prefix }) -> {ok, <>}; apply_node(#{ <<"path">> := Path }, #{ <<"suffix">> := Suffix }) -> @@ -253,7 +253,7 @@ strategy_suite_test_() -> [<<"Random">>, <<"By-Base">>, <<"Nearest">>] ). -%% @doc Ensure that `By-Base` always chooses the same node for the same +%% @doc Ensure that `By-Base' always chooses the same node for the same %% hashpath. by_base_determinism_test() -> FirstN = 5, @@ -499,7 +499,7 @@ simulation_distribution(SimRes, Nodes) -> within_norms(SimRes, Nodes, TestSize) -> Distribution = simulation_distribution(SimRes, Nodes), - % Check that the mean is `TestSize/length(Nodes)` + % Check that the mean is `TestSize/length(Nodes)' Mean = hb_util:mean(Distribution), ?assert(Mean == (TestSize / length(Nodes))), % Check that the highest count is not more than 3 standard deviations diff --git a/src/dev_scheduler.erl b/src/dev_scheduler.erl index 3923c25a..1c36ccfe 100644 --- a/src/dev_scheduler.erl +++ b/src/dev_scheduler.erl @@ -1,15 +1,15 @@ %%% @doc A simple scheduler scheme for AO. %%% This device expects a message of the form: -%%% Process: #{ id, Scheduler: #{ Authority } } +%%% Process: `#{ id, Scheduler: #{ Authority } }' %%% ``` %%% It exposes the following keys for scheduling: -%%% #{ method: GET, path: <<"/info">> } -> +%%% `#{ method: GET, path: <<"/info">> }' -> %%% Returns information about the scheduler. -%%% #{ method: GET, path: <<"/slot">> } -> slot(Msg1, Msg2, Opts) +%%% `#{ method: GET, path: <<"/slot">> }' -> `slot(Msg1, Msg2, Opts)' %%% Returns the current slot for a process. -%%% #{ method: GET, path: <<"/schedule">> } -> get_schedule(Msg1, Msg2, Opts) +%%% `#{ method: GET, path: <<"/schedule">> }' -> `get_schedule(Msg1, Msg2, Opts)' %%% Returns the schedule for a process in a cursor-traversable format. -%%% #{ method: POST, path: <<"/schedule">> } -> post_schedule(Msg1, Msg2, Opts) +%%% ` #{ method: POST, path: <<"/schedule">> }' -> `post_schedule(Msg1, Msg2, Opts)' %%% Schedules a new message for a process, or starts a new scheduler %%% for the given message. %%% ''' @@ -294,12 +294,12 @@ get_schedule(Msg1, Msg2, Opts) -> %% @doc Find the schedule ID from a given request. The precidence order for %% search is as follows: -%% [1. `ToSched/id` -- in the case of `POST schedule`, handled locally] -%% 2. `Msg2/target` -%% 3. `Msg2/id` when `Msg2` has `type: Process` -%% 4. `Msg1/process/id` -%% 5. `Msg1/id` when `Msg1` has `type: Process` -%% 6. `Msg2/id` +%% [1. `ToSched/id' -- in the case of `POST schedule', handled locally] +%% 2. `Msg2/target' +%% 3. `Msg2/id' when `Msg2' has `type: Process' +%% 4. `Msg1/process/id' +%% 5. `Msg1/id' when `Msg1' has `type: Process' +%% 6. `Msg2/id' find_schedule_id(Msg1, Msg2, Opts) -> TempOpts = Opts#{ hashpath => ignore }, Res = case hb_converge:resolve(Msg2, <<"target">>, TempOpts) of @@ -334,8 +334,8 @@ find_schedule_id(Msg1, Msg2, Opts) -> %% @doc Search the given base and request message pair to find the message to %% schedule. The precidence order for search is as follows: -%% 1. `Msg2/body` -%% 2. `Msg2` +%% 1. `Msg2/body' +%% 2. `Msg2' find_message_to_schedule(_Msg1, Msg2, Opts) -> case hb_converge:resolve(Msg2, <<"body">>, Opts#{ hashpath => ignore }) of {ok, Body} -> @@ -343,7 +343,7 @@ find_message_to_schedule(_Msg1, Msg2, Opts) -> _ -> Msg2 end. -%% @doc Find the process from a given request. Check if it has a `process` +%% @doc Find the process from a given request. Check if it has a `process' %% field, and if so, return that. Otherwise, return the full message. find_process(Msg, Opts) -> hb_converge:get(<<"process">>, Msg, Msg, Opts#{ hashpath => ignore }). diff --git a/src/dev_snp.erl b/src/dev_snp.erl index 6c26b0f6..a53b3a05 100644 --- a/src/dev_snp.erl +++ b/src/dev_snp.erl @@ -9,8 +9,8 @@ firmware, kernel, initrd, append]). %%% Test constants -%% Matching attestation report is found in `test/snp-attestation` in -%% `dev_codec_flat:serialize/1`'s format. Alternatively, set the `TEST_NODE` +%% Matching attestation report is found in `test/snp-attestation' in +%% `dev_codec_flat:serialize/1''s format. Alternatively, set the `TEST_NODE' %% constant to a live node to run the tests against it. -define(TEST_NODE, undefined). -define(TEST_TRUSTED_SOFTWARE, #{ @@ -167,7 +167,7 @@ generate(_M1, _M2, Opts) -> Wallet = hb_opts:get(priv_wallet, no_valid_wallet, Opts), Address = hb_util:human_id(ar_wallet:to_address(Wallet)), ?event({snp_wallet, Wallet}), - % Remove the `priv*` keys from the options. + % Remove the `priv*' keys from the options. {ok, PublicNodeMsgID} = dev_message:id( NodeMsg = @@ -205,12 +205,12 @@ is_debug(Report) -> (hb_converge:get(<<"policy">>, Report, #{}) band (1 bsl 19)) =/= 0. %% @doc Ensure that all of the software hashes are trusted. The caller may set -%% a specific device to use for the `is-trusted` key. The device must then -%% implement the `trusted` resolver. +%% a specific device to use for the `is-trusted' key. The device must then +%% implement the `trusted' resolver. execute_is_trusted(M1, Msg, NodeOpts) -> % Generate a modified version of the base message, with the - % `is-trusted-device` key set as the device, if provided by the caller. - % If not provided, use the default resolver (this module's `trusted` + % `is-trusted-device' key set as the device, if provided by the caller. + % If not provided, use the default resolver (this module's `trusted' % function). ModM1 = case hb_converge:get(<<"is-trusted-device">>, M1, NodeOpts) of @@ -244,7 +244,7 @@ execute_is_trusted(M1, Msg, NodeOpts) -> {ok, Result}. %% @doc Default implementation of a resolver for trusted software. Searches the -%% `trusted` key in the base message for a list of trusted values, and checks +%% `trusted' key in the base message for a list of trusted values, and checks %% if the value in the request message is a member of that list. trusted(_Msg1, Msg2, NodeOpts) -> Key = hb_converge:get(<<"key">>, Msg2, NodeOpts), @@ -268,7 +268,7 @@ generate_nonce(RawAddress, RawNodeMsgID) -> NodeMsgID = hb_util:native_id(RawNodeMsgID), << Address/binary, NodeMsgID/binary >>. -%% @doc Generate an attestation report and emit it via HTTP. +%% Generate an attestation report and emit it via HTTP. % generate_test() -> % Trusted = % #{ diff --git a/src/dev_test.erl b/src/dev_test.erl index e9d24aa4..d3ce322f 100644 --- a/src/dev_test.erl +++ b/src/dev_test.erl @@ -45,8 +45,8 @@ init(Msg, _Msg2, Opts) -> ?event({init_called_on_dev_test, Msg}), {ok, hb_converge:set(Msg, #{ <<"already-seen">> => [] }, Opts)}. -%% @doc Example `restore/3' handler. Sets the hidden key `Test/Started` to the -%% value of `Current-Slot` and checks whether the `Already-Seen` key is valid. +%% @doc Example `restore/3' handler. Sets the hidden key `Test/Started' to the +%% value of `Current-Slot' and checks whether the `Already-Seen' key is valid. restore(Msg, _Msg2, Opts) -> ?event({restore_called_on_dev_test, Msg}), case hb_converge:get(<<"already-seen">>, Msg, Opts) of @@ -64,7 +64,7 @@ restore(Msg, _Msg2, Opts) -> } end. -%% @doc Example implementation of an `imported` function for a WASM +%% @doc Example implementation of an `imported' function for a WASM %% executor. mul(Msg1, Msg2) -> ?event(mul_called), diff --git a/src/dev_wasm.erl b/src/dev_wasm.erl index af342872..b9b8c52f 100644 --- a/src/dev_wasm.erl +++ b/src/dev_wasm.erl @@ -1,5 +1,5 @@ %%% @doc A device that executes a WASM image on messages using the Memory-64 -%%% preview standard. In the backend, this device uses `beamr`: An Erlang wrapper +%%% preview standard. In the backend, this device uses `beamr': An Erlang wrapper %%% for WAMR, the WebAssembly Micro Runtime. %%% %%% The device has the following requirements and interface: @@ -111,7 +111,7 @@ init(M1, M2, Opts) -> ) }. -%% @doc Take a BEAMR import call and resolve it using `hb_converge`. +%% @doc Take a BEAMR import call and resolve it using `hb_converge'. default_import_resolver(Msg1, Msg2, Opts) -> #{ instance := WASM, @@ -144,11 +144,11 @@ default_import_resolver(Msg1, Msg2, Opts) -> %% @doc Call the WASM executor with a message that has been prepared by a prior %% pass. compute(RawM1, M2, Opts) -> - % Normalize the message to have an open WASM instance, but no literal `State`. + % Normalize the message to have an open WASM instance, but no literal `State'. % The hashpath is not updated during this process. This allows us to take % two different messages and get the same result: - % - A message with a `State' key but no WASM instance in `priv/`. - % - A message with a WASM instance in `priv/` but no `State' key. + % - A message with a `State' key but no WASM instance in `priv/'. + % - A message with a WASM instance in `priv/' but no `State' key. {ok, M1} = normalize(RawM1, M2, Opts), ?event(running_compute), Prefix = dev_stack:prefix(M1, M2, Opts), @@ -366,8 +366,8 @@ input_prefix_test() -> hb_converge:resolve(Priv, <<"import-resolver">>, #{}) ). -%% @doc Test that realistic prefixing for a `dev_process` works -- -%% including both inputs (from `Process/`) and outputs (to the +%% @doc Test that realistic prefixing for a `dev_process' works -- +%% including both inputs (from `Process/') and outputs (to the %% Device-Key) work process_prefixes_test() -> init(), diff --git a/src/hb.erl b/src/hb.erl index 427fdc8b..afd2dbeb 100644 --- a/src/hb.erl +++ b/src/hb.erl @@ -101,7 +101,7 @@ init() -> ?event({old_system_stack_depth, Old}), ok. -%%% @doc Start a server with a `simple-pay@1.0` pre-processor. +%%% @doc Start a server with a `simple-pay@1.0' pre-processor. start_simple_pay() -> start_simple_pay(address()). start_simple_pay(Addr) -> @@ -188,11 +188,11 @@ event(Topic, X, Mod, Func, Line) -> event(Topic, X, Mod, Func, Line, #{}). event(Topic, X, Mod, undefined, Line, Opts) -> event(Topic, X, Mod, "", Line, Opts); event(Topic, X, Mod, Func, undefined, Opts) -> event(Topic, X, Mod, Func, "", Opts); event(Topic, X, ModAtom, Func, Line, Opts) when is_atom(ModAtom) -> - % Check if the module has the `hb_debug` attribute set to `print`. + % Check if the module has the `hb_debug' attribute set to `print'. case lists:member({hb_debug, [print]}, ModAtom:module_info(attributes)) of true -> hb_util:debug_print(X, atom_to_list(ModAtom), Func, Line); false -> - % Check if the module has the `hb_debug` attribute set to `no_print`. + % Check if the module has the `hb_debug' attribute set to `no_print'. case lists:keyfind(hb_debug, 1, ModAtom:module_info(attributes)) of {hb_debug, [no_print]} -> X; _ -> event(Topic, X, atom_to_list(ModAtom), Func, Line, Opts) diff --git a/src/hb_cache.erl b/src/hb_cache.erl index 230f935b..0e536428 100644 --- a/src/hb_cache.erl +++ b/src/hb_cache.erl @@ -49,7 +49,7 @@ list(Path, Store) -> %% @doc Write a message to the cache. For raw binaries, we write the data at %% the hashpath of the data (by default the SHA2-256 hash of the data). We link -%% the unattended ID's hashpath for the keys (including `/attestations`) on the +%% the unattended ID's hashpath for the keys (including `/attestations') on the %% message to the underlying data and recurse. We then link each attestation ID %% to the unattested message, such that any of the attested or unattested IDs %% can be read, and once in memory all of the attestations are available. For diff --git a/src/hb_cache_control.erl b/src/hb_cache_control.erl index d56723c3..5cab6df5 100644 --- a/src/hb_cache_control.erl +++ b/src/hb_cache_control.erl @@ -16,9 +16,9 @@ %% @doc Write a resulting M3 message to the cache if requested. The precidence %% order of cache control sources is as follows: -%% 1. The `Opts` map (letting the node operator have the final say). -%% 2. The `Msg3` results message (granted by Msg1's device). -%% 3. The `Msg2` message (the user's request). +%% 1. The `Opts' map (letting the node operator have the final say). +%% 2. The `Msg3' results message (granted by Msg1's device). +%% 3. The `Msg2' message (the user's request). %% Msg1 is not used, such that it can specify cache control information about %% itself, without affecting its outputs. maybe_store(Msg1, Msg2, Msg3, Opts) -> @@ -31,12 +31,12 @@ maybe_store(Msg1, Msg2, Msg3, Opts) -> end. %% @doc Handles cache lookup, modulated by the caching options requested by -%% the user. Honors the following `Opts` cache keys: -%% `only_if_cached`: If set and we do not find a result in the cache, -%% return an error with a `Cache-Status` of `miss` and -%% a 504 `Status`. -%% `no_cache`: If set, the cached values are never used. Returns -%% `continue` to the caller. +%% the user. Honors the following `Opts' cache keys: +%% `only_if_cached': If set and we do not find a result in the cache, +%% return an error with a `Cache-Status' of `miss' and +%% a 504 `Status'. +%% `no_cache': If set, the cached values are never used. Returns +%% `continue' to the caller. maybe_lookup(Msg1, Msg2, Opts) -> case exec_likely_faster_heuristic(Msg1, Msg2, Opts) of true -> @@ -124,7 +124,7 @@ dispatch_cache_write(Msg1, Msg2, Msg3, Opts) -> false -> Dispatch() end. -%% @doc Generate a message to return when `only_if_cached` was specified, and +%% @doc Generate a message to return when `only_if_cached' was specified, and %% we don't have a cached result. only_if_cached_not_found_error(Msg1, Msg2, Opts) -> ?event( @@ -164,7 +164,7 @@ necessary_messages_not_found_error(Msg1, Msg2, Opts) -> exec_likely_faster_heuristic(Msg1, #{ <<"path">> := Key }, Opts) -> % For now, just check whether the key is explicitly in the map. That is % a good signal that we will likely be asked by the device to grab it. - % If we have `only-if-cached` in the opts, we always force lookup, too. + % If we have `only-if-cached' in the opts, we always force lookup, too. case specifiers_to_cache_settings(hb_opts:get(cache_control, [], Opts)) of #{ <<"only-if-cached">> := true } -> false; _ -> is_map(Msg1) andalso maps:is_key(Key, Msg1) @@ -175,7 +175,7 @@ exec_likely_faster_heuristic(Msg1, #{ <<"path">> := Key }, Opts) -> %% map with `store' and `lookup' keys, each of which is a boolean. %% %% For example, if the last source has a `no_store', the first expresses no -%% preference, but the Opts has `cache_control => [always]`, then the result +%% preference, but the Opts has `cache_control => [always]', then the result %% will contain a `store => true' entry. derive_cache_settings(SourceList, Opts) -> lists:foldr( @@ -202,8 +202,8 @@ maybe_set(Map1, Map2) -> %% @doc Convert a cache source to a cache setting. The setting _must_ always be %% directly in the source, not a Converge-derivable value. The -%% `to_cache_control_map` function is used as the source of settings in all -%% cases, except where an `Opts` specifies that hashpaths should not be updated, +%% `to_cache_control_map' function is used as the source of settings in all +%% cases, except where an `Opts' specifies that hashpaths should not be updated, %% which leads to the result not being cached (as it may be stored with an %% incorrect hashpath). cache_source_to_cache_settings({opts, Opts}) -> diff --git a/src/hb_converge.erl b/src/hb_converge.erl index 40c86b28..d736f94c 100644 --- a/src/hb_converge.erl +++ b/src/hb_converge.erl @@ -45,7 +45,7 @@ %%% %%% DevMod:info : Optional. Returns a map of options for the device. All %%% options are optional and assumed to be the defaults if -%%% not specified. This function can accept a `Message1` as +%%% not specified. This function can accept a `Message1' as %%% an argument, allowing it to specify its functionality %%% based on a specific message if appropriate. %%% @@ -62,12 +62,12 @@ %%% %%% info/default : A function that should be used to handle all keys that %%% are not explicitly implemented by the device. Defaults to -%%% the `dev_message` device, which contains general keys for +%%% the `dev_message' device, which contains general keys for %%% interacting with messages. %%% %%% info/default_mod : A different device module that should be used to %%% handle all keys that are not explicitly implemented -%%% by the device. Defaults to the `dev_message` device. +%%% by the device. Defaults to the `dev_message' device. %%% %%% info/grouper : A function that returns the concurrency 'group' name for %%% an execution. Executions with the same group name will @@ -88,6 +88,7 @@ %%% Default: true. %%% `add_key': Whether to add the key to the start of the arguments. %%% Default: `'. +%%% ''' -module(hb_converge). %%% Main Converge API: -export([resolve/2, resolve/3, resolve_many/2]). @@ -198,7 +199,7 @@ resolve_stage(2, Msg1, Msg2, Opts) -> ?event(converge_core, {stage, 2, cache_lookup}, Opts), % Lookup request in the cache. If we find a result, return it. % If we do not find a result, we continue to the next stage, - % unless the cache lookup returns `halt` (the user has requested that we + % unless the cache lookup returns `halt' (the user has requested that we % only return a result if it is already in the cache). case hb_cache_control:maybe_lookup(Msg1, Msg2, Opts) of {ok, Msg3} -> @@ -229,8 +230,8 @@ resolve_stage(4, Msg1, Msg2, Opts) -> % Erlang cluster) processes that are already performing the execution. % Before we search for a live executor, we check if the device specifies % a function that tailors the 'group' name of the execution. For example, - % the `dev_process` device 'groups' all calls to the same process onto - % calls to a single executor. By default, `{Msg1, Msg2}` is used as the + % the `dev_process' device 'groups' all calls to the same process onto + % calls to a single executor. By default, `{Msg1, Msg2}' is used as the % group name. case hb_persistent:find_or_register(Msg1, Msg2, Opts) of {leader, ExecName} -> @@ -416,7 +417,7 @@ resolve_stage(6, Func, Msg1, Msg2, ExecName, Opts) -> } ), % If the function call fails, we raise an error in the manner - % indicated by caller's `#Opts`. + % indicated by caller's `#Opts'. error_execution( ExecName, Msg2, @@ -574,7 +575,7 @@ error_execution(ExecGroup, Msg2, Whence, {Class, Exception, Stacktrace}, Opts) - end. %% @doc Force the result of a device call into a message if the result is not -%% requested by the `Opts`. +%% requested by the `Opts'. maybe_force_message({Status, Res}, Opts) -> case hb_opts:get(force_message, false, Opts) and not is_map(Res) of true when is_list(Res) -> {Status, normalize_keys(Res)}; @@ -588,7 +589,7 @@ maybe_force_message({Status, Res}, Opts) -> %% %% Additionally, this function supports the `{as, Device, Msg}' syntax, which %% allows the key to be resolved using another device to resolve the key, -%% while maintaining the tracability of the `HashPath` of the output message. +%% while maintaining the tracability of the `HashPath' of the output message. %% %% Returns the value of the key if it is found, otherwise returns the default %% provided by the user, or `not_found' if no default is provided. @@ -653,7 +654,7 @@ set(RawMsg1, RawMsg2, Opts) when is_map(RawMsg2) -> [] -> Msg1; [Key|_] -> % Get the value to set. Use Converge by default, but fall back to - % getting via `maps` if it is not found. + % getting via `maps' if it is not found. Val = case get(Key, Msg2, internal_opts(Opts)) of not_found -> maps:get(Key, Msg2); @@ -805,7 +806,7 @@ message_to_fun(Msg, Key, Opts) -> ?event(converge_devices, {no_override_handler, {dev, Dev}, {key, Key}}), case {find_exported_function(Msg, Dev, Key, 3, Opts), Exported} of {{ok, Func}, true} -> - % Case 3: The device has a function of the name `Key`. + % Case 3: The device has a function of the name `Key'. {ok, Dev, Func}; _ -> case {maps:find(default, Info), Exported} of @@ -927,10 +928,10 @@ find_exported_function(Msg, Mod, Key, Arity, Opts) -> %% @doc Check if a device is guarding a key via its `exports' list. Defaults to %% true if the device does not specify an `exports' list. The `info' function is -%% always exported, if it exists. Elements of the `exludes` list are not +%% always exported, if it exists. Elements of the `exludes' list are not %% exported. Note that we check for info _twice_ -- once when the device is %% given but the info result is not, and once when the info result is given. -%% The reason for this is that `info/3` calls other functions that may need to +%% The reason for this is that `info/3' calls other functions that may need to %% check if a key is exported, so we must avoid infinite loops. We must, however, %% also return a consistent result in the case that only the info result is %% given, so we check for it in both cases. diff --git a/src/hb_converge_test_vectors.erl b/src/hb_converge_test_vectors.erl index b3650875..8c1bb879 100644 --- a/src/hb_converge_test_vectors.erl +++ b/src/hb_converge_test_vectors.erl @@ -1,15 +1,15 @@ %%% @doc Tests for the core Converge resolution engine. -%%% Uses a series of different `Opts` values to test the resolution engine's +%%% Uses a series of different `Opts' values to test the resolution engine's %%% execution under different circumstances. -module(hb_converge_test_vectors). -include_lib("eunit/include/eunit.hrl"). -include_lib("include/hb.hrl"). -%% @doc Easy hook to make a test executable via the command line: -%% `rebar3 eunit --test hb_converge_test_vectors:run_test` +%% Easy hook to make a test executable via the command line: +%% `rebar3 eunit --test hb_converge_test_vectors:run_test' %% Comment/uncomment out as necessary. -% run_test() -> -% hb_test_utils:run(normal, as, test_suite(), test_opts()). +%% run_test() -> +%% hb_test_utils:run(normal, as, test_suite(), test_opts()). %% @doc Run each test in the file with each set of options. Start and reset %% the store for each test. @@ -601,13 +601,13 @@ list_transform_test(Opts) -> as_test(Opts) -> % Create a message with the test device, which implements the test_func - % function. It normally returns `GOOD_FUNCTION`. + % function. It normally returns `GOOD_FUNCTION'. Msg = #{ <<"device">> => <<"test-device@1.0">>, <<"test_func">> => #{ <<"test_key">> => <<"MESSAGE">> } }, ?assertEqual(<<"GOOD_FUNCTION">>, hb_converge:get(<<"test_func">>, Msg, Opts)), - % Now use the `as` keyword to subresolve a key with the message device. + % Now use the `as' keyword to subresolve a key with the message device. ?assertMatch( {ok, #{ <<"test_key">> := <<"MESSAGE">> }}, hb_converge:resolve( diff --git a/src/hb_http_server.erl b/src/hb_http_server.erl index ef38b885..2f431999 100644 --- a/src/hb_http_server.erl +++ b/src/hb_http_server.erl @@ -6,7 +6,7 @@ %%% `hb_http:reply/4' is used to respond to the client, handling the %%% process of converting a message back into an HTTP response. %%% -%%% The router uses an `Opts` message as its Cowboy initial state, +%%% The router uses an `Opts' message as its Cowboy initial state, %%% such that changing it on start of the router server allows for %%% the execution parameters of all downstream requests to be controlled. -module(hb_http_server). @@ -15,9 +15,9 @@ -include_lib("eunit/include/eunit.hrl"). -include("include/hb.hrl"). -%% @doc Starts the HTTP server. Optionally accepts an `Opts` message, which +%% @doc Starts the HTTP server. Optionally accepts an `Opts' message, which %% is used as the source for server configuration settings, as well as the -%% `Opts` argument to use for all Converge resolution requests downstream. +%% `Opts' argument to use for all Converge resolution requests downstream. start() -> ?event(http, {start_store, "main-cache"}), Store = [{hb_store_fs, #{ prefix => "main-cache" }}], diff --git a/src/hb_path.erl b/src/hb_path.erl index 6736e3e1..fc6caf85 100644 --- a/src/hb_path.erl +++ b/src/hb_path.erl @@ -16,7 +16,8 @@ %%% Msg1.HashPath = Msg1.ID %%% Msg3.HashPath = Msg1.Hash(Msg1.HashPath, Msg2.ID) %%% Msg3.{...} = Converge.apply(Msg1, Msg2) -%%% ...''' +%%% ... +%%% ''' %%% %%% A message's ID itself includes its HashPath, leading to the mixing of %%% a Msg2's merkle list into the resulting Msg3's HashPath. This allows a single @@ -45,8 +46,8 @@ hd(Msg2, Opts) -> case pop_request(Msg2, Opts) of undefined -> undefined; {Head, _} -> - % `term_to_path` returns the full path, so we need to take the - % `hd` of our `Head`. + % `term_to_path' returns the full path, so we need to take the + % `hd' of our `Head'. erlang:hd(term_to_path_parts(Head, Opts)) end. @@ -68,7 +69,7 @@ tl(Path, Opts) when is_list(Path) -> end. %% @doc Return the `Remaining-Path' of a message, from its hidden `Converge' -%% key. Does not use the `get` or set `hb_private` functions, such that it +%% key. Does not use the `get' or set `hb_private' functions, such that it %% can be safely used inside the main Converge resolve function. priv_remaining(Msg, _Opts) -> Priv = hb_private:from_message(Msg), diff --git a/src/hb_singleton.erl b/src/hb_singleton.erl index 91aa7c61..4f49294e 100644 --- a/src/hb_singleton.erl +++ b/src/hb_singleton.erl @@ -173,7 +173,7 @@ parse_full_path(RelativeRef) -> maps:from_list(QKVList) }. -%% @doc Step 2: Decode, split and sanitize the path. Split by `/` but avoid +%% @doc Step 2: Decode, split and sanitize the path. Split by `/' but avoid %% subpath components, such that their own path parts are not dissociated from %% their parent path. path_messages(RawBin) when is_binary(RawBin) -> @@ -240,7 +240,7 @@ apply_types(Msg) -> ). %% @doc Step 4: Group headers/query by N-scope. -%% `N.Key` => applies to Nth step. Otherwise => global +%% `N.Key' => applies to Nth step. Otherwise => `global' group_scoped(Map, Msgs) -> {NScope, Global} = maps:fold( @@ -312,8 +312,8 @@ parse_part(Part) -> end. %% @doc Parse part modifiers: -%% 1. `~Device` => {as, Device, Msg} -%% 2. `&K=V` => Msg#{ K => V } +%% 1. `~Device' => `{as, Device, Msg}' +%% 2. `&K=V' => `Msg#{ K => V }' parse_part_mods([], Msg) -> Msg; parse_part_mods(<<>>, Msg) -> Msg; parse_part_mods(<<"~", PartMods/binary>>, Msg) -> @@ -339,7 +339,7 @@ parse_part_mods(<< "&", InlinedMsgBin/binary >>, Msg) -> %% @doc Extrapolate the inlined key-value pair from a path segment. If the %% key has a value, it may provide a type (as with typical keys), but if a -%% value is not provided, it is assumed to be a boolean `true`. +%% value is not provided, it is assumed to be a boolean `true'. parse_inlined_key_val(Bin) -> case part([$=, $&], Bin) of {no_match, K, <<>>} -> {K, true}; diff --git a/src/hb_test_utils.erl b/src/hb_test_utils.erl index 25709c21..ca178ae7 100644 --- a/src/hb_test_utils.erl +++ b/src/hb_test_utils.erl @@ -7,9 +7,9 @@ %% @doc Run each test in a suite with each set of options. Start and reset %% the store(s) for each test. Expects suites to be a list of tuples with %% the test name, description, and test function. -%% The list of `Opts` should contain maps with the `name` and `opts` keys. -%% Each element may also contain a `skip` key with a list of test names to skip. -%% They can also contain a `desc` key with a description of the options. +%% The list of `Opts' should contain maps with the `name' and `opts' keys. +%% Each element may also contain a `skip' key with a list of test names to skip. +%% They can also contain a `desc' key with a description of the options. suite_with_opts(Suite, OptsList) -> lists:map( fun(OptSpec = #{ name := _Name, opts := Opts, desc := ODesc}) -> diff --git a/src/hb_util.erl b/src/hb_util.erl index ac50e21b..b99eb1c0 100644 --- a/src/hb_util.erl +++ b/src/hb_util.erl @@ -385,7 +385,7 @@ format_binary(Bin) -> lists:flatten(io_lib:format("~s", [ShortID])) end. -%% @doc Add `,` characters to a number every 3 digits to make it human readable. +%% @doc Add `,' characters to a number every 3 digits to make it human readable. human_int(Int) -> lists:reverse(add_commas(lists:reverse(integer_to_list(Int)))). From bce0db8a637a6256ac91cc1d6fee78b9114d9ae3 Mon Sep 17 00:00:00 2001 From: Tyler Hall Date: Mon, 10 Feb 2025 17:09:50 -0500 Subject: [PATCH 2/7] docs(core): generate edoc --- doc/ar_bundles.html | 218 +++++++++++++++++ doc/ar_deep_hash.html | 32 +++ doc/ar_http.html | 76 ++++++ doc/ar_http_sup.html | 41 ++++ doc/ar_rate_limiter.html | 91 +++++++ doc/ar_timestamp.html | 41 ++++ doc/ar_tx.html | 75 ++++++ doc/ar_wallet.html | 119 +++++++++ doc/dev_codec_ans104.html | 61 +++++ doc/dev_codec_flat.html | 72 ++++++ doc/dev_codec_httpsig.html | 104 ++++++++ doc/dev_codec_httpsig_conv.html | 68 ++++++ doc/dev_codec_structured.html | 80 ++++++ doc/dev_codec_structured_conv.html | 146 +++++++++++ doc/dev_compute_lite.html | 37 +++ doc/dev_cron.html | 46 ++++ doc/dev_cu.html | 39 +++ doc/dev_dedup.html | 37 +++ doc/dev_faff.html | 48 ++++ doc/dev_json_iface.html | 111 +++++++++ doc/dev_lookup.html | 35 +++ doc/dev_message.html | 160 ++++++++++++ doc/dev_meta.html | 59 +++++ doc/dev_monitor.html | 60 +++++ doc/dev_multipass.html | 36 +++ doc/dev_p4.html | 78 ++++++ doc/dev_poda.html | 55 +++++ doc/dev_process.html | 162 ++++++++++++ doc/dev_process_cache.html | 74 ++++++ doc/dev_process_worker.html | 54 ++++ doc/dev_relay.html | 60 +++++ doc/dev_router.html | 70 ++++++ doc/dev_scheduler.html | 111 +++++++++ doc/dev_scheduler_cache.html | 46 ++++ doc/dev_scheduler_formats.html | 48 ++++ doc/dev_scheduler_registry.html | 67 +++++ doc/dev_scheduler_server.html | 56 +++++ doc/dev_simple_pay.html | 66 +++++ doc/dev_snp.html | 80 ++++++ doc/dev_snp_nif.html | 60 +++++ doc/dev_stack.html | 160 ++++++++++++ doc/dev_test.html | 81 ++++++ doc/dev_wasi.html | 89 +++++++ doc/dev_wasm.html | 136 +++++++++++ doc/edoc-info | 19 ++ doc/erlang.png | Bin 0 -> 2109 bytes doc/hb.html | 288 ++++++++++++++++++++++ doc/hb_app.html | 41 ++++ doc/hb_beamr.html | 154 ++++++++++++ doc/hb_beamr_io.html | 103 ++++++++ doc/hb_cache.html | 128 ++++++++++ doc/hb_cache_control.html | 56 +++++ doc/hb_cache_render.html | 61 +++++ doc/hb_client.html | 70 ++++++ doc/hb_converge.html | 379 +++++++++++++++++++++++++++++ doc/hb_converge_test_vectors.html | 23 ++ doc/hb_crypto.html | 62 +++++ doc/hb_examples.html | 24 ++ doc/hb_http.html | 121 +++++++++ doc/hb_http_benchmark_tests.html | 20 ++ doc/hb_http_server.html | 96 ++++++++ doc/hb_logger.html | 60 +++++ doc/hb_message.html | 261 ++++++++++++++++++++ doc/hb_metrics_collector.html | 47 ++++ doc/hb_opts.html | 75 ++++++ doc/hb_path.html | 209 ++++++++++++++++ doc/hb_persistent.html | 117 +++++++++ doc/hb_private.html | 102 ++++++++ doc/hb_process_monitor.html | 53 ++++ doc/hb_router.html | 39 +++ doc/hb_singleton.html | 84 +++++++ doc/hb_store.html | 195 +++++++++++++++ doc/hb_store_fs.html | 112 +++++++++ doc/hb_store_remote_node.html | 53 ++++ doc/hb_store_rocksdb.html | 196 +++++++++++++++ doc/hb_sup.html | 47 ++++ doc/hb_test.html | 46 ++++ doc/hb_test_utils.html | 38 +++ doc/hb_util.html | 353 +++++++++++++++++++++++++++ doc/index.html | 17 ++ doc/modules-frame.html | 89 +++++++ doc/overview-summary.html | 16 ++ doc/rsa_pss.html | 77 ++++++ doc/stylesheet.css | 55 +++++ 84 files changed, 7431 insertions(+) create mode 100644 doc/ar_bundles.html create mode 100644 doc/ar_deep_hash.html create mode 100644 doc/ar_http.html create mode 100644 doc/ar_http_sup.html create mode 100644 doc/ar_rate_limiter.html create mode 100644 doc/ar_timestamp.html create mode 100644 doc/ar_tx.html create mode 100644 doc/ar_wallet.html create mode 100644 doc/dev_codec_ans104.html create mode 100644 doc/dev_codec_flat.html create mode 100644 doc/dev_codec_httpsig.html create mode 100644 doc/dev_codec_httpsig_conv.html create mode 100644 doc/dev_codec_structured.html create mode 100644 doc/dev_codec_structured_conv.html create mode 100644 doc/dev_compute_lite.html create mode 100644 doc/dev_cron.html create mode 100644 doc/dev_cu.html create mode 100644 doc/dev_dedup.html create mode 100644 doc/dev_faff.html create mode 100644 doc/dev_json_iface.html create mode 100644 doc/dev_lookup.html create mode 100644 doc/dev_message.html create mode 100644 doc/dev_meta.html create mode 100644 doc/dev_monitor.html create mode 100644 doc/dev_multipass.html create mode 100644 doc/dev_p4.html create mode 100644 doc/dev_poda.html create mode 100644 doc/dev_process.html create mode 100644 doc/dev_process_cache.html create mode 100644 doc/dev_process_worker.html create mode 100644 doc/dev_relay.html create mode 100644 doc/dev_router.html create mode 100644 doc/dev_scheduler.html create mode 100644 doc/dev_scheduler_cache.html create mode 100644 doc/dev_scheduler_formats.html create mode 100644 doc/dev_scheduler_registry.html create mode 100644 doc/dev_scheduler_server.html create mode 100644 doc/dev_simple_pay.html create mode 100644 doc/dev_snp.html create mode 100644 doc/dev_snp_nif.html create mode 100644 doc/dev_stack.html create mode 100644 doc/dev_test.html create mode 100644 doc/dev_wasi.html create mode 100644 doc/dev_wasm.html create mode 100644 doc/edoc-info create mode 100644 doc/erlang.png create mode 100644 doc/hb.html create mode 100644 doc/hb_app.html create mode 100644 doc/hb_beamr.html create mode 100644 doc/hb_beamr_io.html create mode 100644 doc/hb_cache.html create mode 100644 doc/hb_cache_control.html create mode 100644 doc/hb_cache_render.html create mode 100644 doc/hb_client.html create mode 100644 doc/hb_converge.html create mode 100644 doc/hb_converge_test_vectors.html create mode 100644 doc/hb_crypto.html create mode 100644 doc/hb_examples.html create mode 100644 doc/hb_http.html create mode 100644 doc/hb_http_benchmark_tests.html create mode 100644 doc/hb_http_server.html create mode 100644 doc/hb_logger.html create mode 100644 doc/hb_message.html create mode 100644 doc/hb_metrics_collector.html create mode 100644 doc/hb_opts.html create mode 100644 doc/hb_path.html create mode 100644 doc/hb_persistent.html create mode 100644 doc/hb_private.html create mode 100644 doc/hb_process_monitor.html create mode 100644 doc/hb_router.html create mode 100644 doc/hb_singleton.html create mode 100644 doc/hb_store.html create mode 100644 doc/hb_store_fs.html create mode 100644 doc/hb_store_remote_node.html create mode 100644 doc/hb_store_rocksdb.html create mode 100644 doc/hb_sup.html create mode 100644 doc/hb_test.html create mode 100644 doc/hb_test_utils.html create mode 100644 doc/hb_util.html create mode 100644 doc/index.html create mode 100644 doc/modules-frame.html create mode 100644 doc/overview-summary.html create mode 100644 doc/rsa_pss.html create mode 100644 doc/stylesheet.css diff --git a/doc/ar_bundles.html b/doc/ar_bundles.html new file mode 100644 index 00000000..74e4f6ff --- /dev/null +++ b/doc/ar_bundles.html @@ -0,0 +1,218 @@ + + + + +Module ar_bundles + + + +
Overviewerlang logo
+
+ +

Module ar_bundles

+ + + +

Function Index

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
data_item_signature_data/1Generate the data segment to be signed for a data item.
decode_tags/1Decode tags from a binary format using Apache Avro.
deserialize/1Convert binary data back to a #tx record.
deserialize/2
encode_tags/1Encode tags into a binary format using Apache Avro.
find/2Find an item in a bundle-map/list and return it.
format/1
format/2
hd/1Return the first item in a bundle-map/list.
id/1Return the ID of an item -- either signed or unsigned as specified.
id/2
is_signed/1Check if an item is signed.
manifest/1
manifest_item/1Return the manifest item in a bundle-map/list.
map/1Convert an item containing a map or list into an Erlang map.
member/2Check if an item exists in a bundle-map/list.
new_item/4Create a new data item.
normalize/1
parse_manifest/1
print/1Module for creating, signing, and verifying Arweave data items and bundles.
reset_ids/1Re-calculate both of the IDs for an item.
serialize/1Convert a #tx record to its binary representation.
serialize/2
sign_item/2Sign a data item.
signer/1Return the address of the signer of an item, if it is signed.
type/1
verify_item/1Verify the validity of a data item.
+ +

Function Details

+ +

data_item_signature_data/1

+
+

data_item_signature_data(RawItem) -> any()

+

+

Generate the data segment to be signed for a data item.

+ +

decode_tags/1

+
+

decode_tags(X1) -> any()

+

+

Decode tags from a binary format using Apache Avro.

+ +

deserialize/1

+
+

deserialize(Binary) -> any()

+

+

Convert binary data back to a #tx record.

+ +

deserialize/2

+
+

deserialize(Item, X2) -> any()

+

+
+ +

encode_tags/1

+
+

encode_tags(Tags) -> any()

+

+

Encode tags into a binary format using Apache Avro.

+ +

find/2

+
+

find(Key, Map) -> any()

+

+

Find an item in a bundle-map/list and return it.

+ +

format/1

+
+

format(Item) -> any()

+

+
+ +

format/2

+
+

format(Item, Indent) -> any()

+

+
+ +

hd/1

+
+

hd(Tx) -> any()

+

+

Return the first item in a bundle-map/list.

+ +

id/1

+
+

id(Item) -> any()

+

+

Return the ID of an item -- either signed or unsigned as specified. + If the item is unsigned and the user requests the signed ID, we return + the atom not_signed. In all other cases, we return the ID of the item.

+ +

id/2

+
+

id(Item, Type) -> any()

+

+
+ +

is_signed/1

+
+

is_signed(Item) -> any()

+

+

Check if an item is signed.

+ +

manifest/1

+
+

manifest(Map) -> any()

+

+
+ +

manifest_item/1

+
+

manifest_item(Tx) -> any()

+

+

Return the manifest item in a bundle-map/list.

+ +

map/1

+
+

map(Tx) -> any()

+

+

Convert an item containing a map or list into an Erlang map.

+ +

member/2

+
+

member(Key, Item) -> any()

+

+

Check if an item exists in a bundle-map/list.

+ +

new_item/4

+
+

new_item(Target, Anchor, Tags, Data) -> any()

+

+

Create a new data item. Should only be used for testing.

+ +

normalize/1

+
+

normalize(Item) -> any()

+

+
+ +

parse_manifest/1

+
+

parse_manifest(Item) -> any()

+

+
+ +

print/1

+
+

print(Item) -> any()

+

+

Module for creating, signing, and verifying Arweave data items and bundles.

+ +

reset_ids/1

+
+

reset_ids(Item) -> any()

+

+

Re-calculate both of the IDs for an item. This is a wrapper + function around update_id/1 that ensures both IDs are set from + scratch.

+ +

serialize/1

+
+

serialize(TX) -> any()

+

+

Convert a #tx record to its binary representation.

+ +

serialize/2

+
+

serialize(TX, X2) -> any()

+

+
+ +

sign_item/2

+
+

sign_item(RawItem, X2) -> any()

+

+

Sign a data item.

+ +

signer/1

+
+

signer(Tx) -> any()

+

+

Return the address of the signer of an item, if it is signed.

+ +

type/1

+
+

type(Item) -> any()

+

+
+ +

verify_item/1

+
+

verify_item(DataItem) -> any()

+

+

Verify the validity of a data item.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/ar_deep_hash.html b/doc/ar_deep_hash.html new file mode 100644 index 00000000..cfcbc313 --- /dev/null +++ b/doc/ar_deep_hash.html @@ -0,0 +1,32 @@ + + + + +Module ar_deep_hash + + + +
Overviewerlang logo
+
+ +

Module ar_deep_hash

+ + + +

Function Index

+ +
hash/1
+ +

Function Details

+ +

hash/1

+
+

hash(List) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/ar_http.html b/doc/ar_http.html new file mode 100644 index 00000000..8b2ad3ad --- /dev/null +++ b/doc/ar_http.html @@ -0,0 +1,76 @@ + + + + +Module ar_http + + + +
Overviewerlang logo
+
+ +

Module ar_http

+A wrapper library for gun. + +

Behaviours: gen_server.

+ +

Description

A wrapper library for gun. +

Function Index

+ + + + + + + +
handle_call/3
handle_cast/2
handle_info/2
init/1
req/2
start_link/1
terminate/2
+ +

Function Details

+ +

handle_call/3

+
+

handle_call(Request, From, State) -> any()

+

+
+ +

handle_cast/2

+
+

handle_cast(Cast, State) -> any()

+

+
+ +

handle_info/2

+
+

handle_info(Message, State) -> any()

+

+
+ +

init/1

+
+

init(Opts) -> any()

+

+
+ +

req/2

+
+

req(Args, Opts) -> any()

+

+
+ +

start_link/1

+
+

start_link(Opts) -> any()

+

+
+ +

terminate/2

+
+

terminate(Reason, State) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/ar_http_sup.html b/doc/ar_http_sup.html new file mode 100644 index 00000000..5438eb03 --- /dev/null +++ b/doc/ar_http_sup.html @@ -0,0 +1,41 @@ + + + + +Module ar_http_sup + + + +
Overviewerlang logo
+
+ +

Module ar_http_sup

+The supervisor for the gun HTTP client wrapper. + +

Behaviours: supervisor.

+ +

Description

The supervisor for the gun HTTP client wrapper. +

Function Index

+ + +
init/1
start_link/1
+ +

Function Details

+ +

init/1

+
+

init(Opts) -> any()

+

+
+ +

start_link/1

+
+

start_link(Opts) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/ar_rate_limiter.html b/doc/ar_rate_limiter.html new file mode 100644 index 00000000..513e5fad --- /dev/null +++ b/doc/ar_rate_limiter.html @@ -0,0 +1,91 @@ + + + + +Module ar_rate_limiter + + + +
Overviewerlang logo
+
+ +

Module ar_rate_limiter

+ + +

Behaviours: gen_server.

+ +

Function Index

+ + + + + + + + + +
handle_call/3
handle_cast/2
handle_info/2
init/1
off/0Turn rate limiting off.
on/0Turn rate limiting on.
start_link/1
terminate/2
throttle/3Hang until it is safe to make another request to the given Peer with the + given Path.
+ +

Function Details

+ +

handle_call/3

+
+

handle_call(Request, From, State) -> any()

+

+
+ +

handle_cast/2

+
+

handle_cast(Cast, State) -> any()

+

+
+ +

handle_info/2

+
+

handle_info(Message, State) -> any()

+

+
+ +

init/1

+
+

init(Opts) -> any()

+

+
+ +

off/0

+
+

off() -> any()

+

+

Turn rate limiting off.

+ +

on/0

+
+

on() -> any()

+

+

Turn rate limiting on.

+ +

start_link/1

+
+

start_link(Opts) -> any()

+

+
+ +

terminate/2

+
+

terminate(Reason, State) -> any()

+

+
+ +

throttle/3

+
+

throttle(Peer, Path, Opts) -> any()

+

+

Hang until it is safe to make another request to the given Peer with the + given Path. The limits are configured in include/ar_blacklist_middleware.hrl.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/ar_timestamp.html b/doc/ar_timestamp.html new file mode 100644 index 00000000..aa7389f0 --- /dev/null +++ b/doc/ar_timestamp.html @@ -0,0 +1,41 @@ + + + + +Module ar_timestamp + + + +
Overviewerlang logo
+
+ +

Module ar_timestamp

+ + + +

Function Index

+ + +
get/0Get the current timestamp from the server, starting the server if it + isn't already running.
start/0Check if the server is already running, and if not, start it.
+ +

Function Details

+ +

get/0

+
+

get() -> any()

+

+

Get the current timestamp from the server, starting the server if it + isn't already running.

+ +

start/0

+
+

start() -> any()

+

+

Check if the server is already running, and if not, start it.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/ar_tx.html b/doc/ar_tx.html new file mode 100644 index 00000000..8f635a6d --- /dev/null +++ b/doc/ar_tx.html @@ -0,0 +1,75 @@ + + + + +Module ar_tx + + + +
Overviewerlang logo
+
+ +

Module ar_tx

+The module with utilities for transaction creation, signing, and verification. + + +

Description

The module with utilities for transaction creation, signing, and verification. +

Function Index

+ + + + + + + +
json_struct_to_tx/1
new/4Create a new transaction.
new/5
sign/2Cryptographically sign (claim ownership of) a transaction.
tx_to_json_struct/1
verify/1Verify whether a transaction is valid.
verify_tx_id/2Verify the given transaction actually has the given identifier.
+ +

Function Details

+ +

json_struct_to_tx/1

+
+

json_struct_to_tx(TXStruct) -> any()

+

+
+ +

new/4

+
+

new(Dest, Reward, Qty, Last) -> any()

+

+

Create a new transaction.

+ +

new/5

+
+

new(Dest, Reward, Qty, Last, SigType) -> any()

+

+
+ +

sign/2

+
+

sign(TX, X2) -> any()

+

+

Cryptographically sign (claim ownership of) a transaction.

+ +

tx_to_json_struct/1

+
+

tx_to_json_struct(Tx) -> any()

+

+
+ +

verify/1

+
+

verify(TX) -> any()

+

+

Verify whether a transaction is valid.

+ +

verify_tx_id/2

+
+

verify_tx_id(ExpectedID, Tx) -> any()

+

+

Verify the given transaction actually has the given identifier.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/ar_wallet.html b/doc/ar_wallet.html new file mode 100644 index 00000000..6b0765b7 --- /dev/null +++ b/doc/ar_wallet.html @@ -0,0 +1,119 @@ + + + + +Module ar_wallet + + + +
Overviewerlang logo
+
+ +

Module ar_wallet

+ + + +

Function Index

+ + + + + + + + + + + + + +
hmac/1
hmac/2
load_key/1Read the keyfile for the key with the given address from disk.
load_keyfile/1Extract the public and private key from a keyfile.
new/0Utilities for manipulating wallets.
new/1
new_keyfile/2Generate a new wallet public and private key, with a corresponding keyfile.
sign/2Sign some data with a private key.
sign/3sign some data, hashed using the provided DigestType.
to_address/1Generate an address from a public key.
to_address/2
verify/3Verify that a signature is correct.
verify/4
+ +

Function Details

+ +

hmac/1

+
+

hmac(Data) -> any()

+

+
+ +

hmac/2

+
+

hmac(Data, DigestType) -> any()

+

+
+ +

load_key/1

+
+

load_key(Addr) -> any()

+

+

Read the keyfile for the key with the given address from disk. + Return not_found if arweave_keyfile_[addr].json or [addr].json is not found + in [data_dir]/?WALLET_DIR.

+ +

load_keyfile/1

+
+

load_keyfile(File) -> any()

+

+

Extract the public and private key from a keyfile.

+ +

new/0

+
+

new() -> any()

+

+

Utilities for manipulating wallets.

+ +

new/1

+
+

new(KeyType) -> any()

+

+
+ +

new_keyfile/2

+
+

new_keyfile(KeyType, WalletName) -> any()

+

+

Generate a new wallet public and private key, with a corresponding keyfile. + The provided key is used as part of the file name.

+ +

sign/2

+
+

sign(Key, Data) -> any()

+

+

Sign some data with a private key.

+ +

sign/3

+
+

sign(X1, Data, DigestType) -> any()

+

+

sign some data, hashed using the provided DigestType.

+ +

to_address/1

+
+

to_address(Pubkey) -> any()

+

+

Generate an address from a public key.

+ +

to_address/2

+
+

to_address(PubKey, X2) -> any()

+

+
+ +

verify/3

+
+

verify(Key, Data, Sig) -> any()

+

+

Verify that a signature is correct.

+ +

verify/4

+
+

verify(X1, Data, Sig, DigestType) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_codec_ans104.html b/doc/dev_codec_ans104.html new file mode 100644 index 00000000..5fb28dd6 --- /dev/null +++ b/doc/dev_codec_ans104.html @@ -0,0 +1,61 @@ + + + + +Module dev_codec_ans104 + + + +
Overviewerlang logo
+
+ +

Module dev_codec_ans104

+Codec for managing transformations from ar_bundles-style Arweave TX + records to and from TABMs. + + +

Description

Codec for managing transformations from ar_bundles-style Arweave TX + records to and from TABMs. +

Function Index

+ + + + +
attest/3Sign a message using the priv_wallet key in the options.
from/1Convert a #tx record into a message map recursively.
to/1Internal helper to translate a message to its #tx record representation, + which can then be used by ar_bundles to serialize the message.
verify/3Verify an ANS-104 attestation.
+ +

Function Details

+ +

attest/3

+
+

attest(Msg, Req, Opts) -> any()

+

+

Sign a message using the priv_wallet key in the options.

+ +

from/1

+
+

from(Binary) -> any()

+

+

Convert a #tx record into a message map recursively.

+ +

to/1

+
+

to(Binary) -> any()

+

+

Internal helper to translate a message to its #tx record representation, + which can then be used by ar_bundles to serialize the message. We call the + message's device in order to get the keys that we will be checkpointing. We + do this recursively to handle nested messages. The base case is that we hit + a binary, which we return as is.

+ +

verify/3

+
+

verify(Msg, Req, Opts) -> any()

+

+

Verify an ANS-104 attestation.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_codec_flat.html b/doc/dev_codec_flat.html new file mode 100644 index 00000000..4665988f --- /dev/null +++ b/doc/dev_codec_flat.html @@ -0,0 +1,72 @@ + + + + +Module dev_codec_flat + + + +
Overviewerlang logo
+
+ +

Module dev_codec_flat

+A codec for turning TABMs into/from flat Erlang maps that have + (potentially multi-layer) paths as their keys, and a normal TABM binary as + their value. + + +

Description

A codec for turning TABMs into/from flat Erlang maps that have + (potentially multi-layer) paths as their keys, and a normal TABM binary as + their value. +

Function Index

+ + + + + + +
attest/3
deserialize/1
from/1Convert a flat map to a TABM.
serialize/1
to/1Convert a TABM to a flat map.
verify/3
+ +

Function Details

+ +

attest/3

+
+

attest(Msg, Req, Opts) -> any()

+

+
+ +

deserialize/1

+
+

deserialize(Bin) -> any()

+

+
+ +

from/1

+
+

from(Bin) -> any()

+

+

Convert a flat map to a TABM.

+ +

serialize/1

+
+

serialize(Map) -> any()

+

+
+ +

to/1

+
+

to(Bin) -> any()

+

+

Convert a TABM to a flat map.

+ +

verify/3

+
+

verify(Msg, Req, Opts) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_codec_httpsig.html b/doc/dev_codec_httpsig.html new file mode 100644 index 00000000..475a72b9 --- /dev/null +++ b/doc/dev_codec_httpsig.html @@ -0,0 +1,104 @@ + + + + +Module dev_codec_httpsig + + + +
Overviewerlang logo
+
+ +

Module dev_codec_httpsig

+This module implements HTTP Message Signatures as described in RFC-9421 + (https://datatracker.ietf.org/doc/html/rfc9421), as a Converge device. + + +

Description

This module implements HTTP Message Signatures as described in RFC-9421 + (https://datatracker.ietf.org/doc/html/rfc9421), as a Converge device. + It implements the codec standard (from/1, to/1), as well as the optional + attestation functions (id/3, sign/3, verify/3). The attestation functions + are found in this module, while the codec functions are relayed to the + dev_codec_httpsig_conv module. +

Function Index

+ + + + + + + + + + +
add_content_digest/1If the body key is present, replace it with a content-digest.
add_derived_specifiers/1Normalize key parameters to ensure their names are correct.
attest/3Main entrypoint for signing a HTTP Message, using the standardized format.
from/1
id/3
public_keys/1
remove_derived_specifiers/1Remove derived specifiers from a list of component identifiers.
reset_hmac/1Ensure that the attestations and hmac are properly encoded.
to/1
verify/3Verify different forms of httpsig attested messages.
+ +

Function Details

+ +

add_content_digest/1

+
+

add_content_digest(Msg) -> any()

+

+

If the body key is present, replace it with a content-digest.

+ +

add_derived_specifiers/1

+
+

add_derived_specifiers(ComponentIdentifiers) -> any()

+

+

Normalize key parameters to ensure their names are correct.

+ +

attest/3

+
+

attest(MsgToSign, Req, Opts) -> any()

+

+

Main entrypoint for signing a HTTP Message, using the standardized format.

+ +

from/1

+
+

from(Msg) -> any()

+

+
+ +

id/3

+
+

id(Msg, Params, Opts) -> any()

+

+
+ +

public_keys/1

+
+

public_keys(Attestation) -> any()

+

+
+ +

remove_derived_specifiers/1

+
+

remove_derived_specifiers(ComponentIdentifiers) -> any()

+

+

Remove derived specifiers from a list of component identifiers.

+ +

reset_hmac/1

+
+

reset_hmac(RawMsg) -> any()

+

+

Ensure that the attestations and hmac are properly encoded

+ +

to/1

+
+

to(Msg) -> any()

+

+
+ +

verify/3

+
+

verify(MsgToVerify, Req, Opts) -> any()

+

+

Verify different forms of httpsig attested messages. dev_message:verify + already places the keys from the attestation message into the root of the + message.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_codec_httpsig_conv.html b/doc/dev_codec_httpsig_conv.html new file mode 100644 index 00000000..fe226e2f --- /dev/null +++ b/doc/dev_codec_httpsig_conv.html @@ -0,0 +1,68 @@ + + + + +Module dev_codec_httpsig_conv + + + +
Overviewerlang logo
+
+ +

Module dev_codec_httpsig_conv

+A codec for the that marshals TABM encoded messages to and from the +"HTTP" message structure. + + +

Description

A codec for the that marshals TABM encoded messages to and from the +"HTTP" message structure.

+ +

Every HTTP message is an HTTP multipart message. +See https://datatracker.ietf.org/doc/html/rfc7578

+ +

For each TABM Key:

+ +

The Key/Value Pair will be encoded according to the following rules: +"signatures" -> {SignatureInput, Signature} header Tuples, each encoded +as a Structured Field Dictionary +"body" -> +- if a map, then recursively encode as its own HyperBEAM message +- otherwise encode as a normal field +_ -> encode as a normal field

+ + Each field will be mapped to the HTTP Message according to the following + rules: + "body" -> always encoded part of the body as with Content-Disposition + type of "inline" + _ -> + - If the byte size of the value is less than the ?MAX_TAG_VALUE, + then encode as a header, also attempting to encode as a + structured field. + - Otherwise encode the value as a part in the multipart response + +

Function Index

+ + +
from/1Convert an HTTP Message into a TABM.
to/1Convert a TABM into an HTTP Message.
+ +

Function Details

+ +

from/1

+
+

from(Bin) -> any()

+

+

Convert an HTTP Message into a TABM. + HTTP Structured Field is encoded into it's equivalent TABM encoding.

+ +

to/1

+
+

to(Bin) -> any()

+

+

Convert a TABM into an HTTP Message. The HTTP Message is a simple Erlang Map + that can translated to a given web server Response API

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_codec_structured.html b/doc/dev_codec_structured.html new file mode 100644 index 00000000..463634dc --- /dev/null +++ b/doc/dev_codec_structured.html @@ -0,0 +1,80 @@ + + + + +Module dev_codec_structured + + + +
Overviewerlang logo
+
+ +

Module dev_codec_structured

+A device implementing the codec interface (to/1, from/1) for +HyperBEAM's internal, richly typed message format. + + +

Description

A device implementing the codec interface (to/1, from/1) for +HyperBEAM's internal, richly typed message format.

+ +

This format mirrors HTTP Structured Fields, aside from its limitations of +compound type depths, as well as limited floating point representations.

+ +

As with all Converge codecs, its target format (the format it expects to + receive in the to/1 function, and give in from/1) is TABM.

+ + For more details, see the HTTP Structured Fields (RFC-9651) specification. +

Function Index

+ + + + + + +
attest/3
decode_value/2Convert non-binary values to binary for serialization.
encode_value/1Convert a term to a binary representation, emitting its type for + serialization as a separate tag.
from/1Convert a rich message into a 'Type-Annotated-Binary-Message' (TABM).
to/1Convert a TABM into a native HyperBEAM message.
verify/3
+ +

Function Details

+ +

attest/3

+
+

attest(Msg, Req, Opts) -> any()

+

+
+ +

decode_value/2

+
+

decode_value(Type, Value) -> any()

+

+

Convert non-binary values to binary for serialization.

+ +

encode_value/1

+
+

encode_value(Value) -> any()

+

+

Convert a term to a binary representation, emitting its type for + serialization as a separate tag.

+ +

from/1

+
+

from(Bin) -> any()

+

+

Convert a rich message into a 'Type-Annotated-Binary-Message' (TABM).

+ +

to/1

+
+

to(Bin) -> any()

+

+

Convert a TABM into a native HyperBEAM message.

+ +

verify/3

+
+

verify(Msg, Req, Opts) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_codec_structured_conv.html b/doc/dev_codec_structured_conv.html new file mode 100644 index 00000000..1bd78e01 --- /dev/null +++ b/doc/dev_codec_structured_conv.html @@ -0,0 +1,146 @@ + + + + +Module dev_codec_structured_conv + + + +
Overviewerlang logo
+
+ +

Module dev_codec_structured_conv

+ + + +

Data Types

+ +

sh_bare_item()

+

sh_bare_item() = integer() | sh_decimal() | boolean() | {string | token | binary, binary()}

+ + +

sh_decimal()

+

sh_decimal() = {decimal, {integer(), integer()}}

+ + +

sh_dictionary()

+

sh_dictionary() = [{binary(), sh_item() | sh_inner_list()}]

+ + +

sh_inner_list()

+

sh_inner_list() = {list, [sh_item()], sh_params()}

+ + +

sh_item()

+

sh_item() = {item, sh_bare_item(), sh_params()}

+ + +

sh_list()

+

sh_list() = [sh_item() | sh_inner_list()]

+ + +

sh_params()

+

sh_params() = [{binary(), sh_bare_item()}]

+ + +

Function Index

+ + + + + + + + + + + + + +
bare_item/1
dictionary/1
from_bare_item/1
item/1
list/1
parse_bare_item/1
parse_dictionary/1
parse_item/1
parse_list/1
to_dictionary/1
to_item/1
to_item/2
to_list/1
+ +

Function Details

+ +

bare_item/1

+
+

bare_item(Integer) -> any()

+

+
+ +

dictionary/1

+
+

dictionary(Map::#{binary() => sh_item() | sh_inner_list()} | sh_dictionary()) -> iolist()

+

+
+ +

from_bare_item/1

+
+

from_bare_item(BareItem) -> any()

+

+
+ +

item/1

+
+

item(X1::sh_item()) -> iolist()

+

+
+ +

list/1

+
+

list(List::sh_list()) -> iolist()

+

+
+ +

parse_bare_item/1

+
+

parse_bare_item(X1) -> any()

+

+
+ +

parse_dictionary/1

+
+

parse_dictionary(X1::binary()) -> sh_dictionary()

+

+
+ +

parse_item/1

+
+

parse_item(Bin::binary()) -> sh_item()

+

+
+ +

parse_list/1

+
+

parse_list(Bin::binary()) -> sh_list()

+

+
+ +

to_dictionary/1

+
+

to_dictionary(Map) -> any()

+

+
+ +

to_item/1

+
+

to_item(Item) -> any()

+

+
+ +

to_item/2

+
+

to_item(Item, Params) -> any()

+

+
+ +

to_list/1

+
+

to_list(List) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_compute_lite.html b/doc/dev_compute_lite.html new file mode 100644 index 00000000..c46b2cde --- /dev/null +++ b/doc/dev_compute_lite.html @@ -0,0 +1,37 @@ + + + + +Module dev_compute_lite + + + +
Overviewerlang logo
+
+ +

Module dev_compute_lite

+Simple wrapper module that enables compute on remote machines, + implementing the JSON-Iface. + + +

Description

Simple wrapper module that enables compute on remote machines, + implementing the JSON-Iface. This can be used either as a standalone, to + bring trusted results into the local node, or as the Execution-Device of + an AO process. +

Function Index

+ +
compute/3
+ +

Function Details

+ +

compute/3

+
+

compute(Msg1, Msg2, Opts) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_cron.html b/doc/dev_cron.html new file mode 100644 index 00000000..329a16f8 --- /dev/null +++ b/doc/dev_cron.html @@ -0,0 +1,46 @@ + + + + +Module dev_cron + + + +
Overviewerlang logo
+
+ +

Module dev_cron

+ + + +

Function Index

+ + + +
execute/2
init/2
uses/0
+ +

Function Details

+ +

execute/2

+
+

execute(M, State) -> any()

+

+
+ +

init/2

+
+

init(State, Params) -> any()

+

+
+ +

uses/0

+
+

uses() -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_cu.html b/doc/dev_cu.html new file mode 100644 index 00000000..3896b363 --- /dev/null +++ b/doc/dev_cu.html @@ -0,0 +1,39 @@ + + + + +Module dev_cu + + + +
Overviewerlang logo
+
+ +

Module dev_cu

+ + + +

Function Index

+ + +
execute/2
push/2
+ +

Function Details

+ +

execute/2

+
+

execute(CarrierMsg, S) -> any()

+

+
+ +

push/2

+
+

push(Msg, S) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_dedup.html b/doc/dev_dedup.html new file mode 100644 index 00000000..ce8f1b28 --- /dev/null +++ b/doc/dev_dedup.html @@ -0,0 +1,37 @@ + + + + +Module dev_dedup + + + +
Overviewerlang logo
+
+ +

Module dev_dedup

+A device that deduplicates messages send to a process. + + +

Description

A device that deduplicates messages send to a process. + Only runs on the first pass of the compute key call if executed + in a stack. Currently the device stores its list of already seen + items in memory, but at some point it will likely make sense to + drop them in the cache. +

Function Index

+ +
info/1
+ +

Function Details

+ +

info/1

+
+

info(M1) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_faff.html b/doc/dev_faff.html new file mode 100644 index 00000000..3f914d1f --- /dev/null +++ b/doc/dev_faff.html @@ -0,0 +1,48 @@ + + + + +Module dev_faff + + + +
Overviewerlang logo
+
+ +

Module dev_faff

+A module that implements a 'friends and family' pricing policy. + + +

Description

A module that implements a 'friends and family' pricing policy. +It will allow users to process requests only if their addresses are +in the allow-list for the node.

+ + Fundamentally against the spirit of permissionlessness, but it is useful if + you are running a node for your own purposes and would not like to allow + others to make use of it -- even for a fee. It also serves as a useful + example of how to implement a custom pricing policy, as it implements stubs + for both the pricing and ledger P4 APIs. +

Function Index

+ + +
debit/3Debit the user's account if the request is allowed.
estimate/3Decide whether or not to service a request from a given address.
+ +

Function Details

+ +

debit/3

+
+

debit(X1, Req, NodeMsg) -> any()

+

+

Debit the user's account if the request is allowed.

+ +

estimate/3

+
+

estimate(X1, Msg, NodeMsg) -> any()

+

+

Decide whether or not to service a request from a given address.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_json_iface.html b/doc/dev_json_iface.html new file mode 100644 index 00000000..1b67202b --- /dev/null +++ b/doc/dev_json_iface.html @@ -0,0 +1,111 @@ + + + + +Module dev_json_iface + + + +
Overviewerlang logo
+
+ +

Module dev_json_iface

+A device that provides a way for WASM execution to interact with +the HyperBEAM (and AO) systems, using JSON as a shared data representation. + + +

Description

A device that provides a way for WASM execution to interact with +the HyperBEAM (and AO) systems, using JSON as a shared data representation.

+ +

The interface is easy to use. It works as follows:

+ +

1. The device is given a message that contains a process definition, WASM + environment, and a message that contains the data to be processed, + including the image to be used in part of execute{pass=1}. + 2. The device is called with execute{pass=2}, which reads the result of +the process execution from the WASM environment and adds it to the +message.

+ + The device has the following requirements and interface: + 
       M1/Computed when /Pass == 1 ->
+           Assumes:
+               M1/priv/wasm/instance
+               M1/Process
+               M2/Message
+               M2/Assignment/Block-Height
+           Generates:
+               /wasm/handler
+               /wasm/params
+           Side-effects:
+               Writes the process and message as JSON representations into the
+               WASM environment.
+  
+       M1/Computed when M2/Pass == 2 ->
+           Assumes:
+               M1/priv/wasm/instance
+               M2/Results
+               M2/Process
+           Generates:
+               /Results/Outbox
+               /Results/Data
+

Function Index

+ + + + + + + +
compute/3On first pass prepare the call, on second pass get the results.
generate_aos_msg/2
generate_stack/1
generate_stack/2
init/3Initialize the device.
json_to_message/2Translates a compute result -- either from a WASM execution using the + JSON-Iface, or from a Legacy CU -- and transforms it into a result message.
message_to_json_struct/1
+ +

Function Details

+ +

compute/3

+
+

compute(M1, M2, Opts) -> any()

+

+

On first pass prepare the call, on second pass get the results.

+ +

generate_aos_msg/2

+
+

generate_aos_msg(ProcID, Code) -> any()

+

+
+ +

generate_stack/1

+
+

generate_stack(File) -> any()

+

+
+ +

generate_stack/2

+
+

generate_stack(File, Mode) -> any()

+

+
+ +

init/3

+
+

init(M1, M2, Opts) -> any()

+

+

Initialize the device.

+ +

json_to_message/2

+
+

json_to_message(JSON, Opts) -> any()

+

+

Translates a compute result -- either from a WASM execution using the + JSON-Iface, or from a Legacy CU -- and transforms it into a result message.

+ +

message_to_json_struct/1

+
+

message_to_json_struct(RawMsg) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_lookup.html b/doc/dev_lookup.html new file mode 100644 index 00000000..839cdb39 --- /dev/null +++ b/doc/dev_lookup.html @@ -0,0 +1,35 @@ + + + + +Module dev_lookup + + + +
Overviewerlang logo
+
+ +

Module dev_lookup

+A device that looks up an ID from a local store and returns it, honoring + the accept key to return the correct format. + + +

Description

A device that looks up an ID from a local store and returns it, honoring + the accept key to return the correct format. +

Function Index

+ +
read/3
+ +

Function Details

+ +

read/3

+
+

read(M1, M2, Opts) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_message.html b/doc/dev_message.html new file mode 100644 index 00000000..4d15d40d --- /dev/null +++ b/doc/dev_message.html @@ -0,0 +1,160 @@ + + + + +Module dev_message + + + +
Overviewerlang logo
+
+ +

Module dev_message

+The identity device: For non-reserved keys, it simply returns a key + from the message as it is found in the message's underlying Erlang map. + + +

Description

The identity device: For non-reserved keys, it simply returns a key + from the message as it is found in the message's underlying Erlang map. + Private keys (priv[.*]) are not included. + Reserved keys are: id, attestations, attestors, keys, path, + set, remove, get, and verify. Their function comments describe the + behaviour of the device when these keys are set. +

Function Index

+ + + + + + + + + + + + + + + +
attest/3Attest to a message, using the attestation-device key to specify the + device that should be used to attest to the message.
attestors/1Return the attestors of a message that are present in the given request.
attestors/2
attestors/3
get/2Return the value associated with the key as it exists in the message's + underlying Erlang map.
get/3
id/1Return the ID of a message, using the attestors list if it exists.
id/2
id/3
info/0Return the info for the identity device.
keys/1Get the public keys of a message.
remove/2Remove a key or keys from a message.
set/3Set keys in a message.
set_path/3Special case of set/3 for setting the path key.
verify/3Verify a message nested in the body.
+ +

Function Details

+ +

attest/3

+
+

attest(Self, Req, Opts) -> any()

+

+

Attest to a message, using the attestation-device key to specify the + device that should be used to attest to the message. If the key is not set, + the default device (httpsig@1.0) is used.

+ +

attestors/1

+
+

attestors(Base) -> any()

+

+

Return the attestors of a message that are present in the given request.

+ +

attestors/2

+
+

attestors(Base, Req) -> any()

+

+
+ +

attestors/3

+
+

attestors(Base, X2, NodeOpts) -> any()

+

+
+ +

get/2

+
+

get(Key, Msg) -> any()

+

+

Return the value associated with the key as it exists in the message's + underlying Erlang map. First check the public keys, then check case- + insensitively if the key is a binary.

+ +

get/3

+
+

get(Key, Msg, Msg2) -> any()

+

+
+ +

id/1

+
+

id(Base) -> any()

+

+

Return the ID of a message, using the attestors list if it exists. + If the attestors key is all, return the ID including all known + attestations -- none yields the ID without any attestations. If the + attestors key is a list/map, return the ID including only the specified +attestations.

+ +

The id-device key in the message can be used to specify the device that + should be used to calculate the ID. If it is not set, the default device + (httpsig@1.0) is used.

+ + Note: This function _does not_ use Converge's get/3 function, as it + as it would require significant computation. We may want to change this + if/when non-map message structures are created.

+ +

id/2

+
+

id(Base, Req) -> any()

+

+
+ +

id/3

+
+

id(Base, Req, NodeOpts) -> any()

+

+
+ +

info/0

+
+

info() -> any()

+

+

Return the info for the identity device.

+ +

keys/1

+
+

keys(Msg) -> any()

+

+

Get the public keys of a message.

+ +

remove/2

+
+

remove(Message1, X2) -> any()

+

+

Remove a key or keys from a message.

+ +

set/3

+
+

set(Message1, NewValuesMsg, Opts) -> any()

+

+

Set keys in a message. Takes a map of key-value pairs and sets them in + the message, overwriting any existing values.

+ +

set_path/3

+
+

set_path(Message1, X2, Opts) -> any()

+

+

Special case of set/3 for setting the path key. This cannot be set + using the normal set function, as the path is a reserved key, necessary + for Converge to know the key to evaluate in requests.

+ +

verify/3

+
+

verify(Self, Req, Opts) -> any()

+

+

Verify a message nested in the body. As with id, the attestors + key in the request can be used to specify which attestations should be + verified.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_meta.html b/doc/dev_meta.html new file mode 100644 index 00000000..f26ac81a --- /dev/null +++ b/doc/dev_meta.html @@ -0,0 +1,59 @@ + + + + +Module dev_meta + + + +
Overviewerlang logo
+
+ +

Module dev_meta

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

Description

The hyperbeam meta device, which is the default entry point + for all messages processed by the machine. This device executes a + Converge 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 Converge + resolver. Additionally, a post-processor can be set, which is executed after + the Converge resolver has returned a result. +

Function Index

+ + + +
all_attestors/1Return the signers of a list of messages.
handle/2Normalize and route messages downstream based on their path.
info/3Get/set the node message.
+ +

Function Details

+ +

all_attestors/1

+
+

all_attestors(Msgs) -> any()

+

+

Return the signers of a list of messages.

+ +

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_converge/2 function.

+ +

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).

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_monitor.html b/doc/dev_monitor.html new file mode 100644 index 00000000..db8bee88 --- /dev/null +++ b/doc/dev_monitor.html @@ -0,0 +1,60 @@ + + + + +Module dev_monitor + + + +
Overviewerlang logo
+
+ +

Module dev_monitor

+ + + +

Function Index

+ + + + + +
add_monitor/2
end_of_schedule/1
execute/2
init/3
uses/0
+ +

Function Details

+ +

add_monitor/2

+
+

add_monitor(Mon, State) -> any()

+

+
+ +

end_of_schedule/1

+
+

end_of_schedule(State) -> any()

+

+
+ +

execute/2

+
+

execute(Message, State) -> any()

+

+
+ +

init/3

+
+

init(State, X2, InitState) -> any()

+

+
+ +

uses/0

+
+

uses() -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_multipass.html b/doc/dev_multipass.html new file mode 100644 index 00000000..4888b6ac --- /dev/null +++ b/doc/dev_multipass.html @@ -0,0 +1,36 @@ + + + + +Module dev_multipass + + + +
Overviewerlang logo
+
+ +

Module dev_multipass

+A device that triggers repass events until a certain counter has been + reached. + + +

Description

A device that triggers repass events until a certain counter has been + reached. This is useful for certain types of stacks that need various + execution passes to be completed in sequence across devices. +

Function Index

+ +
info/1
+ +

Function Details

+ +

info/1

+
+

info(M1) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_p4.html b/doc/dev_p4.html new file mode 100644 index 00000000..126ce2c8 --- /dev/null +++ b/doc/dev_p4.html @@ -0,0 +1,78 @@ + + + + +Module dev_p4 + + + +
Overviewerlang logo
+
+ +

Module dev_p4

+The HyperBEAM core payment ledger. + + +

Description

The HyperBEAM core payment ledger. This module allows the operator to +specify another device that can act as a pricing mechanism for transactions +on the node, as well as orchestrating a payment ledger to calculate whether +the node should fulfil services for users.

+ +

The device requires the following node message settings in order to function:

+ +

- p4_pricing_device: The device that will estimate the cost of a request. + - p4_ledger_device: The device that will act as a payment ledger.

+ + The pricing device should implement the following keys: + 
               GET /estimate?type=pre|post&body=[...]&request=RequestMessage
+               GET /price?type=pre|post&body=[...]&request=RequestMessage
+ +

The body key is used to pass either the request or response messages to the + device. The type key is used to specify whether the inquiry is for a request + (pre) or a response (post) object. Requests carry lists of messages that will + be executed, while responses carry the results of the execution. The price + key may return infinity if the node will not serve a user under any + circumstances. Else, the value returned by the price key will be passed to + the ledger device as the amount key.

+ + The ledger device should implement the following keys: + 
               POST /credit?message=PaymentMessage&request=RequestMessage
+               POST /debit?amount=PriceMessage&type=pre|post&request=RequestMessage
+ + The type key is optional and defaults to pre. If type is set to post, + the debit must be applied to the ledger, whereas the pre type is used to + check whether the debit would succeed before execution. +

Function Index

+ + + +
balance/3Get the balance of a user in the ledger.
postprocess/3Postprocess the request after it has been fulfilled.
preprocess/3Estimate the cost of a transaction and decide whether to proceed with + a request.
+ +

Function Details

+ +

balance/3

+
+

balance(X1, Req, NodeMsg) -> any()

+

+

Get the balance of a user in the ledger.

+ +

postprocess/3

+
+

postprocess(State, RawResponse, NodeMsg) -> any()

+

+

Postprocess the request after it has been fulfilled.

+ +

preprocess/3

+
+

preprocess(State, Raw, NodeMsg) -> any()

+

+

Estimate the cost of a transaction and decide whether to proceed with + a request. The default behavior if pricing_device or p4_balances are + not set is to proceed, so it is important that a user initialize them.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_poda.html b/doc/dev_poda.html new file mode 100644 index 00000000..14265a07 --- /dev/null +++ b/doc/dev_poda.html @@ -0,0 +1,55 @@ + + + + +Module dev_poda + + + +
Overviewerlang logo
+
+ +

Module dev_poda

+ + + +

Function Index

+ + + + +
execute/3
init/2
is_user_signed/1
push/2Hook used by the MU pathway (currently) to add attestations to an + outbound message if the computation requests it.
+ +

Function Details

+ +

execute/3

+
+

execute(Outer, S, Opts) -> any()

+

+
+ +

init/2

+
+

init(S, Params) -> any()

+

+
+ +

is_user_signed/1

+
+

is_user_signed(Tx) -> any()

+

+
+ +

push/2

+
+

push(Item, S) -> any()

+

+

Hook used by the MU pathway (currently) to add attestations to an + outbound message if the computation requests it.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_process.html b/doc/dev_process.html new file mode 100644 index 00000000..c6cbc9b5 --- /dev/null +++ b/doc/dev_process.html @@ -0,0 +1,162 @@ + + + + +Module dev_process + + + +
Overviewerlang logo
+
+ +

Module dev_process

+This module contains the device implementation of AO processes +in Converge. + + +

Description

This module contains the device implementation of AO processes +in Converge. The core functionality of the module is in 'routing' requests +for different functionality (scheduling, computing, and pushing messages) +to the appropriate device. This is achieved by swapping out the device +of the process message with the necessary component in order to run the +execution, then swapping it back before returning. Computation is supported +as a stack of devices, customizable by the user, while the scheduling +device is (by default) a single device.

+ +

This allows the devices to share state as needed. Additionally, after each + computation step the device caches the result at a path relative to the + process definition itself, such that the process message's ID can act as an + immutable reference to the process's growing list of interactions. See + dev_process_cache for details.

+ + The external API of the device is as follows: + 
   GET /ID/Schedule:                Returns the messages in the schedule
+   POST /ID/Schedule:               Adds a message to the schedule
+  
+   GET /ID/Compute/[IDorSlotNum]:   Returns the state of the process after
+                                    applying a message
+   GET /ID/Now:                     Returns the `/Results' key of the latest
+                                    computed message
+ + An example process definition will look like this: + 
       Device: Process/1.0
+       Scheduler-Device: Scheduler/1.0
+       Execution-Device: Stack/1.0
+       Execution-Stack: "Scheduler/1.0", "Cron/1.0", "WASM/1.0", "PoDA/1.0"
+       Cron-Frequency: 10-Minutes
+       WASM-Image: WASMImageID
+       PoDA:
+           Device: PoDA/1.0
+           Authority: A
+           Authority: B
+           Authority: C
+           Quorum: 2
+ + Runtime options: + Cache-Frequency: The number of assignments that will be computed + before the full (restorable) state should be cached. + Cache-Keys: A list of the keys that should be cached for all + assignments, in addition to /Results. +

Function Index

+ + + + + + + + + + + + +
compute/3Compute the result of an assignment applied to the process state, if it + is the next message.
dev_test_process/0Generate a device that has a stack of two dev_tests for + execution.
do_test_restore/0
ensure_process_key/2Helper function to store a copy of the process key in the message.
info/1When the info key is called, we should return the process exports.
now/3Returns the /Results key of the latest computed message.
push/3Recursively push messages to the scheduler until we find a message + that does not lead to any further messages being scheduled.
schedule/3Wraps functions in the Scheduler device.
slot/3
snapshot/3
test_aos_process/0Generate a process message with a random number, and the + dev_wasm device for execution.
test_wasm_process/1
+ +

Function Details

+ +

compute/3

+
+

compute(Msg1, Msg2, Opts) -> any()

+

+

Compute the result of an assignment applied to the process state, if it + is the next message.

+ +

dev_test_process/0

+
+

dev_test_process() -> any()

+

+

Generate a device that has a stack of two dev_tests for + execution. This should generate a message state has doubled + Already-Seen elements for each assigned slot.

+ +

do_test_restore/0

+
+

do_test_restore() -> any()

+

+
+ +

ensure_process_key/2

+
+

ensure_process_key(Msg1, Opts) -> any()

+

+

Helper function to store a copy of the process key in the message.

+ +

info/1

+
+

info(Msg1) -> any()

+

+

When the info key is called, we should return the process exports.

+ +

now/3

+
+

now(RawMsg1, Msg2, Opts) -> any()

+

+

Returns the /Results key of the latest computed message.

+ +

push/3

+
+

push(Msg1, Msg2, Opts) -> any()

+

+

Recursively push messages to the scheduler until we find a message + that does not lead to any further messages being scheduled.

+ +

schedule/3

+
+

schedule(Msg1, Msg2, Opts) -> any()

+

+

Wraps functions in the Scheduler device.

+ +

slot/3

+
+

slot(Msg1, Msg2, Opts) -> any()

+

+
+ +

snapshot/3

+
+

snapshot(RawMsg1, Msg2, Opts) -> any()

+

+
+ +

test_aos_process/0

+
+

test_aos_process() -> any()

+

+

Generate a process message with a random number, and the + dev_wasm device for execution.

+ +

test_wasm_process/1

+
+

test_wasm_process(WASMImage) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_process_cache.html b/doc/dev_process_cache.html new file mode 100644 index 00000000..7e1f2323 --- /dev/null +++ b/doc/dev_process_cache.html @@ -0,0 +1,74 @@ + + + + +Module dev_process_cache + + + +
Overviewerlang logo
+
+ +

Module dev_process_cache

+A wrapper around the hb_cache module that provides a more + convenient interface for reading the result of a process at a given slot or + message ID. + + +

Description

A wrapper around the hb_cache module that provides a more + convenient interface for reading the result of a process at a given slot or + message ID. +

Function Index

+ + + + + + +
latest/2Retrieve the latest slot for a given process.
latest/3
latest/4
read/2Read the result of a process at a given slot.
read/3
write/4Write a process computation result to the cache.
+ +

Function Details

+ +

latest/2

+
+

latest(ProcID, Opts) -> any()

+

+

Retrieve the latest slot for a given process. Optionally state a limit + on the slot number to search for, as well as a required path that the slot + must have.

+ +

latest/3

+
+

latest(ProcID, RequiredPath, Opts) -> any()

+

+
+ +

latest/4

+
+

latest(ProcID, RawRequiredPath, Limit, Opts) -> any()

+

+
+ +

read/2

+
+

read(ProcID, Opts) -> any()

+

+

Read the result of a process at a given slot.

+ +

read/3

+
+

read(ProcID, SlotRef, Opts) -> any()

+

+
+ +

write/4

+
+

write(ProcID, Slot, Msg, Opts) -> any()

+

+

Write a process computation result to the cache.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_process_worker.html b/doc/dev_process_worker.html new file mode 100644 index 00000000..413bf0a8 --- /dev/null +++ b/doc/dev_process_worker.html @@ -0,0 +1,54 @@ + + + + +Module dev_process_worker + + + +
Overviewerlang logo
+
+ +

Module dev_process_worker

+A long-lived process worker that keeps state in memory between + calls. + + +

Description

A long-lived process worker that keeps state in memory between + calls. Implements the interface of hb_converge to receive and respond + to computation requests regarding a process as a singleton. +

Function Index

+ + + +
group/3Returns a group name for a request.
server/3Spawn a new worker process.
stop/1Stop a worker process.
+ +

Function Details

+ +

group/3

+
+

group(Msg1, Msg2, Opts) -> any()

+

+

Returns a group name for a request. The worker is responsible for all + computation work on the same process on a single node, so we use the + process ID as the group name.

+ +

server/3

+
+

server(GroupName, Msg1, Opts) -> any()

+

+

Spawn a new worker process. This is called after the end of the first + execution of hb_converge:resolve/3, so the state we are given is the + already current.

+ +

stop/1

+
+

stop(Worker) -> any()

+

+

Stop a worker process.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_relay.html b/doc/dev_relay.html new file mode 100644 index 00000000..f52013f9 --- /dev/null +++ b/doc/dev_relay.html @@ -0,0 +1,60 @@ + + + + +Module dev_relay + + + +
Overviewerlang logo
+
+ +

Module dev_relay

+This module implements the relay device, which is responsible for +relaying messages between nodes and other HTTP(S) endpoints. + + +

Description

This module implements the relay device, which is responsible for +relaying messages between nodes and other HTTP(S) endpoints.

+ +

It can be called in either call or cast mode. In call mode, it + returns a {ok, Result} tuple, where Result is the response from the + remote peer to the message sent. In cast mode, the invocation returns + immediately, and the message is relayed asynchronously. No response is given + and the device returns {ok, <<"OK">>}.

+ +

Example usage:

+ + 
       curl /~relay@.1.0/call?method=GET?0.path=https://www.arweave.net/
+

Function Index

+ + +
call/3Execute a call request using a node's routes.
cast/3Execute a request in the same way as call/3, but asynchronously.
+ +

Function Details

+ +

call/3

+
+

call(M1, RawM2, Opts) -> any()

+

+

Execute a call request using a node's routes.

+ + Supports the following options: + - target: The target message to relay. Defaults to the original message. + - relay-path: The path to relay the message to. Defaults to the original path. + - method: The method to use for the request. Defaults to the original method. + - requires-sign: Whether the request requires signing before dispatching. + Defaults to false.

+ +

cast/3

+
+

cast(M1, M2, Opts) -> any()

+

+

Execute a request in the same way as call/3, but asynchronously. Always + returns <<"OK">>.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_router.html b/doc/dev_router.html new file mode 100644 index 00000000..f427a453 --- /dev/null +++ b/doc/dev_router.html @@ -0,0 +1,70 @@ + + + + +Module dev_router + + + +
Overviewerlang logo
+
+ +

Module dev_router

+A device that routes outbound messages from the node to their +appropriate network recipients via HTTP. + + +

Description

A device that routes outbound messages from the node to their +appropriate network recipients via HTTP. All messages are initially +routed to a single process per node, which then load-balances them +between downstream workers that perform the actual requests.

+ +

The routes for the router are defined in the routes key of the Opts, +as a precidence-ordered list of maps. The first map that matches the +message will be used to determine the route.

+ +

Multiple nodes can be specified as viable for a single route, with the + Choose key determining how many nodes to choose from the list (defaulting + to 1). The Strategy key determines the load distribution strategy, + which can be one of Random, By-Base, or Nearest. The route may also + define additional parallel execution parameters, which are used by the + hb_http module to manage control of requests.

+ + The structure of the routes should be as follows: + 
       Node?: The node to route the message to.
+       Nodes?: A list of nodes to route the message to.
+       Strategy?: The load distribution strategy to use.
+       Choose?: The number of nodes to choose from the list.
+       Template?: A message template to match the message against, either as a
+                  map or a path regex.
+

Function Index

+ + + +
match_routes/3Find the first matching template in a list of known routes.
route/3
routes/3Device function that returns all known routes.
+ +

Function Details

+ +

match_routes/3

+
+

match_routes(ToMatch, Routes, Opts) -> any()

+

+

Find the first matching template in a list of known routes.

+ +

route/3

+
+

route(X1, Msg, Opts) -> any()

+

+
+ +

routes/3

+
+

routes(M1, M2, Opts) -> any()

+

+

Device function that returns all known routes.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_scheduler.html b/doc/dev_scheduler.html new file mode 100644 index 00000000..4cab756c --- /dev/null +++ b/doc/dev_scheduler.html @@ -0,0 +1,111 @@ + + + + +Module dev_scheduler + + + +
Overviewerlang logo
+
+ +

Module dev_scheduler

+A simple scheduler scheme for AO. + + +

Description

A simple scheduler scheme for AO. + This device expects a message of the form: + Process: #{ id, Scheduler: #{ Authority } } + 
   It exposes the following keys for scheduling:
+       `#{ method: GET, path: <<"/info">> }' ->
+           Returns information about the scheduler.
+       `#{ method: GET, path: <<"/slot">> }' -> `slot(Msg1, Msg2, Opts)'
+           Returns the current slot for a process.
+       `#{ method: GET, path: <<"/schedule">> }' -> `get_schedule(Msg1, Msg2, Opts)'
+           Returns the schedule for a process in a cursor-traversable format.
+      ` #{ method: POST, path: <<"/schedule">> }' -> `post_schedule(Msg1, Msg2, Opts)'
+           Schedules a new message for a process, or starts a new scheduler
+           for the given message.
+

Function Index

+ + + + + + + + + +
checkpoint/1Returns the current state of the scheduler.
info/0This device uses a default_handler to route requests to the correct + function.
next/3Load the schedule for a process into the cache, then return the next + assignment.
router/4The default handler for the scheduler device.
schedule/3A router for choosing between getting the existing schedule, or + scheduling a new message.
slot/3Returns information about the current slot for a process.
start/0Helper to ensure that the environment is started.
status/3Returns information about the entire scheduler.
test_process/0Generate a _transformed_ process message, not as they are generated + by users.
+ +

Function Details

+ +

checkpoint/1

+
+

checkpoint(State) -> any()

+

+

Returns the current state of the scheduler.

+ +

info/0

+
+

info() -> any()

+

+

This device uses a default_handler to route requests to the correct + function.

+ +

next/3

+
+

next(Msg1, Msg2, Opts) -> any()

+

+

Load the schedule for a process into the cache, then return the next + assignment. Assumes that Msg1 is a dev_process` or similar message, having + a `Current-Slot key. It stores a local cache of the schedule in the + priv/To-Process key.

+ +

router/4

+
+

router(X1, Msg1, Msg2, Opts) -> any()

+

+

The default handler for the scheduler device.

+ +

schedule/3

+
+

schedule(Msg1, Msg2, Opts) -> any()

+

+

A router for choosing between getting the existing schedule, or + scheduling a new message.

+ +

slot/3

+
+

slot(M1, M2, Opts) -> any()

+

+

Returns information about the current slot for a process.

+ +

start/0

+
+

start() -> any()

+

+

Helper to ensure that the environment is started.

+ +

status/3

+
+

status(M1, M2, Opts) -> any()

+

+

Returns information about the entire scheduler.

+ +

test_process/0

+
+

test_process() -> any()

+

+

Generate a _transformed_ process message, not as they are generated + by users. See dev_process for examples of AO process messages.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_scheduler_cache.html b/doc/dev_scheduler_cache.html new file mode 100644 index 00000000..70ba0006 --- /dev/null +++ b/doc/dev_scheduler_cache.html @@ -0,0 +1,46 @@ + + + + +Module dev_scheduler_cache + + + +
Overviewerlang logo
+
+ +

Module dev_scheduler_cache

+ + + +

Function Index

+ + + +
list/2Get the assignments for a process.
read/3Get an assignment message from the cache.
write/2Write an assignment message into the cache.
+ +

Function Details

+ +

list/2

+
+

list(ProcID, Opts) -> any()

+

+

Get the assignments for a process.

+ +

read/3

+
+

read(ProcID, Slot, Opts) -> any()

+

+

Get an assignment message from the cache.

+ +

write/2

+
+

write(Assignment, Opts) -> any()

+

+

Write an assignment message into the cache.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_scheduler_formats.html b/doc/dev_scheduler_formats.html new file mode 100644 index 00000000..18ad3b58 --- /dev/null +++ b/doc/dev_scheduler_formats.html @@ -0,0 +1,48 @@ + + + + +Module dev_scheduler_formats + + + +
Overviewerlang logo
+
+ +

Module dev_scheduler_formats

+This module is used by dev_scheduler in order to produce outputs that +are compatible with various forms of AO clients. + + +

Description

This module is used by dev_scheduler in order to produce outputs that +are compatible with various forms of AO clients. It features two main formats:

+ +

- application/json + - application/http

+ + The application/json format is a legacy format that is not recommended for + new integrations of the AO protocol. +

Function Index

+ + +
assignments_to_aos2/4
assignments_to_bundle/4Generate a GET /schedule response for a process as HTTP-sig bundles.
+ +

Function Details

+ +

assignments_to_aos2/4

+
+

assignments_to_aos2(ProcID, Assignments, More, Opts) -> any()

+

+
+ +

assignments_to_bundle/4

+
+

assignments_to_bundle(ProcID, Assignments, More, Opts) -> any()

+

+

Generate a GET /schedule response for a process as HTTP-sig bundles.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_scheduler_registry.html b/doc/dev_scheduler_registry.html new file mode 100644 index 00000000..84e09b50 --- /dev/null +++ b/doc/dev_scheduler_registry.html @@ -0,0 +1,67 @@ + + + + +Module dev_scheduler_registry + + + +
Overviewerlang logo
+
+ +

Module dev_scheduler_registry

+ + + +

Function Index

+ + + + + + +
find/1
find/2
find/3
get_processes/0
get_wallet/0
start/0
+ +

Function Details

+ +

find/1

+
+

find(ProcID) -> any()

+

+
+ +

find/2

+
+

find(ProcID, GenIfNotHosted) -> any()

+

+
+ +

find/3

+
+

find(ProcID, GenIfNotHosted, Opts) -> any()

+

+
+ +

get_processes/0

+
+

get_processes() -> any()

+

+
+ +

get_wallet/0

+
+

get_wallet() -> any()

+

+
+ +

start/0

+
+

start() -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_scheduler_server.html b/doc/dev_scheduler_server.html new file mode 100644 index 00000000..92713d4b --- /dev/null +++ b/doc/dev_scheduler_server.html @@ -0,0 +1,56 @@ + + + + +Module dev_scheduler_server + + + +
Overviewerlang logo
+
+ +

Module dev_scheduler_server

+A long-lived server that schedules messages for a process. + + +

Description

A long-lived server that schedules messages for a process. + It acts as a deliberate 'bottleneck' to prevent the server accidentally + assigning multiple messages to the same slot. +

Function Index

+ + + + +
info/1Get the current slot from the scheduling server.
schedule/2Call the appropriate scheduling server to assign a message.
start/2Start a scheduling server for a given computation.
stop/1
+ +

Function Details

+ +

info/1

+
+

info(ProcID) -> any()

+

+

Get the current slot from the scheduling server.

+ +

schedule/2

+
+

schedule(AOProcID, Message) -> any()

+

+

Call the appropriate scheduling server to assign a message.

+ +

start/2

+
+

start(ProcID, Opts) -> any()

+

+

Start a scheduling server for a given computation.

+ +

stop/1

+
+

stop(ProcID) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_simple_pay.html b/doc/dev_simple_pay.html new file mode 100644 index 00000000..e8f05a9c --- /dev/null +++ b/doc/dev_simple_pay.html @@ -0,0 +1,66 @@ + + + + +Module dev_simple_pay + + + +
Overviewerlang logo
+
+ +

Module dev_simple_pay

+A simple device that allows the operator to specify a price for a + request and then charge the user for it, on a per message basis. + + +

Description

A simple device that allows the operator to specify a price for a + request and then charge the user for it, on a per message basis. + The device's ledger is stored in the node message at simple_pay_ledger`, + and can be topped-up by either the operator, or an external device. The + price is specified in the node message at `simple_pay_price`. + This device acts as both a pricing device and a ledger device, by p4s + definition. +

Function Index

+ + + + +
balance/3Get the balance of a user in the ledger.
debit/3Preprocess a request by checking the ledger and charging the user.
estimate/3Estimate the cost of a request by counting the number of messages in + the request, then multiplying by the per-message price.
topup/3Top up the user's balance in the ledger.
+ +

Function Details

+ +

balance/3

+
+

balance(X1, RawReq, NodeMsg) -> any()

+

+

Get the balance of a user in the ledger.

+ +

debit/3

+
+

debit(X1, RawReq, NodeMsg) -> any()

+

+

Preprocess a request by checking the ledger and charging the user. We + can charge the user at this stage because we know statically what the price + will be

+ +

estimate/3

+
+

estimate(X1, EstimateReq, NodeMsg) -> any()

+

+

Estimate the cost of a request by counting the number of messages in + the request, then multiplying by the per-message price. The operator does + not pay for their own requests.

+ +

topup/3

+
+

topup(X1, Req, NodeMsg) -> any()

+

+

Top up the user's balance in the ledger.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_snp.html b/doc/dev_snp.html new file mode 100644 index 00000000..84f2efa3 --- /dev/null +++ b/doc/dev_snp.html @@ -0,0 +1,80 @@ + + + + +Module dev_snp + + + +
Overviewerlang logo
+
+ +

Module dev_snp

+This device offers an interface for validating AMD SEV-SNP attestations, + as well as generating them, if called in an appropriate environment. + + +

Description

This device offers an interface for validating AMD SEV-SNP attestations, + as well as generating them, if called in an appropriate environment. +

Function Index

+ + + + +
generate/3Generate an attestation report and emit it as a message, including all of + the necessary data to generate the nonce (ephemeral node address + node + message ID), as well as the expected measurement (firmware, kernel, and VMSAs + hashes).
init/3Should take in options to set for the device such as kernel, initrd, firmware, + and append hashes and make them available to the device.
trusted/3Default implementation of a resolver for trusted software.
verify/3Verify an attestation report message; validating the identity of a + remote node, its ephemeral private address, and the integrity of the report.
+ +

Function Details

+ +

generate/3

+
+

generate(M1, M2, Opts) -> any()

+

+

Generate an attestation report and emit it as a message, including all of + the necessary data to generate the nonce (ephemeral node address + node + message ID), as well as the expected measurement (firmware, kernel, and VMSAs + hashes).

+ +

init/3

+
+

init(M1, M2, Opts) -> any()

+

+

Should take in options to set for the device such as kernel, initrd, firmware, + and append hashes and make them available to the device. Only runnable once, + and only if the operator is not set to an address (and thus, the node has not + had any priviledged access).

+ +

trusted/3

+
+

trusted(Msg1, Msg2, NodeOpts) -> any()

+

+

Default implementation of a resolver for trusted software. Searches the + trusted key in the base message for a list of trusted values, and checks + if the value in the request message is a member of that list.

+ +

verify/3

+
+

verify(M1, M2, NodeOpts) -> any()

+

+

Verify an attestation report message; validating the identity of a + remote node, its ephemeral private address, and the integrity of the report. + The checks that must be performed to validate the report are: + 1. Verify the address and the node message ID are the same as the ones + used to generate the nonce. + 2. Verify the address that signed the message is the same as the one used + to generate the nonce. + 3. Verify that the debug flag is disabled. + 4. Verify that the firmware, kernel, and OS (VMSAs) hashes, part of the + measurement, are trusted. + 5. Verify the measurement is valid. + 6. Verify the report's certificate chain to hardware root of trust.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_snp_nif.html b/doc/dev_snp_nif.html new file mode 100644 index 00000000..d86214ea --- /dev/null +++ b/doc/dev_snp_nif.html @@ -0,0 +1,60 @@ + + + + +Module dev_snp_nif + + + +
Overviewerlang logo
+
+ +

Module dev_snp_nif

+ + + +

Function Index

+ + + + + +
check_snp_support/0
compute_launch_digest/1
generate_attestation_report/2
verify_measurement/2
verify_signature/1
+ +

Function Details

+ +

check_snp_support/0

+
+

check_snp_support() -> any()

+

+
+ +

compute_launch_digest/1

+
+

compute_launch_digest(Args) -> any()

+

+
+ +

generate_attestation_report/2

+
+

generate_attestation_report(UniqueData, VMPL) -> any()

+

+
+ +

verify_measurement/2

+
+

verify_measurement(Report, Expected) -> any()

+

+
+ +

verify_signature/1

+
+

verify_signature(Report) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_stack.html b/doc/dev_stack.html new file mode 100644 index 00000000..20656f25 --- /dev/null +++ b/doc/dev_stack.html @@ -0,0 +1,160 @@ + + + + +Module dev_stack + + + +
Overviewerlang logo
+
+ +

Module dev_stack

+A device that contains a stack of other devices, and manages their +execution. + + +

Description

A device that contains a stack of other devices, and manages their +execution. It can run in two modes: fold (the default), and map.

+ +

In fold mode, it runs upon input messages in the order of their keys. A +stack maintains and passes forward a state (expressed as a message) as it +progresses through devices.

+ + For example, a stack of devices as follows: + 
   Device -> Stack
+   Device-Stack/1/Name -> Add-One-Device
+   Device-Stack/2/Name -> Add-Two-Device
+ + When called with the message: + 
   #{ Path = "FuncName", binary => <<"0">> }
+ + Will produce the output: + 
   #{ Path = "FuncName", binary => <<"3">> }
+   {ok, #{ bin => <<"3">> }}
+ +

In map mode, the stack will run over all the devices in the stack, and + combine their results into a single message. Each of the devices' + output values have a key that is the device's name in the Device-Stack` + (its number if the stack is a list). + + You can switch between fold and map modes by setting the `Mode` key in the + `Msg2` to either `Fold` or `Map`, or set it globally for the stack by + setting the `Mode` key in the `Msg1` message. The key in `Msg2` takes + precedence over the key in `Msg1`. + + The key that is called upon the device stack is the same key that is used + upon the devices that are contained within it. For example, in the above + scenario we resolve FuncName on the stack, leading FuncName to be called on + Add-One-Device and Add-Two-Device. + + A device stack responds to special statuses upon responses as follows: + + `skip: Skips the rest of the device stack for the current pass.

+ +

pass: Causes the stack to increment its pass number and re-execute +the stack from the first device, maintaining the state +accumulated so far. Only available in fold mode.

+ +

In all cases, the device stack will return the accumulated state to the +caller as the result of the call to the stack.

+ +

The dev_stack adds additional metadata to the message in order to track +the state of its execution as it progresses through devices. These keys +are as follows:

+ +

Stack-Pass: The number of times the stack has reset and re-executed +from the first device for the current message.

+ +

Input-Prefix: The prefix that the device should use for its outputs +and inputs.

+ +

Output-Prefix: The device that was previously executed.

+ +

All counters used by the stack are initialized to 1.

+ +

Additionally, as implemented in HyperBEAM, the device stack will honor a +number of options that are passed to it as keys in the message. Each of +these options is also passed through to the devices contained within the +stack during execution. These options include:

+ +

Error-Strategy: Determines how the stack handles errors from devices. + See maybe_error/5 for more information.

+ +

Allow-Multipass: Determines whether the stack is allowed to automatically + re-execute from the first device when the pass tag is returned. See + maybe_pass/3 for more information.

+ + Under-the-hood, dev_stack uses a default handler to resolve all calls to + devices, aside set/2 which it calls itself to mutate the message's device + key in order to change which device is currently being executed. This method + allows dev_stack to ensure that the message's HashPath is always correct, + even as it delegates calls to other devices. An example flow for a dev_stack + execution is as follows: + 
   	/Msg1/AlicesExcitingKey ->
+   		dev_stack:execute ->
+   			/Msg1/Set?device=/Device-Stack/1 ->
+   			/Msg2/AlicesExcitingKey ->
+   			/Msg3/Set?device=/Device-Stack/2 ->
+   			/Msg4/AlicesExcitingKey
+   			... ->
+   			/MsgN/Set?device=[This-Device] ->
+   		returns {ok, /MsgN+1} ->
+   	/MsgN+1
+ + In this example, the device key is mutated a number of times, but the + resulting HashPath remains correct and verifiable. +

Function Index

+ + + + + + +
generate_append_device/1
info/1
input_prefix/3Return the input prefix for the stack.
output_prefix/3Return the output prefix for the stack.
prefix/3Return the default prefix for the stack.
router/4The device stack key router.
+ +

Function Details

+ +

generate_append_device/1

+
+

generate_append_device(Separator) -> any()

+

+
+ +

info/1

+
+

info(Msg) -> any()

+

+
+ +

input_prefix/3

+
+

input_prefix(Msg1, Msg2, Opts) -> any()

+

+

Return the input prefix for the stack.

+ +

output_prefix/3

+
+

output_prefix(Msg1, Msg2, Opts) -> any()

+

+

Return the output prefix for the stack.

+ +

prefix/3

+
+

prefix(Msg1, Msg2, Opts) -> any()

+

+

Return the default prefix for the stack.

+ +

router/4

+
+

router(Key, Message1, Message2, Opts) -> any()

+

+

The device stack key router. Sends the request to resolve_stack, + except for set/2 which is handled by the default implementation in + dev_message.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_test.html b/doc/dev_test.html new file mode 100644 index 00000000..fb7e1c9a --- /dev/null +++ b/doc/dev_test.html @@ -0,0 +1,81 @@ + + + + +Module dev_test + + + +
Overviewerlang logo
+
+ +

Module dev_test

+ + + +

Function Index

+ + + + + + + +
compute/3Example implementation of a compute handler.
info/1Exports a default_handler function that can be used to test the + handler resolution mechanism.
init/3Example init/3 handler.
mul/2Example implementation of an imported function for a WASM + executor.
restore/3Example restore/3 handler.
snapshot/3Do nothing when asked to snapshot.
test_func/1
+ +

Function Details

+ +

compute/3

+
+

compute(Msg1, Msg2, Opts) -> any()

+

+

Example implementation of a compute handler. Makes a running list of + the slots that have been computed in the state message and places the new + slot number in the results key.

+ +

info/1

+
+

info(X1) -> any()

+

+

Exports a default_handler function that can be used to test the + handler resolution mechanism.

+ +

init/3

+
+

init(Msg, Msg2, Opts) -> any()

+

+

Example init/3 handler. Sets the Already-Seen key to an empty list.

+ +

mul/2

+
+

mul(Msg1, Msg2) -> any()

+

+

Example implementation of an imported function for a WASM + executor.

+ +

restore/3

+
+

restore(Msg, Msg2, Opts) -> any()

+

+

Example restore/3 handler. Sets the hidden key Test/Started to the + value of Current-Slot and checks whether the Already-Seen key is valid.

+ +

snapshot/3

+
+

snapshot(Msg1, Msg2, Opts) -> any()

+

+

Do nothing when asked to snapshot.

+ +

test_func/1

+
+

test_func(X1) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_wasi.html b/doc/dev_wasi.html new file mode 100644 index 00000000..b7b0d45e --- /dev/null +++ b/doc/dev_wasi.html @@ -0,0 +1,89 @@ + + + + +Module dev_wasi + + + +
Overviewerlang logo
+
+ +

Module dev_wasi

+A virtual filesystem device. + + +

Description

A virtual filesystem device. + Implements a file-system-as-map structure, which is traversible externally. + Each file is a binary and each directory is a Converge message. + Additionally, this module adds a series of WASI-preview-1 compatible + functions for accessing the filesystem as imported functions by WASM + modules. +

Function Index

+ + + + + + + +
clock_time_get/3
compute/1
fd_read/3Read from a file using the WASI-p1 standard interface.
fd_write/3WASM stdlib implementation of fd_write, using the WASI-p1 standard + interface.
init/3On-boot, initialize the virtual file system with: + - Empty stdio files + - WASI-preview-1 compatible functions for accessing the filesystem + - File descriptors for those files.
path_open/3Adds a file descriptor to the state message.
stdout/1Return the stdout buffer from a state message.
+ +

Function Details

+ +

clock_time_get/3

+
+

clock_time_get(Msg1, Msg2, Opts) -> any()

+

+
+ +

compute/1

+
+

compute(Msg1) -> any()

+

+
+ +

fd_read/3

+
+

fd_read(Msg1, Msg2, Opts) -> any()

+

+

Read from a file using the WASI-p1 standard interface.

+ +

fd_write/3

+
+

fd_write(Msg1, Msg2, Opts) -> any()

+

+

WASM stdlib implementation of fd_write, using the WASI-p1 standard + interface.

+ +

init/3

+
+

init(M1, M2, Opts) -> any()

+

+

On-boot, initialize the virtual file system with: + - Empty stdio files + - WASI-preview-1 compatible functions for accessing the filesystem + - File descriptors for those files.

+ +

path_open/3

+
+

path_open(Msg1, Msg2, Opts) -> any()

+

+

Adds a file descriptor to the state message. +path_open(M, Instance, [FDPtr, LookupFlag, PathPtr|_]) ->

+ +

stdout/1

+
+

stdout(M) -> any()

+

+

Return the stdout buffer from a state message.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/dev_wasm.html b/doc/dev_wasm.html new file mode 100644 index 00000000..d1052350 --- /dev/null +++ b/doc/dev_wasm.html @@ -0,0 +1,136 @@ + + + + +Module dev_wasm + + + +
Overviewerlang logo
+
+ +

Module dev_wasm

+A device that executes a WASM image on messages using the Memory-64 + preview standard. + + +

Description

A device that executes a WASM image on messages using the Memory-64 + preview standard. In the backend, this device uses beamr: An Erlang wrapper +for WAMR, the WebAssembly Micro Runtime.

+ + The device has the following requirements and interface: + 
       M1/Init ->
+           Assumes:
+               M1/process
+               M1/[Prefix]/image
+           Generates:
+               /priv/wasm/instance
+               /priv/wasm/import-resolver
+           Side-effects:
+               Creates a WASM executor loaded in memory of the HyperBEAM node.
+  
+       M1/Compute ->
+           Assumes:
+               M1/priv/wasm/instance
+               M1/priv/wasm/import-resolver
+               M1/process
+               M2/message
+               M2/message/wasm-function OR M1/wasm-function
+               M2/message/wasm-params OR M1/wasm-params
+           Generates:
+               /results/wasm/type
+               /results/wasm/body
+           Side-effects:
+               Calls the WASM executor with the message and process.
+       M1/wasm/state ->
+           Assumes:
+               M1/priv/wasm/instance
+           Generates:
+               Raw binary WASM state
+

Function Index

+ + + + + + + + + +
cache_wasm_image/1
compute/3Call the WASM executor with a message that has been prepared by a prior + pass.
import/3Handle standard library calls by: + 1.
info/2Export all functions aside the instance/3 function.
init/3Boot a WASM image on the image stated in the process/image field of + the message.
instance/3Get the WASM instance from the message.
normalize/3Normalize the message to have an open WASM instance, but no literal + State key.
snapshot/3Serialize the WASM state to a binary.
terminate/3Tear down the WASM executor.
+ +

Function Details

+ +

cache_wasm_image/1

+
+

cache_wasm_image(Image) -> any()

+

+
+ +

compute/3

+
+

compute(RawM1, M2, Opts) -> any()

+

+

Call the WASM executor with a message that has been prepared by a prior + pass.

+ +

import/3

+
+

import(Msg1, Msg2, Opts) -> any()

+

+

Handle standard library calls by: + 1. Adding the right prefix to the path from BEAMR. + 2. Adding the state to the message at the stdlib path. + 3. Resolving the adjusted-path-Msg2 against the added-state-Msg1. + 4. If it succeeds, return the new state from the message. + 5. If it fails with not_found, call the stub handler.

+ +

info/2

+
+

info(Msg1, Opts) -> any()

+

+

Export all functions aside the instance/3 function.

+ +

init/3

+
+

init(M1, M2, Opts) -> any()

+

+

Boot a WASM image on the image stated in the process/image field of + the message.

+ +

instance/3

+
+

instance(M1, M2, Opts) -> any()

+

+

Get the WASM instance from the message. Note that this function is exported + such that other devices can use it, but it is excluded from calls from Converge + resolution directly.

+ +

normalize/3

+
+

normalize(RawM1, M2, Opts) -> any()

+

+

Normalize the message to have an open WASM instance, but no literal + State key. Ensure that we do not change the hashpath during this process.

+ +

snapshot/3

+
+

snapshot(M1, M2, Opts) -> any()

+

+

Serialize the WASM state to a binary.

+ +

terminate/3

+
+

terminate(M1, M2, Opts) -> any()

+

+

Tear down the WASM executor.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/edoc-info b/doc/edoc-info new file mode 100644 index 00000000..7a4c34fb --- /dev/null +++ b/doc/edoc-info @@ -0,0 +1,19 @@ +%% encoding: UTF-8 +{application,hb}. +{modules,[ar_bundles,ar_deep_hash,ar_http,ar_http_sup,ar_rate_limiter, + ar_timestamp,ar_tx,ar_wallet,dev_codec_ans104,dev_codec_flat, + dev_codec_httpsig,dev_codec_httpsig_conv,dev_codec_structured, + dev_codec_structured_conv,dev_compute_lite,dev_cron,dev_cu, + dev_dedup,dev_faff,dev_json_iface,dev_lookup,dev_message,dev_meta, + dev_monitor,dev_multipass,dev_p4,dev_poda,dev_process, + dev_process_cache,dev_process_worker,dev_relay,dev_router, + dev_scheduler,dev_scheduler_cache,dev_scheduler_formats, + dev_scheduler_registry,dev_scheduler_server,dev_simple_pay,dev_snp, + dev_snp_nif,dev_stack,dev_test,dev_wasi,dev_wasm,hb,hb_app,hb_beamr, + hb_beamr_io,hb_cache,hb_cache_control,hb_cache_render,hb_client, + hb_converge,hb_converge_test_vectors,hb_crypto,hb_examples,hb_http, + hb_http_benchmark_tests,hb_http_server,hb_logger,hb_message, + hb_metrics_collector,hb_opts,hb_path,hb_persistent,hb_private, + hb_process_monitor,hb_router,hb_singleton,hb_store,hb_store_fs, + hb_store_remote_node,hb_store_rocksdb,hb_sup,hb_test,hb_test_utils, + hb_util,rsa_pss]}. diff --git a/doc/erlang.png b/doc/erlang.png new file mode 100644 index 0000000000000000000000000000000000000000..987a618e2403af895bfaf8c2f929e3a4f3746659 GIT binary patch literal 2109 zcmV-D2*US?P)rez_nr%N ze)-p~%6|a|LA_bA=l=$|3jjqS$tjbGG?@TN0w$Azq7Z{YeQxKcpLO55vno1^u23DP&V=i9-KAAsU*ECy^#OtaDC!lVSo!+|-%T+LhTHP^Oqwx8m)b4r3V28JmV&6M#iG)&0;P`j>XGfomEIEK6wPkhI{{K?3#uAGq$!`N_F)TNX zAvuspF?^;c9h%CPWyTDc_03%r4N8+Yzzo_VSfa!zo_7F6D?<+-+KkHwXiWQR=Mr(9|K@{{xEjfDvAbS9uNCP&{)NNCoC?XA$aRe>R8-> z5N<#S_)$d|EYpJfPC?{`$Y~f4yjH&dxHXIGG8wiaLBD6usC87cg+dd&3WLJd4_TcmEeAOz8R>ikgW(9821 z{34Se09Y?KoG<_Y;DDSoyTk>fUN0YO5)3^Za{&s1JbidC9}56{px+f|K_0;YuL5h} z_9J3y%7ucwM)E4K#=Cn7tCjjRkKjnQuiFcM6{17Jt#5F}7z8~RYqW24xV?kAU6xQN zh+h4|SmO1;TdsVOaOeD*kKf}6I7=6ZNig_rtqV?Ov1HrU(P%Hi#6npSe>%qGaNK1w zW$v+r`r0>#p~AN^8b)#7Yesu(ys(>3SCYb4sF9%A9=kMHrLmzk}E&WPG~Jx z9!r{qo5M184t;<7I`t1AsNjv912EeKkHKtOSl%wbcjFh7L6|G?Q+{?radOvuEW$>1 zoc+c&F+u$^0f}1_2dN&lS#I#p3e&+|YGHlMzRC)%&8TnGt+p*;Oz z`0=D=n|qcN+f@07;QjB@ktLhZ`+qz;(xYDli^Pex&&wwU2V4N-a3b@veqHg2cvCRb zoi=ZerLk!4t5!s3?|ARuWx_4-VCgl|TY2qa@$Dr~5QdiT8?$oPpZhaF5UOZ&x=+I9 zt((`6wBPM((BS{;2lmSB;o%z{>=mg*1k2oLjI=+zcf5$4BIZmkOrjrE z*VY(<@FO?zBVDc+Q~Lh;LnlYodZ$J3tmWJBN4j~wVOWelzexhft2nY6A3PZAcm!q} z931CL#1Ki6;HM{agTbKF>3(R-yuF1&Apn3Nh@PGvv)K$mkVqu*^z@vaFgQ3kFfg!s z^=f26@{Ny=_w@7x1qHF$bEk5X$)wR}0s{l>V!TCGM=R5Ei1Ll8u7Z*N0G1CPgB zyLPP|0H{-FRUDJv`Ea=9fX zC63D4+FBlumz$eAJv~j5q*|@^_xC?_>XiL0K@bH61$;i=&CLx(QGb8`8#iu{BnjJW zHUvSgUcK7T&~W(h;koN8t5vB~Ha0dgnane1&RA#87dVcaOpEMM)6>)E&YiPZEXBpe zlarHk89g;+G#U#E3hL_W002xT6UTApOeR%UR_5g7q^73!_4PG2Hi|@|ii(Pfi3vIY z0ES^?Mx1IOizO0?e0_a!9483k`PtCk-rm~Unwpw=?b@~O?(WdgP^bMMAYlLg{dIM9 zOy}OcxVTs%k(@q#n$PF+`TXkYYA%;cr_*5ofWcr$PEL-Ai772Db)3`L*|~G)&eqn} zq@*OrbXim`UAiO`3XdK=%H#1=D%HHV>FMbqAtCAM=@!e}C6Cc))ai5zg~H3rYjkup zD=RBMKR+`wv!kN}1^{3fR#a3}RaLcP#}20|H!^bT)~%G3lp{xu!0_{Wr2hW?>({UQ z`T1F`)|D$)*3{IP&1UDKhLn_)sMYHH{QRkzV=$M?#W2idGFh!wf*`b7ZGC-xVPT=c zV1Vs&!otFoN~M>VQ$G_G6}5No-m0pqwzjr;?W@INu~;m#k*%qz(P%VUt#;3zJ^lUt zU0q%G?%kVzvF7cqQmLw|tA~e&XIqun*x2Ug=9-!s48ty7ycil9Di(|7aybkD7#y?%lgQ z9`Ewy%eDpgxlvJ3Cr+GTFc>(F+cg;(8TPc>y?b|jeEgLwR}LLIBoqp1+1c4_HrvO? z$J5g@G&D3gIC$2ITrQ7`iwh4AfA;K|OePZu1oriTVVG1Zl}e@S)~)mK@UU1cI-Ty| z!Gj8gg2UmUD2ibif*{e+(R4bU#bU|j@{Joe^7(uSf+8X!q*7@_M1;L=AqbM3oXp{H nT3T9A6wS=c+_!HZolgHhw9g$%O4Wbp00000NkvXXu0mjf3HKBY literal 0 HcmV?d00001 diff --git a/doc/hb.html b/doc/hb.html new file mode 100644 index 00000000..49c5d5ce --- /dev/null +++ b/doc/hb.html @@ -0,0 +1,288 @@ + + + + +Module hb + + + +
Overviewerlang logo
+
+ +

Module hb

+Hyperbeam is a decentralized node implementating the Converge Protocol +on top of Arweave. + + +

Description

Hyperbeam is a decentralized node implementating the Converge Protocol +on top of Arweave.

+ +

This protocol offers a computation layer for executing arbitrary logic on +top of the network's data.

+ +

Arweave is built to offer a robust, permanent storage layer for static data +over time. It can be seen as a globally distributed key-value store that +allows users to lookup IDs to retrieve data at any point in time:

+ +

Arweave(ID) => Message

+ +

Hyperbeam adds another layer of functionality on top of Arweave's protocol: +Allowing users to store and retrieve not only arbitrary bytes, but also to +perform execution of computation upon that data:

+ +

Hyperbeam(Message1, Message2) => Message3

+ +

When Hyperbeam executes a message, it will return a new message containing +the result of that execution, as well as signed attestations of its +correctness. If the computation that is executed is deterministic, recipients +of the new message are able to verify that the computation was performed +correctly. The new message may be stored back to Arweave if desired, +forming a permanent, verifiable, and decentralized log of computation.

+ +

The mechanisms described above form the basis of a decentralized and +verifiable compute engine without any relevant protocol-enforced +scalability limits. It is an implementation of a global, shared +supercomputer.

+ +

Hyperbeam can be used for an extremely large variety of applications, from +serving static Arweave data with signed commitments of correctness, to +executing smart contracts that have _built-in_ HTTP APIs. The Hyperbeam +node implementation implements AO, an Actor-Oriented process-based +environment for orchestrating computation over Arweave messages in order to +facilitate the execution of more traditional, consensus-based smart +contracts.

+ +

The core abstractions of the Hyperbeam node are broadly as follows:

+ +

1. The hb and hb_opts modules manage the node's configuration, +environment variables, and debugging tools.

+ +

2. The hb_http and hb_http_server modules manage all HTTP-related + functionality. hb_http_server handles turning received HTTP requests + into messages and applying those messages with the appropriate devices. + hb_http handles making requests and responding with messages. cowboy +is used to implement the underlying HTTP server.

+ +

3. hb_converge implements the computation logic of the node: A mechanism + for resolving messages to other messages, via the application of logic + implemented in devices. hb_converge also manages the loading of Erlang + modules for each device into the node's environment. There are many + different default devices implemented in the hyperbeam node, using the + namespace dev_*. Some of the critical components are:

+ +

- dev_message: The default handler for all messages that do not +specify their own device. The message device is also used to resolve +keys that are not implemented by the device specified in a message, +unless otherwise signalled.

+ +

- dev_stack: The device responsible for creating and executing stacks +of other devices on messages that request it. There are many uses for +this device, one of which is the resolution of AO processes.

+ +

- dev_p4: The device responsible for managing payments for the services +provided by the node.

+ +

4. hb_store, hb_cache and the store implementations forms a layered + system for managing the node's access to persistent storage. hb_cache + is used as a resolution mechanism for reading and writing messages, while + hb_store provides an abstraction over the underlying persistent key-value + byte storage mechanisms. Example hb_store mechanisms can be found in + hb_store_fs and hb_store_remote_node.

+ +

5. ar_* modules implement functionality related to the base-layer Arweave +protocol and are largely unchanged from their counterparts in the Arweave +node codebase presently maintained by the Digital History Association +(@dha-team/Arweave).

+ + You can find documentation of a similar form to this note in each of the core + modules of the hyperbeam node. +

Function Index

+ + + + + + + + + + + + + + + + + + + + + + + + +
address/0Get the address of a wallet.
benchmark/2Run a function as many times as possible in a given amount of time.
benchmark/3Run multiple instances of a function in parallel for a given amount of time.
build/0Utility function to hot-recompile and load the hyperbeam environment.
debug_wait/4Utility function to wait for a given amount of time, printing a debug + message to the console first.
event/1Debugging event logging function.
event/2
event/3
event/4
event/5
event/6
init/0Initialize system-wide settings for the hyperbeam node.
no_prod/3Utility function to throw an error if the current mode is prod and + non-prod ready code is being executed.
now/0Utility function to get the current time in milliseconds.
profile/1Utility function to start a profiling session and run a function, + then analyze the results.
read/1Debugging function to read a message from the cache.
read/2
start_simple_pay/0Start a server with a simple-pay@1.0 pre-processor.
start_simple_pay/1
start_simple_pay/2
topup/3Helper for topping up a user's balance on a simple-pay node.
topup/4
wallet/0
wallet/1
+ +

Function Details

+ +

address/0

+
+

address() -> any()

+

+

Get the address of a wallet. Defaults to the address of the wallet + specified by the key_location configuration key. It can also take a + wallet tuple as an argument.

+ +

benchmark/2

+
+

benchmark(Fun, TLen) -> any()

+

+

Run a function as many times as possible in a given amount of time.

+ +

benchmark/3

+
+

benchmark(Fun, TLen, Procs) -> any()

+

+

Run multiple instances of a function in parallel for a given amount of time.

+ +

build/0

+
+

build() -> any()

+

+

Utility function to hot-recompile and load the hyperbeam environment.

+ +

debug_wait/4

+
+

debug_wait(T, Mod, Func, Line) -> any()

+

+

Utility function to wait for a given amount of time, printing a debug + message to the console first.

+ +

event/1

+
+

event(X) -> any()

+

+

Debugging event logging function. For now, it just prints to standard + error.

+ +

event/2

+
+

event(Topic, X) -> any()

+

+
+ +

event/3

+
+

event(Topic, X, Mod) -> any()

+

+
+ +

event/4

+
+

event(Topic, X, Mod, Func) -> any()

+

+
+ +

event/5

+
+

event(Topic, X, Mod, Func, Line) -> any()

+

+
+ +

event/6

+
+

event(Topic, X, Mod, Func, Line, Opts) -> any()

+

+
+ +

init/0

+
+

init() -> any()

+

+

Initialize system-wide settings for the hyperbeam node.

+ +

no_prod/3

+
+

no_prod(X, Mod, Line) -> any()

+

+

Utility function to throw an error if the current mode is prod and + non-prod ready code is being executed. You can find these in the codebase + by looking for ?NO_PROD calls.

+ +

now/0

+
+

now() -> any()

+

+

Utility function to get the current time in milliseconds.

+ +

profile/1

+
+

profile(Fun) -> any()

+

+

Utility function to start a profiling session and run a function, + then analyze the results. Obviously -- do not use in production.

+ +

read/1

+
+

read(ID) -> any()

+

+

Debugging function to read a message from the cache. + Specify either a scope atom (local or remote) or a store tuple + as the second argument.

+ +

read/2

+
+

read(ID, ScopeAtom) -> any()

+

+
+ +

start_simple_pay/0

+
+

start_simple_pay() -> any()

+

+

Start a server with a simple-pay@1.0 pre-processor.

+ +

start_simple_pay/1

+
+

start_simple_pay(Addr) -> any()

+

+
+ +

start_simple_pay/2

+
+

start_simple_pay(Addr, Port) -> any()

+

+
+ +

topup/3

+
+

topup(Node, Amount, Recipient) -> any()

+

+

Helper for topping up a user's balance on a simple-pay node.

+ +

topup/4

+
+

topup(Node, Amount, Recipient, Wallet) -> any()

+

+
+ +

wallet/0

+
+

wallet() -> any()

+

+
+ +

wallet/1

+
+

wallet(Location) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_app.html b/doc/hb_app.html new file mode 100644 index 00000000..421e8ab1 --- /dev/null +++ b/doc/hb_app.html @@ -0,0 +1,41 @@ + + + + +Module hb_app + + + +
Overviewerlang logo
+
+ +

Module hb_app

+The main HyperBEAM application module. + +

Behaviours: application.

+ +

Description

The main HyperBEAM application module. +

Function Index

+ + +
start/2
stop/1
+ +

Function Details

+ +

start/2

+
+

start(StartType, StartArgs) -> any()

+

+
+ +

stop/1

+
+

stop(State) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_beamr.html b/doc/hb_beamr.html new file mode 100644 index 00000000..ea704442 --- /dev/null +++ b/doc/hb_beamr.html @@ -0,0 +1,154 @@ + + + + +Module hb_beamr + + + +
Overviewerlang logo
+
+ +

Module hb_beamr

+BEAMR: A WAMR wrapper for BEAM. + + +

Description

BEAMR: A WAMR wrapper for BEAM.

+ +

Beamr is a library that allows you to run WASM modules in BEAM, using the +Webassembly Micro Runtime (WAMR) as its engine. Each WASM module is +executed using a Linked-In Driver (LID) that is loaded into BEAM. It is +designed with a focus on supporting long-running WASM executions that +interact with Erlang functions and processes easily.

+ +

Because each WASM module runs as an independent async worker, if you plan + to run many instances in parallel, you should be sure to configure the + BEAM to have enough async worker threads enabled (see erl +A N` in the + Erlang manuals). + + The core API is simple: + ``` + start(WasmBinary) -> {ok, Port, Imports, Exports} + Where: + WasmBinary is the WASM binary to load. + Port is the port to the LID. + Imports is a list of tuples of the form {Module, Function, + Args, Signature}. + Exports is a list of tuples of the form {Function, Args, + Signature}. + stop(Port) -> ok + call(Port, FunctionName, Args) -> {ok, Result} + Where: + FunctionName is the name of the function to call. + Args is a list of Erlang terms (converted to WASM values by + BEAMR) that match the signature of the function. + Result is a list of Erlang terms (converted from WASM values). + call(Port, FunName, Args[, Import, State, Opts]) -> {ok, Res, NewState} + Where: + ImportFun is a function that will be called upon each import. + ImportFun must have an arity of 2: Taking an arbitrary `state` + term, and a map containing the `port`, `module`, `func`, `args`, + `signature`, and the `options` map of the import. + It must return a tuple of the form {ok, Response, NewState}. + serialize(Port) -> {ok, Mem} + Where: + Port is the port to the LID. + Mem is a binary representing the full WASM state. + deserialize(Port, Mem) -> ok + Where: + Port is the port to the LID. + Mem is a binary output of a previous `serialize/1 call. +'''

+ + BEAMR was designed for use in the HyperBEAM project, but is suitable for + deployment in other Erlang applications that need to run WASM modules. PRs + are welcome. +

Function Index

+ + + + + + + + + + + +
call/3Call a function in the WASM executor (see moduledoc for more details).
call/4
call/5
call/6
deserialize/2Deserialize a WASM state from a binary.
serialize/1Serialize the WASM state to a binary.
start/1Start a WASM executor context.
start/2
stop/1Stop a WASM executor context.
stub/3Stub import function for the WASM executor.
wasm_send/2
+ +

Function Details

+ +

call/3

+
+

call(PID, FuncRef, Args) -> any()

+

+

Call a function in the WASM executor (see moduledoc for more details).

+ +

call/4

+
+

call(PID, FuncRef, Args, ImportFun) -> any()

+

+
+ +

call/5

+
+

call(PID, FuncRef, Args, ImportFun, StateMsg) -> any()

+

+
+ +

call/6

+
+

call(PID, FuncRef, Args, ImportFun, StateMsg, Opts) -> any()

+

+
+ +

deserialize/2

+
+

deserialize(WASM, Bin) -> any()

+

+

Deserialize a WASM state from a binary.

+ +

serialize/1

+
+

serialize(WASM) -> any()

+

+

Serialize the WASM state to a binary.

+ +

start/1

+
+

start(WasmBinary) -> any()

+

+

Start a WASM executor context. Yields a port to the LID, and the + imports and exports of the WASM module. Optionally, specify a mode + (wasm or aot) to indicate the type of WASM module being loaded.

+ +

start/2

+
+

start(WasmBinary, Mode) -> any()

+

+
+ +

stop/1

+
+

stop(WASM) -> any()

+

+

Stop a WASM executor context.

+ +

stub/3

+
+

stub(Msg1, Msg2, Opts) -> any()

+

+

Stub import function for the WASM executor.

+ +

wasm_send/2

+
+

wasm_send(WASM, Message) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_beamr_io.html b/doc/hb_beamr_io.html new file mode 100644 index 00000000..cdc58b7a --- /dev/null +++ b/doc/hb_beamr_io.html @@ -0,0 +1,103 @@ + + + + +Module hb_beamr_io + + + +
Overviewerlang logo
+
+ +

Module hb_beamr_io

+Simple interface for memory management for Beamr instances. + + +

Description

Simple interface for memory management for Beamr instances. +It allows for reading and writing to memory, as well as allocating and +freeing memory by calling the WASM module's exported malloc and free +functions.

+ + Unlike the majority of HyperBEAM modules, this module takes a defensive + approach to type checking, breaking from the conventional Erlang style, + such that failures are caught in the Erlang-side of functions rather than + in the C/WASM-side. +

Function Index

+ + + + + + + +
free/2Free space allocated in the Beamr instance's native memory via a + call to the exported free function from the WASM.
malloc/2Allocate space for (via an exported malloc function from the WASM) in + the Beamr instance's native memory.
read/3Read a binary from the Beamr instance's native memory at a given offset + and of a given size.
read_string/2Simple helper function to read a string from the Beamr instance's native + memory at a given offset.
size/1Get the size (in bytes) of the native memory allocated in the Beamr + instance.
write/3Write a binary to the Beamr instance's native memory at a given offset.
write_string/2Simple helper function to allocate space for (via malloc) and write a + string to the Beamr instance's native memory.
+ +

Function Details

+ +

free/2

+
+

free(WASM, Ptr) -> any()

+

+

Free space allocated in the Beamr instance's native memory via a + call to the exported free function from the WASM.

+ +

malloc/2

+
+

malloc(WASM, Size) -> any()

+

+

Allocate space for (via an exported malloc function from the WASM) in + the Beamr instance's native memory.

+ +

read/3

+
+

read(WASM, Offset, Size) -> any()

+

+

Read a binary from the Beamr instance's native memory at a given offset + and of a given size.

+ +

read_string/2

+
+

read_string(Port, Offset) -> any()

+

+

Simple helper function to read a string from the Beamr instance's native + memory at a given offset. Memory is read by default in chunks of 8 bytes, + but this can be overridden by passing a different chunk size. Strings are + assumed to be null-terminated.

+ +

size/1

+
+

size(WASM) -> any()

+

+

Get the size (in bytes) of the native memory allocated in the Beamr + instance. Note that WASM memory can never be reduced once granted to an + instance (although it can, of course, be reallocated _inside_ the + environment).

+ +

write/3

+
+

write(WASM, Offset, Data) -> any()

+

+

Write a binary to the Beamr instance's native memory at a given offset.

+ +

write_string/2

+
+

write_string(WASM, Data) -> any()

+

+

Simple helper function to allocate space for (via malloc) and write a + string to the Beamr instance's native memory. This can be helpful for easily + pushing a string into the instance, such that the resulting pointer can be + passed to exported functions from the instance. + Assumes that the input is either an iolist or a binary, adding a null byte + to the end of the string.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_cache.html b/doc/hb_cache.html new file mode 100644 index 00000000..a4f7dbe0 --- /dev/null +++ b/doc/hb_cache.html @@ -0,0 +1,128 @@ + + + + +Module hb_cache + + + +
Overviewerlang logo
+
+ +

Module hb_cache

+A cache of Converge Protocol messages and compute results. + + +

Description

A cache of Converge Protocol messages and compute results.

+ +

HyperBEAM stores all paths in key value stores, abstracted by the hb_store +module. Each store has its own storage backend, but each works with simple +key-value pairs. Each store can write binary keys at paths, and link between +paths.

+ +

There are three layers to HyperBEAMs internal data representation on-disk:

+ +

1. The raw binary data, written to the store at the hash of the content. +Storing binary paths in this way effectively deduplicates the data. +2. The hashpath-graph of all content, stored as a set of links between +hashpaths, their keys, and the data that underlies them. This allows +all messages to share the same hashpath space, such that all requests +from users additively fill-in the hashpath space, minimizing duplicated +compute. +3. Messages, referrable by their IDs (attested or unattested). These are +stored as a set of links attestation IDs and the unattested message.

+ + Before writing a message to the store, we convert it to Type-Annotated + Binary Messages (TABMs), such that each of the keys in the message is + either a map or a direct binary. +

Function Index

+ + + + + + + + + + +
link/3Make a link from one path to another in the store.
list/2List all items under a given path.
list_numbered/2
read/2Read the message at a path.
read_output/3Read the output of a computation, given Msg1, Msg2, and some options.
test_signed/1
test_unsigned/1
write/2Write a message to the cache.
write_binary/3Write a raw binary keys into the store and link it at a given hashpath.
write_hashpath/2Write a hashpath and its message to the store and link it.
+ +

Function Details

+ +

link/3

+
+

link(Existing, New, Opts) -> any()

+

+

Make a link from one path to another in the store. + Note: Argument order is link(Src, Dst, Opts).

+ +

list/2

+
+

list(Path, Opts) -> any()

+

+

List all items under a given path.

+ +

list_numbered/2

+
+

list_numbered(Path, Opts) -> any()

+

+
+ +

read/2

+
+

read(Path, Opts) -> any()

+

+

Read the message at a path. Returns in 'structured@1.0' format: Either a + richly typed map or a direct binary.

+ +

read_output/3

+
+

read_output(MsgID1, MsgID2, Opts) -> any()

+

+

Read the output of a computation, given Msg1, Msg2, and some options.

+ +

test_signed/1

+
+

test_signed(Data) -> any()

+

+
+ +

test_unsigned/1

+
+

test_unsigned(Data) -> any()

+

+
+ +

write/2

+
+

write(RawMsg, Opts) -> any()

+

+

Write a message to the cache. For raw binaries, we write the data at + the hashpath of the data (by default the SHA2-256 hash of the data). We link + the unattended ID's hashpath for the keys (including /attestations) on the + message to the underlying data and recurse. We then link each attestation ID + to the unattested message, such that any of the attested or unattested IDs + can be read, and once in memory all of the attestations are available. For + deep messages, the attestations will also be read, such that the ID of the + outer message (which does not include its attestations) will be built upon + the attestations of the inner messages. We do not, however, store the IDs from + attestations on signed _inner_ messages. We may wish to revisit this.

+ +

write_binary/3

+
+

write_binary(Hashpath, Bin, Opts) -> any()

+

+

Write a raw binary keys into the store and link it at a given hashpath.

+ +

write_hashpath/2

+
+

write_hashpath(Msg, Opts) -> any()

+

+

Write a hashpath and its message to the store and link it.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_cache_control.html b/doc/hb_cache_control.html new file mode 100644 index 00000000..264e190e --- /dev/null +++ b/doc/hb_cache_control.html @@ -0,0 +1,56 @@ + + + + +Module hb_cache_control + + + +
Overviewerlang logo
+
+ +

Module hb_cache_control

+Cache control logic for the Converge resolver. + + +

Description

Cache control logic for the Converge resolver. It derives cache settings + from request, response, execution-local node Opts, as well as the global + node Opts. It applies these settings when asked to maybe store/lookup in + response to a request. +

Function Index

+ + +
maybe_lookup/3Handles cache lookup, modulated by the caching options requested by + the user.
maybe_store/4Write a resulting M3 message to the cache if requested.
+ +

Function Details

+ +

maybe_lookup/3

+
+

maybe_lookup(Msg1, Msg2, Opts) -> any()

+

+

Handles cache lookup, modulated by the caching options requested by + the user. Honors the following Opts cache keys: + only_if_cached: If set and we do not find a result in the cache, + return an error with a Cache-Status of miss and + a 504 Status. + no_cache: If set, the cached values are never used. Returns + continue to the caller.

+ +

maybe_store/4

+
+

maybe_store(Msg1, Msg2, Msg3, Opts) -> any()

+

+

Write a resulting M3 message to the cache if requested. The precidence + order of cache control sources is as follows: + 1. The Opts map (letting the node operator have the final say). + 2. The Msg3 results message (granted by Msg1's device). + 3. The Msg2 message (the user's request). + Msg1 is not used, such that it can specify cache control information about + itself, without affecting its outputs.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_cache_render.html b/doc/hb_cache_render.html new file mode 100644 index 00000000..c79f019b --- /dev/null +++ b/doc/hb_cache_render.html @@ -0,0 +1,61 @@ + + + + +Module hb_cache_render + + + +
Overviewerlang logo
+
+ +

Module hb_cache_render

+A module that helps to render given Key graphs into the .dot files. + + +

Description

A module that helps to render given Key graphs into the .dot files +

Function Index

+ + + + + +
prepare_deeply_nested_complex_message/0
prepare_signed_data/0
prepare_unsigned_data/0
render/1Render the given Key into svg.
render/3
+ +

Function Details

+ +

prepare_deeply_nested_complex_message/0

+
+

prepare_deeply_nested_complex_message() -> any()

+

+
+ +

prepare_signed_data/0

+
+

prepare_signed_data() -> any()

+

+
+ +

prepare_unsigned_data/0

+
+

prepare_unsigned_data() -> any()

+

+
+ +

render/1

+
+

render(StartKeys) -> any()

+

+

Render the given Key into svg

+ +

render/3

+
+

render(IoDevice, Store, Key) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_client.html b/doc/hb_client.html new file mode 100644 index 00000000..514a65f3 --- /dev/null +++ b/doc/hb_client.html @@ -0,0 +1,70 @@ + + + + +Module hb_client + + + +
Overviewerlang logo
+
+ +

Module hb_client

+ + + +

Function Index

+ + + + + + +
add_route/3
arweave_timestamp/0Grab the latest block information from the Arweave gateway node.
download/1Download the data associated with a given ID.
resolve/4Resolve a message pair on a remote node.
routes/2
upload/1Upload a data item to the bundler node.
+ +

Function Details

+ +

add_route/3

+
+

add_route(Node, Route, Opts) -> any()

+

+
+ +

arweave_timestamp/0

+
+

arweave_timestamp() -> any()

+

+

Grab the latest block information from the Arweave gateway node.

+ +

download/1

+
+

download(ID) -> any()

+

+

Download the data associated with a given ID. See TODO below.

+ +

resolve/4

+
+

resolve(Node, Msg1, Msg2, Opts) -> any()

+

+

Resolve a message pair on a remote node. + The message pair is first transformed into a singleton request, by + prefixing the keys in both messages for the path segment that they relate to, + and then adjusting the "Path" field from the second message.

+ +

routes/2

+
+

routes(Node, Opts) -> any()

+

+
+ +

upload/1

+
+

upload(HyperbeamMsg) -> any()

+

+

Upload a data item to the bundler node.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_converge.html b/doc/hb_converge.html new file mode 100644 index 00000000..0b4b8de6 --- /dev/null +++ b/doc/hb_converge.html @@ -0,0 +1,379 @@ + + + + +Module hb_converge + + + +
Overviewerlang logo
+
+ +

Module hb_converge

+This module is the root of the device call logic of the +Converge Protocol in HyperBEAM. + + +

Description

This module is the root of the device call logic of the +Converge Protocol in HyperBEAM.

+ +

At the implementation level, every message is simply a collection of keys, + dictated by its Device, that can be resolved in order to yield their +values. Each key may return another message or a raw value:

+ +

converge(Message1, Message2) -> {Status, Message3}

+ +

Under-the-hood, Converge(Message1, Message2) leads to the evaluation of + DeviceMod:PathPart(Message1, Message2), which defines the user compute + to be performed. If Message1 does not specify a device, dev_message is + assumed. The key to resolve is specified by the Path field of the message.

+ +

After each output, the HashPath is updated to include the Message2 +that was executed upon it.

+ +

Because each message implies a device that can resolve its keys, as well + as generating a merkle tree of the computation that led to the result, + you can see Converge Protocol as a system for cryptographically chaining + the execution of combinators. See docs/converge-protocol.md for more +information about Converge.

+ +

The Fun(Message1, Message2) pattern is repeated throughout the HyperBEAM + codebase, sometimes with MessageX replaced with MX or MsgX for brevity.

+ +

Message3 can be either a new message or a raw output value (a binary, integer, +float, atom, or list of such values).

+ +

Devices can be expressed as either modules or maps. They can also be + referenced by an Arweave ID, which can be used to load a device from + the network (depending on the value of the load_remote_devices and + trusted_device_signers environment settings).

+ + HyperBEAM device implementations are defined as follows: + 
       DevMod:ExportedFunc : Key resolution functions. All are assumed to be
+                             device keys (thus, present in every message that
+                             uses it) unless specified by `DevMod:info()'.
+                             Each function takes a set of parameters
+                             of the form `DevMod:KeyHandler(Msg1, Msg2, Opts)'.
+                             Each of these arguments can be ommitted if not
+                             needed. Non-exported functions are not assumed
+                             to be device keys.
+  
+       DevMod:info : Optional. Returns a map of options for the device. All
+                     options are optional and assumed to be the defaults if
+                     not specified. This function can accept a `Message1' as
+                     an argument, allowing it to specify its functionality
+                     based on a specific message if appropriate.
+  
+       info/exports : Overrides the export list of the Erlang module, such that
+                     only the functions in this list are assumed to be device
+                     keys. Defaults to all of the functions that DevMod
+                     exports in the Erlang environment.
+  
+       info/excludes : A list of keys that should not be resolved by the device,
+                       despite being present in the Erlang module exports list.
+  
+       info/handler : A function that should be used to handle _all_ keys for
+                      messages using the device.
+  
+       info/default : A function that should be used to handle all keys that
+                      are not explicitly implemented by the device. Defaults to
+                      the `dev_message' device, which contains general keys for
+                      interacting with messages.
+  
+       info/default_mod : A different device module that should be used to
+                      handle all keys that are not explicitly implemented
+                      by the device. Defaults to the `dev_message' device.
+  
+       info/grouper : A function that returns the concurrency 'group' name for
+                      an execution. Executions with the same group name will
+                      be executed by sending a message to the associated process
+                      and waiting for a response. This allows you to control
+                      concurrency of execution and to allow executions to share
+                      in-memory state as applicable. Default: A derivation of
+                      Msg1+Msg2. This means that concurrent calls for the same
+                      output will lead to only a single execution.
+  
+       info/worker : A function that should be run as the 'server' loop of
+                     the executor for interactions using the device.
+  
+   The HyperBEAM resolver also takes a number of runtime options that change
+   the way that the environment operates:
+  
+   `update_hashpath':  Whether to add the `Msg2' to `HashPath' for the `Msg3'.
+   					Default: true.
+   `add_key':          Whether to add the key to the start of the arguments.
+   					Default: `<not set>'.
+

Function Index

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
deep_set/4Recursively search a map, resolving keys, and set the value of the key + at the given path.
find_exported_function/5Find the function with the highest arity that has the given name, if it +exists.
get/2Shortcut for resolving a key in a message without its status if it is + ok.
get/3
get/4
get_first/2take a sequence of base messages and paths, then return the value of the + first message that can be resolved using a path.
get_first/3
info/2Get the info map for a device, optionally giving it a message if the + device's info function is parameterized by one.
is_exported/4Check if a device is guarding a key via its exports list.
keys/1Shortcut to get the list of keys from a message.
keys/2
keys/3
load_device/2Load a device module from its name or a message ID.
message_to_device/2Extract the device module from a message.
message_to_fun/3Calculate the Erlang function that should be called to get a value for +a given key from a device.
normalize_key/1Convert a key to a binary in normalized form.
normalize_key/2
normalize_keys/1Ensure that a message is processable by the Converge resolver: No lists.
remove/2Remove a key from a message, using its underlying device.
remove/3
resolve/2Get the value of a message's key by running its associated device + function.
resolve/3
resolve_many/2Resolve a list of messages in sequence.
set/2Shortcut for setting a key in the message using its underlying device.
set/3
set/4
truncate_args/2Truncate the arguments of a function to the number of arguments it + actually takes.
+ +

Function Details

+ +

deep_set/4

+
+

deep_set(Msg, Rest, Value, Opts) -> any()

+

+

Recursively search a map, resolving keys, and set the value of the key + at the given path.

+ +

find_exported_function/5

+
+

find_exported_function(Msg, Dev, Key, MaxArity, Opts) -> any()

+

+

Find the function with the highest arity that has the given name, if it +exists.

+ +

If the device is a module, we look for a function with the given name.

+ + If the device is a map, we look for a key in the map. First we try to find + the key using its literal value. If that fails, we cast the key to an atom + and try again.

+ +

get/2

+
+

get(Path, Msg) -> any()

+

+

Shortcut for resolving a key in a message without its status if it is + ok. This makes it easier to write complex logic on top of messages while +maintaining a functional style.

+ +

Additionally, this function supports the {as, Device, Msg} syntax, which + allows the key to be resolved using another device to resolve the key, + while maintaining the tracability of the HashPath of the output message.

+ + Returns the value of the key if it is found, otherwise returns the default + provided by the user, or not_found if no default is provided.

+ +

get/3

+
+

get(Path, Msg, Opts) -> any()

+

+
+ +

get/4

+
+

get(Path, Msg, Default, Opts) -> any()

+

+
+ +

get_first/2

+
+

get_first(Paths, Opts) -> any()

+

+

take a sequence of base messages and paths, then return the value of the + first message that can be resolved using a path.

+ +

get_first/3

+
+

get_first(Msgs, Default, Opts) -> any()

+

+
+ +

info/2

+
+

info(Msg, Opts) -> any()

+

+

Get the info map for a device, optionally giving it a message if the + device's info function is parameterized by one.

+ +

is_exported/4

+
+

is_exported(Msg, Dev, Key, Opts) -> any()

+

+

Check if a device is guarding a key via its exports list. Defaults to + true if the device does not specify an exports list. The info function is + always exported, if it exists. Elements of the exludes list are not + exported. Note that we check for info _twice_ -- once when the device is + given but the info result is not, and once when the info result is given. + The reason for this is that info/3 calls other functions that may need to + check if a key is exported, so we must avoid infinite loops. We must, however, + also return a consistent result in the case that only the info result is + given, so we check for it in both cases.

+ +

keys/1

+
+

keys(Msg) -> any()

+

+

Shortcut to get the list of keys from a message.

+ +

keys/2

+
+

keys(Msg, Opts) -> any()

+

+
+ +

keys/3

+
+

keys(Msg, Opts, X3) -> any()

+

+
+ +

load_device/2

+
+

load_device(Map, Opts) -> any()

+

+

Load a device module from its name or a message ID. + Returns {ok, Executable} where Executable is the device module. On error, + a tuple of the form {error, Reason} is returned.

+ +

message_to_device/2

+
+

message_to_device(Msg, Opts) -> any()

+

+

Extract the device module from a message.

+ +

message_to_fun/3

+
+

message_to_fun(Msg, Key, Opts) -> any()

+

+

Calculate the Erlang function that should be called to get a value for +a given key from a device.

+ +

This comes in 7 forms: + 1. The message does not specify a device, so we use the default device. + 2. The device has a handler key in its Dev:info() map, which is a + function that takes a key and returns a function to handle that key. We pass + the key as an additional argument to this function. + 3. The device has a function of the name Key, which should be called +directly. +4. The device does not implement the key, but does have a default handler +for us to call. We pass it the key as an additional argument. +5. The device does not implement the key, and has no default handler. We use +the default device to handle the key. +Error: If the device is specified, but not loadable, we raise an error.

+ + Returns {ok | add_key, Fun} where Fun is the function to call, and add_key + indicates that the key should be added to the start of the call's arguments.

+ +

normalize_key/1

+
+

normalize_key(Key) -> any()

+

+

Convert a key to a binary in normalized form.

+ +

normalize_key/2

+
+

normalize_key(Key, Opts) -> any()

+

+
+ +

normalize_keys/1

+
+

normalize_keys(Msg1) -> any()

+

+

Ensure that a message is processable by the Converge resolver: No lists.

+ +

remove/2

+
+

remove(Msg, Key) -> any()

+

+

Remove a key from a message, using its underlying device.

+ +

remove/3

+
+

remove(Msg, Key, Opts) -> any()

+

+
+ +

resolve/2

+
+

resolve(SingletonMsg, Opts) -> any()

+

+

Get the value of a message's key by running its associated device + function. Optionally, takes options that control the runtime environment. + This function returns the raw result of the device function call: + {ok | error, NewMessage}. + The resolver is composed of a series of discrete phases: + 1: Normalization. + 2: Cache lookup. + 3: Validation check. + 4: Persistent-resolver lookup. + 5: Device lookup. + 6: Execution. + 7: Cryptographic linking. + 8: Result caching. + 9: Notify waiters. + 10: Fork worker. + 11: Recurse or terminate.

+ +

resolve/3

+
+

resolve(Msg1, Path, Opts) -> any()

+

+
+ +

resolve_many/2

+
+

resolve_many(MsgList, Opts) -> any()

+

+

Resolve a list of messages in sequence. Take the output of the first + message as the input for the next message. Once the last message is resolved, + return the result.

+ +

set/2

+
+

set(Msg1, Msg2) -> any()

+

+

Shortcut for setting a key in the message using its underlying device. + Like the get/3 function, this function honors the error_strategy option. + set works with maps and recursive paths while maintaining the appropriate + HashPath for each step.

+ +

set/3

+
+

set(RawMsg1, RawMsg2, Opts) -> any()

+

+
+ +

set/4

+
+

set(Msg1, Key, Value, Opts) -> any()

+

+
+ +

truncate_args/2

+
+

truncate_args(Fun, Args) -> any()

+

+

Truncate the arguments of a function to the number of arguments it + actually takes.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_converge_test_vectors.html b/doc/hb_converge_test_vectors.html new file mode 100644 index 00000000..f3916e99 --- /dev/null +++ b/doc/hb_converge_test_vectors.html @@ -0,0 +1,23 @@ + + + + +Module hb_converge_test_vectors + + + +
Overviewerlang logo
+
+ +

Module hb_converge_test_vectors

+Tests for the core Converge resolution engine. + + +

Description

Tests for the core Converge resolution engine. + Uses a series of different Opts values to test the resolution engine's + execution under different circumstances.
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_crypto.html b/doc/hb_crypto.html new file mode 100644 index 00000000..e20c9c0a --- /dev/null +++ b/doc/hb_crypto.html @@ -0,0 +1,62 @@ + + + + +Module hb_crypto + + + +
Overviewerlang logo
+
+ +

Module hb_crypto

+Implements the cryptographic functions and wraps the primitives +used in HyperBEAM. + + +

Description

Implements the cryptographic functions and wraps the primitives +used in HyperBEAM. Abstracted such that this (extremely!) dangerous code +can be carefully managed.

+ +

HyperBEAM currently implements two hashpath algorithms:

+ +

* sha-256-chain: A simple chained SHA-256 hash.

+ +

* accumulate-256: A SHA-256 hash that chains the given IDs and accumulates +their values into a single commitment.

+ + The accumulate algorithm is experimental and at this point only exists to + allow us to test multiple HashPath algorithms in HyperBEAM. +

Function Index

+ + + +
accumulate/2Accumulate two IDs into a single commitment.
sha256/1Wrap Erlang's crypto:hash/2 to provide a standard interface.
sha256_chain/2Add a new ID to the end of a SHA-256 hash chain.
+ +

Function Details

+ +

accumulate/2

+
+

accumulate(ID1, ID2) -> any()

+

+

Accumulate two IDs into a single commitment. + Experimental! This is not necessarily a cryptographically-secure operation.

+ +

sha256/1

+
+

sha256(Data) -> any()

+

+

Wrap Erlang's crypto:hash/2 to provide a standard interface. + Under-the-hood, this uses OpenSSL.

+ +

sha256_chain/2

+
+

sha256_chain(ID1, ID2) -> any()

+

+

Add a new ID to the end of a SHA-256 hash chain.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_examples.html b/doc/hb_examples.html new file mode 100644 index 00000000..64954124 --- /dev/null +++ b/doc/hb_examples.html @@ -0,0 +1,24 @@ + + + + +Module hb_examples + + + +
Overviewerlang logo
+
+ +

Module hb_examples

+This module contains end-to-end tests for Hyperbeam, accessing through + the HTTP interface. + + +

Description

This module contains end-to-end tests for Hyperbeam, accessing through + the HTTP interface. As well as testing the system, you can use these tests + as examples of how to interact with HyperBEAM nodes.
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_http.html b/doc/hb_http.html new file mode 100644 index 00000000..e871b695 --- /dev/null +++ b/doc/hb_http.html @@ -0,0 +1,121 @@ + + + + +Module hb_http + + + +
Overviewerlang logo
+
+ +

Module hb_http

+ + + +

Function Index

+ + + + + + + + + + + + + +
get/2Gets a URL via HTTP and returns the resulting message in deserialized + form.
get/3
message_to_status/1Get the HTTP status code from a transaction (if it exists).
post/3Posts a message to a URL on a remote peer via HTTP.
post/4
reply/3Reply to the client's HTTP request with a message.
reply/4
req_to_tabm_singleton/2Convert a cowboy request to a normalized message.
request/2Posts a binary to a URL on a remote peer via HTTP, returning the raw + binary body.
request/4
request/5
start/0
status_code/1Convert an HTTP status code to an atom.
+ +

Function Details

+ +

get/2

+
+

get(Node, Opts) -> any()

+

+

Gets a URL via HTTP and returns the resulting message in deserialized + form.

+ +

get/3

+
+

get(Node, PathBin, Opts) -> any()

+

+
+ +

message_to_status/1

+
+

message_to_status(Item) -> any()

+

+

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

+ +

post/3

+
+

post(Node, Message, Opts) -> any()

+

+

Posts a message to a URL on a remote peer via HTTP. Returns the + resulting message in deserialized form.

+ +

post/4

+
+

post(Node, Path, Message, Opts) -> any()

+

+
+ +

reply/3

+
+

reply(Req, Message, Opts) -> any()

+

+

Reply to the client's HTTP request with a message.

+ +

reply/4

+
+

reply(Req, Status, RawMessage, Opts) -> any()

+

+
+ +

req_to_tabm_singleton/2

+
+

req_to_tabm_singleton(Req, Opts) -> any()

+

+

Convert a cowboy request to a normalized message.

+ +

request/2

+
+

request(Message, Opts) -> any()

+

+

Posts a binary to a URL on a remote peer via HTTP, returning the raw + binary body.

+ +

request/4

+
+

request(Method, Peer, Path, Opts) -> any()

+

+
+ +

request/5

+
+

request(Method, Config, Path, Message, Opts) -> any()

+

+
+ +

start/0

+
+

start() -> any()

+

+
+ +

status_code/1

+
+

status_code(Status) -> any()

+

+

Convert an HTTP status code to an atom.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_http_benchmark_tests.html b/doc/hb_http_benchmark_tests.html new file mode 100644 index 00000000..cdf87ae5 --- /dev/null +++ b/doc/hb_http_benchmark_tests.html @@ -0,0 +1,20 @@ + + + + +Module hb_http_benchmark_tests + + + +
Overviewerlang logo
+
+ +

Module hb_http_benchmark_tests

+ + +
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_http_server.html b/doc/hb_http_server.html new file mode 100644 index 00000000..55f3a164 --- /dev/null +++ b/doc/hb_http_server.html @@ -0,0 +1,96 @@ + + + + +Module hb_http_server + + + +
Overviewerlang logo
+
+ +

Module hb_http_server

+A router that attaches a HTTP server to the Converge resolver. + + +

Description

A router that attaches a HTTP server to the Converge resolver. +Because Converge is built to speak in HTTP semantics, this module +only has to marshal the HTTP request into a message, and then +pass it to the Converge resolver.

+ +

hb_http:reply/4 is used to respond to the client, handling the +process of converting a message back into an HTTP response.

+ + The router uses an Opts message as its Cowboy initial state, + such that changing it on start of the router server allows for + the execution parameters of all downstream requests to be controlled. +

Function Index

+ + + + + + + + +
allowed_methods/2
get_opts/1
init/2
set_opts/1Update the Opts map that the HTTP server uses for all future + requests.
start/0Starts the HTTP server.
start/1
start_node/0Test that we can start the server, send a message, and get a response.
start_node/1
+ +

Function Details

+ +

allowed_methods/2

+
+

allowed_methods(Req, State) -> any()

+

+
+ +

get_opts/1

+
+

get_opts(NodeMsg) -> any()

+

+
+ +

init/2

+
+

init(Req, ServerID) -> any()

+

+
+ +

set_opts/1

+
+

set_opts(Opts) -> any()

+

+

Update the Opts map that the HTTP server uses for all future + requests.

+ +

start/0

+
+

start() -> any()

+

+

Starts the HTTP server. Optionally accepts an Opts message, which + is used as the source for server configuration settings, as well as the + Opts argument to use for all Converge resolution requests downstream.

+ +

start/1

+
+

start(Opts) -> any()

+

+
+ +

start_node/0

+
+

start_node() -> any()

+

+

Test that we can start the server, send a message, and get a response.

+ +

start_node/1

+
+

start_node(Opts) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_logger.html b/doc/hb_logger.html new file mode 100644 index 00000000..81ab7541 --- /dev/null +++ b/doc/hb_logger.html @@ -0,0 +1,60 @@ + + + + +Module hb_logger + + + +
Overviewerlang logo
+
+ +

Module hb_logger

+ + + +

Function Index

+ + + + + +
log/2
register/1
report/1
start/0
start/1
+ +

Function Details

+ +

log/2

+
+

log(Monitor, Data) -> any()

+

+
+ +

register/1

+
+

register(Monitor) -> any()

+

+
+ +

report/1

+
+

report(Monitor) -> any()

+

+
+ +

start/0

+
+

start() -> any()

+

+
+ +

start/1

+
+

start(Client) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_message.html b/doc/hb_message.html new file mode 100644 index 00000000..ab37af04 --- /dev/null +++ b/doc/hb_message.html @@ -0,0 +1,261 @@ + + + + +Module hb_message + + + +
Overviewerlang logo
+
+ +

Module hb_message

+This module acts an adapter between messages, as modeled in the +Converge Protocol, and their uderlying binary representations and formats. + + +

Description

This module acts an adapter between messages, as modeled in the +Converge Protocol, and their uderlying binary representations and formats.

+ +

Unless you are implementing a new message serialization codec, you should + not need to interact with this module directly. Instead, use the + hb_converge interfaces to interact with all messages. The dev_message +module implements a device interface for abstracting over the different +message formats.

+ +

hb_message and the HyperBEAM caches can interact with multiple different +types of message formats:

+ +

- Richly typed Converge structured messages. +- Arweave transations. +- ANS-104 data items. +- HTTP Signed Messages. +- Flat Maps.

+ +

This module is responsible for converting between these formats. It does so + by normalizing messages to a common format: Type Annotated Binary Messages` + (TABM). TABMs are deep Erlang maps with keys than only contain either other + TABMs or binary values. By marshalling all messages into this format, they + can easily be coerced into other output formats. For example, generating a + `HTTP Signed Message` format output from an Arweave transaction. TABM is + also a simple format from a computational perspective (only binary literals + and O(1) access maps), such that operations upon them are efficient. + + The structure of the conversions is as follows: + + ``` + Arweave TX/ANS-104 ==> dev_codec_ans104:from/1 ==> TABM + HTTP Signed Message ==> dev_codec_httpsig_conv:from/1 ==> TABM + Flat Maps ==> dev_codec_flat:from/1 ==> TABM + + TABM ==> dev_codec_structured:to/1 ==> Converge Message + Converge Message ==> dev_codec_structured:from/1 ==> TABM + + TABM ==> dev_codec_ans104:to/1 ==> Arweave TX/ANS-104 + TABM ==> dev_codec_httpsig_conv:to/1 ==> HTTP Signed Message + TABM ==> dev_codec_flat:to/1 ==> Flat Maps + ...''

+ +

Additionally, this module provides a number of utility functions for + manipulating messages. For example, hb_message:sign/2 to sign a message of + arbitrary type, or hb_message:format/1 to print a Converge/TABM message in +a human-readable format.

+ + The hb_cache module is responsible for storing and retrieving messages in + the HyperBEAM stores configured on the node. Each store has its own storage + backend, but each works with simple key-value pairs. Subsequently, the + hb_cache module uses TABMs as the internal format for storing and + retrieving messages. +

Function Index

+ + + + + + + + + + + + + + + + + + + + + + +
attest/2Sign a message with the given wallet.
attest/3
convert/3Convert a message from one format to another.
convert/4
default_tx_list/0Get the ordered list of fields as Converge keys and default values of + the tx record.
filter_default_keys/1Remove keys from a map that have the default values found in the tx + record.
find_target/3Implements a standard pattern in which the target for an operation is + found by looking for a target key in the request.
format/1Format a message for printing, optionally taking an indentation level + to start from.
format/2
from_tabm/3
id/1Return the ID of a message.
id/2
id/3
match/2Check if two maps match, including recursively checking nested maps.
match/3
minimize/1Remove keys from the map that can be regenerated.
print/1Pretty-print a message.
signers/1Return all of the attestors on a message that have 'normal', 256 bit, + addresses.
to_tabm/3
type/1Return the type of an encoded message.
unattested/1Return the unsigned version of a message in Converge format.
verify/1wrapper function to verify a message.
+ +

Function Details

+ +

attest/2

+
+

attest(Msg, WalletOrOpts) -> any()

+

+

Sign a message with the given wallet. Only supports the tx format + at the moment.

+ +

attest/3

+
+

attest(Msg, Opts, Format) -> any()

+

+
+ +

convert/3

+
+

convert(Msg, TargetFormat, Opts) -> any()

+

+

Convert a message from one format to another. Taking a message in the + source format, a target format, and a set of opts. If not given, the source + is assumed to be converge`. Additional codecs can be added by ensuring they + are part of the `Opts` map -- either globally, or locally for a computation. + + The encoding happens in two phases: + 1. Convert the message to a TABM. + 2. Convert the TABM to the target format. + + The conversion to a TABM is done by the `converge codec, which is always + available. The conversion from a TABM is done by the target codec.

+ +

convert/4

+
+

convert(Msg, TargetFormat, SourceFormat, Opts) -> any()

+

+
+ +

default_tx_list/0

+
+

default_tx_list() -> any()

+

+

Get the ordered list of fields as Converge keys and default values of + the tx record.

+ +

filter_default_keys/1

+
+

filter_default_keys(Map) -> any()

+

+

Remove keys from a map that have the default values found in the tx + record.

+ +

find_target/3

+
+

find_target(Self, Req, Opts) -> any()

+

+

Implements a standard pattern in which the target for an operation is + found by looking for a target key in the request. If the target is self, + or not present, the operation is performed on the original message. Otherwise, + the target is expected to be a key in the message, and the operation is + performed on the value of that key.

+ +

format/1

+
+

format(Item) -> any()

+

+

Format a message for printing, optionally taking an indentation level + to start from.

+ +

format/2

+
+

format(Bin, Indent) -> any()

+

+
+ +

from_tabm/3

+
+

from_tabm(Msg, TargetFormat, Opts) -> any()

+

+
+ +

id/1

+
+

id(Msg) -> any()

+

+

Return the ID of a message.

+ +

id/2

+
+

id(Msg, Attestors) -> any()

+

+
+ +

id/3

+
+

id(Msg, RawAttestors, Opts) -> any()

+

+
+ +

match/2

+
+

match(Map1, Map2) -> any()

+

+

Check if two maps match, including recursively checking nested maps. + Takes an optional mode argument to control the matching behavior: + strict: All keys in both maps be present and match. + only_present: Only present keys in both maps must match. + primary: Only the primary map's keys must be present.

+ +

match/3

+
+

match(Map1, Map2, Mode) -> any()

+

+
+ +

minimize/1

+
+

minimize(Msg) -> any()

+

+

Remove keys from the map that can be regenerated. Optionally takes an + additional list of keys to include in the minimization.

+ +

print/1

+
+

print(Msg) -> any()

+

+

Pretty-print a message.

+ +

signers/1

+
+

signers(Msg) -> any()

+

+

Return all of the attestors on a message that have 'normal', 256 bit, + addresses.

+ +

to_tabm/3

+
+

to_tabm(Msg, SourceFormat, Opts) -> any()

+

+
+ +

type/1

+
+

type(TX) -> any()

+

+

Return the type of an encoded message.

+ +

unattested/1

+
+

unattested(Bin) -> any()

+

+

Return the unsigned version of a message in Converge format.

+ +

verify/1

+
+

verify(Msg) -> any()

+

+

wrapper function to verify a message.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_metrics_collector.html b/doc/hb_metrics_collector.html new file mode 100644 index 00000000..832420d3 --- /dev/null +++ b/doc/hb_metrics_collector.html @@ -0,0 +1,47 @@ + + + + +Module hb_metrics_collector + + + +
Overviewerlang logo
+
+ +

Module hb_metrics_collector

+ + +

Behaviours: prometheus_collector.

+ +

Function Index

+ + + +
collect_metrics/2
collect_mf/2
deregister_cleanup/1
+ +

Function Details

+ +

collect_metrics/2

+
+

collect_metrics(X1, SystemLoad) -> any()

+

+
+ +

collect_mf/2

+
+

collect_mf(Registry, Callback) -> any()

+

+
+ +

deregister_cleanup/1

+
+

deregister_cleanup(X1) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_opts.html b/doc/hb_opts.html new file mode 100644 index 00000000..0394cebf --- /dev/null +++ b/doc/hb_opts.html @@ -0,0 +1,75 @@ + + + + +Module hb_opts + + + +
Overviewerlang logo
+
+ +

Module hb_opts

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

Description

A module for interacting with local and global options inside + HyperBEAM. 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

+ + + + +
default_message/0The default configuration options of the hyperbeam node.
get/1Get 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
+ +

Function Details

+ +

default_message/0

+
+

default_message() -> any()

+

+

The default configuration options of the hyperbeam node.

+ +

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()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_path.html b/doc/hb_path.html new file mode 100644 index 00000000..87d1115f --- /dev/null +++ b/doc/hb_path.html @@ -0,0 +1,209 @@ + + + + +Module hb_path + + + +
Overviewerlang logo
+
+ +

Module hb_path

+This module provides utilities for manipulating the paths of a + message: Its request path (referred to in messages as just the Path), and +its HashPath. + + +

Description

This module provides utilities for manipulating the paths of a + message: Its request path (referred to in messages as just the Path), and +its HashPath.

+ +

A HashPath is a rolling Merkle list of the messages that have been applied +in order to generate a given message. Because applied messages can +themselves be the result of message applications with the Converge Protocol, +the HashPath can be thought of as the tree of messages that represent the +history of a given message. The initial message on a HashPath is referred to +by its ID and serves as its user-generated 'root'.

+ + Specifically, the HashPath can be generated by hashing the previous HashPath + and the current message. This means that each message in the HashPath is + dependent on all previous messages. + 
       Msg1.HashPath = Msg1.ID
+       Msg3.HashPath = Msg1.Hash(Msg1.HashPath, Msg2.ID)
+       Msg3.{...} = Converge.apply(Msg1, Msg2)
+       ...
+ +

A message's ID itself includes its HashPath, leading to the mixing of +a Msg2's merkle list into the resulting Msg3's HashPath. This allows a single +message to represent a history _tree_ of all of the messages that were +applied to generate it -- rather than just a linear history.

+ + A message may also specify its own algorithm for generating its HashPath, + which allows for custom logic to be used for representing the history of a + message. When Msg2's are applied to a Msg1, the resulting Msg3's HashPath + will be generated according to Msg1's algorithm choice. +

Function Index

+ + + + + + + + + + + + + + + + + + + +
from_message/2Extract the request path or hashpath from a message.
hashpath/2Add an ID of a Msg2 to the HashPath of another message.
hashpath/3
hashpath/4
hashpath_alg/1Get the hashpath function for a message from its HashPath-Alg.
hd/2Extract the first key from a Message2's Path field.
matches/2Check if two keys match.
normalize/1Normalize a path to a binary, removing the leading slash if present.
pop_request/2Pop the next element from a request path or path list.
priv_remaining/2Return the Remaining-Path of a message, from its hidden Converge + key.
priv_store_remaining/2Store the remaining path of a message in its hidden Converge key.
push_request/2Add a message to the head (next to execute) of a request path.
queue_request/2Queue a message at the back of a request path.
regex_matches/2Check if two keys match using regex.
term_to_path_parts/1Convert a term into an executable path.
term_to_path_parts/2
tl/2Return the message without its first path element.
to_binary/1Convert a path of any form to a binary.
verify_hashpath/2Verify the HashPath of a message, given a list of messages that + represent its history.
+ +

Function Details

+ +

from_message/2

+
+

from_message(X1, Msg) -> any()

+

+

Extract the request path or hashpath from a message. We do not use + Converge for this resolution because this function is called from inside Converge + itself. This imparts a requirement: the message's device must store a + viable hashpath and path in its Erlang map at all times, unless the message + is directly from a user (in which case paths and hashpaths will not have + been assigned yet).

+ +

hashpath/2

+
+

hashpath(Bin, Opts) -> any()

+

+

Add an ID of a Msg2 to the HashPath of another message.

+ +

hashpath/3

+
+

hashpath(Msg1, Msg2, Opts) -> any()

+

+
+ +

hashpath/4

+
+

hashpath(Msg1, Msg2, HashpathAlg, Opts) -> any()

+

+
+ +

hashpath_alg/1

+
+

hashpath_alg(Msg) -> any()

+

+

Get the hashpath function for a message from its HashPath-Alg. + If no hashpath algorithm is specified, the protocol defaults to + sha-256-chain.

+ +

hd/2

+
+

hd(Msg2, Opts) -> any()

+

+

Extract the first key from a Message2's Path field. + Note: This function uses the dev_message:get/2 function, rather than + a generic call as the path should always be an explicit key in the message.

+ +

matches/2

+
+

matches(Key1, Key2) -> any()

+

+

Check if two keys match.

+ +

normalize/1

+
+

normalize(Path) -> any()

+

+

Normalize a path to a binary, removing the leading slash if present.

+ +

pop_request/2

+
+

pop_request(Msg, Opts) -> any()

+

+

Pop the next element from a request path or path list.

+ +

priv_remaining/2

+
+

priv_remaining(Msg, Opts) -> any()

+

+

Return the Remaining-Path of a message, from its hidden Converge + key. Does not use the get or set hb_private functions, such that it + can be safely used inside the main Converge resolve function.

+ +

priv_store_remaining/2

+
+

priv_store_remaining(Msg, RemainingPath) -> any()

+

+

Store the remaining path of a message in its hidden Converge key.

+ +

push_request/2

+
+

push_request(Msg, Path) -> any()

+

+

Add a message to the head (next to execute) of a request path.

+ +

queue_request/2

+
+

queue_request(Msg, Path) -> any()

+

+

Queue a message at the back of a request path. path is the only + key that we cannot use dev_message's set/3 function for (as it expects + the compute path to be there), so we use maps:put/3 instead.

+ +

regex_matches/2

+
+

regex_matches(Path1, Path2) -> any()

+

+

Check if two keys match using regex.

+ +

term_to_path_parts/1

+
+

term_to_path_parts(Path) -> any()

+

+

Convert a term into an executable path. Supports binaries, lists, and + atoms. Notably, it does not support strings as lists of characters.

+ +

term_to_path_parts/2

+
+

term_to_path_parts(Binary, Opts) -> any()

+

+
+ +

tl/2

+
+

tl(Msg2, Opts) -> any()

+

+

Return the message without its first path element. Note that this + is the only transformation in Converge that does _not_ make a log of its + transformation. Subsequently, the message's IDs will not be verifiable + after executing this transformation. + This may or may not be the mainnet behavior we want.

+ +

to_binary/1

+
+

to_binary(Path) -> any()

+

+

Convert a path of any form to a binary.

+ +

verify_hashpath/2

+
+

verify_hashpath(Rest, Opts) -> any()

+

+

Verify the HashPath of a message, given a list of messages that + represent its history.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_persistent.html b/doc/hb_persistent.html new file mode 100644 index 00000000..391502d7 --- /dev/null +++ b/doc/hb_persistent.html @@ -0,0 +1,117 @@ + + + + +Module hb_persistent + + + +
Overviewerlang logo
+
+ +

Module hb_persistent

+Creates and manages long-lived Converge resolution processes. + + +

Description

Creates and manages long-lived Converge resolution processes. + These can be useful for situations where a message is large and expensive + to serialize and deserialize, or when executions should be deliberately + serialized to avoid parallel executions of the same computation. This + module is called during the core hb_converge execution process, so care +must be taken to avoid recursive spawns/loops.

+ + Built using the pg module, which is a distributed Erlang process group + manager. +

Function Index

+ + + + + + + + + + +
await/4If there was already an Erlang process handling this execution, + we should register with them and wait for them to notify us of + completion.
default_grouper/3Create a group name from a Msg1 and Msg2 pair as a tuple.
default_worker/3A server function for handling persistent executions.
find_or_register/3Register the process to lead an execution if none is found, otherwise + signal that we should await resolution.
forward_work/2Forward requests to a newly delegated execution process.
group/3Calculate the group name for a Msg1 and Msg2 pair.
notify/4Check our inbox for processes that are waiting for the resolution + of this execution.
start_worker/2Start a worker process that will hold a message in memory for + future executions.
start_worker/3
unregister_notify/4Unregister as the leader for an execution and notify waiting processes.
+ +

Function Details

+ +

await/4

+
+

await(Worker, Msg1, Msg2, Opts) -> any()

+

+

If there was already an Erlang process handling this execution, + we should register with them and wait for them to notify us of + completion.

+ +

default_grouper/3

+
+

default_grouper(Msg1, Msg2, Opts) -> any()

+

+

Create a group name from a Msg1 and Msg2 pair as a tuple.

+ +

default_worker/3

+
+

default_worker(GroupName, Msg1, Opts) -> any()

+

+

A server function for handling persistent executions.

+ +

find_or_register/3

+
+

find_or_register(Msg1, Msg2, Opts) -> any()

+

+

Register the process to lead an execution if none is found, otherwise + signal that we should await resolution.

+ +

forward_work/2

+
+

forward_work(NewPID, Opts) -> any()

+

+

Forward requests to a newly delegated execution process.

+ +

group/3

+
+

group(Msg1, Msg2, Opts) -> any()

+

+

Calculate the group name for a Msg1 and Msg2 pair. Uses the Msg1's + group function if it is found in the info, otherwise uses the default.

+ +

notify/4

+
+

notify(GroupName, Msg2, Msg3, Opts) -> any()

+

+

Check our inbox for processes that are waiting for the resolution + of this execution. Comes in two forms: + 1. Notify on group name alone. + 2. Notify on group name and Msg2.

+ +

start_worker/2

+
+

start_worker(Msg, Opts) -> any()

+

+

Start a worker process that will hold a message in memory for + future executions.

+ +

start_worker/3

+
+

start_worker(GroupName, NotMsg, Opts) -> any()

+

+
+ +

unregister_notify/4

+
+

unregister_notify(GroupName, Msg2, Msg3, Opts) -> any()

+

+

Unregister as the leader for an execution and notify waiting processes.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_private.html b/doc/hb_private.html new file mode 100644 index 00000000..7bf1b44f --- /dev/null +++ b/doc/hb_private.html @@ -0,0 +1,102 @@ + + + + +Module hb_private + + + +
Overviewerlang logo
+
+ +

Module hb_private

+This module provides basic helper utilities for managing the +private element of a message, which can be used to store state that is +not included in serialized messages, or those granted to users via the +APIs. + + +

Description

This module provides basic helper utilities for managing the +private element of a message, which can be used to store state that is +not included in serialized messages, or those granted to users via the +APIs. Private elements of a message can be useful for storing state that +is only relevant temporarily. For example, a device might use the private +element to store a cache of values that are expensive to recompute. They +should _not_ be used for encoding state that makes the execution of a +device non-deterministic (unless you are sure you know what you are doing).

+ + The set` and `get` functions of this module allow you to run those keys + as converge paths if you would like to have private `devices` in the + messages non-public zone. + + See `hb_converge for more information about the Converge Protocol + and private elements of messages. +

Function Index

+ + + + + + + + +
from_message/1Return the private key from a message.
get/3Helper for getting a value from the private element of a message.
get/4
is_private/1Check if a key is private.
reset/1Unset all of the private keys in a message.
set/3
set/4Helper function for setting a key in the private element of a message.
set_priv/2Helper function for setting the complete private element of a message.
+ +

Function Details

+ +

from_message/1

+
+

from_message(Msg) -> any()

+

+

Return the private key from a message. If the key does not exist, an + empty map is returned.

+ +

get/3

+
+

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

+

+

Helper for getting a value from the private element of a message. Uses + Converge resolve under-the-hood, removing the private specifier from the + path if it exists.

+ +

get/4

+
+

get(InputPath, Msg, Default, Opts) -> any()

+

+
+ +

is_private/1

+
+

is_private(Key) -> any()

+

+

Check if a key is private.

+ +

reset/1

+
+

reset(Msg) -> any()

+

+

Unset all of the private keys in a message.

+ +

set/3

+
+

set(Msg, PrivMap, Opts) -> any()

+

+
+ +

set/4

+
+

set(Msg, InputPath, Value, Opts) -> any()

+

+

Helper function for setting a key in the private element of a message.

+ +

set_priv/2

+
+

set_priv(Msg, PrivMap) -> any()

+

+

Helper function for setting the complete private element of a message.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_process_monitor.html b/doc/hb_process_monitor.html new file mode 100644 index 00000000..79044547 --- /dev/null +++ b/doc/hb_process_monitor.html @@ -0,0 +1,53 @@ + + + + +Module hb_process_monitor + + + +
Overviewerlang logo
+
+ +

Module hb_process_monitor

+ + + +

Function Index

+ + + + +
start/1
start/2
start/3
stop/1
+ +

Function Details

+ +

start/1

+
+

start(ProcID) -> any()

+

+
+ +

start/2

+
+

start(ProcID, Rate) -> any()

+

+
+ +

start/3

+
+

start(ProcID, Rate, Cursor) -> any()

+

+
+ +

stop/1

+
+

stop(PID) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_router.html b/doc/hb_router.html new file mode 100644 index 00000000..fc3c47d9 --- /dev/null +++ b/doc/hb_router.html @@ -0,0 +1,39 @@ + + + + +Module hb_router + + + +
Overviewerlang logo
+
+ +

Module hb_router

+ + + +

Function Index

+ + +
find/2
find/3
+ +

Function Details

+ +

find/2

+
+

find(Type, ID) -> any()

+

+
+ +

find/3

+
+

find(Type, ID, Address) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_singleton.html b/doc/hb_singleton.html new file mode 100644 index 00000000..ee29f60f --- /dev/null +++ b/doc/hb_singleton.html @@ -0,0 +1,84 @@ + + + + +Module hb_singleton + + + +
Overviewerlang logo
+
+ +

Module hb_singleton

+A parser that translates Converge HTTP API requests in TABM format + into an ordered list of messages to evaluate. + + +

Description

A parser that translates Converge HTTP API requests in TABM format + into an ordered list of messages to evaluate. The details of this format + are described in docs/converge-http-api.md`. + + Syntax overview: + ``` + Singleton: Message containing keys and a `path` field, + which may also contain a query string of key-value pairs. + + Path: + - /Part1/Part2/.../PartN/ => [Part1, Part2, ..., PartN] + - /ID/Part2/.../PartN => [ID, Part2, ..., PartN] + + Part: (Key + Resolution), Device?, #{ K => V}? + - Part => #{ path => Part } + - Part&Key=Value => #{ path => Part, Key => Value } + - Part&Key => #{ path => Part, Key => true } + - Part&k1=v1&k2=v2 => #{ path => Part, k1 => <<"v1">>, k2 => <<"v2">> } + - Part~Device => {as, Device, #{ path => Part }} + - Part~D&K1=V1 => {as, D, #{ path => Part, K1 => <<"v1">> }} + - pt&k1+int=1 => #{ path => pt, k1 => 1 } + - pt~d&k1+int=1 => {as, d, #{ path => pt, k1 => 1 }} + - (/nested/path) => Resolution of the path /nested/path + - (/nested/path&k1=v1) => (resolve /nested/path)#{k1 => v1} + - (/nested/path~D&K1=V1) => (resolve /nested/path)#{K1 => V1} + - pt&k1+res=(/a/b/c) => #{ path => pt, k1 => (resolve /a/b/c) } + Key: + - key: <<"value">> => #{ key => <<"value">>, ... } for all messages + - n.key: <<"value">> => #{ key => <<"value">>, ... } for Nth message + - key+Int: 1 => #{ key => 1, ... } + - key+Res: /nested/path => #{ key => (resolve /nested/path), ... } + - N.Key+Res=(/a/b/c) => #{ Key => (resolve /a/b/c), ... }'' +

Data Types

+ +

converge_message()

+

converge_message() = map() | binary()

+ + +

tabm_message()

+

tabm_message() = map()

+ + +

Function Index

+ + +
from/1Normalize a singleton TABM message into a list of executable Converge + messages.
to/1Convert a list of converge message into TABM message.
+ +

Function Details

+ +

from/1

+
+

from(RawMsg) -> any()

+

+

Normalize a singleton TABM message into a list of executable Converge + messages.

+ +

to/1

+
+

to(Messages::[converge_message()]) -> tabm_message()

+

+

Convert a list of converge message into TABM message.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_store.html b/doc/hb_store.html new file mode 100644 index 00000000..ebbdc631 --- /dev/null +++ b/doc/hb_store.html @@ -0,0 +1,195 @@ + + + + +Module hb_store + + + +
Overviewerlang logo
+
+ +

Module hb_store

+ + + +

Function Index

+ + + + + + + + + + + + + + + + + + + + + + +
add_path/2Add two path components together.
add_path/3
behavior_info/1
filter/2Takes a store object and a filter function or match spec, returning a + new store object with only the modules that match the filter.
generate_test_suite/1
generate_test_suite/2
join/1Join a list of path components together.
list/2List the keys in a group in the store.
make_group/2Make a group in the store.
make_link/3Make a link from one path to another in the store.
path/1Create a path from a list of path components.
path/2
read/2Read a key from the store.
reset/1Delete all of the keys in a store.
resolve/2Follow links through the store to resolve a path to its ultimate target.
scope/2Limit the store scope to only a specific (set of) option(s).
sort/2Order a store by a preference of its scopes.
start/1
stop/1
test_stores/0
type/2Get the type of element of a given path in the store.
write/3Write a key with a value to the store.
+ +

Function Details

+ +

add_path/2

+
+

add_path(Path1, Path2) -> any()

+

+

Add two path components together. If no store implements the add_path + function, we concatenate the paths.

+ +

add_path/3

+
+

add_path(Store, Path1, Path2) -> any()

+

+
+ +

behavior_info/1

+
+

behavior_info(X1) -> any()

+

+
+ +

filter/2

+
+

filter(Module, Filter) -> any()

+

+

Takes a store object and a filter function or match spec, returning a + new store object with only the modules that match the filter. The filter + function takes 2 arguments: the scope and the options. It calls the store's + scope function to get the scope of the module.

+ +

generate_test_suite/1

+
+

generate_test_suite(Suite) -> any()

+

+
+ +

generate_test_suite/2

+
+

generate_test_suite(Suite, Stores) -> any()

+

+
+ +

join/1

+
+

join(Path) -> any()

+

+

Join a list of path components together.

+ +

list/2

+
+

list(Modules, Path) -> any()

+

+

List the keys in a group in the store. Use only in debugging. + The hyperbeam model assumes that stores are built as efficient hash-based + structures, so this is likely to be very slow for most stores.

+ +

make_group/2

+
+

make_group(Modules, Path) -> any()

+

+

Make a group in the store. A group can be seen as a namespace or + 'directory' in a filesystem.

+ +

make_link/3

+
+

make_link(Modules, Existing, New) -> any()

+

+

Make a link from one path to another in the store.

+ +

path/1

+
+

path(Path) -> any()

+

+

Create a path from a list of path components. If no store implements + the path function, we return the path with the 'default' transformation (id).

+ +

path/2

+
+

path(X1, Path) -> any()

+

+
+ +

read/2

+
+

read(Modules, Key) -> any()

+

+

Read a key from the store.

+ +

reset/1

+
+

reset(Modules) -> any()

+

+

Delete all of the keys in a store. Should be used with extreme + caution. Lost data can lose money in many/most of hyperbeam's use cases.

+ +

resolve/2

+
+

resolve(Modules, Path) -> any()

+

+

Follow links through the store to resolve a path to its ultimate target.

+ +

scope/2

+
+

scope(Store, Scope) -> any()

+

+

Limit the store scope to only a specific (set of) option(s). + Takes either a single scope or a list of scopes.

+ +

sort/2

+
+

sort(Stores, PreferenceOrder) -> any()

+

+

Order a store by a preference of its scopes. This is useful for making + sure that faster (or perhaps cheaper) stores are used first. If a list is + provided, it will be used as a preference order. If a map is provided, + scopes will be ordered by the scores in the map. Any unknown scopes will + default to a score of 0.

+ +

start/1

+
+

start(Modules) -> any()

+

+
+ +

stop/1

+
+

stop(Modules) -> any()

+

+
+ +

test_stores/0

+
+

test_stores() -> any()

+

+
+ +

type/2

+
+

type(Modules, Path) -> any()

+

+

Get the type of element of a given path in the store. This can be + a performance killer if the store is remote etc. Use only when necessary.

+ +

write/3

+
+

write(Modules, Key, Value) -> any()

+

+

Write a key with a value to the store.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_store_fs.html b/doc/hb_store_fs.html new file mode 100644 index 00000000..3f61141a --- /dev/null +++ b/doc/hb_store_fs.html @@ -0,0 +1,112 @@ + + + + +Module hb_store_fs + + + +
Overviewerlang logo
+
+ +

Module hb_store_fs

+ + + +

Function Index

+ + + + + + + + + + + +
list/2
make_group/2
make_link/3
read/2Read a key from the store, following symlinks as needed.
reset/1
resolve/2Replace links in a path successively, returning the final path.
scope/1The file-based store is always local, for now.
start/1
stop/1
type/2
write/3
+ +

Function Details

+ +

list/2

+
+

list(Opts, Path) -> any()

+

+
+ +

make_group/2

+
+

make_group(X1, Path) -> any()

+

+
+ +

make_link/3

+
+

make_link(Opts, Link, New) -> any()

+

+
+ +

read/2

+
+

read(Opts, Key) -> any()

+

+

Read a key from the store, following symlinks as needed.

+ +

reset/1

+
+

reset(X1) -> any()

+

+
+ +

resolve/2

+
+

resolve(Opts, RawPath) -> any()

+

+

Replace links in a path successively, returning the final path. +Each element of the path is resolved in turn, with the result of each +resolution becoming the prefix for the next resolution. This allows +paths to resolve across many links. For example, a structure as follows:

+ +

/a/b/c: "Not the right data" +/a/b -> /a/alt-b +/a/alt-b/c: "Correct data"

+ + will resolve "a/b/c" to "Correct data".

+ +

scope/1

+
+

scope(X1) -> any()

+

+

The file-based store is always local, for now. In the future, we may + want to allow that an FS store is shared across a cluster and thus remote.

+ +

start/1

+
+

start(X1) -> any()

+

+
+ +

stop/1

+
+

stop(X1) -> any()

+

+
+ +

type/2

+
+

type(Opts, Key) -> any()

+

+
+ +

write/3

+
+

write(Opts, PathComponents, Value) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_store_remote_node.html b/doc/hb_store_remote_node.html new file mode 100644 index 00000000..b9470195 --- /dev/null +++ b/doc/hb_store_remote_node.html @@ -0,0 +1,53 @@ + + + + +Module hb_store_remote_node + + + +
Overviewerlang logo
+
+ +

Module hb_store_remote_node

+ + + +

Function Index

+ + + + +
read/2
resolve/2
scope/1
type/2
+ +

Function Details

+ +

read/2

+
+

read(Opts, Key) -> any()

+

+
+ +

resolve/2

+
+

resolve(X1, Key) -> any()

+

+
+ +

scope/1

+
+

scope(X1) -> any()

+

+
+ +

type/2

+
+

type(Opts, Key) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_store_rocksdb.html b/doc/hb_store_rocksdb.html new file mode 100644 index 00000000..fee54370 --- /dev/null +++ b/doc/hb_store_rocksdb.html @@ -0,0 +1,196 @@ + + + + +Module hb_store_rocksdb + + + +
Overviewerlang logo
+
+ +

Module hb_store_rocksdb

+A process wrapper over rocksdb storage. + +

Behaviours: gen_server, hb_store.

+ +

Description

A process wrapper over rocksdb storage. Replicates functionality of the +hb_fs_store module.

+ + The data is stored in two Column Families: + 1. Default - for raw data (e.g. message records) + 2. Meta - for meta information + (<<"raw">>/<<"link">>/<<"composite">> or <<"group">>) +

Data Types

+ +

key()

+

key() = binary() | list()

+ + +

value()

+

value() = binary() | list()

+ + +

Function Index

+ + + + + + + + + + + + + + + + + + + + +
add_path/3Add two path components together.
code_change/3
handle_call/3
handle_cast/2
handle_info/2
init/1
list/2List key/values stored in the storage so far.
make_group/2Creates group under the given path.
make_link/3
path/2Return path.
read/2Read data by the key.
reset/1
resolve/2Replace links in a path with the target of the link.
scope/1Return scope (local).
start/1
start_link/1
stop/1
terminate/2
type/2Get type of the current item.
write/3Write given Key and Value to the database.
+ +

Function Details

+ +

add_path/3

+
+

add_path(Opts, Path1, Path2) -> any()

+

+

Add two path components together. // is not used

+ +

code_change/3

+
+

code_change(OldVsn, State, Extra) -> any()

+

+
+ +

handle_call/3

+
+

handle_call(Request, From, State) -> any()

+

+
+ +

handle_cast/2

+
+

handle_cast(Request, State) -> any()

+

+
+ +

handle_info/2

+
+

handle_info(Info, State) -> any()

+

+
+ +

init/1

+
+

init(Dir) -> any()

+

+
+ +

list/2

+
+

list(Opts, Path) -> Result +

  • Opts = any()
  • Path = any()
  • Result = [string()]

+

+

List key/values stored in the storage so far. +*Note*: This function is slow, and probably should not be used on +production. Right now it's used for debugging purposes.

+ + This can't work as it works for FS store, especially for large sets + of data.

+ +

make_group/2

+
+

make_group(Opts, Path) -> any()

+

+

Creates group under the given path. + Creates an entry in the database and store <<"group">> as a type in + the meta family.

+ +

make_link/3

+
+

make_link(Opts::any(), Key1::key(), New::key()) -> ok

+

+
+ +

path/2

+
+

path(Opts, Path) -> any()

+

+

Return path

+ +

read/2

+
+

read(Opts, Key) -> Result +

  • Opts = map()
  • Key = key() | list()
  • Result = {ok, value()} | not_found | {error, {corruption, string()}} | {error, any()}

+

+

Read data by the key. + Recursively follows link messages

+ +

reset/1

+
+

reset(Opts::[]) -> ok | no_return()

+

+
+ +

resolve/2

+
+

resolve(Opts, Path) -> Result +

  • Opts = any()
  • Path = binary() | list()
  • Result = not_found | string()

+

+

Replace links in a path with the target of the link.

+ +

scope/1

+
+

scope(X1) -> any()

+

+

Return scope (local)

+ +

start/1

+
+

start(Opts) -> any()

+

+
+ +

start_link/1

+
+

start_link(Stores) -> any()

+

+
+ +

stop/1

+
+

stop(Opts::any()) -> ok

+

+
+ +

terminate/2

+
+

terminate(Reason, State) -> any()

+

+
+ +

type/2

+
+

type(Opts, Key) -> Result +

  • Opts = map()
  • Key = binary()
  • Result = composite | simple | not_found

+

+

Get type of the current item

+ +

write/3

+
+

write(Opts, Key, Value) -> Result +

  • Opts = map()
  • Key = key()
  • Value = value()
  • Result = ok | {error, any()}

+

+

Write given Key and Value to the database

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_sup.html b/doc/hb_sup.html new file mode 100644 index 00000000..c511da4a --- /dev/null +++ b/doc/hb_sup.html @@ -0,0 +1,47 @@ + + + + +Module hb_sup + + + +
Overviewerlang logo
+
+ +

Module hb_sup

+ + +

Behaviours: supervisor.

+ +

Function Index

+ + + +
init/1
start_link/0
start_link/1
+ +

Function Details

+ +

init/1

+
+

init(Opts) -> any()

+

+
+ +

start_link/0

+
+

start_link() -> any()

+

+
+ +

start_link/1

+
+

start_link(Opts) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_test.html b/doc/hb_test.html new file mode 100644 index 00000000..03219832 --- /dev/null +++ b/doc/hb_test.html @@ -0,0 +1,46 @@ + + + + +Module hb_test + + + +
Overviewerlang logo
+
+ +

Module hb_test

+ + + +

Function Index

+ + + +
generate_test_data/1
init/0
run/2
+ +

Function Details

+ +

generate_test_data/1

+
+

generate_test_data(Script) -> any()

+

+
+ +

init/0

+
+

init() -> any()

+

+
+ +

run/2

+
+

run(Proc, Msg) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_test_utils.html b/doc/hb_test_utils.html new file mode 100644 index 00000000..bc17d2c7 --- /dev/null +++ b/doc/hb_test_utils.html @@ -0,0 +1,38 @@ + + + + +Module hb_test_utils + + + +
Overviewerlang logo
+
+ +

Module hb_test_utils

+Simple utilities for testing HyperBEAM. + + +

Description

Simple utilities for testing HyperBEAM. +

Function Index

+ +
suite_with_opts/2Run each test in a suite with each set of options.
+ +

Function Details

+ +

suite_with_opts/2

+
+

suite_with_opts(Suite, OptsList) -> any()

+

+

Run each test in a suite with each set of options. Start and reset + the store(s) for each test. Expects suites to be a list of tuples with + the test name, description, and test function. + The list of Opts should contain maps with the name and opts keys. + Each element may also contain a skip key with a list of test names to skip. + They can also contain a desc key with a description of the options.

+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/hb_util.html b/doc/hb_util.html new file mode 100644 index 00000000..231fc5a4 --- /dev/null +++ b/doc/hb_util.html @@ -0,0 +1,353 @@ + + + + +Module hb_util + + + +
Overviewerlang logo
+
+ +

Module hb_util

+A collection of utility functions for building with HyperBEAM. + + +

Description

A collection of utility functions for building with HyperBEAM. +

Function Index

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
count/2
debug_fmt/1Convert a term to a string for debugging print purposes.
debug_print/4Print a message to the standard error stream, prefixed by the amount + of time that has elapsed since the last call to this function.
decode/1Try to decode a URL safe base64 into a binary or throw an error when + invalid.
encode/1Encode a binary to URL safe base64 binary string.
eunit_print/2Format and print an indented string to standard error.
find_value/2Find the value associated with a key in parsed a JSON structure list.
find_value/3
format_binary/1Format a binary as a short string suitable for printing.
format_indented/2Format a string with an indentation level.
format_indented/3
format_map/1Format a map as either a single line or a multi-line string depending + on the value of the debug_print_map_line_threshold runtime option.
format_map/2
format_trace_short/1Format a trace to a short string.
hd/1Get the first element (the lowest integer key >= 1) of a numbered map.
hd/2
hd/3
human_id/1Convert a native binary ID to a human readable ID.
human_int/1Add , characters to a number every 3 digits to make it human readable.
id/1Return the human-readable form of an ID of a message when given either + a message explicitly, raw encoded ID, or an Erlang Arweave tx record.
id/2
is_string_list/1Is the given term a string list?.
list_to_numbered_map/1Convert a list of elements to a map with numbered keys.
maybe_throw/2Throw an exception if the Opts map has an error_strategy key with the + value throw.
mean/1
message_to_numbered_list/1Take a message with numbered keys and convert it to a list of tuples + with the associated key as an integer and a value.
native_id/1Convert a human readable ID to a native binary ID.
number/1Label a list of elements with a number.
ok/1Unwrap a tuple of the form {ok, Value}, or throw/return, depending on + the value of the error_strategy option.
ok/2
print_trace/4Print the trace of the current stack, up to the first non-hyperbeam + module.
print_trace_short/4Print a trace to the standard error stream.
remove_common/2Remove the common prefix from two strings, returning the remainder of the + first string.
remove_trailing_noise/2
safe_decode/1Safely decode a URL safe base64 into a binary returning an ok or error + tuple.
safe_encode/1Safely encode a binary to URL safe base64.
short_id/1Return a short ID for the different types of IDs used in Converge.
stddev/1
to_hex/1Convert a binary to a hex string.
to_lower/1Convert a binary to a lowercase.
trace_macro_helper/5Utility function to help macro ?trace/0 remove the first frame of the + stack trace.
variance/1
+ +

Function Details

+ +

count/2

+
+

count(Item, List) -> any()

+

+
+ +

debug_fmt/1

+
+

debug_fmt(X) -> any()

+

+

Convert a term to a string for debugging print purposes.

+ +

debug_print/4

+
+

debug_print(X, Mod, Func, LineNum) -> any()

+

+

Print a message to the standard error stream, prefixed by the amount + of time that has elapsed since the last call to this function.

+ +

decode/1

+
+

decode(Input) -> any()

+

+

Try to decode a URL safe base64 into a binary or throw an error when + invalid.

+ +

encode/1

+
+

encode(Bin) -> any()

+

+

Encode a binary to URL safe base64 binary string.

+ +

eunit_print/2

+
+

eunit_print(FmtStr, FmtArgs) -> any()

+

+

Format and print an indented string to standard error.

+ +

find_value/2

+
+

find_value(Key, List) -> any()

+

+

Find the value associated with a key in parsed a JSON structure list.

+ +

find_value/3

+
+

find_value(Key, Map, Default) -> any()

+

+
+ +

format_binary/1

+
+

format_binary(Bin) -> any()

+

+

Format a binary as a short string suitable for printing.

+ +

format_indented/2

+
+

format_indented(Str, Indent) -> any()

+

+

Format a string with an indentation level.

+ +

format_indented/3

+
+

format_indented(RawStr, Fmt, Ind) -> any()

+

+
+ +

format_map/1

+
+

format_map(Map) -> any()

+

+

Format a map as either a single line or a multi-line string depending + on the value of the debug_print_map_line_threshold runtime option.

+ +

format_map/2

+
+

format_map(Map, Indent) -> any()

+

+
+ +

format_trace_short/1

+
+

format_trace_short(Trace) -> any()

+

+

Format a trace to a short string.

+ +

hd/1

+
+

hd(Message) -> any()

+

+

Get the first element (the lowest integer key >= 1) of a numbered map. + Optionally, it takes a specifier of whether to return the key or the value, + as well as a standard map of HyperBEAM runtime options.

+ +

hd/2

+
+

hd(Message, ReturnType) -> any()

+

+
+ +

hd/3

+
+

hd(Message, ReturnType, Opts) -> any()

+

+
+ +

human_id/1

+
+

human_id(Bin) -> any()

+

+

Convert a native binary ID to a human readable ID. If the ID is already + a human readable ID, it is returned as is.

+ +

human_int/1

+
+

human_int(Int) -> any()

+

+

Add , characters to a number every 3 digits to make it human readable.

+ +

id/1

+
+

id(Item) -> any()

+

+

Return the human-readable form of an ID of a message when given either + a message explicitly, raw encoded ID, or an Erlang Arweave tx record.

+ +

id/2

+
+

id(TX, Type) -> any()

+

+
+ +

is_string_list/1

+
+

is_string_list(MaybeString) -> any()

+

+

Is the given term a string list?

+ +

list_to_numbered_map/1

+
+

list_to_numbered_map(List) -> any()

+

+

Convert a list of elements to a map with numbered keys.

+ +

maybe_throw/2

+
+

maybe_throw(Val, Opts) -> any()

+

+

Throw an exception if the Opts map has an error_strategy key with the + value throw. Otherwise, return the value.

+ +

mean/1

+
+

mean(List) -> any()

+

+
+ +

message_to_numbered_list/1

+
+

message_to_numbered_list(Message) -> any()

+

+

Take a message with numbered keys and convert it to a list of tuples + with the associated key as an integer and a value. Optionally, it takes a + standard map of HyperBEAM runtime options.

+ +

native_id/1

+
+

native_id(Bin) -> any()

+

+

Convert a human readable ID to a native binary ID. If the ID is already + a native binary ID, it is returned as is.

+ +

number/1

+
+

number(List) -> any()

+

+

Label a list of elements with a number.

+ +

ok/1

+
+

ok(Value) -> any()

+

+

Unwrap a tuple of the form {ok, Value}, or throw/return, depending on + the value of the error_strategy option.

+ +

ok/2

+
+

ok(Other, Opts) -> any()

+

+
+ +

print_trace/4

+
+

print_trace(Stack, CallMod, CallFunc, CallLine) -> any()

+

+

Print the trace of the current stack, up to the first non-hyperbeam + module. Prints each stack frame on a new line, until it finds a frame that + does not start with a prefix in the stack_print_prefixes hb_opts. + Optionally, you may call this function with a custom label and caller info, + which will be used instead of the default.

+ +

print_trace_short/4

+
+

print_trace_short(Trace, Mod, Func, Line) -> any()

+

+

Print a trace to the standard error stream.

+ +

remove_common/2

+
+

remove_common(MainStr, SubStr) -> any()

+

+

Remove the common prefix from two strings, returning the remainder of the + first string. This function also coerces lists to binaries where appropriate, + returning the type of the first argument.

+ +

remove_trailing_noise/2

+
+

remove_trailing_noise(Str, Noise) -> any()

+

+
+ +

safe_decode/1

+
+

safe_decode(E) -> any()

+

+

Safely decode a URL safe base64 into a binary returning an ok or error + tuple.

+ +

safe_encode/1

+
+

safe_encode(Bin) -> any()

+

+

Safely encode a binary to URL safe base64.

+ +

short_id/1

+
+

short_id(Bin) -> any()

+

+

Return a short ID for the different types of IDs used in Converge.

+ +

stddev/1

+
+

stddev(List) -> any()

+

+
+ +

to_hex/1

+
+

to_hex(Bin) -> any()

+

+

Convert a binary to a hex string. Do not use this for anything other than + generating a lower-case, non-special character id. It should not become part of + the core protocol. We use b64u for efficient encoding.

+ +

to_lower/1

+
+

to_lower(Str) -> any()

+

+

Convert a binary to a lowercase.

+ +

trace_macro_helper/5

+
+

trace_macro_helper(Fun, X2, Mod, Func, Line) -> any()

+

+

Utility function to help macro ?trace/0 remove the first frame of the + stack trace.

+ +

variance/1

+
+

variance(List) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 00000000..271e36bd --- /dev/null +++ b/doc/index.html @@ -0,0 +1,17 @@ + + + +The hb application + + + + + + +<h2>This page uses frames</h2> +<p>Your browser does not accept frames. +<br>You should go to the <a href="overview-summary.html">non-frame version</a> instead. +</p> + + + \ No newline at end of file diff --git a/doc/modules-frame.html b/doc/modules-frame.html new file mode 100644 index 00000000..b81fd68c --- /dev/null +++ b/doc/modules-frame.html @@ -0,0 +1,89 @@ + + + +The hb application + + + +

Modules

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ar_bundles
ar_deep_hash
ar_http
ar_http_sup
ar_rate_limiter
ar_timestamp
ar_tx
ar_wallet
dev_codec_ans104
dev_codec_flat
dev_codec_httpsig
dev_codec_httpsig_conv
dev_codec_structured
dev_codec_structured_conv
dev_compute_lite
dev_cron
dev_cu
dev_dedup
dev_faff
dev_json_iface
dev_lookup
dev_message
dev_meta
dev_monitor
dev_multipass
dev_p4
dev_poda
dev_process
dev_process_cache
dev_process_worker
dev_relay
dev_router
dev_scheduler
dev_scheduler_cache
dev_scheduler_formats
dev_scheduler_registry
dev_scheduler_server
dev_simple_pay
dev_snp
dev_snp_nif
dev_stack
dev_test
dev_wasi
dev_wasm
hb
hb_app
hb_beamr
hb_beamr_io
hb_cache
hb_cache_control
hb_cache_render
hb_client
hb_converge
hb_converge_test_vectors
hb_crypto
hb_examples
hb_http
hb_http_benchmark_tests
hb_http_server
hb_logger
hb_message
hb_metrics_collector
hb_opts
hb_path
hb_persistent
hb_private
hb_process_monitor
hb_router
hb_singleton
hb_store
hb_store_fs
hb_store_remote_node
hb_store_rocksdb
hb_sup
hb_test
hb_test_utils
hb_util
rsa_pss
+ + \ No newline at end of file diff --git a/doc/overview-summary.html b/doc/overview-summary.html new file mode 100644 index 00000000..212e0ad4 --- /dev/null +++ b/doc/overview-summary.html @@ -0,0 +1,16 @@ + + + + +The hb application + + + +
Overviewerlang logo
+

The hb application

+ +
+
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/rsa_pss.html b/doc/rsa_pss.html new file mode 100644 index 00000000..2634c7a5 --- /dev/null +++ b/doc/rsa_pss.html @@ -0,0 +1,77 @@ + + + + +Module rsa_pss + + + +
Overviewerlang logo
+
+ +

Module rsa_pss

+ + Distributed under the Mozilla Public License v2.0. +

Copyright © 2014-2015, Andrew Bennett

+ +

Authors: Andrew Bennett (andrew@pixid.com).

+ +

Description

+ Distributed under the Mozilla Public License v2.0. + Original available at: + https://github.com/potatosalad/erlang-crypto_rsassa_pss +

Data Types

+ +

rsa_digest_type()

+

rsa_digest_type() = md5 | sha | sha224 | sha256 | sha384 | sha512

+ + +

rsa_private_key()

+

rsa_private_key() = #'RSAPrivateKey'{}

+ + +

rsa_public_key()

+

rsa_public_key() = #'RSAPublicKey'{}

+ + +

Function Index

+ + + + +
sign/3
sign/4
verify/4
verify_legacy/4
+ +

Function Details

+ +

sign/3

+
+

sign(Message, DigestType, PrivateKey) -> Signature +

+

+
+ +

sign/4

+
+

sign(Message, DigestType, Salt, PrivateKey) -> Signature +

+

+
+ +

verify/4

+
+

verify(Message, DigestType, Signature, PublicKey) -> boolean() +

+

+
+ +

verify_legacy/4

+
+

verify_legacy(Message, DigestType, Signature, PublicKey) -> any()

+

+
+
+ +
Overviewerlang logo
+

Generated by EDoc

+ + diff --git a/doc/stylesheet.css b/doc/stylesheet.css new file mode 100644 index 00000000..ab170c09 --- /dev/null +++ b/doc/stylesheet.css @@ -0,0 +1,55 @@ +/* standard EDoc style sheet */ +body { + font-family: Verdana, Arial, Helvetica, sans-serif; + margin-left: .25in; + margin-right: .2in; + margin-top: 0.2in; + margin-bottom: 0.2in; + color: #000000; + background-color: #ffffff; +} +h1,h2 { + margin-left: -0.2in; +} +div.navbar { + background-color: #add8e6; + padding: 0.2em; +} +h2.indextitle { + padding: 0.4em; + background-color: #add8e6; +} +h3.function,h3.typedecl { + background-color: #add8e6; + padding-left: 1em; +} +div.spec { + margin-left: 2em; + background-color: #eeeeee; +} +a.module { + text-decoration:none +} +a.module:hover { + background-color: #eeeeee; +} +ul.definitions { + list-style-type: none; +} +ul.index { + list-style-type: none; + background-color: #eeeeee; +} + +/* + * Minor style tweaks + */ +ul { + list-style-type: square; +} +table { + border-collapse: collapse; +} +td { + padding: 3 +} From 812ea77ef05e60c50b349098e417ef559f413e9a Mon Sep 17 00:00:00 2001 From: Tyler Hall Date: Mon, 10 Feb 2025 17:21:00 -0500 Subject: [PATCH 3/7] docs(README): initial --- README.md | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 98 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c97f65ef..6c595957 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,100 @@ -Soon. \ No newline at end of file +This repository contains a reference implementation of AO-Core, along with an +Erlang-based (BEAM) client implementing a number of devices for the protocol. + +AO-Core is a protocol built to enable decentralized computations, offering a +series of universal primitives to achieve this end. Instead of enforcing a single, +monolithic architecture, AO-Core provides a framework into which any number of +different `devices' can be attached. + +AO's protocol offers a framework for decentralized computations, built upon the +following fundamental primitives: + +1. Hashpaths: A mechanism for referencing locations in a program's state-space +prior to execution. These state-space `links` are represented as Merklized lists of +programs inputs and initial states. +2. A unified data structure for representing program states as HTTP documents, +as described in the [HTTP Semantics RFC](https://www.rfc-editor.org/rfc/rfc9110.html). +3. A unified protocol for expressing `attestations` of the `states` found at +particular `hashpaths`. These attestations allow nodes to participate in varied +economic and cryptographic mechanisms to prove and challenge each-other's +representations regarding the programs that operate inside the AO protocol. +4. A meta-VM that allows any number of different virtual machines and computational +models (`devices`) to be executed inside the AO protocol, while enabling their +states and inputs to be calculated and attested to in a unified format. + +## What is HyperBeam? + +HyperBeam is a client implementation of the AO-Core protocol, written in Erlang. +It can be seen as the 'node' software for the decentralized operating system that +AO enables; abstracting hardware provisioning and details from the execution of +individual programs. + +HyperBEAM node operators can offer the services of their machine to others inside +the network by electing to execute any number of different devices, charging +users for their computation as necessary. + +Each HyperBEAM node is configured using the `~meta@1.0` device, which provides +an interface for specifying the node's hardware, supported devices, metering and +payments information, amongst other configuration options. + +## Getting Started + +To begin using HyperBeam, you will need to install the Erlang runtime and the +HyperBeam client. + +```bash +git clone https://github.com/ao-labs/hyperbeam.git +cd hyperbeam +rebar3 compile +``` + +If you would prefer to execute HyperBEAM in a containerized environment, you +can use the provided Dockerfile to build a container image. + +```bash +docker build -t hyperbeam . +``` + +If you intend to offer TEE-based computation of AO-Core devices, please see the +[`HyperBEAM OS`]() repo for details on configuration and deployment. + +## Configuration + +HyperBeam can be configured using a `~meta@1.0` device. This device is initialized +via the command line arguments provided when the node is started. + +```bash +rebar3 shell --eval "hb:start_mainnet(#{ [OPTS] })." +``` + +For example, in order to start a node using a custom port and Arweave wallet, +you could execute the following command: + +```bash +rebar3 shell --eval "hb:start_mainnet(#{ port => 10001, key_location => 'path/to/my/wallet.key' })." +``` + +Additionally, if you would like to modify a running node's configuration, you can +do so by sending a HTTP Signed Message using any RFC-9421 compatible client in +the following form: + +``` +POST /~meta@1.0/info +Your-Config-Tag: Your-Config-Tag +``` + +The individual headers provided in the message will each be interpreted as additional +configuration options for the node. + +## Devices + +HyperBeam supports a number of different devices, each of which enable different +services to be offered by the node. There are presently 25 different devices +included in the `preloaded_devices` of a HyperBEAM node, although it is possible +to add and remove devices as necessary. + +### Preloaded Devices + +The following devices are included in the `preloaded_devices` of a HyperBEAM node: \ No newline at end of file From 668882c050bd27dfe1df1c46a5e93f52ae7f69a1 Mon Sep 17 00:00:00 2001 From: Tyler Hall Date: Mon, 10 Feb 2025 18:03:19 -0500 Subject: [PATCH 4/7] docs(README): wording adjustments --- README.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 6c595957..2da2d998 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@ Erlang-based (BEAM) client implementing a number of devices for the protocol. AO-Core is a protocol built to enable decentralized computations, offering a series of universal primitives to achieve this end. Instead of enforcing a single, monolithic architecture, AO-Core provides a framework into which any number of -different `devices' can be attached. +different computational models, encapsulated as primitive `devices`, can be attached. -AO's protocol offers a framework for decentralized computations, built upon the +AO-Core's protocol offers a framework for decentralized computations, built upon the following fundamental primitives: 1. Hashpaths: A mechanism for referencing locations in a program's state-space @@ -19,9 +19,9 @@ as described in the [HTTP Semantics RFC](https://www.rfc-editor.org/rfc/rfc9110. 3. A unified protocol for expressing `attestations` of the `states` found at particular `hashpaths`. These attestations allow nodes to participate in varied economic and cryptographic mechanisms to prove and challenge each-other's -representations regarding the programs that operate inside the AO protocol. +representations regarding the programs that operate inside the AO-Core protocol. 4. A meta-VM that allows any number of different virtual machines and computational -models (`devices`) to be executed inside the AO protocol, while enabling their +models (`devices`) to be executed inside the AO-Core protocol, while enabling their states and inputs to be calculated and attested to in a unified format. ## What is HyperBeam? @@ -32,7 +32,7 @@ AO enables; abstracting hardware provisioning and details from the execution of individual programs. HyperBEAM node operators can offer the services of their machine to others inside -the network by electing to execute any number of different devices, charging +the network by electing to execute any number of different `devices`, charging users for their computation as necessary. Each HyperBEAM node is configured using the `~meta@1.0` device, which provides @@ -41,8 +41,12 @@ payments information, amongst other configuration options. ## Getting Started -To begin using HyperBeam, you will need to install the Erlang runtime and the -HyperBeam client. +To begin using HyperBeam, you will need to install: + +- The Erlang runtime (OTP 27) +- Rebar3 + +Then you can clone the HyperBEAM source and build it: ```bash git clone https://github.com/ao-labs/hyperbeam.git From d4823fd9d78719ed6e24b1baed06f932bbc1088d Mon Sep 17 00:00:00 2001 From: Tyler Hall Date: Mon, 10 Feb 2025 18:04:25 -0500 Subject: [PATCH 5/7] docs(README): add `Messages` section --- README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/README.md b/README.md index 2da2d998..d6cd51fa 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,27 @@ Your-Config-Tag: Your-Config-Tag The individual headers provided in the message will each be interpreted as additional configuration options for the node. +## Messages + +HyperBEAM describes every piece of data as a `message`, which can be interpreted as +a binary term or as collection of named functions aka. a `Map` of functions. + +Every message _may_ specify a `device` which is interpreted by the AO-Core compatible +system in order to operate upon the message's contents, which to say read it, or +execute it. Executing a named function within a message, providing a map of arguments, +results in yet another `message`. + +In this way, A `message` _begets_ another `message`, giving rise to a vast computational +space, leveraging function application and composition at its core. + +> Notably, this computation does not require the computor of a message +> to know the values of all the keys contained therin. In other words, keys +> may be _lazily_ evaluated, and only by computors that are interested +> in their outputs, or even _sharded_ across arbitrary sets of nodes, as necessary + +If a `message` does not explicitly specify a `device`, its implied `device` is `Map`, +which simply returns the binary or message at a given named function. + ## Devices HyperBeam supports a number of different devices, each of which enable different From c269f65f97fba5a6e6be32a99f73a67f090cdc39 Mon Sep 17 00:00:00 2001 From: Tyler Hall Date: Mon, 10 Feb 2025 18:24:36 -0500 Subject: [PATCH 6/7] docs(README): section on IDs Hashpaths and Converge --- README.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d6cd51fa..c745b196 100644 --- a/README.md +++ b/README.md @@ -111,7 +111,7 @@ space, leveraging function application and composition at its core. > in their outputs, or even _sharded_ across arbitrary sets of nodes, as necessary If a `message` does not explicitly specify a `device`, its implied `device` is `Map`, -which simply returns the binary or message at a given named function. +which simply returns the binary or `message` at a given named function. ## Devices @@ -122,4 +122,21 @@ to add and remove devices as necessary. ### Preloaded Devices -The following devices are included in the `preloaded_devices` of a HyperBEAM node: \ No newline at end of file +The following devices are included in the `preloaded_devices` of a HyperBEAM node: + +## IDs, Hashpaths & Converge. + +Along the path of executing and orchestrating `devices`, HyperBEAM will compute a +a number of resultant `messages` as well as a series of cryptographic linkages. First, +each `message` has a cryptographic ID that uniquely identifies it in the space of computation. +Second, each `message` will have linked the series of function applications that produced it. +This value is called the `hashpath` and can be undestood as a memoization of the tree of execution +that was applied to produce the message. + +Due to it Merkalized form, a `hashpath` can be used as concise, and cryptographically verifiable, way +to reconstruct the entire branch of inputs used to generate a given `message`. + +Also, because multiple paths of executions may produce the same resultant `message`, HyperBEAM is able +to compute and store "links" between `hashpaths` that each point to the same underlying `message`. +In this sense, HyperBEAM "converges" computation, linking paths to the same data, similar to how HTTP +may respond with a `Redirect` to a Hyperlink. From 49abff859f898e06036ed006a15a0d9fefa86dbb Mon Sep 17 00:00:00 2001 From: Sam Williams Date: Mon, 10 Feb 2025 21:50:27 -0500 Subject: [PATCH 7/7] chore: README updates --- README.md | 101 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 79 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index c745b196..14149e59 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ For example, in order to start a node using a custom port and Arweave wallet, you could execute the following command: ```bash -rebar3 shell --eval "hb:start_mainnet(#{ port => 10001, key_location => 'path/to/my/wallet.key' })." +rebar3 shell --eval "hb:start_mainnet(#{ port => 9001, key_location => 'path/to/my/wallet.key' })." ``` Additionally, if you would like to modify a running node's configuration, you can @@ -100,18 +100,20 @@ a binary term or as collection of named functions aka. a `Map` of functions. Every message _may_ specify a `device` which is interpreted by the AO-Core compatible system in order to operate upon the message's contents, which to say read it, or execute it. Executing a named function within a message, providing a map of arguments, -results in yet another `message`. +results in another `message`. -In this way, A `message` _begets_ another `message`, giving rise to a vast computational -space, leveraging function application and composition at its core. +In this way, `messages` in AO-Core always _beget_ further `messages`, giving rise +to a vast computational space, leveraging function application and composition at its core. +For those familiar with the concept, this programming model is similar to that +described by traditional `combinator` systems. > Notably, this computation does not require the computor of a message > to know the values of all the keys contained therin. In other words, keys > may be _lazily_ evaluated, and only by computors that are interested > in their outputs, or even _sharded_ across arbitrary sets of nodes, as necessary -If a `message` does not explicitly specify a `device`, its implied `device` is `Map`, -which simply returns the binary or `message` at a given named function. +If a `message` does not explicitly specify a `device`, its implied `device` is a + `message@1.0`, which simply returns the binary or `message` at a given named function. ## Devices @@ -124,19 +126,74 @@ to add and remove devices as necessary. The following devices are included in the `preloaded_devices` of a HyperBEAM node: -## IDs, Hashpaths & Converge. - -Along the path of executing and orchestrating `devices`, HyperBEAM will compute a -a number of resultant `messages` as well as a series of cryptographic linkages. First, -each `message` has a cryptographic ID that uniquely identifies it in the space of computation. -Second, each `message` will have linked the series of function applications that produced it. -This value is called the `hashpath` and can be undestood as a memoization of the tree of execution -that was applied to produce the message. - -Due to it Merkalized form, a `hashpath` can be used as concise, and cryptographically verifiable, way -to reconstruct the entire branch of inputs used to generate a given `message`. - -Also, because multiple paths of executions may produce the same resultant `message`, HyperBEAM is able -to compute and store "links" between `hashpaths` that each point to the same underlying `message`. -In this sense, HyperBEAM "converges" computation, linking paths to the same data, similar to how HTTP -may respond with a `Redirect` to a Hyperlink. +- `~meta@1.0`: The `~meta@1.0` device is used to configure the node's hardware, +supported devices, metering and payments information, amongst other configuration options. +Additionally, this device allows external clients to find and validate the configuration +of nodes in the network. + +- `~relay@1.0`: The `~relay@1.0` device is used to relay messages between nodes +and the wider HTTP network. It offers an interface for sending and receiving messages +to and from nodes in the network, using a variety of execution strategies. + +- `~wasm64@1.0`: The `~wasm64@1.0` device is used to execute WebAssembly code, using +the [Web Assembly Micro-Runtime (WAMR)](https://github.com/bytecodealliance/wasm-micro-runtime) +under-the-hood. WASM modules can be called from any other device, and can also be +used to execute `devices` written in languages such as Rust, C, and C++. + +- `~json-iface@1.0`: The `~json-iface@1.0` device offers a translation layer between +the JSON-encoded message format used by AOS 2.0 and prior versions, to HyperBEAM's +native HTTP message format. + +- `~compute-lite@1.0`: The `~compute-lite@1.0` device is a lightweight device wrapping +a local WASM executor, used for executing legacynet AO processes inside HyperBEAM. +See the [HyperBEAM OS](https://github.com/PeterFarber/hb-os) repository for an +example setup with co-executing HyperBEAM and legacy-CU nodes. + +- `~snp@1.0`: The `~snp@1.0` device is used to generate and validate proofs that +the local node, or another node in the network, is executing inside a [Trusted Execution +Environment (TEE)](https://en.wikipedia.org/wiki/Trusted_execution_environment). +Nodes executing inside these environments use an ephemeral key pair, provably +only existing inside the TEE, and can be sign attestations of AO-Core executions +in a trust-minimized way. + +- `p4@1.0`: The `p4@1.0` device runs as a `pre-processor` and `post-processor` in +the framework provided by `~meta@1.0`, enabling a framework for node operators to +sell usage of their machine's hardware to execute AO-Core devices. The `p4@1.0` +framework offers two additional hooks, allowing node operators flexibility in how +their hardware is offered: A `pricing` device, and a `ledger` device. + +- `~simple-pay@1.0`: Implements a simple, flexible pricing device that can be used +in conjunction with `p4@1.0` to offer flat-fees for the execution of AO-Core messages. + +- `~faff@1.0`: A simple pricing (and ledger) device for `p4@1.0`, allowing nodes +to offer access to their services only to a specific set of users. This device is +useful if you intend to operate your node onmly for personal use, or for a specific +subset of users (servicing an individual app, for example). + +- `scheduler@1.0`: The `scheduler@1.0` device is used to assign a linear hashpath +to an execution, such that all users may access it with a deterministic ordering. +When used in conjunction with other AO-Core devices, this allows for the creation +of executions that mirror the behaviour of traditional smart contracting networks. + +- `stack@1.0`: The `stack@1.0` device is used to execute an ordered set of devices, +over the same inputs. This device allows its users to create complex combinations of +other devices and apply them as a single unit, with a single hashpath. + +- `~process@1.0`: Processes enable users to create persistent, shared executions +that can be accessed by any number of users, each of whom may add additional inputs +to its hashpath. The `~process@1.0` allows users to customize the `execution` and +`scheduler` devices that they choose for their process, such that a variety of different +execution patterns can be created. In addition, the `~process@1.0` device offers a +`push` key, which moves messages from a process's execution `outbox` into the +schedule of another execution. + +Details on other devices found in the pre-loaded set can be located in their +respective documentation. + +## Contributing + +HyperBEAM is developed as an open source implementation of the AO-Core protocol +by [Forward Research](https://fwd.arweave.net). Pull Requests are always welcome! + +To get started building on HyperBEAM, check out the [hacking on HyperBEAM](./docs/hacking-on-hyperbeam.md) +guide.