101 lines
4.0 KiB
Markdown
101 lines
4.0 KiB
Markdown
# 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](examples/) for a more holistic listing of features
|
|
|
|
```rust
|
|
#[tokio::main]
|
|
async fn main() -> anyhow::Result<()> {
|
|
let crunch = crunch::Builder::default().build()?;
|
|
|
|
crunch.subscribe(|event| async move {
|
|
println!("received event: {:?}", event);
|
|
|
|
Ok(())
|
|
})
|
|
.await?;
|
|
|
|
crunch
|
|
.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](crates/crunch-cli) for more info, it can automatically discover and add subscriptions, bump version, publish schemas etc.
|
|
|
|
```toml
|
|
[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](docs/index.md) 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.
|
|
|
|
- [x] [Cli](crates/crunch-cli) Used to generate code, add subscriptions, publish event schema, bump versions and more
|
|
- [x] Codegen done (at least for an alpha)
|
|
- [ ] Rest
|
|
- [x] [Codegen](crates/crunch-codegen) Can be used to automatically generate rust code depending on your crunch.toml file
|
|
- [x] Main serialization and protobuf -> rust
|
|
- [ ] Domain information
|
|
|
|
## Extensions
|
|
|
|
At its heart crunch is just a opinionated transport protocol, as such additional packages can be added for various needs:
|
|
|
|
- [ ] [Replay](crates/crunch-replay) Stores events in a replay store, so that consumers can choose to replay them whenever they want
|
|
- [ ] [Eventsource](crates/crunch-eventsource) Allows proper eventsourcing for the application, check the readme for more info
|
|
- [ ] [Cuddle](crates/crunch-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.
|
|
|
|
- [x] [NATS (recommended)](crates/crunch-transport-nats)
|
|
- [x] [Tokio channel (used for in-memory processing)](crates/crunch-transport-tokio-channel)
|
|
|
|
### Persistence
|
|
|
|
Crunch will need a persistence layer, like the other components these can be swapped in
|
|
|
|
- [ ] [PostgreSQL (recommended)](crates/crunch-postgres)
|
|
- [x] [In memory (used for in-memory processing)](crates/crunch-in-memory)
|