Search documentation of macula

# macula_deliver_packet (macula v4.4.1)

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