Module dev_codec_httpsig_conv.erl

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

Description

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

body_to_parts/3*	Split the body into parts, if it is a multipart.
body_to_tabm/2*	Generate the body TABM from the body key of the encoded message.
boundary_from_parts/1*	Generate a unique, reproducible boundary for the multipart body, however we cannot use the id of the message as the boundary, as the id is not known until the message is encoded.
do_to/3*
encode_body_part/4*	Encode a multipart body part to a flat binary.
encode_http_msg/2	Encode a HTTP message into a binary.
encode_message_with_links_test/0*
field_to_http/3*	All maps are encoded into the body of the HTTP message to be further encoded later.
from/3	Convert a HTTP Message into a TABM.
from_body_part/3*	Parse a single part of a multipart body into a TABM.
group_ids/1*	Group all elements with: 1.
group_maps/1*	Merge maps at the same level, if possible.
group_maps/4*
group_maps_flat_compatible_test/0*	The grouped maps encoding is a subset of the flat encoding, where on keys with maps values are flattened.
group_maps_test/0*
inline_key/1*	given a message, returns a binary tuple: - A list of pairs to add to the msg, if any - the field name for the inlined key.
inline_key/2*
to/3	Convert a TABM into an HTTP Message.
to/4*
ungroup_ids/2*	Decode the ao-ids key into a map.

Function Details

body_to_parts/3 *

body_to_parts(ContentType, Body, Opts) -> any()

Split the body into parts, if it is a multipart.

body_to_tabm/2 *

body_to_tabm(HTTP, Opts) -> any()

Generate the body TABM from the body key of the encoded message.

boundary_from_parts/1 *

boundary_from_parts(PartList) -> any()

Generate a unique, reproducible boundary for the multipart body, however we cannot use the id of the message as the boundary, as the id is not known until the message is encoded. Subsequently, we generate each body part individually, concatenate them, and apply a SHA2-256 hash to the result. This ensures that the boundary is unique, reproducible, and secure.

do_to/3 *

do_to(Binary, FormatOpts, Opts) -> any()

encode_body_part/4 *

encode_body_part(PartName, BodyPart, InlineKey, Opts) -> any()

Encode a multipart body part to a flat binary.

encode_http_msg/2

encode_http_msg(Msg, Opts) -> any()

Encode a HTTP message into a binary.

encode_message_with_links_test/0 *

encode_message_with_links_test() -> any()

field_to_http/3 *

field_to_http(Httpsig, X2, Opts) -> any()

All maps are encoded into the body of the HTTP message to be further encoded later.

from/3

from(Bin, Req, Opts) -> any()

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

from_body_part/3 *

from_body_part(InlinedKey, Part, Opts) -> any()

Parse a single part of a multipart body into a TABM.

group_ids/1 *

group_ids(Map) -> any()

Group all elements with: 1. A key that ?IS_ID returns true for, and 2. A value that is immediate into a combined SF dict-like structure. If not encoded, these keys would be sent as headers and lower-cased, losing their comparability against the original keys. The structure follows all SF dict rules, except that it allows for keys to contain capitals. The HyperBEAM SF parser will accept these keys, but standard RFC 8741 parsers will not. Subsequently, the resulting ao-cased key is not added to the ao-types map.

group_maps/1 *

group_maps(Map) -> any()

Merge maps at the same level, if possible.

group_maps/4 *

group_maps(Map, Parent, Top, Opts) -> any()

group_maps_flat_compatible_test/0 *

group_maps_flat_compatible_test() -> any()

The grouped maps encoding is a subset of the flat encoding, where on keys with maps values are flattened.

So despite needing a special encoder to produce it We can simply apply the flat encoder to it to get back the original message.

The test asserts that is indeed the case.

group_maps_test/0 *

group_maps_test() -> any()

inline_key/1 *

inline_key(Msg) -> any()

given a message, returns a binary tuple: - A list of pairs to add to the msg, if any - the field name for the inlined key

In order to preserve the field name of the inlined part, an additional field may need to be added

inline_key/2 *

inline_key(Msg, Opts) -> any()

to/3

to(TABM, Req, Opts) -> 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

to/4 *

to(Bin, Req, FormatOpts, Opts) -> any()

ungroup_ids/2 *

ungroup_ids(Msg, Opts) -> any()

Decode the ao-ids key into a map.