byte_engine / network / datagram

Module `datagram`

Raw BETP datagram processing for transport adapters and defensive tests. Pure BETP datagram processing for engine-owned transports.

Socket and channel adapters can pass raw datagrams through these pipelines before exposing application payloads. BETP remains the sans-I/O protocol layer; this module owns framing, endpoint routing, and delivery policy.

Quick Reference

Item	Kind	Description
`EncodedDatagram`	struct	The `EncodedDatagram` struct provides transport adapters with one canonical BETP packet and its exact wire length.
`ClientDatagramPipeline`	struct	The `ClientDatagramPipeline` struct isolates untrusted wire input from a client application's accepted-payload boundary.
`ServerDatagramPipeline`	struct	The `ServerDatagramPipeline` struct gives one engine-owned peer route an isolated handshake, session, and application delivery boundary.
`DatagramOutcome`	enum	The `DatagramOutcome` enum gives transport adapters a bounded, typed result for routing one peer datagram.
`DatagramDrop`	enum	The `DatagramDrop` enum helps transport adapters measure and contain invalid peer traffic without turning it into an application failure.
`PipelineError`	enum	The `PipelineError` enum separates local encoding failures from peer-input drops so adapters can fail explicitly at the responsible layer.
`MAX_BETP_DATAGRAM_SIZE`	const	The largest canonical BETP wire packet, including its header.

Structs

`EncodedDatagram`

