Notre première route avec Rocket

Ajout de Rocket à notre projet

Bon, il est maintenant temps de se salir les mains et d'ajouter notre framework web à notre projet. Nous utiliserons Rocket car c'est à mon sens la crate la plus facile à appréhender et à mettre en place. Vous pouvez également consulter la crate actix-web qui peut être une très bonne alternative.
Pour les personnes n'étant pas familières avec le concept de crates, il s'agit de librairies (plugins, package...) permettant d'étendre les fonctionnalités du langage sans avoir besoin de réinventer la roue.

Si vous utilisez la crate cargo-edit vous pouvez simplement taper cargo add rocket dans votre terminal. Sinon, ajoutez simplement la version à votre fichier Cargo. Pour cet article, nous utiliserons la version 0.5.0-rc.2. Votre Cargo.toml devrait maintenant ressembler à ça :

[package]
name = "web_server"
version = "0.1.0"
edition = "2021"

[dependencies]
rocket = "0.5.0-rc.2"

On est paré ! Commençons à coder.

Créons notre première route

Mettre en place un serveur web en Rust avec Rocket est vraiment (très) simple. Qui a dit que le Rust était seulement un langage de bas niveau ?

Remplaçons le contenu de notre main.rs et voyons ce que ça donne.

#[macro_use]
extern crate rocket;

#[get("/health")]
fn healthcheck() -> &'static str {
    "OK"
}

#[launch]
fn rocket() -> _ {
    rocket::build().mount("/", routes![healthcheck])
}

Les deux premières lignes nous permettent d'utiliser les macros de Rocket telles que get ou launch. Vous devriez être familier avec ça si vous avez déjà fait du Rust. Vous pouvez aussi décider de retirer ces lignes et n'importer que les macros dont vous avez besoin.

La macro get transforme notre simple fonction en un endpoint pour notre API. Elle prend en paramèter une string qui correspond au chemin de notre endpoint (à noter que cette route peut être préfixée comme nous le verrons ci-après). Ce n'est évidemment pas la seule macro de ce type et il en existe d'autres correspondant à tous les verbes HTTP.

Notez qu'une route peut retourner n'importe quel type implémentant le trait Responder. Il est déjà implémenté pour certains types tels que &str, String, ou encore Json mais vous pouvez aussi l'implémenter pour vos propres types. Je vous encourage à aller consulter cette page si vous souhaitez en savoir plus sur le trait Responder et les réponses en général.

Finalement, la macro launch génère une fonction main qui appelle la fonction launch de la structure retournée par la fonction à laquelle la macro est appliquée. En l'occurrence, le code généré serait le suivant :

#[rocket::main]
async fn main() {
    let _ = rocket().launch().await;
}

Enfin, en ce qui concerne la fonction rocket() elle-même, elle se contente de monter les routes transmises en paramètre, préfixées du chemin indiqué. Notez qu'il est tout à fait possible d'appeler plusieurs fois la fonction mount si l'on souhaite monter différentes routes avec différents préfixes (nous aurons l'occasion d'y revenir plus tard dans cette série d'articles).

Nous pouvons maintenant lancer le serveur en tapant la commande cargo run dans notre terminal et voir les lignes suivantes nous indiquant que le serveur a démarré avec succès.

Configured for debug.
   >> address: 127.0.0.1
   >> port: 1234
   >> workers: 8
   >> ident: Rocket
   >> limits: bytes = 8KiB, data-form = 2MiB, file = 1MiB, form = 32KiB, json = 1MiB, msgpack = 1MiB, string = 8KiB
   >> temp dir: C:\Users\Thibaut\AppData\Local\Temp\
   >> http/2: true
   >> keep-alive: 5s
   >> tls: disabled
   >> shutdown: ctrlc = true, force = true, grace = 2s, mercy = 3s
   >> log level: debug
   >> cli colors: true
Routes:
   >> (healthcheck) GET /health
Fairings:
   >> Shield (liftoff, response, singleton)
registering event source with poller: token=Token(0), interests=READABLE | WRITABLE
Shield:
   >> X-Frame-Options: SAMEORIGIN
   >> Permissions-Policy: interest-cohort=()
   >> X-Content-Type-Options: nosniff
Rocket has launched from http://127.0.0.1:1234

Rendez-vous dans votre navigateur à l'adresse indiquée (en n'oubliant pas d'y ajouter le chemin de notre endpoint) et vous devriez voir le contenu souhaité à savoir "OK".

Changer la configuration avec le ficher Rocket.toml

Vous souhaitez peut-être configurer votre serveur Rocket pour qu'il se lance sur un port différent, avec un niveau de log plus ou moins élevé ou encore changer le nombre de workers ? Peut-être souhaitez vous aussi avoir des configurations différentes dépendamment des environnements dans lesquels sont déployés l'application ? Bonne nouvelle, le fichier Rocket.toml est là pour ça.

Dans ce fichier, vous pouvez spécifier comment lancer votre serveur et configurer celui-ci par profil. Vous pouvez aussi avoir des configurations par défaut ou au contraire des configurations écrasant toutes les autres valeurs.

Voici une exemple de configuration. Vous pouvez trouver tous les champs disponibles dans la documentation.

[debug]
address = "127.0.0.1"
port = 1234
log_level = "debug"

Dans le prochain article, nous irons un peu plus loin en ajoutant un système d'authentification à notre serveur !