lifeline-rs
Lifeline is a dependency injection library for message-based applications. Lifeline produces applications which are:
- Clean: Bus implementations provide a high-level overview of the application, and services clearly define the messages they send and receive.
- Decoupled: Services and tasks have no dependency on their peers, as they only depend on the message types they send and receive.
- Stoppable: Services and tasks are trivially cancellable. For example, you can terminate all tasks associated with a connection when a client disconnects.
- Greppable: The impact/reach of a message can be easily understood by searching for the type in the source code.
- Testable: Lifeline applications communicate via messages, which makes unit testing easy. Create the bus, spawn the service, send a message, and expect an output message.
In order to achieve these goals, lifeline provides patterns, traits, and implementations:
- The Bus, which constructs & distributes channel Senders/Receivers, and Resources.
- The Carrier, which translates messages between two Bus instances. Carriers are critical when building large applications, and help minimize the complexity of the messages on each bus.
- The Service, which takes channels from the bus, and spawns tasks which send and receive messages.
- The Task, an async future which returns a lifeline when spawned. When the lifeline is dropped, the future is immedately cancelled.
- The Resource, a struct which can be stored in the bus, and taken (or cloned) when services spawn.
For a quick introduction, see the hello.rs example. For a full-scale application see tab-rs.
Quickstart
Lifeline uses tokio
as it's default runtime. Tokio provides a rich set of async channels.
= "0.3"
Lifeline also supports the async-std runtime, and it's mpsc
channel implementation:
= { = "0.3", = ["dyn-bus", "async-std-executor", "async-std-channels"] }
The Bus
The bus carries channels and resources. When services spawn, they receive a reference to the bus.
Channels can be taken from the bus. If the channel endpoint is clonable, it will remain available for other services. If the channel is not clonable, future calls will receive an Err
value. The Rx/Tx type parameters are type-safe, and will produce a compile error
if you attempt to take a channel for an message type which the bus does not carry.
Bus Example
use lifeline_bus;
use Message;
use Bus;
use MainSend;
use MainRecv;
use mpsc;
lifeline_bus!
The Carrier
Carriers provide a way to move messages between busses. Carriers can translate, ignore, or collect information, providing each bus with the messages that it needs.
Large applications have a tree of Busses. This is good, it breaks your app into small chunks.
- MainBus
| ConnectionListenerBus
| | ConnectionBus
| DomainSpecificBus
| | ...
Carriers allow each bus to define messages that minimally represent the information it's services need to function, and prevent an explosion of messages which are copied to all busses.
Carriers centralize the communication between busses, making large applications easier to reason about.
Carrier Example
Busses deeper in the tree should implement FromCarrier
for their parents - see the carrier.rs example for more details.
let main_bus = default;
let connection_listener_bus = default;
let _carrier = connection_listener_bus.carry_from?;
// you can also use the IntoCarrier trait, which has a blanket implementation
let _carrier = main_bus.carry_into?;
The Service
The Service synchronously takes channels from the Bus, and spawns a tree of async tasks (which send & receive messages). When spawned, the service returns one or more Lifeline values. When a Lifeline is dropped, the associated task is immediately cancelled.
It's common for Service::spawn
to return a Result. Taking channel endpoints is a fallible operation. This is because, depending on the channel type, the endpoint may not be clonable. Lifeline clones endpoints when it can (mpsc::Sender
, broadcast::*
, and watch::Receiver
). Lifeline tries to make this happen as early as possible.
use ;
The Task
The Task executes a Future
, and returns a Lifeline
value when spawned. When the lifeline is dropped, the future is immediately cancelled.
Task
is a trait that is implemented for all types - you can import it and use Self::task
in any type. In lifeline, it's
most commonly used in Service implementations.
Tasks can be infallible:
Self task
Or, if you have a fallible task, you can return anyhow::Result<T>
. Anyhow is required to solve type inference issues.
Self try_task
Testing
One of the goals of Lifeline is to provide interfaces that are very easy to test. Lifeline runtimes are easy to construct in tests:
async
The Details
Logging
Tasks (via log) provide debug logs when the are started, ended, or cancelled.
If the task returns a value, it is also printed to the debug log using Debug
.
2020-08-23 16:45:10,422 DEBUG [lifeline::spawn] START ExampleService/ok_task
2020-08-23 16:45:10,422 DEBUG [lifeline::spawn] END ExampleService/ok_task
2020-08-23 16:45:10,422 DEBUG [lifeline::spawn] START ExampleService/valued_task
2020-08-23 16:45:10,422 DEBUG [lifeline::spawn] END ExampleService/valued_task: MyStruct {}
If the task is cancelled (because it's lifeline is dropped), that is also printed.
2020-08-23 16:45:10,422 DEBUG [lifeline::spawn] START ExampleService/cancelled_task
2020-08-23 16:45:10,422 DEBUG [lifeline::spawn] CANCEL ExampleService/cancelled_task
If the task is started using Task::try_task
, the Ok
/Err
value will be printed with Display
.
2020-08-23 16:45:10,422 DEBUG [lifeline::spawn] START ExampleService/ok_task
2020-08-23 16:45:10,422 DEBUG [lifeline::spawn] OK ExampleService/ok_task
2020-08-23 16:45:10,422 DEBUG [lifeline::spawn] END ExampleService/ok_task
2020-08-23 16:45:10,422 DEBUG [lifeline::spawn] START ExampleService/err_task
2020-08-23 16:45:10,422 ERROR [lifeline::service] ERR: ExampleService/err_task: my error
2020-08-23 16:45:10,422 DEBUG [lifeline::spawn] END ExampleService/err_task
A note about autocomplete
rust-analyzer
does not currently support auto-import for structs defined in macros. Lifeline really needs the
struct defined in the macro, as it injects magic fields which store the channels at runtime.
There is a workaround: define a prelude.rs
file in your crate root that exports pub use
for all your bus implementations.
pub use lifeline::*;
pub use crate::bus::MainBus;
pub use crate::other::OtherBus;
...
Then in all your modules:
use crate::prelude::*
The Resource
Resources can be stored on the bus. This is very useful for configuration (e.g MainConfig
), or connections (e.g. a TcpStream
).
Resources implement the Storage
trait, which is easy with the impl_storage_clone!
and impl_storage_take!
macros.
use ;
lifeline_bus!;
impl_storage_clone!;
Lifeline does not provide Resource
implementations for Channel endpoints - use bus.rx()
and bus.tx()
.
The Channel
Channel senders must implement the Channel
trait to be usable in an impl Message
binding.
In most cases, the Channel
endpoints just implement Storage
, which determines whether to 'take or clone' the endpoint on a bus.rx()
or bus.tx()
call.
Here is an example implem
use Channel;
use crate::;
use ;
impl_channel_clone!;
impl_channel_take!;
Broadcast senders should implement the trait with the clone_rx
method overriden, to take from Rx
, then subscribe to Tx
.