NetKernel

What a finished handshake knows about the peer: its identity, the role it announced for this connection, its advertised address ("" when it sent none), its VERIFIED certificate (certificate mode) and whether the connection's frames are sealed from here on.

The String whose bytes are [b] (the inverse of str_to_bytes): what the socket layer writes.

Decode a MONITOR_FIRE frame payload into (target_pid, reason_tag, reason_msg). Err for bytes that are not MessagePack or not a MONITOR_FIRE.

Decode a MONITOR_REQ frame payload into (watcher_node, watcher_pid, target_pid). Err for bytes that are not MessagePack or not a MONITOR_REQ.

Decode a REGISTRY_SYNC_REQ frame payload into its root hash. Err for bytes that are not MessagePack or not a REGISTRY_SYNC_REQ.

Decode a REGISTRY_SYNC_RESP frame payload into (root hash, leaves). Older leaf shapes still decode: a 4-element leaf with an empty clock, a

1. A malformed leaf is skipped and a malformed

clock pair ignored; a decoded entry's registrant is "", and a present entry never carries a tombstone stamp. Err for bytes that are not MessagePack or not a REGISTRY_SYNC_RESP.

A MONITOR_FIRE frame payload (MessagePack, tag 8): the watched process [target_pid] died, for [reason_tag] (0 = Normal, 1 = Killed, 2 = Crash, 3 = NodeDown) with [reason_msg]; the receiver notifies its local watcher.

A MONITOR_REQ frame payload (MessagePack, tag 7): [watcher_pid] on node [watcher_node] asks to watch the receiver's local process [target_pid].

A REGISTRY_SYNC_REQ frame payload (MessagePack, tag 5): our registry's Merkle [root_hash], asking the peer to diff.

A REGISTRY_SYNC_RESP frame payload (MessagePack, tag 6): our [root_hash] and the [leaves] that differ. Each leaf is [name, node_id, pid, present (1/0), clock, creation], clock the entry's VectorClock as [[actor_id, ts], ...], plus a [0, retired_at] pair for a tombstone.

Drop [fd]'s MAC state: its frames are plain again (see the rule above).

The tag of a frame payload: the first element of its outer MessagePack array, when that is an Int. None for bytes that do not decode, or another shape. It decodes the whole payload (it is not a cheap peek).

match NetKernel.frame_tag(frame) do
  Some(7) -> handle_monitor_req(frame)
  _ -> ()
end

Frames dropped for a failed MAC, in this process, since it started.

A fresh random nonce for a handshake challenge: 16 random bytes as 32 hex digits (Crypto.random_hex(16)).

The shared-secret handshake on [fd], opening a control connection. Both peers run the same sequence: send hello, read the peer's, send a proof bound to the peer's nonce, read the peer's proof, authenticate (it must bind to the nonce WE issued, [my_nonce]). Returns the authenticated peer's identity, or why it was refused. Blocks with no timeout; handshake_auth is the general form.

match NetKernel.handshake(fd, me, secret, NetKernel.fresh_nonce()) do
  Ok(peer) -> println("joined by " ++ peer.name)
  Err(e) -> println("refused: " ++ e)
end

The shared-secret handshake of handshake_role, sending [addr] (this node's advertised listen address) in the hello, with the whole exchange bounded by [timeout_ms] (<= 0: no bound). Returns the peer's identity, the role it announced and the address it advertised ("" from a peer that sends none).

The handshake, in either mode ([auth]): send a hello, read the peer's, check the modes agree, prove ourselves bound to the peer's nonce, check the peer's proof bound to ours. Shared-secret mode: an HMAC of the nonce under the secret (wire-compatible with pre-11a nodes). Certificate mode: the hello carries our certificate and an ephemeral X25519 key; we verify the peer's certificate (operator signature, expiry, revocation, name) and its ed25519 signature over our nonce and the transcript. When both sides support it, the connection's frames are sealed from then on (NetFrame.seal; mac in the result). [role] names the connection ("control"/"data"), [addr] is our advertised address ("" for none), [timeout_ms] bounds the whole exchange (<= 0: no bound).

handshake, opening a connection of [role] ("control" or "data", Handshake.role_*); returns the peer's identity AND the role the peer announced, so an acceptor knows which of a peer's two connections it just took. A pre-split peer announces no role and reads as control. Reads are exact: nothing past the handshake's own two frames is consumed, so the connection is handed over with the peer's first real frame still unread.

The handshake transcript of [fd]'s sealed connection (empty when it has none: unsealed, or never handshaked here).

Frames that may fail their MAC on one connection before it is closed.

Record a raw frame refused on a connection (raw_allowed false): counted in raw_refused().

Remove the hook on_frame_rejected returned [id] for; an unknown id is ignored.

Call f whenever a frame fails its MAC (the connection's reader calls it, in its own task). Returns an id for off_frame_rejected.

May raw frames (anything but session traffic) cross [fd]? False only on a certificate-mode connection where this node's or the peer's certificate lacks raw_send. Checked by NodeSend (Node.send) and NodeCall (RemoteCall); ClusterNode checks its own connections by certificate.

Raw frames refused on connections this process handshaked, in either direction.

One frame off [fd], exactly (never over-read, as recv_frame_exact, but never MAC-checked: for the handshake's own frames), before [deadline] (absolute unix ms). Err("net-kernel: handshake timed out") when the deadline passes first, or an error when the read fails or the connection closes.

Are [fd]'s frames sealed?

Frame [payload] and write it to [fd]; sealed (NetFrame.seal, with the connection's next frame number) when the connection's handshake agreed a MAC key. Err with the socket's message when the write fails.

match NetKernel.send_frame(fd, NodeSend.encode_failed(seq, "no such actor")) do
  Ok(_) -> ()
  Err(e) -> println("write failed: " ++ e)
end

The bytes of [s] (its UTF-8 encoding) as a List(Int), each 0..255.

Frame [payload] (NetFrame.encode) and render it as the String the socket layer sends. Never sealed.

NetKernel.str_to_bytes(NetKernel.to_wire([104, 105]))   -- [0, 0, 0, 2, 104, 105]

Write an already-framed (length-prefixed, unsealed) frame, sealing it first when [fd] is sealed: NodeQueue frames its messages when they are queued, before it knows when they will be written.