Métodos genéricos en óxido: cómo el exón se desplazó del hierro a la web Actix

El ecosistema de Rust todavía está creciendo. Como resultado, las nuevas bibliotecas con funcionalidad mejorada se lanzan con frecuencia a la comunidad de desarrolladores, mientras que las bibliotecas más antiguas se vuelven obsoletas. Cuando inicialmente diseñamos Exonum, utilizamos el framework web Iron. En este artículo, describimos cómo portamos el framework Exonum a actix-web usando programación genérica.

Exonum sobre hierro

En la plataforma Exonum, el marco de hierro se utilizó sin abstracciones. Instalamos manejadores para ciertos recursos y obtuvimos parámetros de solicitud al analizar URL usando métodos auxiliares; el resultado se devolvió simplemente en forma de cadena.

El proceso se parecía (aproximadamente) al siguiente:

fn set_blocks_response(self, router: &mut Router) { let blocks = move |req: &mut Request| -> IronResult<Response> { let count: usize = self.required_param(req, "count")?; let latest: Option<u64> = 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"); } 

Además, utilizamos algunos complementos de middleware en forma de encabezados CORS. Utilizamos mount para fusionar todos los controladores en una sola API.

Nuestra decisión de alejarnos del hierro

Iron era una buena biblioteca, con muchos complementos. Sin embargo, fue escrito en los días en que no existían proyectos como futuros y tokio .

La arquitectura de Iron implica el procesamiento de solicitudes sincrónicas, que pueden verse fácilmente afectadas por una gran cantidad de conexiones abiertas simultáneamente. Para ser escalable, Iron necesitaba volverse asíncrono, lo que implicaría repensar y reescribir todo el marco. Como resultado, hemos visto una desviación gradual del uso de Iron por parte de ingenieros de software.

Por qué elegimos Actix-Web

Actix-web es un marco popular que ocupa un lugar destacado en los puntos de referencia de TechEmpower . Tiene una comunidad de desarrolladores activa, a diferencia de Iron, y tiene una API bien diseñada y una implementación de alta calidad basada en el marco del actor actix. Las solicitudes son procesadas asincrónicamente por el grupo de subprocesos; si la solicitud procesa el pánico, el actor se reinicia automáticamente.

Anteriormente, se planteó la preocupación de que actix-web contenía una gran cantidad de código inseguro. Sin embargo, la cantidad de código inseguro se redujo significativamente cuando el marco se reescribió en un lenguaje de programación seguro: Rust. Los ingenieros de Bitfury han revisado este código ellos mismos y se sienten seguros de su estabilidad a largo plazo.

Para el marco Exonum, el cambio a actix resolvió el problema de la estabilidad de la operación. El marco de Iron podría fallar si hubiera una gran cantidad de conexiones. También hemos descubierto que la API actix-web es más simple, más productiva y más unificada. Estamos seguros de que a los usuarios y desarrolladores les resultará más fácil usar la interfaz de programación Exonum, que ahora puede operar más rápido gracias al diseño web actix.

Lo que requerimos de un marco web

Durante este proceso, nos dimos cuenta de que era importante para nosotros no simplemente cambiar los marcos, sino también diseñar una nueva arquitectura API independiente de cualquier marco web específico. Dicha arquitectura permitiría crear controladores, con poca o ninguna preocupación por los detalles web, y transferirlos a cualquier backend. Esta concepción puede implementarse escribiendo una interfaz que aplique tipos y rasgos básicos.

Para comprender cómo debe verse esta interfaz, definamos qué es realmente cualquier API HTTP:

• Las solicitudes son hechas exclusivamente por clientes; el servidor solo responde a ellas (el servidor no inicia solicitudes).
• Solicita leer datos o cambiar datos.
• Como resultado del procesamiento de la solicitud, el servidor devuelve una respuesta, que contiene los datos requeridos, en caso de éxito; o información sobre el error, en caso de falla.

Si vamos a analizar todas las capas de abstracción, resulta que cualquier solicitud HTTP es solo una llamada de función:

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

Todo lo demás puede considerarse una extensión de esta entidad básica. Por lo tanto, para ser independientes de una implementación específica de un marco web, necesitamos escribir controladores en un estilo similar al ejemplo anterior.

Rasgo `Punto final` para el procesamiento genérico de solicitudes HTTP

El enfoque más simple y directo sería declarar el rasgo `Endpoint`, que describe las implementaciones de solicitudes específicas:

 // 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<Self::Response, io::Error>; } 

Ahora necesitamos implementar este controlador en un marco específico. Por ejemplo, en actix-web tiene el siguiente aspecto:

 // Response type in actix-web. Note that they are asynchronous, even though `Endpoint` assumes that // processing is synchronous. type FutureResponse = actix_web::FutureResponse<HttpResponse, actix_web::Error>; // 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<Context>) -> 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<RawHandler>, } 

Podemos usar estructuras para pasar parámetros de solicitud a través del contexto. Actix-web puede deserializar parámetros automáticamente usando serde. Por ejemplo, a = 15 & b = hola se deserializa en una estructura como esta:

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

Esta funcionalidad de deserialización concuerda bien con el tipo asociado Solicitud del rasgo `Punto final`.

A continuación, ideemos un adaptador que envuelva una implementación específica de 'Endpoint' en un RequestHandler para actix-web. Preste atención al hecho de que al hacerlo, la información sobre los tipos de Solicitud y Respuesta desaparece. Esta técnica se denomina borrado de tipo: transforma el envío estático en uno dinámico.

 impl RequestHandler { fn from_endpoint<E: Endpoint>(name: &str, endpoint: E) -> RequestHandler { let index = move |request: HttpRequest<Context>| -> FutureResponse { let context = request.state(); let future = Query::from_request(&request, &()) .map(|query: Query<E::Request>| 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<RawHandler>, } } } 

En esta etapa, sería suficiente agregar controladores para las solicitudes POST, ya que hemos creado un rasgo que es independiente de los detalles de implementación. Sin embargo, descubrimos que esta solución no era lo suficientemente avanzada.

Los inconvenientes del rasgo `Punto final`

Se genera una gran cantidad de código auxiliar cuando se escribe un controlador:

 // A structure with the context of the handler. struct ElementCountEndpoint { elements: Rc<RefCell<Vec<Something>>>, } // Implementation of the `Endpoint` trait. impl Endpoint for ElementCountEndpoint { type Request = (); type Result = usize; fn handle(&self, context: &Context, _request: ()) -> Result<usize, io::Error> { 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); 

Idealmente, necesitamos poder pasar un cierre simple como manejador, reduciendo así significativamente la cantidad de ruido sintáctico.

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

A continuación discutiremos cómo se puede hacer esto.

Inmersión ligera en programación genérica

Necesitamos agregar la capacidad de generar automáticamente un adaptador que implemente el rasgo `Endpoint` con los tipos asociados correctos. La entrada consistirá solo en un cierre con un controlador de solicitud HTTP.

Los argumentos y el resultado del cierre pueden tener diferentes tipos, por lo que tenemos que trabajar con métodos de sobrecarga aquí. Rust no admite la sobrecarga directamente, pero permite que se emule usando los rasgos 'Into' y 'From'.

Además, el tipo devuelto del valor de cierre no tiene que coincidir con el valor devuelto de la implementación `Endpoint`. Para manipular este tipo, debe extraerse del tipo del cierre recibido.

Obteniendo tipos del rasgo `Fn`

En Rust, cada cierre tiene su propio tipo único, que no se puede indicar explícitamente en el programa. Para manipulaciones con cierres, utilizamos el rasgo `Fn`. El rasgo contiene la firma de la función con los tipos de argumentos y del valor devuelto, sin embargo, no es fácil recuperar estos elementos por separado.

La idea principal es utilizar una estructura auxiliar de la siguiente forma:

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

Tenemos que usar PhantomData, ya que Rust requiere que todos los parámetros genéricos estén indicados en la definición de la estructura. Sin embargo, el tipo de cierre o función F en sí no es genérico (aunque implementa un rasgo genérico `Fn`). Los parámetros de tipo A y B no se utilizan directamente en él.

Es esta restricción del sistema de tipo Rust lo que nos impide aplicar una estrategia más simple al implementar el rasgo `Endpoint` directamente para los cierres:

 impl<A, B, F> Endpoint for F where F: Fn(&Context, A) -> B { type Request = A; type Response = B; fn handle(&self, context: &Context, request: A) -> Result<B, io::Error> { // ... } } 

En el caso anterior, el compilador devuelve un error:

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

La estructura auxiliar SimpleExtractor permite describir la conversión de `From`. Esta conversión nos permite guardar cualquier función y extraer los tipos de sus argumentos:

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

El siguiente código se compila correctamente:

 #[derive(Deserialize)] struct Query { a: i32, b: String, }; // Verification of the ordinary structure. fn my_handler(_: &Context, q: Query) -> String { format!("{} has {} apples.", qb, qa) } 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 {}", qb, qa, c) }; let closure_extractor = SimpleExtractor::from(my_closure); 

Especialización y tipos de marcadores

Ahora tenemos una función con tipos de argumentos parametrizados explícitamente, que se pueden usar en lugar del rasgo `Endpoint`. Por ejemplo, podemos implementar fácilmente la conversión de SimpleExtractor a RequestHandler. Aún así, esta no es una solución completa. Necesitamos distinguir de alguna manera entre los controladores para las solicitudes GET y POST a nivel de tipo (y entre los controladores síncronos y asíncronos). En esta tarea, los tipos de marcadores nos ayudan.

En primer lugar, reescribamos SimpleExtractor para que pueda distinguir entre resultados síncronos y asíncronos. Al mismo tiempo, implementaremos el rasgo `De` para cada uno de los casos. Tenga en cuenta que los rasgos se pueden implementar para variantes específicas de estructuras genéricas.

 /// Generic handler for HTTP-requests. pub struct With<Q, I, R, F> { /// A specific handler function. pub handler: F, /// Structure type containing the parameters of the request. _query_type: PhantomData<Q>, /// Type of the request result. _item_type: PhantomData<I>, /// Type of the value returned by the handler. /// Note that this value can differ from the result of the request. _result_type: PhantomData<R>, } // Implementation of an ordinary synchronous returned value. impl<Q, I, F> From<F> for With<Q, I, Result<I>, F> where F: Fn(&ServiceApiState, Q) -> Result<I>, { fn from(handler: F) -> Self { Self { handler, _query_type: PhantomData, _item_type: PhantomData, _result_type: PhantomData, } } } // Implementation of an asynchronous request handler. impl<Q, I, F> From<F> for With<Q, I, FutureResult<I>, F> where F: Fn(&ServiceApiState, Q) -> FutureResult<I>, { fn from(handler: F) -> Self { Self { handler, _query_type: PhantomData, _item_type: PhantomData, _result_type: PhantomData, } } } 

Ahora necesitamos declarar la estructura que combinará el manejador de solicitudes con su nombre y tipo:

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

A continuación, declaramos varias estructuras vacías que actuarán como tipos de marcadores. Los marcadores nos permitirán implementar para cada controlador su propio código para convertir el controlador en el RequestHandler descrito anteriormente.

 /// 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; 

Ahora podemos definir cuatro implementaciones diferentes del rasgo `De` para todas las combinaciones de parámetros de plantilla R y K (el valor devuelto del controlador y el tipo de solicitud).

 // Implementation of a synchronous handler of GET requests. impl<Q, I, F> From<NamedWith<Q, I, Result<I>, F, Immutable>> for RequestHandler where F: Fn(&ServiceApiState, Q) -> Result<I> + 'static + Send + Sync + Clone, Q: DeserializeOwned + 'static, I: Serialize + 'static, { fn from(f: NamedWith<Q, I, Result<I>, 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<Q>| 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<RawHandler>, } } } // Implementation of a synchronous handler of POST requests. impl<Q, I, F> From<NamedWith<Q, I, Result<I>, F, Mutable>> for RequestHandler where F: Fn(&ServiceApiState, Q) -> Result<I> + 'static + Send + Sync + Clone, Q: DeserializeOwned + 'static, I: Serialize + 'static, { fn from(f: NamedWith<Q, I, Result<I>, 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<RawHandler>, } } } // Implementation of an asynchronous handler of GET requests. impl<Q, I, F> From<NamedWith<Q, I, FutureResult<I>, F, Immutable>> for RequestHandler where F: Fn(&ServiceApiState, Q) -> FutureResult<I> + 'static + Clone + Send + Sync, Q: DeserializeOwned + 'static, I: Serialize + 'static, { fn from(f: NamedWith<Q, I, FutureResult<I>, 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<Q>| 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<RawHandler>, } } } // Implementation of an asynchronous handler of POST requests. impl<Q, I, F> From<NamedWith<Q, I, FutureResult<I>, F, Mutable>> for RequestHandler where F: Fn(&ServiceApiState, Q) -> FutureResult<I> + 'static + Clone + Send + Sync, Q: DeserializeOwned + 'static, I: Serialize + 'static, { fn from(f: NamedWith<Q, I, FutureResult<I>, 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<RawHandler>, } } } 

Fachada para el backend

El paso final es diseñar una fachada que acepte cierres y los agregue al backend correspondiente. En el caso dado, tenemos un único backend: actix-web. Sin embargo, existe el potencial de una implementación adicional detrás de la fachada. Por ejemplo: un generador de especificaciones Swagger.

 pub struct ServiceApiScope { actix_backend: actix::ApiBuilder, } impl ServiceApiScope { /// This method adds an Immutable handler to all backends. pub fn endpoint<Q, I, R, F, E>(&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<With<Q, I, R, F>>, // Note that the list of restrictions includes the conversion from NamedWith into RequestHandler // we have implemented earlier. RequestHandler: From<NamedWith<Q, I, R, F, Immutable>>, { self.actix_backend.endpoint(name, endpoint); self } /// A similar method for Mutable handlers. pub fn endpoint_mut<Q, I, R, F, E>(&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<With<Q, I, R, F>>, RequestHandler: From<NamedWith<Q, I, R, F, Mutable>>, { self.actix_backend.endpoint_mut(name, endpoint); self } 

Observe cómo los tipos de los parámetros de solicitud, el tipo del resultado de la solicitud y la sincronía / asincronía del controlador se derivan automáticamente de su firma. Además, debemos especificar explícitamente el nombre y el tipo de la solicitud.

Inconvenientes del enfoque

El enfoque descrito anteriormente, a pesar de ser bastante efectivo, tiene sus inconvenientes. En particular, los métodos endpoint y endpoint_mut deben considerar las peculiaridades de implementación de backends específicos . Esta restricción nos impide agregar backends sobre la marcha, aunque esta funcionalidad rara vez es necesaria.

Otro problema es que no podemos definir la especialización de un controlador sin argumentos adicionales . En otras palabras, si escribimos el siguiente código, no se compilará ya que está en conflicto con la implementación genérica existente:

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

Como resultado, las solicitudes que no tienen ningún parámetro aún deben aceptar la cadena JSON nula, que se deserializa en (). Este problema podría resolverse mediante la especialización en estilo C ++, pero por ahora está disponible solo en la versión nocturna del compilador y no está claro cuándo se convertirá en una característica estable.

Del mismo modo, el tipo del valor devuelto no puede ser especializado . Incluso si la solicitud no implica un cierto tipo de valor devuelto, seguirá pasando JSON con nulo.

La decodificación de la consulta de URL en las solicitudes GET también impone algunas restricciones obvias sobre el tipo de parámetros , pero este problema se relaciona más bien con las peculiaridades de la implementación codificada por el servidor.

Conclusión

Como se describió anteriormente, hemos implementado una API mejorada, que permite una creación simple y clara de controladores, sin la necesidad de preocuparse por los detalles web. Estos manejadores pueden funcionar con cualquier backend o incluso con varios backends simultáneamente.

---

• Web: Bitfury.com , Exonum.com
• Redes sociales: Facebook , Twitter , LinkedIn
• I + D: investigación y libros blancos

---