Typed actors for Rust, on Tokio.
An actor framework for Rust, built on Tokio: typed messages, supervision trees, death watch with an ordering guarantee, optional event-sourced persistence and optional clustered remoting over QUIC. Inspired by Carl Hewitt's Actor Model and strongly influenced by Akka, continued as open source by Apache Pekko.
tellus is available on crates.io:
cargo add tellustellus: the actor framework itself. See its README for highlights, getting started and the core concepts. Behind thetest-utilfeature it providesTestContextfor unit testing actors without a running actor system.tellus-bootstrap-dns: DNS seed discovery for cluster bootstrap, SRV or A/AAAA records; the discovery contract and the bootstrap logic ship withtellusitself, behind theclusterfeature.tellus-bootstrap-k8s: Kubernetes seed discovery for cluster bootstrap, the pods matching a label selector listed through the API, which sees a pod before it is ready.tellus-persistence-postgres: PostgreSQL event and snapshot stores for tellus persistence. The contract test suite any store implementation must pass ships withtellusitself, behind thepersistence-testsfeature, and an in-memory store for tests behindpersistence-in-memory.tellus-cluster-inspect: an axum router to mount into your own HTTP server, answering a snapshot of the node's cluster view and streaming every change of it as server-sent events, resumable and never silently skipping. See its README.tellus-cluster-demo: a five node cluster running forever under continuous chaos, managed by Docker Compose or in kind. Its nodes find each other through DNS or Kubernetes seed discovery, and every cycle brings one fault: a crash, a departure or a network partition. A verifier checks convergence, cross-node messaging, receptionist settlement and the pub-sub publisher set in every quiet window. See its README.tellus-cluster-demo-tui: a terminal observer for the running demo, fed by the nodes' and the verifier's event streams: the membership matrix as each node sees it, a merged timeline of transitions and chaos, and the verifier's verdicts. See its README.tellus-comparison: messaging benchmarks comparing tellus against kameo and ractor. See its README for the methodology, fairness rules and caveats and the comparison dashboard for published results.
tellus is under active development and its API is still settling.
Two extensions have landed, each behind a feature: persistence adds event-sourced actors, and
cluster makes actor refs serializable, so actors on different nodes message and watch each other
through the same API. Both features are off by default, so tellus stays purely local and free of
their dependencies. Remoting is clustered: nodes join through seed addresses, the member list is
gossiped, and a pluggable failure detector plus downing provider down vanished members. The watchers
of a downed member's actors get synthesized terminated signals. A node shutting down cleanly
announces its own departure. Every node publishes its view of the cluster as a versioned value. A
receptionist answers every actor registered under a name across the cluster, and pub-sub tells every
subscriber of a topic the publisher's receptionist currently resolves.
The open items on the remoting side are listed under the limitations in docs/cluster.md. What comes next, the cluster singleton and then sharding, is laid out in docs/roadmap.md.
How tellus works internally, top-down with links into the implementation:
- docs/actors.md: the core, from the
Actortrait down to the run loop. - docs/persistence.md: event-sourced persistence, from the
EventSourcedtrait to recovery, fencing and schema evolution. - docs/cluster.md: the
clusterfeature, from cluster membership and gossip to the wire model, in particular which of the core guarantees carry over the network and which weaken. - docs/roadmap.md: what comes next and in which order, from the cluster singleton to sharding.
The justfile defines the usual tasks; just all runs check, fmt, lint, test and doc.
Check and lint run across the feature combinations, test across the ones which run tests
differently. Check, lint and test need cargo-hack, and formatting needs taplo for TOML.
Formatting runs on nightly, since the rustfmt configuration uses unstable options, and so does doc.
The justfile picks the nightly of the date rustc --version reports, which must be installed. The
tellus-persistence-postgres tests run against a container, so just all needs Docker. The
benchmark report, the allocation checks and the demo's status recipes also use jq.
Regression benchmarks (criterion) run with just bench: messaging, persistence against an in-memory
store, and stashing. On CI every pull request is benchmarked against its merge base and the
comparison posted as a comment. That comparison measures one stack position and is a hint, never a
verdict; the performance gate is the stack sweep, started by the
label sweep (messaging), sweep-persistence (persistence) or sweep-stash (stashing) on a pull
request. Every commit on main is tracked over time on the benchmark dashboard.
For a local before and after, just bench-save <baseline> and just bench-compare <baseline> (and
the bench-persistence- and bench-stash- pairs) compare against a saved baseline. just profile
and just profile-persistence attribute the time of the hot paths per function with
hotpath, and their -alloc variants the allocations. The
-alloc-gate recipes fail if a function which must not allocate does. just criterion-profile
runs one criterion benchmark as a hotpath report. just bench-cluster, bench-gossip and
bench-streams measure remoting across spawned processes and do not run on CI.
The benchmarks against kameo and ractor run with just bench-comparison; they are excluded from
per-pull-request CI and published to the comparison dashboard on version tags
and manual runs.
The cluster demo runs with just start-cluster-demo-compose, which needs Docker, or just start-cluster-demo-k8s in a kind cluster, and just run-cluster-demo-tui watches it from a
terminal. Both crates are checked, linted and tested by just all like the rest; running the
stack itself is a soak test and stays manual.
Contributions are welcome; CONTRIBUTING.md describes how to build, test and submit them. Please report vulnerabilities privately, as described in the security policy.
This code is open source software licensed under the Apache 2.0 License.