CERK

CERK is an open-source CloudEvents Router written in Rust with a MicroKernel architecture.

Introduction

CERK lets you route your CloudEvents between different different ports. Ports are transport layer bindings over which CloudEvents can be exchanged. It is built with modularity and portability in mind.

The project was initially created during the student research project CloudEvents Router and extended in the bachelor thesis Reliable Messaging using the CloudEvents Router.

The conference paper Reliable Event Routing in the Cloud and on the Edge: An Internet-of-Things Solution in the AgeTech Domain describes a specific problem and the solution that was addressed with CERK.

Get Started

The easiest way to use the router is to use the docker image.

If you like to build the router by yourself, start with an example. E.g. the hello world example.

Components

CERK comes with a couple of prefabricated components, but implementing custom components is easy.

MicroKernel

The MicroKernel is responsible for starting the other components with the help of the Scheduler and brokering messages between them.

The MicroKernel is implemented in the cerk crate.

Runtimes

The Runtime provides a Scheduler and a Channel (Sender/Receiver) implementation.

The Scheduler is responsible for scheduling the internal servers with a platform specific scheduling strategy.

Name	Scheduling Strategy	Channel Strategy	Compatible with
cerk_runtime_threading	std::thread	std::sync::mpsc	Linux / MacOS

Ports

The Port is responsible for exchanging CloudEvents with the outside world. A Port can be instantiated multiple times with different configurations.

Name	type	Serialization	Connection
port_input_unix_socket_json	input	JSON	UNIX Socket
port_output_unix_socket_json	output	JSON	UNIX Socket
port_mqtt	input/output	JSON	MQTT
port_mqtt_mosquitto	input/output	JSON	MQTT
port_amqp	input/output	JSON	AMQP
port_sequence_generator	input	-	<time based>
port_printer	output	TEXT

Routers

The Router is responsible for deciding to which port a received CloudEvent should be forwarded to.

Name	Description
cerk_router_broadcast	The broadcast router forwards all incoming CloudEvents to the configured ports.
cerk_router_rule_based	The rule-based router routes events based on the given configuration. The configurations are structured in a tree format. One configuration tree per output port needs to be configured. The operations And, Or, Contains, StartsWith and more are supported.

ConfigLoaders

The ConfigLoader is responsible for providing the newest port configurations and routing rules.

Name	Description
config_loader_file	Loads the configurations from a json based file
config loader_static	Have to be implemented for each project individually

Loaders

The Loader helps by starting the router with different components.

Name	Description
cerk_loader_file	Starts the router by configuration provided by a json file

Health Check Ports

The Health Check Port provides an interface to check if the router is healthy. Technically they use the same plugin interface as the ports; however, they do not send or receive CloudEvents.

Name	Interface
cerk_port_health_check_http	HTTP

Examples

Check out the README in the folder of each example for more details and setup instructions.

Name	Description
Hello World	Routing CloudEvents that are generated from an input port to an output port, the output port print the result to the console.
Rule Based Routing Example	CloudEvents that are generated from an input port are routed to an output port, but in this example only every tenth event gets routed to the output port because they are filtered by id. The id has to end with 0, thus only 10,20,30,... are printed.
UNIX Socket	Routes CloudEvents from an input UNIX Socket port to an output UNIX Socket port
MQTT	Routes CloudEvents that are generated from an input port to an output port, the output port publishes the events on an MQTT topic. A second router subscribes to the same topic with an MQTT port and routes them to a port which prints the event to stdout.
AMQP to Printer	Routes CloudEvents from a RabbitMQ exchange to a queue to CERK and finally prints them to the console.
Sequence to AMQP to Printer	The setup contains two routers. One Router generates events and routs them to a RabbitMQ exchange. Another router consumes the CloudEvents from a bound queue and prints them to the console.
UNIX Socket and MQTT for armv7	Routes CloudEvents that are received on an input UNIX Socket port to an output UNIX Socket port and an MQTT output port.

Delivery Guarantees

The router supports two delivery guarantees: BestEffort and AtLeastOnce

The delivery guarantee is defined on the incoming port and is attached to each message that gets transferred through the router.

Development Setup

Different Docker-based development environments can be found here.

Prerequisites without Docker

1. latest version of rustup
2. Rust version 1.67.0: rustup install 1.67.0
3. Additional C libraries depending on the platform (examples can be found in the Docker containers)

Optional Tooling:

1. rustfmt: rustup component add rustfmt
2. cargo-readme: cargo install cargo-readme

Run Tests

cargo test --all

Format Code

cargo fmt --all

Generate Documentation

cargo doc --no-deps --open

Update a Crate Readme

1. cargo install cargo-readme
2. cd <crate>
3. cargo readme > README.md

Release Management

Release management is organized by cargo-workspaces.

pre-requirement: cargo install cargo-workspaces

1. check out master and create a new branch release
2. cargo workspaces publish --allow-branch="release" --no-git-push sometimes the publish command hangs ... if so, you could repeat the cargo publish with the script ./publish-packages.sh
3. update the dependencies of the docker container (cd docker/cerk-common; cargo update)
4. merge it back into the master with a pull request

License

Apache-2.0