Trait Encoder 

pub trait Encoder: Send + Sync {
    // Required methods
    fn encode(
        &self,
        event: &ReplicationEvent,
        buffer: &mut [u8],
    ) -> Result<usize, EncodeError>;
    fn decode(&self, buffer: &[u8]) -> Result<ComponentUpdate, EncodeError>;
    fn encode_event(&self, event: &NetworkEvent) -> Result<Vec<u8>, EncodeError>;
    fn decode_event(&self, data: &[u8]) -> Result<NetworkEvent, EncodeError>;
    fn max_encoded_size(&self) -> usize;
}

Defines the serialization strategy for network payloads.

Why this exists

In Phase 1, this wraps serde + rmp-serde for rapid iteration. In Phase 3, this becomes a custom bit-packer that writes individual bits across 32-bit word boundaries for maximum compression.

Performance contract

Phase 1 (current) implementations may allocate during serialization to simplify development. However, avoiding allocations is a primary Phase 3 goal for the custom bit-packer.

In Phase 3, implementations MUST be allocation-free on the hot path. The encode method writes into a caller-provided buffer. The decode method reads from a borrowed slice. No Vec, no String, no heap allocation during steady-state operation.

Required Methods

fn encode( &self, event: &ReplicationEvent, buffer: &mut [u8], ) -> Result<usize, EncodeError>

Serializes a replication event into the provided buffer.

Returns the number of bytes written. If the buffer is too small, returns EncodeError::BufferOverflow — the caller must retry with a larger buffer or fragment the event.

Errors

Returns EncodeError::BufferOverflow if the buffer is too small.

fn decode(&self, buffer: &[u8]) -> Result<ComponentUpdate, EncodeError>

Deserializes raw bytes into a component update.

Returns EncodeError::MalformedPayload if the bytes do not constitute a valid event. The caller must handle this gracefully (log + discard) — malformed packets are expected from lossy networks.

Errors

Returns EncodeError::MalformedPayload on invalid payload bytes, or EncodeError::UnknownComponent for unregistered component types.

fn encode_event(&self, event: &NetworkEvent) -> Result<Vec<u8>, EncodeError>

Encodes a high-level NetworkEvent into a byte vector.

Errors

Returns EncodeError::Io if serialization fails.

fn decode_event(&self, data: &[u8]) -> Result<NetworkEvent, EncodeError>

Decodes a high-level NetworkEvent from a byte slice.

Errors

Returns EncodeError::MalformedPayload if the bytes are not a valid event.

fn max_encoded_size(&self) -> usize

Returns the maximum possible encoded size for a single event.

Used by the transport layer to pre-allocate datagram buffers. Implementations should return a tight upper bound, not a wild guess.

Implementors