Generic Methods in Rust: How Exonum Shifted from Iron to Actix-web07.02.2019 01:04

The Rust ecosystem is still growing. As a result, new libraries with improved functionality are frequently released into the developer community, while older libraries become obsolete. When we initially designed Exonum, we used the Iron web-framework. In this article, we describe how we ported the Exonum framework to actix-web using generic programming.

Exonum on Iron

In the Exonum platform, the Iron framework was used without any abstractions. We installed handlers for certain resources and obtained request parameters by parsing URLs using auxiliary methods; the result was returned simply in the form of a string.

The process looked (approximately) like the following:

fn set_blocks_response(self, router: &mut Router) {
    let blocks = move |req: &mut Request| -> IronResult {
        let count: usize = self.required_param(req, "count")?;
        let latest: Option = self.optional_param(req, "latest")?;
        let skip_empty_blocks: bool = self.optional_param(req, "skip_empty_blocks")?
            .unwrap_or(false);
        let info = self.blocks(count, latest.map(Height), skip_empty_blocks)?;
        self.ok_response(&::serde_json::to_value(info).unwrap())
    };

    router.get("/v1/blocks", blocks, "blocks");
}

In addition, we used some middleware plugins in the form of CORS headers. We used mount to merge all the handlers into a single API.

Our Decision to Shift Away from Iron

Iron was a good library, with plenty of plugins. However, it was written in the days when such projects as futures and tokio did not exist.

The architecture of Iron involves synchronous requests processing, which can be easily affected by a large number of simultaneously open connections. To be scalable, Iron needed to become asynchronous, which would involve rethinking and rewriting the whole framework. As a result, we«ve seen a gradual departure from using Iron by software engineers.

Why We Chose Actix-Web

Actix-web is a popular framework that ranks high on TechEmpower benchmarks. It has an active developer community, unlike Iron, and it has a well-designed API and high-quality implementation based on the actix actor framework. Requests are processed asynchronously by the thread pool; if request processing panics, the actor is automatically restarted.

Previously, concerns were raised that actix-web contained a lot of unsafe code. However, the amount of unsafe code was significantly reduced when the framework was rewritten in a safe programming language — Rust. Bitfury«s engineers have reviewed this code themselves and feel confident in its long-term stability.

For the Exonum framework, shifting to actix solved the issue of operation stability. The Iron framework could fail if there were a large number of connections. We have also found that the actix-web API is simpler, more productive and more unified. We are confident that users and developers will have an easier time using the Exonum programming interface, which can now operate faster thanks to the actix-web design.

What We Require from a Web Framework

During this process we realized it was important for us not to simply shift frameworks, but to also devise a new API architecture independent of any specific web framework. Such architecture would allow for creating handlers, with little to no concern about web specifics, and transferring them to any backend. This conception can be implemented by writing a frontend that would apply basic types and traits.

To understand what this frontend needs to look like, let«s define what any HTTP API really is:

• Requests are made exclusively by clients; the server only responds to them (the server does not initiate requests).
• Requests either read data or change data.
• As a result of the request processing, the server returns a response, which contains the required data, in case of success; or information about the error, in case of failure.

If we are to analyze all the abstraction layers, it turns out that any HTTP request is just a function call:

fn request(context: &ServiceContext, query: Query) -> Result

Everything else can be considered an extension of this basic entity. Thus, in order to be independent from a specific implementation of a web framework, we need to write handlers in a style similar to the example above.

Trait `Endpoint` for Generic Processing of HTTP-requests

The most simple and straightforward approach would be declaring the `Endpoint` trait, which describes the implementations of specific requests:

// A trait describing GET request handlers. It should be possible to call each of the handlers from any freed
// thread. This requirement imposes certain restrictions on the trait. Parameters and request results are
// configured using associated types.
trait Endpoint: Sync + Send + 'static {
    type Request: DeserializeOwned + 'static;
    type Response: Serialize + 'static;

    fn handle(&self, context: &Context, request: Self::Request) -> Result;
}

Now we need to implement this handler in a specific framework. For example, in actix-web it looks like the following:

