macula_deliver_packet (macula v4.2.2)

View Source

Ingress delivery for macula-net packets.

Receives a CBOR-encoded macula-net envelope (typically from macula_net_transport_quic), decodes it via macula_cbor_nif, validates against spec, and writes the inner IPv6 packet to the local TUN device when the destination is one of the locally-hosted addresses.

Phase 1 simplification (PLAN_MACULA_NET.md §5.2): single-hop only. This station receives a packet whose dst is expected to be local; if not, we drop and log. Multi-hop forwarding (decrement TTL, re-route) lands in Phase 2 alongside the DHT.

Decoupled from macula_tun via a TunWriter callback so this slice has no compile-time dependency on the kernel-side NIF.

Summary

Types

config/0
tun_writer/0

Functions

configure(_)

Install the local-addresses set + TUN writer callback. Calling configure/1 again replaces the previous config.

handle_envelope(Cbor)

Handle a single inbound CBOR-encoded macula-net envelope.

Types

config/0

-type config() :: #{local_addresses := [<<_:128>>], tun_writer := tun_writer()}.

tun_writer/0

-type tun_writer() :: fun((IPv6Packet :: binary()) -> ok | {error, term()}).

Functions

configure(_)

-spec configure(config()) -> ok.

Install the local-addresses set + TUN writer callback. Calling configure/1 again replaces the previous config.

handle_envelope(Cbor)

-spec handle_envelope(binary()) ->
                         ok |
                         {error,
                          version_unsupported | decode_failed | no_route | not_configured |
                          tun_write_failed |
                          term()}.

Handle a single inbound CBOR-encoded macula-net envelope.

Returns:

  • ok — payload delivered to local TUN, OR a non-data control message accepted but not handled (Phase 1 stub for ctrl/gossip)
  • {error, version_unsupported} — packet's v field unknown
  • {error, decode_failed} — CBOR malformed / missing fields
  • {error, no_route} — dst not in local-addresses set
  • {error, not_configured} — configure/1 not called yet
  • {error, tun_write_failed} — kernel write returned an error