Trait Event 

pub trait Event:
    Serialize
    + DeserializeOwned
    + Send
    + Sync {
    const SUBJECT: &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> { ... }
}

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: &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