Tutorial de Rocket, echa a volar tus webapps con Rust
15/04/2017
Previamente ya hemos hablado de Iron como un web framework para Rust. Sin embargo desde que escribí ese post ha surgido otra librería que ha ganado mucha popularidad en poco tiempo. Se trata de Rocket. Un web framework que propone usar el rendimiento que ofrece Rust sin sacrificar la facilidad de uso de otros lenguajes.
A diferencia de Iron, Rocket incluye bastantes prestaciones por defecto con soporte para:
Rocket necesita una versión nightly del compilador de Rust. Una vez lo tengas creamos una aplicación con Cargo.
Ahora modificamos el fichero Cargo.toml generado en la carpeta rocket_app para añadir las siguientes dependencias:
Editamos el archivo src/main.rs para que se parezca algo a esto:
Con esto iniciamos Rocket y dejamos a la función index que gestione las peticiones GET encaminadas a /. El servidor devolverá El cohete ha despegado.
Ahora si ejecutamos cargo run veremos algo similar a esto:
Vemos que el servidor ya está escuchando en el puerto 8000 y está usando todos los cores (en mi caso 4) del ordenador.
Rocket dispone de varias configuraciones predeterminadas que afectan a su funcionamiento. Para alternar entre las configuraciones debemos usar variables de entorno y para modificar las configuraciones en sí debemos usar un fichero llamado Rocket.toml.
Las configuraciones por defecto son: dev (development), stage (staging) y prod (production). Si no indicamos nada, Rocket se inicia con la configuración dev. Para arrancar con la configuración de producción modificamos el valor de ROCKET_ENV.
Sería el comando para arrancar Rocket en modo producción. En el archivo Rocket.toml se puede modificar cada configuración, estableciendo el puerto, el número de workers y parámetros extra pero no vamos a entrar en ello.
Rocket soporta rutas dinámicas. Por ejemplo, si hacemos GET /pelicula/Intocable podemos definir que la parte del nombre de la película sea un parámetro. Esto hará que la función encargada de /pelicula/Intocable y de /pelicula/Ratatouille sea la misma.
Los argumentos de la función son los parámetros de la petición GET. ¿Qué pasa si no concuerda el tipo de la función con lo que se pasa por HTTP? Nada. Sencillamente Rocket ignora esa petición, busca otra ruta (puede haber sobrecarga de rutas) y si encuentra otra que si satisfaga los parámetros será esa la escogida. Para especificar el orden en el que se hace la sobrecarga de rutas puede usarse rank. En caso de no encontrarse nada, se devuelve un error 404.
Rocket se integra con Serde para lograr una serialización/deserialización con JSON inocua. Si añadimos las dependencias serde, serde_json y serde_derive al fichero Cargo.toml podemos tener un método que acepete una petición POST solo para mensajes del tipo application/json con deserialización incorporada.
Si el JSON no se ajusta a la estructura User simplemente se descarta devolviendo un error 400.
Lo mismo que es posible hacer con JSON puede hacerse con formularios usando el trait FromForm.
En Rocket, como es lógico, es posible crear páginas personalizadas para cada error.
La lista de métodos que manejan errores hay que pasarla en el método catch de rocket::ignite
Rocket nos permite devolver cualquier cosa que implemente el trait Responder. Algunos tipos ya lo llevan como String, File, JSON, Option y Result. Pero nada nos impide que nuestros propios tipos implementen Responder. Con Responder tenemos el contenido y el código de error (que en la mayoría de casos será 200). En el caso de Result es muy interesante, pues si Err contiene algo que implementa Responder, se devolverá la salida que implemente también, pudiendo así hacer mejores respuestas de error, mientras que si no lo hacen se llamará al método que implemente el error 500 de forma genérica. Con Option, si el valor es Some se devolverá el contenido, si es None se generará un error 404.
Este ejemplo para /pelicula/Intocable devolverá: La película Intocable se hizo en Francia mientras que para /pelicula/Ratatouille dirá No existe esa película en nuestra base de datos.
También es posible devolver plantillas. Rocket se integra por defecto con Handlebars y Tera, aunque no es muy costoso añadir cualquier otra como Maud.
Rocket es un prometedor web framework para Rust, bastante idiomático, que se integra muy bien con el lenguaje. Espero con ansia las nuevas veriones. Es posible que la API cambie bastante hasta que salga la versión 1.0, no obstante así es como ahora mismo funciona.
Rocket lleva las pilas cargadas
A diferencia de Iron, Rocket incluye bastantes prestaciones por defecto con soporte para:
- Plantillas
- Cookies
- Formularios
- JSON
- Soporte para rutas dinámicas
Un "Hola Mundo"
Rocket necesita una versión nightly del compilador de Rust. Una vez lo tengas creamos una aplicación con Cargo.
cargo new --bin rocket_app
Ahora modificamos el fichero Cargo.toml generado en la carpeta rocket_app para añadir las siguientes dependencias:
rocket = "0.2.4"
rocket_codegen = "0.2.4"
rocket_contrib = "*"
Editamos el archivo src/main.rs para que se parezca algo a esto:
#![feature(plugin)]
#![plugin(rocket_codegen)]
extern crate rocket;
#[get("/")]
fn index() -> &'static str {
"El cohete ha despegado"
}
fn main() {
rocket::ignite().mount("/",routes![index]).launch();
}
Con esto iniciamos Rocket y dejamos a la función index que gestione las peticiones GET encaminadas a /. El servidor devolverá El cohete ha despegado.
Ahora si ejecutamos cargo run veremos algo similar a esto:
Vemos que el servidor ya está escuchando en el puerto 8000 y está usando todos los cores (en mi caso 4) del ordenador.Configurar Rocket
Rocket dispone de varias configuraciones predeterminadas que afectan a su funcionamiento. Para alternar entre las configuraciones debemos usar variables de entorno y para modificar las configuraciones en sí debemos usar un fichero llamado Rocket.toml.
Las configuraciones por defecto son: dev (development), stage (staging) y prod (production). Si no indicamos nada, Rocket se inicia con la configuración dev. Para arrancar con la configuración de producción modificamos el valor de ROCKET_ENV.
ROCKET_ENV=prod cargo run --release
Sería el comando para arrancar Rocket en modo producción. En el archivo Rocket.toml se puede modificar cada configuración, estableciendo el puerto, el número de workers y parámetros extra pero no vamos a entrar en ello.
Rutas dinámicas
Rocket soporta rutas dinámicas. Por ejemplo, si hacemos GET /pelicula/Intocable podemos definir que la parte del nombre de la película sea un parámetro. Esto hará que la función encargada de /pelicula/Intocable y de /pelicula/Ratatouille sea la misma.
#![feature(plugin)]
#![plugin(rocket_codegen)]
extern crate rocket;
#[get("/pelicula/<pelicula>")]
fn pelicula(pelicula: &str) -> String {
format!("Veo que te gusta {}, a mi también!",pelicula)
}
#[get("/")]
fn index() -> &'static str {
"El cohete ha despegado"
}
fn main() {
rocket::ignite().mount("/",routes![index,pelicula]).launch();
}
Los argumentos de la función son los parámetros de la petición GET. ¿Qué pasa si no concuerda el tipo de la función con lo que se pasa por HTTP? Nada. Sencillamente Rocket ignora esa petición, busca otra ruta (puede haber sobrecarga de rutas) y si encuentra otra que si satisfaga los parámetros será esa la escogida. Para especificar el orden en el que se hace la sobrecarga de rutas puede usarse rank. En caso de no encontrarse nada, se devuelve un error 404.
POST, subir JSON y formularios
Rocket se integra con Serde para lograr una serialización/deserialización con JSON inocua. Si añadimos las dependencias serde, serde_json y serde_derive al fichero Cargo.toml podemos tener un método que acepete una petición POST solo para mensajes del tipo application/json con deserialización incorporada.
#![feature(plugin)]
#![plugin(rocket_codegen)]
#[macro_use] extern crate rocket_contrib;
#[macro_use] extern crate serde_derive;
extern crate serde_json;
extern crate rocket;
use rocket_contrib::{JSON, Value};
#[derive(Serialize,Deserialize)]
struct User{
name: String,
email: String
}
#[post("/upload", format="application/json", data="<user>")]
fn upload_user(user: JSON<User>) -> JSON<Value> {
JSON(json!({
"status" : 200,
"message" : format!("Usuario {} registrado con éxito",user.email)
}))
}
fn main() {
rocket::ignite().mount("/",routes![upload_user]).launch();
}
Si el JSON no se ajusta a la estructura User simplemente se descarta devolviendo un error 400.
Lo mismo que es posible hacer con JSON puede hacerse con formularios usando el trait FromForm.
#![feature(plugin,custom_derive)]
#![plugin(rocket_codegen)]
#[macro_use] extern crate rocket_contrib;
#[macro_use] extern crate serde_derive;
extern crate serde_json;
extern crate rocket;
use rocket_contrib::{JSON, Value};
use rocket::request::{FromForm, Form};
#[derive(FromForm)]
struct User{
name: String,
email: String
}
#[post("/upload", data="<user>")]
fn upload_user(user: Form<User>) -> String {
format!("Hola {}",user.get().name)
}
fn main() {
rocket::ignite().mount("/",routes![upload_user]).launch();
}
Errores
En Rocket, como es lógico, es posible crear páginas personalizadas para cada error.
#![feature(plugin,custom_derive)]
#![plugin(rocket_codegen)]
#[get("/")]
fn index() -> &'static str {
"El cohete ha despegado"
}
#[error(404)]
fn not_found() -> &'static str {
"La página no ha podido ser encontrada"
}
fn main() {
rocket::ignite().mount("/",routes![index]).catch(errors![not_found]).launch();
}
La lista de métodos que manejan errores hay que pasarla en el método catch de rocket::ignite
Respuestas
Rocket nos permite devolver cualquier cosa que implemente el trait Responder. Algunos tipos ya lo llevan como String, File, JSON, Option y Result. Pero nada nos impide que nuestros propios tipos implementen Responder. Con Responder tenemos el contenido y el código de error (que en la mayoría de casos será 200). En el caso de Result es muy interesante, pues si Err contiene algo que implementa Responder, se devolverá la salida que implemente también, pudiendo así hacer mejores respuestas de error, mientras que si no lo hacen se llamará al método que implemente el error 500 de forma genérica. Con Option, si el valor es Some se devolverá el contenido, si es None se generará un error 404.
#![feature(plugin,custom_derive)]
#![plugin(rocket_codegen)]
#[macro_use] extern crate rocket_contrib;
extern crate rocket;
use rocket::response::{self, Responder, Response};
use std::io::Cursor;
use rocket::http::ContentType;
struct Pelicula{
nombre: &'static str,
pais: &'static str
}
impl<'r> Responder<'r> for Pelicula{
fn respond(self) -> response::Result<'r> {
Response::build()
.sized_body(Cursor::new(format!("La película {} se hizo en {}",self.nombre,self.pais)))
.header(ContentType::new("text","plain"))
.ok()
}
}
#[get("/pelicula/<pelicula>")]
fn pelicula(pelicula: &str) -> Result<Pelicula,String> {
let intocable = Pelicula{
nombre: "Intocable",
pais: "Francia"
};
let madMax = Pelicula{
nombre: "Mad Max",
pais: "Estados Unidos"
};
match pelicula {
"Intocable" => Ok(intocable),
"Mad Max" => Ok(madMax),
_ => Err(format!("No existe esa película en nuestra base de datos"))
}
}
#[get("/")]
fn index() -> Result<String,String> {
Err(format!("No implementado"))
}
#[error(404)]
fn not_found() -> &'static str {
"La página no ha podido ser encontrada"
}
fn main() {
rocket::ignite().mount("/",routes![index,pelicula]).catch(errors![not_found]).launch();
}
Este ejemplo para /pelicula/Intocable devolverá: La película Intocable se hizo en Francia mientras que para /pelicula/Ratatouille dirá No existe esa película en nuestra base de datos.
También es posible devolver plantillas. Rocket se integra por defecto con Handlebars y Tera, aunque no es muy costoso añadir cualquier otra como Maud.
Conclusión
Rocket es un prometedor web framework para Rust, bastante idiomático, que se integra muy bien con el lenguaje. Espero con ansia las nuevas veriones. Es posible que la API cambie bastante hasta que salga la versión 1.0, no obstante así es como ahora mismo funciona.