Struct EmergentMessage 

pub struct EmergentMessage {
    pub id: MessageId,
    pub message_type: MessageType,
    pub source: PrimitiveName,
    pub correlation_id: Option<CorrelationId>,
    pub causation_id: Option<CausationId>,
    pub timestamp_ms: Timestamp,
    pub payload: Value,
    pub metadata: Option<Value>,
}

Standard message envelope for all Emergent communications.

All messages in Emergent use this standard envelope format. Developers specify a message_type string and put their domain data in the payload field.

Example

use emergent_client::EmergentMessage;
use serde_json::json;

let message = EmergentMessage::new("user.created")
    .with_source("user_service")
    .with_payload(json!({
        "user_id": "u_12345",
        "email": "user@example.com"
    }));

Fields

id: MessageId

Unique message ID (TypeID format: msg_<uuid_v7>).

message_type: MessageType

Message type for routing (e.g., “email.received”, “timer.tick”).

source: PrimitiveName

Source client that published this message.

correlation_id: Option<CorrelationId>

Optional correlation ID for request-response or tracing.

causation_id: Option<CausationId>

Optional causation ID (ID of message that triggered this one).

timestamp_ms: Timestamp

Timestamp when message was created (Unix ms).

payload: Value

User-defined payload (any serializable data).

metadata: Option<Value>

Optional metadata for debugging, tracing, etc.

Implementations

impl EmergentMessage

pub fn new(message_type: &str) -> Self

Create a new message with the given type.

Generates a unique ID and sets the current timestamp.

Panics

Panics if the message type is invalid.

pub fn new_with_id_and_timestamp( message_type: &str, id: MessageId, timestamp_ms: Timestamp, ) -> Self

Create a new message with explicit ID and timestamp.

This is a pure function suitable for testing and deterministic message creation. For production use, prefer new() which generates a unique ID and current timestamp.

Panics

Panics if the message type is invalid.

pub fn with_source(self, source: &str) -> Self

Set the source of this message.

Panics

Panics if the source name is invalid.

pub fn with_payload(self, payload: impl Serialize) -> Self

Set the payload of this message.

pub fn with_correlation_id(self, id: impl Into<CorrelationId>) -> Self

Set the correlation ID (for request-response patterns).

pub fn with_causation_id(self, id: impl Into<CausationId>) -> Self

Set the causation ID (ID of the message that triggered this one).

pub fn with_correlation_id_option(self, id: Option<&CorrelationId>) -> Self

Set the correlation ID from an optional value.

Useful for copying correlation IDs from request messages to responses.

pub fn with_causation_from_message(self, msg_id: &MessageId) -> Self

Set the causation ID from a MessageId.

This is a convenience method that converts the MessageId to a CausationId.

pub fn with_metadata(self, metadata: impl Serialize) -> Self

Set optional metadata.

pub fn id(&self) -> &MessageId

Get the message ID.

pub fn message_type(&self) -> &MessageType

Get the message type.

pub fn source(&self) -> &PrimitiveName

Get the source.

pub fn payload(&self) -> &Value

Get the raw payload value.

pub fn payload_as<T: DeserializeOwned>(&self) -> Result<T, Error>

Deserialize the payload into a specific type.

Errors

Returns an error if the payload cannot be deserialized into type T.

pub fn has_stdout_payload(&self) -> bool

Check whether this message has an exec-source payload shape.

Returns true if the payload is a JSON object with a stdout string field, which is the envelope format produced by the exec-source primitive.

pub fn unwrap_stdout(self) -> Self

Unwrap an exec-source payload by extracting and parsing the stdout field.

If the payload is an object with a stdout string field (the envelope format produced by exec-source), extracts that string and attempts to parse it as JSON. If parsing succeeds, the payload is replaced with the parsed value. If stdout is not valid JSON, the payload is replaced with the raw string value.

If the payload does not have the exec-source shape, the message is returned unchanged.

This eliminates the need for a dedicated exec-handler running jq -c '.stdout | fromjson' in the pipeline.

pub fn to_json(&self) -> Result<Vec<u8>, Error>

Serialize the message to JSON bytes.

Errors

Returns an error if serialization fails.

pub fn from_json(data: &[u8]) -> Result<Self, Error>

Deserialize a message from JSON bytes.

Errors

Returns an error if deserialization fails.

pub fn to_msgpack(&self) -> Result<Vec<u8>, Error>

Serialize the message to MessagePack bytes.

Errors

Returns an error if serialization fails.

pub fn from_msgpack(data: &[u8]) -> Result<Self, Error>

Deserialize a message from MessagePack bytes.

Errors

Returns an error if deserialization fails.

Trait Implementations

impl Clone for EmergentMessage

fn clone(&self) -> EmergentMessage

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EmergentMessage

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for EmergentMessage

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for EmergentMessage

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.