Byte Engine Docs
View on docs.rs

datagram

Generated Rust API reference for byte_engine.

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 and decides delivery; this module owns framing and endpoint routing.

Contents

Quick Reference

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

Structs

EncodedDatagram

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

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

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
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 DowncastSync for EncodedDatagram
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
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
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:132-135

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>

    Related: EncodedDatagram, DatagramOutcome, PipelineError

    Advances handshake, retry, keepalive, and timeout work when no datagram was received.

    Returns DatagramOutcome::Disconnected once the server goes quiet for betp::TIMEOUT, or never confirms

    the connection within it. Check Self::is_connected to learn when the server has confirmed it.

  • fn send(&mut self, reliable: bool, data: Payload)

    Related: Payload

    Queues one application payload for reliable or unreliable delivery.

  • fn drain_received(&mut self) -> impl Iterator<Item = Payload> + '_

    Related: Payload

    Removes and returns the payloads delivered so far, reliable ones in the order they were sent.

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 DowncastSync for ClientDatagramPipeline
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
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 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:238-242

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>

    Related: EncodedDatagram, DatagramOutcome, PipelineError

    Advances timeout and retry work when no datagram was received.

  • fn send(&mut self, reliable: bool, data: Payload)

    Related: Payload

    Queues one application payload for reliable or unreliable delivery.

  • fn drain_received(&mut self) -> impl Iterator<Item = Payload> + '_

    Related: Payload

    Removes and returns the payloads delivered so far, reliable ones in the order they were sent.

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 DowncastSync for ServerDatagramPipeline
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
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 Pointee for ServerDatagramPipeline
  • type Metadata = ()
impl Read for ServerDatagramPipeline
impl<R> ReadPrimitive for ServerDatagramPipeline
impl WithSubscriber for ServerDatagramPipeline

Enums

DatagramOutcome

enum DatagramOutcome {
    Connected {
        id: u64,
    },
    Disconnected {
        id: u64,
    },
    Handled,
    Dropped(DatagramDrop),
}

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

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

Payloads are not part of the outcome: one datagram can complete a run of reliable messages, so read them with the pipeline's drain_received after each call.

Variants

  • Connected

    The server accepted a client's handshake and established a session with this connection identifier. A client learns of its own connection through ClientDatagramPipeline::is_connected instead.

  • 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
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 DowncastSync for DatagramOutcome
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
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
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:89-107

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
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 DowncastSync for DatagramDrop
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
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 Pointee for DatagramDrop
  • type Metadata = ()
impl Read for DatagramDrop
impl StructuralPartialEq for DatagramDrop
impl WithSubscriber for DatagramDrop

PipelineError

enum PipelineError {
    EncodingFailed,
}

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

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
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 DowncastSync for PipelineError
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Eq for PipelineError
impl<K> Equivalent for PipelineError
  • fn equivalent(&self, key: &K) -> bool
impl Error for PipelineError
impl Instrument for PipelineError
impl LayoutRaw for PipelineError
  • 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 Pointee for PipelineError
  • type Metadata = ()
impl Read for PipelineError
impl StructuralPartialEq for PipelineError
impl ToString for PipelineError
  • fn to_string(&self) -> String
impl WithSubscriber for PipelineError

Constants

MAX_BETP_DATAGRAM_SIZE

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.

On this page

