Packets and links
Actual packet construction, validation limits and incomplete link transport integration.
The packet crate encodes wire data; the link crate models session state and encrypted channels. They expose separate APIs and do not automatically establish a network connection when composed.
Local packet round trip
Packet::new takes a packet type, destination type, address bytes and data bytes. It returns a Result<Packet>. It does not take a Header plus payload.
This example uses an unauthenticated local fixture with one 16-byte address and no IFAC field. Signatures and method bodies were checked against source; this documentation pass did not execute or compile the example.
use filament_packet::{DestinationType, Packet, PacketType, PacketValidator};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let packet = Packet::new(
PacketType::Data,
DestinationType::Single,
vec![0u8; 16],
b"local packet fixture".to_vec(),
)?;
PacketValidator::new().validate(&packet)?;
let wire = packet.encode()?;
let decoded = Packet::parse(wire)?;
assert_eq!(decoded.data.as_ref(), b"local packet fixture");
Ok(())
}Header::new(packet_type, destination_type) is the separate header constructor. Header type controls whether an address section contains 16 or 32 bytes. Packet builders expose context, propagation, hop count and IFAC fields. The current protocol MTU constant is 500 bytes. Packet declarations, header declarations.
Validation is structural
PacketValidator checks packet size, hop count, address/header consistency, context flags and IFAC field consistency. It does not verify HMAC or Ed25519 signatures. with_strict_ifac changes field validation, not cryptographic verification.
Packet::parse currently returns IFAC size encoding not yet implemented for an IFAC-flagged header. Encoding an IFAC-bearing packet does not make that packet parseable by this implementation. Validation reference.
Link API and current state
| Operation | Actual shape and behavior |
|---|---|
| Create initiator | Link::establish(identity, destination, options).await creates pending local state. Destination is a 16-byte array. |
| Accept request | Link::accept(identity, request, options).await validates the request and prepares proof/channel state. Sending that proof is still a transport TODO. |
| Handle proof | handle_proof(proof, responder_identity).await requires an initiator ephemeral secret; establish currently leaves it unset, so the public handshake flow is incomplete. |
| Send | send(bytes).await requires an established state, encrypts and queues bytes locally; remote transmission is unfinished. |
| Receive | recv().await waits on the receive queue and returns Result<Option<ChannelMessage>>. recv_timeout(duration).await adds a timeout. |
| Inspect | id() is synchronous; state(), is_active() and is_established() are async. LinkState is a struct containing a LinkStatus. |
| Close | close().await updates local state. It is not a demonstrated remote close handshake. |
Use the link declarations, state declarations, channel declarations, keepalive declarations and resource declarations for precise types. Resource and keepalive APIs inherit the unfinished link/transport integration; their presence is not a file-delivery or reliability guarantee.
