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.