Crunch - Domain event interface

Crunch allows services to distribute their own events, as domain events. Domain events are a more strict representation on the api between services in different domains, they are meant to tell the subscriber what has happened in the domain.

The value of crunch is that you can separate your own business domain from other services, and communicate through schemas and events rather than depending on each others libraries.

Usage

See examples for a more holistic listing of features

impl Event for SomeEvent {
    fn event_info(&self) -> EventInfo {
        EventInfo {
            domain: "some-domain",
            entity_type: "some-entity",
        }
    }
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let in_memory = Persistence::in_memory();
    OutboxHandler::new(in_memory.clone()).spawn();
    let publisher = Publisher::new(in_memory);

    publisher
        .publish(SomeEvent {
            name: "some-name".into(),
        })
        .await?;

    Ok(())
}

This will publish SomeEvent as a domain event. The API is subject to change, as the codegen is being built.

Workflow

Domain events works off of the principle that your interface is protobuf, as such your service will publish protobuf events, and subscribe to other services if needed.

To handle this workflow we introduce crunch.toml a file to manage these relationships.

Bootstrap the file using crunch init, see crunch cli for more info, it can automatically discover and add subscriptions, bump version, publish schemas etc.

[service]
service = "users-creation"
domain = "users"
codegen = ["rust"]

[[publish]]	
path = "crates/users-service/crunch"

[[subscription]]
service = "onboarding-signup"
domain = "onboarding"
version = "1.0.1"
output-path = "crates/users-service/crunch"

See docs for more information (TBA)

Tooling

When crunch is used in services it needs some supportive tooling, it isn't a requirement, but it helps ease development when using them.

• Cli Used to generate code, add subscriptions, publish event schema, bump versions and more
• Codegen Can be used to automatically generate rust code depending on your crunch.toml file

Extensions

At its heart crunch is just a opinionated transport protocol, as such additional packages can be added for various needs:

• Replay Stores events in a replay store, so that consumers can choose to replay them whenever they want
• Eventsource Allows proper eventsourcing for the application, check the readme for more info
• Cuddle Will read overlapping values from .cuddle.yaml, as such we don't have to define service, domain multiple times, this also allows inheritance for certain fields.

Features

Crunch will is configurable to a variety of different transports, persistence layers and more. We recommend a few of them, which crunch automatically ships with (opt out via. default-features = false in Cargo.toml)

See the docs for each of them, to see how they can be enabled, and how to setup settings for them. If using crunch-cuddle, these settings can be inherited from a cuddle-component

We recommend wrapping and exposing the parts you need to the library, so that your services uses a consistent and opinionated layer on top of crunch.

Transport

You will need a transport of some sort. Transport is what transfers messages between services, crunch is built to be configurable, and unopinionated, as such most messaging protocols should work fine.

• NATS (recommended)
• Tokio channel (used for in-memory processing)

Persistence

Crunch will need a persistence layer, like the other components these can be swapped in

• PostgreSQL (recommended)
• In memory (used for in-memory processing)