Crate burger 

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

balance

Various load balancer implementations.

buffer

The ServiceExt::buffer combinator returns Buffer, whose Service::acquire immediately resolves until the buffer is at maximum capacity, at which point it defers to the inner service’s Service::acquire. The buffer is drained when the inner service’s permit becomes available.

concurrency_limit

The ServiceExt::concurrency_limit combinator returns ConcurrencyLimit which restricts the number of inflight calls to a specified value.

depressurize

In burger backpressure is exerted by Service::acquire. The ServiceExt::depressurize combinator returns Depressurize, which moves the Service::acquire execution into the Service::call, causing Service::acquire to resolve immediately.

either

Often we want the branches of a runtime condition to output different service types. The Either Service allows the reconciliation of two separate types. The Either::Left and Either::Right variants can be constructed by ServiceExt::left and ServiceExt::right respectively.

leak

The ServiceExt::leak combinator returns Leak, which extends the lifetime of the Service::Permit.

load

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.

load_shed

The ServiceExt::load_shed combinator returns LoadShed, which causes Service::acquire to immediately return Some(permit) when the inner permit is ready and immediately return None otherwise.

map

The ServiceExt::map combinator returns Map, which extends a service with a specified closure from the modifying the Service::Response.

rate_limit

The ServiceExt::rate_limit combinator returns RateLimit, which limits the number of Service::calls invoked per period of time.

retry

The ServiceExt::retry combinator returns Retry, which retries following a specified Policy.

select

Given a collection of some services, select constructs a Service which uses the first permit available.

service_fn

The service_fn function accepts a closure accepting a request and returning a Future and returns ServiceFn, a Service which is immediately permitted to run the closure.

steer

Given a collection of services and a Picker, the steer function constructs a Steer Service.

then

The ServiceExt::then combinator returns Then, which extends a service with a closure modifying a Service::Response asynchronously.

Structs

MiddlewareBuilder

The root of a chain of Middlewares.

Traits

Middleware

A middleware, used to incrementally add behaviour to a Service.

Service

An asynchronous function call, which can only be executed after obtaining a permit.

ServiceExt

An extension trait for Service.

TryService

A fallible Service.

Functions

select

Constructs a Service from a collection (IntoIterator must be implemented for its reference) of services whose Service::call is the by the first available child.

service_fn

Constructs a Service from a closure.

steer

Constructs a Service from a collection of services whose Service::call is steered via a Picker.