Module datagramContentsQuick ReferenceStructsEncodedDatagramImplementationsTrait Implementationsimpl ArchivePointee for EncodedDatagramimpl<ST> CastableFrom for EncodedDatagramimpl Clone for EncodedDatagramimpl Debug for EncodedDatagramimpl Downcast for EncodedDatagramimpl DowncastSync for EncodedDatagramimpl Eq for EncodedDatagramimpl<K> Equivalent for EncodedDatagramimpl Instrument for EncodedDatagramimpl LayoutRaw for EncodedDatagramimpl<T, N1> Niching for EncodedDatagramimpl PartialEq for EncodedDatagramimpl Pointee for EncodedDatagramimpl Read for EncodedDatagramimpl StructuralPartialEq for EncodedDatagramimpl WithSubscriber for EncodedDatagramClientDatagramPipelineImplementationsTrait Implementationsimpl ArchivePointee for ClientDatagramPipelineimpl<ST> CastableFrom for ClientDatagramPipelineimpl Downcast for ClientDatagramPipelineimpl DowncastSync for ClientDatagramPipelineimpl Instrument for ClientDatagramPipelineimpl LayoutRaw for ClientDatagramPipelineimpl<T, N1> Niching for ClientDatagramPipelineimpl Pointee for ClientDatagramPipelineimpl Read for ClientDatagramPipelineimpl WithSubscriber for ClientDatagramPipelineServerDatagramPipelineImplementationsTrait Implementationsimpl ArchivePointee for ServerDatagramPipelineimpl<ST> CastableFrom for ServerDatagramPipelineimpl Default for ServerDatagramPipelineimpl Downcast for ServerDatagramPipelineimpl DowncastSync for ServerDatagramPipelineimpl Instrument for ServerDatagramPipelineimpl LayoutRaw for ServerDatagramPipelineimpl<T, N1> Niching for ServerDatagramPipelineimpl Pointee for ServerDatagramPipelineimpl Read for ServerDatagramPipelineimpl<R> ReadPrimitive for ServerDatagramPipelineimpl WithSubscriber for ServerDatagramPipelineEnumsDatagramOutcomeVariantsTrait Implementationsimpl ArchivePointee for DatagramOutcomeimpl<ST> CastableFrom for DatagramOutcomeimpl Clone for DatagramOutcomeimpl Copy for DatagramOutcomeimpl Debug for DatagramOutcomeimpl Downcast for DatagramOutcomeimpl DowncastSync for DatagramOutcomeimpl Eq for DatagramOutcomeimpl<K> Equivalent for DatagramOutcomeimpl Instrument for DatagramOutcomeimpl LayoutRaw for DatagramOutcomeimpl<T, N1> Niching for DatagramOutcomeimpl PartialEq for DatagramOutcomeimpl Pointee for DatagramOutcomeimpl Read for DatagramOutcomeimpl StructuralPartialEq for DatagramOutcomeimpl WithSubscriber for DatagramOutcomeDatagramDropVariantsTrait Implementationsimpl ArchivePointee for DatagramDropimpl<ST> CastableFrom for DatagramDropimpl Clone for DatagramDropimpl Copy for DatagramDropimpl Debug for DatagramDropimpl Downcast for DatagramDropimpl DowncastSync for DatagramDropimpl Eq for DatagramDropimpl<K> Equivalent for DatagramDropimpl Instrument for DatagramDropimpl LayoutRaw for DatagramDropimpl<T, N1> Niching for DatagramDropimpl PartialEq for DatagramDropimpl Pointee for DatagramDropimpl Read for DatagramDropimpl StructuralPartialEq for DatagramDropimpl WithSubscriber for DatagramDropPipelineErrorVariantsTrait Implementationsimpl ArchivePointee for PipelineErrorimpl<ST> CastableFrom for PipelineErrorimpl Clone for PipelineErrorimpl Copy for PipelineErrorimpl Debug for PipelineErrorimpl Display for PipelineErrorimpl Downcast for PipelineErrorimpl DowncastSync for PipelineErrorimpl Eq for PipelineErrorimpl<K> Equivalent for PipelineErrorimpl Error for PipelineErrorimpl Instrument for PipelineErrorimpl LayoutRaw for PipelineErrorimpl<T, N1> Niching for PipelineErrorimpl PartialEq for PipelineErrorimpl Pointee for PipelineErrorimpl Read for PipelineErrorimpl StructuralPartialEq for PipelineErrorimpl ToString for PipelineErrorimpl WithSubscriber for PipelineErrorConstantsMAX_BETP_DATAGRAM_SIZE