Motore

The core abstraction in Motore is the Service trait. It is an async middleware abstraction designed to reduce the mental burden of writing asynchronous code by leveraging AFIT (Async Functions in Traits) and RPITIT (Return Position Impl Trait in Traits). This approach avoids the need for manual Boxing of futures, making the code more concise and performant.

To implement a service, you define how it processes a request given a context (Cx) and returns a Result containing either a Response or an Error asynchronously.

pub trait Service<Cx, Request> {
    /// Responses given by the service.
    type Response;
    /// Errors produced by the service.
    type Error;

    /// Process the request and return the response asynchronously.
    async fn call(&self, cx: &mut Cx, req: Request) -> Result<Self::Response, Self::Error>;
}

LayerFn is a wrapper around a closure that implements the Layer trait. It serves as a lightweight utility to avoid the boilerplate of creating a custom struct every time you want to implement a Layer.

It is created via the layer_fn constructor. Its primary purpose is to take an existing Service and return a new Service (the Out type in the Layer implementation) by applying the closure logic.

The ServiceBuilder provides a declarative interface for composing multiple middleware layers to be applied to a Service. You can stack layers using .layer(), .option_layer(), or .layer_fn(), and then apply the resulting stack to a service using .service() or .service_fn().

Layers are applied in the order they are added, wrapping the inner service. The final service is produced by calling .service(inner_service) at the end of the builder chain.

use motore::ServiceBuilder;
use std::time::Duration;

// Assuming 'inner_service' is an existing Service
let middleware_stack = ServiceBuilder::new()
    .timeout(Some(Duration::from_secs(5)))
    .layer_fn(|svc| {
        // custom logic to wrap service
        svc
    })
    .service(inner_service);

Motore is built around two core abstractions designed for building composable networking clients and servers:

1. Service trait: Represents an asynchronous function that takes a request and returns either a response or an error. It can model both clients and servers.
2. Layer trait: Used to compose middleware with Services. A Layer is a function that takes a Service of one type and returns a Service of a different type (e.g., adding a timeout or rate limiting).

Middleware (like timeouts, rate limiting, or load balancing) is implemented as a Service that wraps an inner service, applying additional behavior before or after the inner service is called. This allows for protocol-agnostic, composable components.

To finalize the builder and produce a concrete service, use one of the following:

1. .service(S): Wraps an existing service S with the composed layers.
2. .service_fn(F): Wraps an async function F (converted to a ServiceFn) with the composed layers.

// Using an existing service
let service = ServiceBuilder::new()
    .timeout(None)
    .service(inner_service);

// Using an async function
let service = ServiceBuilder::new()
    .service_fn(|req| async move {
        // handle request
        Ok(Response::new())
    });

The ServiceExt trait provides convenient adapter methods for any type implementing the Service trait. It allows you to transform the output of a service using functional mapping, similar to standard Result methods.

• map_err: Transforms the service's Error type into a different type using a provided closure. Use this to unify error types across different services.
• map_response: Transforms the service's Response type into a different type. Use this to chain computations or reshape data immediately after a service resolves.

// Example usage pattern
let transformed_service = original_service
    .map_err(|e| MyCustomError::from(e))
    .map_response(|res| MyCustomResponse::from(res));

Use BoxService<Cx, T, U, E> to turn a concrete Service into a trait object. This is useful when you need to:

1. Use a dynamic response type.
2. Store different service implementations in the same collection.
3. Erase the specific type of the service implementation.

BoxService::new(s) creates a new boxed service. If the service_send feature is enabled, the contained service must be Send + Sync + 'static.

// Example usage pattern
let boxed_service = BoxService::new(my_concrete_service);

Add a layer using a function that accepts a service and returns a new service using .layer_fn(f).

let builder = ServiceBuilder::new().layer_fn(|svc| {
    // return a wrapped service
    svc
});