// Response type in actix-web. Note that they are asynchronous, even though `Endpoint` assumes that 
// processing is synchronous.
type FutureResponse = actix_web::FutureResponse;

// A raw request handler for actix-web. This is what the framework ultimately works with. The handler 
// receives parameters from an arbitrary context, through which the request parameters are passed.
type RawHandler = dyn Fn(HttpRequest) -> FutureResponse + 'static + Send + Sync;

// For convenience, let’s put everything we need from the handler into a single structure.
#[derive(Clone)]
struct RequestHandler {
    /// The name of the resource.
    pub name: String,
    /// HTTP method.
    pub method: actix_web::http::Method,
    /// The raw handler. Note that it will be used from multiple threads.
    pub inner: Arc,
}

We can use structures for passing request parameters through the context. Actix-web can automatically deserialize parameters using serde. For example, a=15&b=hello is deserialized into a structure like this one:

#[derive(Deserialize)]
struct SimpleQuery {
    a: i32,
    b: String,
}

This deserialization functionality agrees well with the associated type Request from the `Endpoint` trait.

Next, lets devise an adapter which wraps a specific implementation of `Endpoint` into a RequestHandler for actix-web. Pay attention to the fact that while doing so, the information on Request and Response types disappears. This technique is called type erasure — it transforms static dispatching into a dynamic one.

impl RequestHandler {
    fn from_endpoint(name: &str, endpoint: E) -> RequestHandler {
        let index = move |request: HttpRequest| -> FutureResponse {
            let context = request.state();
            let future = Query::from_request(&request, &())
                .map(|query: Query| query.into_inner())
                .and_then(|query| endpoint.handle(context, query).map_err(From::from))
                .and_then(|value| Ok(HttpResponse::Ok().json(value)))
                .into_future();
            Box::new(future)
        };

        Self {
            name: name.to_owned(),
            method: actix_web::http::Method::GET,
            inner: Arc::from(index) as Arc,
        }
    }
}

At this stage, it would be enough just to add handlers for POST requests, as we have created a trait that is independent from the implementation details. However, we found that this solution was not quite advanced enough.

The Drawbacks of the `Endpoint` Trait

A large amount of auxiliary code is generated when a handler is written:

// A structure with the context of the handler.
struct ElementCountEndpoint {
    elements: Rc>>,
}

// Implementation of the `Endpoint` trait.
impl Endpoint for ElementCountEndpoint {
    type Request = ();
    type Result = usize;

    fn handle(&self, context: &Context, _request: ()) -> Result {
        Ok(self.elements.borrow().len())
    }
}

// Installation of the handler in the backend.
let endpoint = ElementCountEndpoint::new(elements.clone());
let handler = RequestHandler::from_endpoint("/v1/element_count", endpoint);
actix_backend.endpoint(handler);

Ideally, we need to be able to pass a simple closure as a handler, thus significantly reducing the amount of syntactic noise.

let elements = elements.clone();
actix_backend.endpoint("/v1/elements_count", move || {
    Ok(elements.borrow().len())
});

Below we will discuss how this can be done.

Light Immersion into Generic Programming

We need to add the ability to automatically generate an adapter that implements the `Endpoint` trait with the correct associated types. The input will consist only of a closure with an HTTP request handler.

Arguments and the result of the closure can have different types, so we have to work with methods overloading here. Rust does not support overloading directly but allows it to be emulated using the `Into` and `From` traits.

In addition, the returned type of the closure value does not have to match the returned value of the `Endpoint` implementation. To manipulate this type, it must be extracted from the type of the received closure.

Fetching Types from the `Fn` Trait

In Rust, each closure has its own unique type, which cannot be explicitly indicated in the program. For manipulations with closures, we use the `Fn` trait. The trait contains the signature of the function with the types of the arguments and of the returned value, however, retrieving these elements separately is not easily done.

The main idea is to use an auxiliary structure of the following form:

/// Simplified example of extracting types from an F closure: Fn(A) -> B.
struct SimpleExtractor
{
    // The original function.
    inner: F,
    _a: PhantomData,
    _b: PhantomData,
}

