Trait Event 

pub trait Event:
    Serialize
    + DeserializeOwned
    + Send
    + Sync {
    const SUBJECT: &'static str;
    const COMPATIBLE_SUBJECTS: &'static [&'static str] = _;

    // Provided methods
    fn subject(&self) -> Cow<'static, str> { ... }
    fn into_payload(self) -> Result<Vec<u8>, Error> { ... }
    fn from_payload(subject: &str, payload: &[u8]) -> Result<Self, Error> { ... }
}

Re-exported so services only need to depend on arminius-lib-nats.

The message-bus Subscriber trait is intentionally not re-exported here to avoid clashing with the async_nats::Subscriber re-export above; reach it via arminius_lib_message_bus::Subscriber. Generic event type that can be sent between services.

Events must be serializable and define a subject (topic) where they will be published. The subject typically includes version information for compatibility handling.

Example

use arminius_lib_message_bus::Event;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct RoomCreated {
	room_id: String,
}

impl Event for RoomCreated {
	const SUBJECT: &str = "RoomCreated.v1";
}

Derive macro

Use #[derive(Event)] with a #[subject(...)] attribute to avoid the boilerplate:

use arminius_lib_message_bus::Event;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Event)]
#[subject(version = "1")]
struct RoomCreated {
	room_id: String,
}

Supported #[subject(...)] forms:

1. #[subject("MyEvent.v1")]
2. #[subject(name = "MyEvent", version = 1)]
3. #[subject(name = "MyEvent", version = "1")]
4. #[subject(name = "MyEvent", version("1"))]
5. #[subject(name = "MyEvent", version = "2", compatible = [v0::MyEvent])]

When name is omitted the struct name is used. The compatible list names older event types whose subjects the subscriber will also consume, converting each to Self via the required From<OldType> for Self implementation.

Per-instance (dynamic) subjects

A subject template may contain {field} placeholders that name fields of the struct. Each placeholder becomes a NATS * wildcard in Event::SUBJECT (the subscribe/stream pattern) and is interpolated via Display in Event::subject (the concrete publish subject):

use arminius_lib_message_bus::Event;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Event)]
#[subject(name = "rooms.{room_id}.events", version = "1")]
struct RoomCreated {
	room_id: u64,
}
// RoomCreated::SUBJECT             == "rooms.*.events.v1"   (subscribe to all)
// RoomCreated { room_id: 7 }.subject() == "rooms.7.events.v1"   (publish target)

Required Associated Constants

const SUBJECT: &'static str

The NATS subject pattern this event type lives under.

Used for stream creation and subscription, so it may contain NATS wildcards (*) when the event uses per-instance subjects. For static events it equals the concrete publish subject. Should include version information for backward compatibility, e.g., "RoomCreated.v1", "RoomCreated.v2", "rooms.*.events.v1".

Provided Associated Constants

const COMPATIBLE_SUBJECTS: &'static [&'static str] = _

Subjects of older compatible versions of this event type.

When non-empty, a subscriber will also consume messages on these subjects and convert them to Self via the generated From impls. Populated automatically by #[subject(version = ..., compatible = [OldType, ...])].

Provided Methods

fn subject(&self) -> Cow<'static, str>

The concrete subject this instance is published to.

Defaults to Event::SUBJECT. Events that use {field} placeholders in their #[subject(...)] template get a generated override that interpolates the named fields, e.g. rooms.7.events.v1.

fn into_payload(self) -> Result<Vec<u8>, Error>

Serialize this event into the transport payload.

The wire format is owned here, not by the transport, so the encoding can change (e.g. JSON to protobuf) without the publisher knowing.

fn from_payload(subject: &str, payload: &[u8]) -> Result<Self, Error>

Deserialize a raw payload into Self, using subject to select the right schema when compatible older versions are present.

The default implementation ignores subject and deserializes directly as Self.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors