Struct DeRecMessageBuilder 

pub struct DeRecMessageBuilder<State, Mode> { /* private fields */ }

Builds a DeRecMessage envelope containing protocol metadata and an encrypted payload.

The builder uses typestate and mode generics:

• State controls whether the payload is ready to build
• Mode controls which encryption method is permitted

This ensures at compile time that:

• build cannot be called before encryption
• a pairing builder cannot call channel encryption
• a channel builder cannot call pairing encryption

Type parameters

• State - encryption state marker, typically NotEncrypted or Encrypted
• Mode - builder mode marker, either PairingMode or ChannelMode

Required fields

Before calling build, the builder must have:

• channel_id
• timestamp
• message
• the appropriate encryption method applied

Typical usage

Pairing mode:

let envelope = DeRecMessageBuilder::new()
    .channel_id(channel_id)
    .timestamp(current_timestamp())
    .message(&pair_request)
    .encrypt_pairing(helper_public_key)?
    .build()?;

Channel mode:

let envelope = DeRecMessageBuilder::channel()
    .channel_id(channel_id)
    .timestamp(current_timestamp())
    .message_body(MessageBody::VerifyShareRequest(&verify_request))
    .encrypt(shared_key)?
    .build()?;

Implementations

impl<State, Mode> DeRecMessageBuilder<State, Mode>

pub fn channel_id(self, channel_id: ChannelId) -> Self

Sets the channel identifier for the envelope.

In the DeRec protocol, channel_id identifies the logical communication channel associated with the message.

Arguments

• channel_id - channel identifier to embed in the envelope

Returns

The updated builder.

pub fn sequence(self, sequence: u32) -> Self

Sets the sequence number for the envelope.

The sequence number tracks message ordering and may also be used by higher-level protocol logic such as key rotation or replay detection.

Arguments

• sequence - monotonically increasing message counter

Returns

The updated builder.

pub fn timestamp(self, timestamp: Timestamp) -> Self

Sets the timestamp for the envelope.

Arguments

• timestamp - protobuf Timestamp representing message creation time

Returns

The updated builder.

pub fn trace_id(self, trace_id: u64) -> Self

Sets the request/response correlation token for the envelope.

On request envelopes the requester chooses any opaque u64 to identify the in-flight call. On response envelopes the responder echoes back the value from the request. Both happens automatically when this builder is driven by the standard request/response producers, but the value can also be set explicitly by callers that need to correlate from outside.

Defaults to zero when not set, which the protocol treats as “no correlation requested.”

Arguments

• trace_id - opaque correlation token

Returns

The updated builder.

pub fn auto_trace_id(self) -> Self

Sets a freshly-drawn random trace_id on the envelope.

Convenience for request producers that want a new correlation token without managing the RNG themselves. Uses the same random source as the rest of the library (rand::rng().next_u64()).

Returns

The updated builder with a random trace_id.

pub fn message_body(self, body: MessageBody) -> Self

Encodes the inner payload and sets the message_type discriminant from a MessageBody.

This is the canonical way to attach the inner message — prost-encodes the payload and records the correct i32 message_type value so that DeRecMessageBuilder::build can embed it in the outer DeRecMessage envelope.

Arguments

• body - a MessageBody variant wrapping a reference to the inner protocol message

Returns

The updated builder.

impl DeRecMessageBuilder<NotEncrypted, PairingMode>

pub fn pairing() -> Self

Creates a new pairing-mode DeRecMessageBuilder.

This constructor is intended for flows that use pairing-envelope encryption. Builders created with this constructor can call encrypt_pairing but cannot call channel encryption.

Returns

A new empty builder in pairing mode.

Example

let builder = DeRecMessageBuilder::new();

pub fn encrypt_pairing( self, public_key: impl AsRef<[u8]>, ) -> Result<DeRecMessageBuilder<Encrypted, PairingMode>, DeRecMessageBuilderError>

Encrypts the encoded payload using pairing-envelope encryption.

This method is only available on builders created in PairingMode. After successful encryption, the builder transitions to the Encrypted state, enabling build.

Arguments

• public_key - recipient public key used for asymmetric pairing encryption

Returns

On success, returns a new builder in the Encrypted state.

Errors

Returns DeRecMessageBuilderError if:

• DeRecMessageBuilderError::MissingMessage if no payload was set
• the underlying pairing encryption routine fails

impl DeRecMessageBuilder<NotEncrypted, ChannelMode>

pub fn channel() -> Self

Creates a new channel-mode DeRecMessageBuilder.

This constructor is intended for flows that use symmetric channel encryption. Builders created with this constructor can call encrypt but cannot call pairing encryption.

Returns

A new empty builder in channel mode.

Example

let builder = DeRecMessageBuilder::channel();

pub fn encrypt( self, shared_key: &[u8; 32], ) -> Result<DeRecMessageBuilder<Encrypted, ChannelMode>, DeRecMessageBuilderError>

Encrypts the encoded payload using channel encryption.

This method is only available on builders created in ChannelMode. The nonce is derived from the channel ID by placing the big-endian u64 channel identifier into the last 8 bytes of a 32-byte nonce.

After successful encryption, the builder transitions to the Encrypted state, enabling build.

Arguments

• shared_key - 32-byte symmetric channel key

Returns

On success, returns a new builder in the Encrypted state.

Errors

Returns DeRecMessageBuilderError if:

• DeRecMessageBuilderError::MissingMessage if no payload was set
• DeRecMessageBuilderError::MissingChannelId if channel_id was not set
• the underlying channel encryption routine fails

impl<Mode> DeRecMessageBuilder<Encrypted, Mode>

pub fn build(self) -> Result<DeRecMessage, DeRecMessageBuilderError>

Builds the final DeRecMessage envelope.

This method is only available after one of the permitted encryption methods has been called successfully.

Returns

On success returns a DeRecMessage containing:

• protocol version from ProtocolVersion::current
• channel_id
• sequence or 0 if no sequence was set
• timestamp
• message containing the encrypted payload bytes

Errors

Returns DeRecMessageBuilderError if:

• DeRecMessageBuilderError::MissingChannelId if channel_id was not set
• DeRecMessageBuilderError::MissingTimestamp if timestamp was not set
• DeRecMessageBuilderError::MissingMessage if the encrypted payload is empty

Notes

This function does not perform any additional cryptographic validation. It only validates that the required envelope fields are present.

Trait Implementations

impl<State: Debug, Mode: Debug> Debug for DeRecMessageBuilder<State, Mode>

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

Formats the value using the given formatter.