Module protocol 

The discovery wire protocol: one envelope, every transport. A multicast datagram, a broadcast datagram and a rendezvous candidate all carry the same signed advertisement, so there is one serializer, one parser and one verification path — a second protocol per transport is exactly the five-truths defect ADR 0050 refuses.

An advertisement says “a Majordomus node exists, here is its public key, here is where it answers, and the key signs all of it”. It grants nothing: trust is evaluated above this module, and authorization does not exist at this layer at all. It never carries a secret, a repository’s content, or an environment.

The parser is written for hostile input: bounded before it is read, refused before it is trusted, and no input of any shape panics — a property test holds that.

use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::protocol::{advertise, encode, parse, Refusal, MAX_DATAGRAM};

let node = NodeIdentity::ephemeral().unwrap();
let envelope = advertise(&node, 1, &["127.0.0.1:8741".into()], &[], &[], "docs");
let bytes = encode(&envelope).unwrap();
assert!(bytes.len() <= MAX_DATAGRAM);
assert!(parse(&bytes).is_ok());
assert_eq!(parse(&vec![0u8; MAX_DATAGRAM + 1]), Err(Refusal::Oversized));

Structs

Advertisement

The advertised body: everything the signature covers. Field names are one or two characters because this travels in a single UDP datagram; the types above the wire spell things out.

Envelope

The wire envelope: the advertisement plus its signature.

Enums

Refusal

Why a packet was refused. Every reason is a counter somewhere: refusals are the diagnosis of a hostile network, not silence.

Constants

MAX_CLOCK_SKEW_SECONDS

How far an advertisement’s timestamp may sit from the reader’s clock, in seconds, before the packet is stale (or from the future) and ignored.

MAX_DATAGRAM

The largest datagram the protocol sends or reads, in bytes. A packet above this is refused before parsing: the bound is the first defense, not the parser.

MAX_ENDPOINTS

The most endpoints one advertisement may carry.

MIN_PROTOCOL_VERSION

The oldest protocol version this executable reads. A version-1 advertisement has no runtime slot and is recorded as the node’s unnamed runtime.

PROTOCOL_VERSION

The protocol version this executable writes. Version 2 added the runtime slot (rt), so that two servers of one machine — two worktrees — are two runtimes rather than one node restarting forever. A version-1 reader refuses a version-2 datagram as version, which is counted and explicit; a version-2 reader reads both.

Functions

advertise

Build and sign this node’s advertisement, for the node’s unnamed runtime.

advertise_as

Build and sign the advertisement of one runtime of this node.

encode

Encode an envelope for the wire. An envelope that does not fit MAX_DATAGRAM is an error at the sender — the receiver’s bound must never be the first place it is felt.

now

Seconds since the Unix epoch, the clock advertisements are stamped and judged with; zero when the system clock sits before the epoch, which only ever refuses packets.

parse

Parse and verify one datagram. Ok means: well-formed, in bounds, current, and the signature proves the key. It does NOT mean trusted — trust policy runs above.

parse_at

parse against an explicit clock, so staleness is a tested property rather than a property of the test machine’s clock.