struct EncodedDatagram {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/network/datagram.rs:25-28

The EncodedDatagram struct provides transport adapters with one canonical BETP packet and its exact wire length.

Implementations

```
fn encode(packet: Packets) -> Result<Self, PipelineError>
```
Related: PipelineError

Encodes one typed packet without allocating storage for its bytes.
```
fn as_bytes(&self) -> &[u8]
```
Returns the encoded packet without unused capacity.
```
fn len(&self) -> usize
```
Returns the encoded packet length.
```
fn is_empty(&self) -> bool
```
Returns whether the encoded packet contains no bytes.

Trait Implementations

`impl ArchivePointee for EncodedDatagram`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for EncodedDatagram`

`impl Clone for EncodedDatagram`

```
fn clone(&self) -> EncodedDatagram
```
Related: EncodedDatagram

`impl Debug for EncodedDatagram`

fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result

`impl Downcast for EncodedDatagram`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for EncodedDatagram`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for EncodedDatagram`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Eq for EncodedDatagram`

`impl<K> Equivalent for EncodedDatagram`

```
fn equivalent(&self, key: &K) -> bool
```

`impl Instrument for EncodedDatagram`

`impl LayoutRaw for EncodedDatagram`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for EncodedDatagram`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl PartialEq for EncodedDatagram`

fn eq(&self, other: &EncodedDatagram) -> bool

Related: EncodedDatagram

`impl Pointable for EncodedDatagram`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for EncodedDatagram`

```
type Metadata = ()
```

`impl Read for EncodedDatagram`

`impl StructuralPartialEq for EncodedDatagram`

`impl WithSubscriber for EncodedDatagram`

`ClientDatagramPipeline`

struct ClientDatagramPipeline {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/network/datagram.rs:133-137

The ClientDatagramPipeline struct isolates untrusted wire input from a client application's accepted-payload boundary.

Implementations

```
fn new(client_salt: u64) -> Self
```
Creates a client pipeline and begins a connection using the caller-owned salt.
```
fn is_connected(&self) -> bool
```
Returns whether the client handshake has established a session.
```
fn connection_id(&self) -> Option<u64>
```
Returns the active connection identifier after the handshake completes.
```
fn process_datagram(&mut self, datagram: &[u8], _current_time: Instant, outbound: &mut Vec<EncodedDatagram>) -> Result<DatagramOutcome, PipelineError>
```
Related: EncodedDatagram, DatagramOutcome, PipelineError

Routes one raw datagram through decoding and session validation before

returning any application-visible data.

fn advance(&mut self, _current_time: Instant, outbound: &mut Vec<EncodedDatagram>) -> Result<DatagramOutcome, PipelineError>

Advances handshake and retry work when no datagram was received.

```
fn send(&mut self, reliable: bool, data: [u8; 1024])
```
Queues one application payload for reliable or unreliable delivery.

Trait Implementations

`impl ArchivePointee for ClientDatagramPipeline`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for ClientDatagramPipeline`

`impl Downcast for ClientDatagramPipeline`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for ClientDatagramPipeline`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for ClientDatagramPipeline`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for ClientDatagramPipeline`

`impl LayoutRaw for ClientDatagramPipeline`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for ClientDatagramPipeline`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl Pointable for ClientDatagramPipeline`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for ClientDatagramPipeline`

```
type Metadata = ()
```

`impl Read for ClientDatagramPipeline`

`impl WithSubscriber for ClientDatagramPipeline`

`ServerDatagramPipeline`

struct ServerDatagramPipeline {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/network/datagram.rs:272-277

The ServerDatagramPipeline struct gives one engine-owned peer route an isolated handshake, session, and application delivery boundary.

Implementations

```
fn new(server_salt: u64) -> Self
```
Creates a server pipeline that challenges peers with the supplied salt.
```
fn is_connected(&self) -> bool
```
Returns whether this peer route has established a session.
```
fn connection_id(&self) -> Option<u64>
```
Returns the active connection identifier after the handshake completes.
```
fn process_datagram(&mut self, datagram: &[u8], current_time: Instant, outbound: &mut Vec<EncodedDatagram>) -> Result<DatagramOutcome, PipelineError>
```
Related: EncodedDatagram, DatagramOutcome, PipelineError

Routes one raw peer datagram through server handshake or connected-session

validation before returning any application-visible data.

fn advance(&mut self, current_time: Instant, outbound: &mut Vec<EncodedDatagram>) -> Result<DatagramOutcome, PipelineError>

Advances timeout and retry work when no datagram was received.

```
fn send(&mut self, reliable: bool, data: [u8; 1024])
```
Queues one application payload for reliable or unreliable delivery.

Trait Implementations

`impl ArchivePointee for ServerDatagramPipeline`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for ServerDatagramPipeline`

`impl Default for ServerDatagramPipeline`

```
fn default() -> Self
```

`impl Downcast for ServerDatagramPipeline`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for ServerDatagramPipeline`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for ServerDatagramPipeline`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for ServerDatagramPipeline`

`impl LayoutRaw for ServerDatagramPipeline`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for ServerDatagramPipeline`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl Pointable for ServerDatagramPipeline`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for ServerDatagramPipeline`

```
type Metadata = ()
```

`impl Read for ServerDatagramPipeline`

`impl<R> ReadPrimitive for ServerDatagramPipeline`

`impl WithSubscriber for ServerDatagramPipeline`

Enums

`DatagramOutcome`

enum DatagramOutcome {
    Accepted([u8; 1024]),
    Connected {
        id: u64,
    },
    Disconnected {
        id: u64,
    },
    Handled,
    Dropped(DatagramDrop),
}

Defined in crates/byte-engine/src/network/datagram.rs:68-85

The DatagramOutcome enum gives transport adapters a bounded, typed result for routing one peer datagram.

Variants

Accepted

A payload passed framing, endpoint, session, and receive-window validation.
Connected

A handshake established a session with this connection identifier.
Disconnected

A validated disconnect or timeout ended this session.
Handled

The packet was valid protocol traffic but produced no application event.
Dropped

The packet was rejected before it could become application-visible.

Trait Implementations

`impl ArchivePointee for DatagramOutcome`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for DatagramOutcome`

`impl Clone for DatagramOutcome`

```
fn clone(&self) -> DatagramOutcome
```
Related: DatagramOutcome

`impl Copy for DatagramOutcome`

`impl Debug for DatagramOutcome`

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl Downcast for DatagramOutcome`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for DatagramOutcome`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for DatagramOutcome`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Eq for DatagramOutcome`

`impl<K> Equivalent for DatagramOutcome`

```
fn equivalent(&self, key: &K) -> bool
```

`impl Instrument for DatagramOutcome`

`impl LayoutRaw for DatagramOutcome`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for DatagramOutcome`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl PartialEq for DatagramOutcome`

fn eq(&self, other: &DatagramOutcome) -> bool

Related: DatagramOutcome

`impl Pointable for DatagramOutcome`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for DatagramOutcome`

```
type Metadata = ()
```

`impl Read for DatagramOutcome`

`impl StructuralPartialEq for DatagramOutcome`

`impl WithSubscriber for DatagramOutcome`

`DatagramDrop`

enum DatagramDrop {
    TooLarge {
        actual: usize,
    },
    Decode(betp::PacketReadError),
    UnexpectedPacket,
    SessionNotEstablished,
    ConnectionIdMismatch,
    ClientSession(betp::client::Errors),
    ServerSession(betp::server::PacketHandlingResults),
}

Defined in crates/byte-engine/src/network/datagram.rs:90-108

The DatagramDrop enum helps transport adapters measure and contain invalid peer traffic without turning it into an application failure.

Variants

TooLarge

The datagram exceeds every canonical BETP packet size.
Decode

The datagram is not a canonical BETP packet.
UnexpectedPacket

The packet is not valid for this endpoint or lifecycle state.
SessionNotEstablished

Session data arrived before a connection was established.
ConnectionIdMismatch

The packet belongs to a different connection.
ClientSession

The BETP client session rejected the packet.
ServerSession

The BETP server session rejected the packet.

Trait Implementations

`impl ArchivePointee for DatagramDrop`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for DatagramDrop`

`impl Clone for DatagramDrop`

```
fn clone(&self) -> DatagramDrop
```
Related: DatagramDrop

`impl Copy for DatagramDrop`

`impl Debug for DatagramDrop`

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl Downcast for DatagramDrop`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for DatagramDrop`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for DatagramDrop`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Eq for DatagramDrop`

`impl<K> Equivalent for DatagramDrop`

```
fn equivalent(&self, key: &K) -> bool
```

`impl Instrument for DatagramDrop`

`impl LayoutRaw for DatagramDrop`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for DatagramDrop`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl PartialEq for DatagramDrop`

fn eq(&self, other: &DatagramDrop) -> bool

Related: DatagramDrop

`impl Pointable for DatagramDrop`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for DatagramDrop`

```
type Metadata = ()
```

enum PipelineError {
    EncodingFailed,
}

Defined in crates/byte-engine/src/network/datagram.rs:113-116

The PipelineError enum separates local encoding failures from peer-input drops so adapters can fail explicitly at the responsible layer.

Variants

EncodingFailed

A typed BETP packet could not fit its canonical wire representation.

Trait Implementations

`impl ArchivePointee for PipelineError`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for PipelineError`

`impl Clone for PipelineError`

```
fn clone(&self) -> PipelineError
```
Related: PipelineError

`impl Copy for PipelineError`

`impl Debug for PipelineError`

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl Display for PipelineError`

fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result

`impl Downcast for PipelineError`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for PipelineError`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for PipelineError`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Eq for PipelineError`

`impl<K> Equivalent for PipelineError`

```
fn equivalent(&self, key: &K) -> bool
```

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for PipelineError`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl PartialEq for PipelineError`

fn eq(&self, other: &PipelineError) -> bool

Related: PipelineError

`impl Pointable for PipelineError`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for PipelineError`

```
type Metadata = ()
```

```
fn to_string(&self) -> String
```

const MAX_BETP_DATAGRAM_SIZE: usize = 1_045usize;

Defined in crates/byte-engine/src/network/datagram.rs:17

The largest canonical BETP wire packet, including its header.

datagram

On this page