macula_dht_procedures (macula v15.1.0)
View SourceThe argument and reply shapes of the _dht.* procedures every station serves in the zero realm (wire 1.0, macula#102, docs/design/WIRE_1_0.md section 6). One argument form, a map with text keys and v 1, and one reply form per procedure, so an LTS station and a client of any language keep reaching the DHT.
A station reads arguments with read_args/2, refusing another v, a missing or extra key, or a field of the wrong type or length as malformed_args before any DHT work, and answers with reply/2. A caller builds arguments with args/2 and reads the answer with read_reply/2: another v is reply_version_unsupported, a missing or extra key or a value of the wrong shape is malformed_reply. A caller verifies every record it gets back as a reader (macula_record:verify/3) and drops those that fail; that is the caller's, not this module's.
Values travel in the frame payload's one key form (D26): text read as {text, Bin}, bytes as binaries. Built values use atom keys and atoms for text, which the frame encoder writes as text.
Summary
Types
A put's answer, a find's record or its absence, or the records at a key or of a type.
A put's wire record, a find's 32-byte storage key, or a record type tag.
Functions
A procedure's arguments: {v 1, record} for a put, {v 1, key} for a find at a key, {v 1, type} for a find by type.
The procedure a _dht.* name names, or error for any other name.
The wire name of a _dht.* procedure.
The argument a station reads from a call's payload: exactly v 1 and the procedure's one field, of its type and length, else malformed_args.
The result a caller reads from a station's reply. A v other than 1 is reply_version_unsupported; no v, a result the procedure does not answer, a missing or extra key or a value of the wrong shape is malformed_reply.
A station's reply: a put's ok or refused with the custodian's refusal name, a find's record or not_found, or the records at a key or of a type, possibly none.
Types
-type argument() :: binary() | <<_:256>> | 0..255.
A put's answer, a find's record or its absence, or the records at a key or of a type.
-type procedure() :: put_record | find_record | find_records | find_records_by_type.
A put's wire record, a find's 32-byte storage key, or a record type tag.
Functions
A procedure's arguments: {v 1, record} for a put, {v 1, key} for a find at a key, {v 1, type} for a find by type.
The procedure a _dht.* name names, or error for any other name.
The wire name of a _dht.* procedure.
The argument a station reads from a call's payload: exactly v 1 and the procedure's one field, of its type and length, else malformed_args.
-spec read_reply(procedure(), term()) -> {ok, result()} | {error, reply_version_unsupported | malformed_reply}.
The result a caller reads from a station's reply. A v other than 1 is reply_version_unsupported; no v, a result the procedure does not answer, a missing or extra key or a value of the wrong shape is malformed_reply.
A station's reply: a put's ok or refused with the custodian's refusal name, a find's record or not_found, or the records at a key or of a type, possibly none.