Expand description
An experimental service framework.
The Service
trait is the central abstraction. It is an
asynchronous function, accepting a request and returning a response, which
can only be executed after a permit is acquired.
The root exports Service
constructors, and an extension trait, ServiceExt
containing
combinators to modify a Service
. Both the combinators and constructors each have an
associated module containing related documentation, traits, and types.
§Example
use burger::*;
let svc = service_fn(|x| async move {
sleep(Duration::from_secs(1)).await;
2 * x
})
.map(|x| x + 3)
.concurrency_limit(1)
.buffer(3)
.load_shed();
let response = svc.oneshot(30).await;
assert_eq!(Ok(63), response);
§Usage
A typical Service
will consist of distinct layers, each providing specific dynamics. The
following flowchart attempts to categorize the exports of this crate:
--- title: Which constructor should I use? --- flowchart TD A{I want to...} --> |Create a fresh service| B{Using a...} B --> |Closure| service_fn B --> |tower::Service| compat A --> |Modify an existing service| C{ } C --> |Modify the permit| D{ } D --> |Extend lifetime of permit| ServiceExt::leak D --> |Reduce backpressure| E{ } E --> |Buffer| ServiceExt::buffer E --> |Remove backpressure| ServiceExt::depressurize E --> |Shed load| ServiceExt::load_shed D --> |Increase backpressure| F{ } F --> |Limit concurrency| ServiceExt::concurrency_limit F --> |Limit rate| ServiceExt::rate_limit C --> |Modify response| G{ } G --> |Synchronously| ServiceExt::map G --> |Asychronously| ServiceExt::then C --> |Consolidate service types| ServiceExt::left/right C --> |Add retries| ServiceExt::retry A --> |Combine existing services| H{By directing \nrequests via...} H --> |Manual picking| steer H --> |First permitted| select H --> |Load balancer| balance
Modules§
- Various load balancer implementations.
- The
ServiceExt::buffer
combinator returnsBuffer
, whoseService::acquire
immediately resolves until the buffer is at maximum capacity, at which point it defers to the inner service’sService::acquire
. The buffer is drained when the inner service’s permit becomes available. - The
ServiceExt::concurrency_limit
combinator returnsConcurrencyLimit
which restricts the number of inflight calls to a specified value. - In
burger
backpressure is exerted byService::acquire
. TheServiceExt::depressurize
combinator returnsDepressurize
, which moves theService::acquire
execution into theService::call
, causingService::acquire
to resolve immediately. - Often we want the branches of a runtime condition to output different service types. The
Either
Service
allows the reconciliation of two separate types. TheEither::Left
andEither::Right
variants can be constructed byServiceExt::left
andServiceExt::right
respectively. - Load is a measurement of the amount of work a service is experiencing. The
Load
trait provides an interface to measure it and therefore informs business logic in applications such as load balancers. - The
ServiceExt::load_shed
combinator returnsLoadShed
, which causesService::acquire
to immediately returnSome(permit)
when the inner permit is ready and immediately returnNone
otherwise. - The
ServiceExt::map
combinator returnsMap
, which extends a service with a specified closure from the modifying theService::Response
. - The
ServiceExt::rate_limit
combinator returnsRateLimit
, which limits the number ofService::call
s invoked per period of time. - The
service_fn
function accepts a closure accepting a request and returning aFuture
and returnsServiceFn
, aService
which is immediately permitted to run the closure. - The
ServiceExt::then
combinator returnsThen
, which extends a service with a closure modifying aService::Response
asynchronously.
Structs§
- The root of a chain of
Middleware
s.
Traits§
- A middleware, used to incrementally add behaviour to a
Service
. - An asynchronous function call, which can only be executed after obtaining a permit.
- An extension trait for
Service
. - A fallible
Service
.
Functions§
- Constructs a
Service
from a collection (IntoIterator
must be implemented for its reference) of services whoseService::call
is the by the first available child. - Constructs a
Service
from a closure.