We have to use PhantomData, since Rust requires that all the generic parameters are indicated in the definition of the structure. However, the type of closure or function F itself is not a generic one (although it implements a generic `Fn` trait). The type parameters A and B are not used in it directly.

impl Endpoint for F where F: Fn(&Context, A) -> B {
    type Request = A;
    type Response = B;

    fn handle(&self, context: &Context, request: A) -> Result {
        // ...
    }
}

error[E0207]: the type parameter `A` is not constrained by the impl trait, self type, or predicates
  --> src/main.rs:10:6
   |
10 | impl Endpoint for F where F: Fn(&Context, A) -> B {
   |      ^ unconstrained type parameter

impl From for SimpleExtractor
where
    F: Fn(&Context, A) -> B,
    A: DeserializeOwned,
    B: Serialize,
{
    fn from(inner: F) -> Self {
        SimpleExtractor {
            inner,
            _a: PhantomData,
            _b: PhantomData,
        }
    }
}

#[derive(Deserialize)]
struct Query {
    a: i32,
    b: String,
};

// Verification of the ordinary structure.
fn my_handler(_: &Context, q: Query) -> String {
    format!("{} has {} apples.", q.b, q.a)
}
let fn_extractor = SimpleExtractor::from(my_handler);

// Verification of the closure.
let c = 15;
let my_closure = |_: &Context, q: Query| -> String {
    format!("{} has {} apples, but Alice has {}", q.b, q.a, c)
};
let closure_extractor = SimpleExtractor::from(my_closure);

/// Generic handler for HTTP-requests.
pub struct With {
    /// A specific handler function.
    pub handler: F,
    /// Structure type containing the parameters of the request.
    _query_type: PhantomData,
    /// Type of the request result.
    _item_type: PhantomData,
    /// Type of the value returned by the handler.
    /// Note that this value can differ from the result of the request.
    _result_type: PhantomData,
}

// Implementation of an ordinary synchronous returned value.
impl From for With, F>
where
    F: Fn(&ServiceApiState, Q) -> Result,
{
    fn from(handler: F) -> Self {
        Self {
            handler,
            _query_type: PhantomData,
            _item_type: PhantomData,
            _result_type: PhantomData,
        }
    }
}

// Implementation of an asynchronous request handler.
impl From for With, F>
where
    F: Fn(&ServiceApiState, Q) -> FutureResult,
{
    fn from(handler: F) -> Self {
        Self {
            handler,
            _query_type: PhantomData,
            _item_type: PhantomData,
            _result_type: PhantomData,
        }
    }
}

#[derive(Debug)]
pub struct NamedWith {
    /// The name of the handler.
    pub name: String,
    /// The handler with the extracted types.
    pub inner: With,
    /// The type of the handler.
    _kind: PhantomData,
}

/// A handler that does not change the state of the service. In HTTP, GET-requests correspond to this 
// handler.
pub struct Immutable;
/// A handler that changes the state of the service. In HTTP, POST, PUT, UPDATE and other similar 
//requests correspond to this handler, but for the current case POST will suffice.
pub struct Mutable;

// Implementation of a synchronous handler of GET requests.
impl From, F, Immutable>> for RequestHandler
where
    F: Fn(&ServiceApiState, Q) -> Result + 'static + Send + Sync + Clone,
    Q: DeserializeOwned + 'static,
    I: Serialize + 'static,
{
    fn from(f: NamedWith, F, Immutable>) -> Self {
        let handler = f.inner.handler;
        let index = move |request: HttpRequest| -> FutureResponse {
            let context = request.state();
            let future = Query::from_request(&request, &())
                .map(|query: Query| query.into_inner())
                .and_then(|query| handler(context, query).map_err(From::from))
                .and_then(|value| Ok(HttpResponse::Ok().json(value)))
                .into_future();
            Box::new(future)
        };

        Self {
            name: f.name,
            method: actix_web::http::Method::GET,
            inner: Arc::from(index) as Arc,
        }
    }
}
// Implementation of a synchronous handler of POST requests.
impl From, F, Mutable>> for RequestHandler
where
    F: Fn(&ServiceApiState, Q) -> Result + 'static + Send + Sync + Clone,
    Q: DeserializeOwned + 'static,
    I: Serialize + 'static,
{
    fn from(f: NamedWith, F, Mutable>) -> Self {
        let handler = f.inner.handler;
        let index = move |request: HttpRequest| -> FutureResponse {
            let handler = handler.clone();
            let context = request.state().clone();
            request
                .json()
                .from_err()
                .and_then(move |query: Q| {
                    handler(&context, query)
                        .map(|value| HttpResponse::Ok().json(value))
                        .map_err(From::from)
                })
                .responder()
        };

        Self {
            name: f.name,
            method: actix_web::http::Method::POST,
            inner: Arc::from(index) as Arc,
        }
    }
}
// Implementation of an asynchronous handler of GET requests.
impl From, F, Immutable>> for RequestHandler
where
    F: Fn(&ServiceApiState, Q) -> FutureResult + 'static + Clone + Send + Sync,
    Q: DeserializeOwned + 'static,
    I: Serialize + 'static,
{
    fn from(f: NamedWith, F, Immutable>) -> Self {
        let handler = f.inner.handler;
        let index = move |request: HttpRequest| -> FutureResponse {
            let context = request.state().clone();
            let handler = handler.clone();
            Query::from_request(&request, &())
                .map(move |query: Query| query.into_inner())
                .into_future()
                .and_then(move |query| handler(&context, query).map_err(From::from))
                .map(|value| HttpResponse::Ok().json(value))
                .responder()
        };

        Self {
            name: f.name,
            method: actix_web::http::Method::GET,
            inner: Arc::from(index) as Arc,
        }
    }
}
// Implementation of an asynchronous handler of POST requests.
impl From, F, Mutable>> for RequestHandler
where
    F: Fn(&ServiceApiState, Q) -> FutureResult + 'static + Clone + Send + Sync,
    Q: DeserializeOwned + 'static,
    I: Serialize + 'static,
{
    fn from(f: NamedWith, F, Mutable>) -> Self {
        let handler = f.inner.handler;
        let index = move |request: HttpRequest| -> FutureResponse {
            let handler = handler.clone();
            let context = request.state().clone();
            request
                .json()
                .from_err()
                .and_then(move |query: Q| {
                    handler(&context, query)
                        .map(|value| HttpResponse::Ok().json(value))
                        .map_err(From::from)
                })
                .responder()
        };

        Self {
            name: f.name,
            method: actix_web::http::Method::POST,
            inner: Arc::from(index) as Arc,
        }
    }
}

pub struct ServiceApiScope {
    actix_backend: actix::ApiBuilder,
}

impl ServiceApiScope {
    /// This method adds an Immutable handler to all backends.
    pub fn endpoint(&mut self, name: &'static str, endpoint: E) -> &mut Self
    where
        // Here we list the typical restrictions which we have encountered earlier:
        Q: DeserializeOwned + 'static,
        I: Serialize + 'static,
        F: Fn(&ServiceApiState, Q) -> R + 'static + Clone,
        E: Into>,
        // Note that the list of restrictions includes the conversion from NamedWith into RequestHandler 
        // we have implemented earlier.
        RequestHandler: From>,
    {
        self.actix_backend.endpoint(name, endpoint);
        self
    }

    /// A similar method for Mutable handlers.
    pub fn endpoint_mut(&mut self, name: &'static str, endpoint: E) -> &mut Self
    where
        Q: DeserializeOwned + 'static,
        I: Serialize + 'static,
        F: Fn(&ServiceApiState, Q) -> R + 'static + Clone,
        E: Into>,
        RequestHandler: From>,
    {
        self.actix_backend.endpoint_mut(name, endpoint);
        self
    }

impl<(), I, F> From for With<(), I, Result, F>
    where
        F: Fn(&ServiceApiState) -> Result,
    {
        fn from(handler: F) -> Self {
            Self {
                handler,
                _query_type: PhantomData,
                _item_type: PhantomData,
                _result_type: PhantomData,
            }
        }
    }