feat(scaffold): add Axum + Leptos SSR base structure

Sets up the full project skeleton: Cargo.toml with ssr/hydrate features, Axum server entry point, shared Leptos lib, root App component with router, server/client module split, and Trunk config for WASM build. Both `cargo check --features ssr` and `cargo check --features hydrate --target wasm32-unknown-unknown` pass. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-15 19:16:35 +02:00
parent 11b0f60892
commit efad573c3b
11 changed files with 3128 additions and 3 deletions
--- a/Cargo.lock
+++ b/Cargo.lock
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,77 @@
 [package]
 name = "rust-ipam"
 version = "0.1.0"
-edition = "2024"
+edition = "2021"
+
+# Leptos nécessite deux formats de compilation :
+# - rlib   : bibliothèque normale, utilisée par le serveur Axum
+# - cdylib : bibliothèque dynamique compilée en WebAssembly pour le navigateur
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+# Les "features" permettent d'activer du code conditionnellement selon le contexte.
+# On compile deux fois le même code : une fois en mode "ssr" (serveur), une fois "hydrate" (WASM).
+[features]
+# Mode serveur : active Axum, Tokio, et le rendu HTML côté serveur
+ssr = [
+    "dep:axum",
+    "dep:tokio",
+    "dep:tower-http",
+    "dep:leptos_axum",
+    "dep:tracing-subscriber",
+    "leptos/ssr",
+    "leptos_meta/ssr",
+    "leptos_router/ssr",
+]
+# Mode client : compile l'application en WebAssembly pour le navigateur
+# Note : seul `leptos` expose une feature "hydrate" ; leptos_meta et leptos_router
+# n'en ont pas besoin — ils s'adaptent automatiquement au mode de compilation.
+hydrate = [
+    "dep:console_error_panic_hook",
+    "dep:wasm-bindgen",
+    "leptos/hydrate",
+]

 [dependencies]
+# --- Dépendances partagées (compilées côté serveur ET client) ---
+
+# Framework UI réactif full-stack : le cœur du projet
+leptos = { version = "0.7", features = [] }
+# Gestion des balises HTML <head> (title, meta tags, liens CSS...)
+leptos_meta = { version = "0.7", features = [] }
+# Routeur : associe des URLs à des composants, côté serveur et client
+leptos_router = { version = "0.7", features = [] }
+
+# Dérive automatiquement des types d'erreurs idiomatiques Rust
+thiserror = "1"
+# Macros pour les logs : tracing::info!(), tracing::error!()...
+tracing = "0.1"
+
+# --- Dépendances serveur uniquement (activées par la feature "ssr") ---
+
+# Serveur HTTP asynchrone rapide et ergonomique
+axum = { version = "0.7", optional = true }
+# Runtime asynchrone Rust (nécessaire pour `async fn main()` et les Futures)
+tokio = { version = "1", features = ["full"], optional = true }
+# Pont entre Leptos et Axum : SSR, server functions, streaming...
+leptos_axum = { version = "0.7", optional = true }
+# Middleware HTTP : sert les fichiers statiques (CSS, WASM compilé, images...)
+tower-http = { version = "0.5", features = ["fs"], optional = true }
+# Formateur de logs pour le terminal (affiche les messages tracing::info!...)
+tracing-subscriber = { version = "0.3", features = ["env-filter"], optional = true }
+
+# --- Dépendances client uniquement (activées par la feature "hydrate") ---
+
+# Affiche les panics Rust dans la console du navigateur (indispensable pour déboguer)
+console_error_panic_hook = { version = "0.1", optional = true }
+# Pont entre Rust/WASM et JavaScript : permet d'appeler du JS depuis Rust
+wasm-bindgen = { version = "0.2", optional = true }
+
+# Profil de compilation WASM optimisé pour réduire la taille du fichier .wasm
+# Un fichier WASM plus petit = page qui charge plus vite
+[profile.wasm-release]
+inherits = "release"
+opt-level = "z"     # Optimise pour la taille (z) plutôt que la vitesse (3)
+lto = true           # Link-Time Optimization : élimine le code mort entre crates
+codegen-units = 1    # Un seul thread de codegen = meilleure optimisation globale
+panic = "abort"      # Pas de stack unwinding = binaire plus petit
--- a/Trunk.toml
+++ b/Trunk.toml
@@ -0,0 +1,25 @@
+# Trunk.toml — Configuration de trunk
+# trunk est l'outil de build pour les applications Rust/WASM.
+#
+# Commandes principales :
+#   trunk serve          → serveur de dev avec hot-reload (recompile à chaque changement)
+#   trunk build          → compilation production (dans target/site/)
+#   trunk build --release → compilation production optimisée (avec profile wasm-release)
+
+[build]
+# Feature à activer lors de la compilation WASM
+# "hydrate" active le code client et désactive le code serveur
+features = ["hydrate"]
+# Dossier de sortie des fichiers compilés (JS, WASM, CSS, HTML)
+dist = "target/site"
+
+[watch]
+# Dossiers à ignorer lors de la surveillance des changements de fichiers
+# Sans ça, trunk se relancerait en boucle en détectant ses propres fichiers compilés
+ignore = ["./target"]
+
+[serve]
+# Port du serveur de développement trunk
+port = 3000
+# Ne pas ouvrir le navigateur automatiquement au démarrage
+open = false
--- a/index.html
+++ b/index.html
@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html lang="fr">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <!--
+      trunk complète automatiquement ce fichier lors de `trunk build` ou `trunk serve` :
+      - Il injecte les balises <link> pour charger le CSS compilé
+      - Il injecte les balises <script> pour charger le bundle WebAssembly
+      Ne pas ajouter ces balises manuellement ici — trunk le fait pour vous.
+    -->
+  </head>
+  <body>
+    <!--
+      Leptos monte l'application ici via mount_to_body() (défini dans lib.rs).
+
+      Flux SSR + Hydration :
+      1. Le navigateur demande la page au serveur Axum
+      2. Axum rend le composant App() en HTML (SSR) et l'envoie
+      3. Le navigateur affiche le HTML instantanément (pas d'écran blanc)
+      4. Le bundle WASM se charge en arrière-plan
+      5. Leptos "hydrate" le HTML : attache les event listeners pour le rendre interactif
+    -->
+  </body>
+</html>
--- a/src/app.rs
+++ b/src/app.rs
@@ -0,0 +1,62 @@
+// app.rs — Composant racine de l'application Leptos
+//
+// Ce composant est le point d'entrée de toute l'interface.
+// Il définit :
+//   - Les métadonnées globales (title, CSS...)
+//   - Le routeur : quelle page afficher selon l'URL
+//   - Les contextes globaux partagés (à ajouter plus tard : auth, thème...)
+
+use leptos::prelude::*;
+use leptos_meta::*;
+use leptos_router::{
+    components::{Route, Router, Routes},
+    path,
+};
+
+use crate::client::home::HomePage;
+
+// `#[component]` est un attribut procédural Leptos.
+// Il transforme une fonction Rust normale en composant réutilisable et traçable.
+//
+// Règle de nommage : toujours PascalCase pour les composants Leptos.
+//
+// `-> impl IntoView` : la fonction retourne "quelque chose affichable".
+// On utilise `impl` (type opaque) car le type exact généré par `view!` est complexe.
+#[component]
+pub fn App() -> impl IntoView {
+    // Initialise le contexte de métadonnées Leptos.
+    // Sans cet appel, les composants <Title>, <Meta>, <Stylesheet> plus bas ne fonctionnent pas.
+    provide_meta_context();
+
+    // La macro `view!` permet d'écrire du HTML dans du Rust.
+    // Leptos la transforme en code Rust pur à la compilation — pas de runtime template engine.
+    view! {
+        // Définit le titre de l'onglet navigateur (injecté dans le <head> HTML)
+        <Title text="Rust IPAM — Gestionnaire d'adresses IP"/>
+
+        // Charge le CSS global. Le nom de fichier suit la convention Leptos :
+        // `{nom-du-crate}.css` dans le dossier `/pkg/` servi par Axum.
+        <Stylesheet id="main" href="/pkg/rust-ipam.css"/>
+
+        // Le Router gère la navigation côté client sans rechargement de page.
+        // Côté serveur (SSR), il détermine quel composant rendre selon l'URL demandée.
+        <Router>
+            <main>
+                // `<Routes>` est le conteneur pour toutes les définitions de routes.
+                // `fallback` est affiché si aucune route ne correspond à l'URL actuelle.
+                <Routes fallback=|| view! {
+                    <div class="page-erreur">
+                        <h1>"404 — Page introuvable"</h1>
+                        <a href="/">"← Retour à l'accueil"</a>
+                    </div>
+                }>
+                    // Chaque `<Route>` associe un chemin URL à un composant.
+                    // `path!(/)` correspond exactement à l'URL racine "/".
+                    // Ajouter de nouvelles pages ici, exemple :
+                    //   <Route path=path!("/reseaux") view=ReseauxPage/>
+                    <Route path=path!("/") view=HomePage/>
+                </Routes>
+            </main>
+        </Router>
+    }
+}
--- a/src/client/home.rs
+++ b/src/client/home.rs
@@ -0,0 +1,78 @@
+// client/home.rs — Page d'accueil
+//
+// Ce fichier illustre les concepts fondamentaux de Leptos :
+//   - Composants (`#[component]`)
+//   - Signals (valeurs réactives)
+//   - Memos (valeurs dérivées)
+//   - Gestion d'événements (`on:click`)
+
+use leptos::prelude::*;
+
+// Composant de la page d'accueil.
+//
+// En Leptos, un composant est une simple fonction Rust avec l'attribut `#[component]`.
+// Elle est appelée une seule fois pour construire le graphe réactif —
+// ce n'est pas comme React où le composant se "ré-exécute" à chaque mise à jour.
+#[component]
+pub fn HomePage() -> impl IntoView {
+    // `RwSignal<T>` (Read-Write Signal) est une valeur réactive mutable.
+    //
+    // Quand on appelle `.set()` ou `.update()`, Leptos identifie automatiquement
+    // tous les éléments du DOM qui dépendent de ce signal et les met à jour —
+    // sans Virtual DOM, sans diff complet : seulement ce qui change.
+    //
+    // `i32` = entier signé 32 bits (le type entier par défaut en Rust)
+    let compteur = RwSignal::new(0i32);
+
+    // `Memo<T>` est une valeur calculée à partir d'un ou plusieurs signals.
+    // Elle se recalcule automatiquement quand `compteur` change, mais
+    // ne notifie ses dépendants que si sa valeur a effectivement changé.
+    //
+    // `move |_|` : une closure qui capture `compteur` par déplacement (ownership).
+    //   - `move` : la closure prend possession de `compteur`
+    //   - `|_|`  : elle ignore son argument (la valeur précédente du memo)
+    let double = Memo::new(move |_| compteur.get() * 2);
+
+    view! {
+        <div class="page-accueil">
+            <h1>"Rust IPAM"</h1>
+            <p class="sous-titre">"Gestionnaire d'adresses IP"</p>
+
+            // --- Démonstration de la réactivité ---
+            // Dans un vrai projet IPAM, on afficherait ici la liste des sous-réseaux,
+            // les adresses disponibles, les statistiques d'utilisation...
+            <section class="demo-reactive">
+                <h2>"Réactivité Leptos"</h2>
+
+                // `{compteur}` insère la valeur du signal directement dans le DOM.
+                // Leptos met à jour UNIQUEMENT ce nœud texte quand compteur change.
+                // Pas de re-render du composant entier : c'est granulaire et efficace.
+                <p>"Compteur : " {compteur}</p>
+
+                // `{double}` : idem, mais pour le memo (valeur dérivée)
+                <p>"Double : " {double}</p>
+
+                <div class="boutons">
+                    // `on:click` attache un event listener au bouton.
+                    //
+                    // `.update(|n| *n += 1)` :
+                    //   - prend une closure qui reçoit une référence mutable `&mut i32`
+                    //   - `*n` déréférence le pointeur pour modifier la valeur pointée
+                    //   - `+= 1` incrémente la valeur en place
+                    <button on:click=move |_| compteur.update(|n| *n += 1)>
+                        "+"
+                    </button>
+
+                    <button on:click=move |_| compteur.update(|n| *n -= 1)>
+                        "-"
+                    </button>
+
+                    // `.set(0)` remplace directement la valeur (plus simple qu'update ici)
+                    <button on:click=move |_| compteur.set(0)>
+                        "Réinitialiser"
+                    </button>
+                </div>
+            </section>
+        </div>
+    }
+}
--- a/src/client/mod.rs
+++ b/src/client/mod.rs
@@ -0,0 +1,12 @@
+// client/mod.rs — Module client (composants UI)
+//
+// Contient les pages et composants Leptos de l'application.
+//
+// Important : malgré le nom "client", ce code s'exécute des DEUX côtés :
+//   - Côté serveur : pour générer le HTML initial (SSR)
+//   - Côté navigateur : compilé en WASM pour rendre l'interface interactive
+//
+// Ne pas mettre ici de code qui nécessite des APIs navigateur (window, document...)
+// sans le protéger avec `#[cfg(target_arch = "wasm32")]`.
+
+pub mod home; // Page d'accueil
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -0,0 +1,40 @@
+// lib.rs — Racine de la bibliothèque partagée
+//
+// Ce fichier est compilé dans les DEUX modes :
+//   "ssr"     → le serveur Axum l'utilise pour rendre du HTML
+//   "hydrate" → trunk le compile en WebAssembly pour le navigateur
+//
+// C'est ce partage de code qui rend Leptos "full-stack" :
+// on écrit les composants une fois, ils s'exécutent des deux côtés.
+
+// Déclaration des sous-modules de cette bibliothèque.
+// `pub` les rend accessibles depuis main.rs et d'autres crates.
+pub mod app;    // Composant racine App() et configuration du routeur
+pub mod client; // Pages et composants de l'interface utilisateur
+pub mod server; // Handlers HTTP et logique métier côté serveur
+
+// Point d'entrée WebAssembly — exécuté par le navigateur au chargement du bundle .wasm
+//
+// `#[cfg(feature = "hydrate")]` : ce code n'existe que dans le bundle WASM.
+// `#[wasm_bindgen(start)]`      : demande à wasm-bindgen d'appeler cette fonction
+//                                  automatiquement sans intervention JavaScript.
+#[cfg(feature = "hydrate")]
+#[wasm_bindgen::prelude::wasm_bindgen(start)]
+pub fn hydrate() {
+    use crate::app::App;
+
+    // Active les messages d'erreur Rust dans la console du navigateur.
+    // Sans ça, un panic Rust en WASM affiche juste "unreachable executed" — inutile.
+    // `set_once()` garantit qu'on ne l'initialise pas plusieurs fois si hydrate() est appelé plusieurs fois.
+    console_error_panic_hook::set_once();
+
+    // Monte l'application Leptos dans le <body> de la page HTML.
+    //
+    // En mode "hydration" (SSR + WASM), Leptos ne recrée pas le DOM depuis zéro.
+    // Il trouve le HTML déjà rendu par le serveur et y attache les event listeners
+    // pour rendre l'interface interactive. C'est plus rapide qu'un SPA classique
+    // qui construit tout le DOM côté client.
+    //
+    // `hydrate_body` (Leptos 0.7) = mode SSR + hydration (≠ `mount_to_body` qui repart de zéro)
+    leptos::mount::hydrate_body(App);
+}
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,3 +1,86 @@
-fn main() {
-    println!("Hello, world!");
+// main.rs — Point d'entrée du serveur Axum
+//
+// Ce fichier est compilé UNIQUEMENT en mode "ssr" (Server-Side Rendering).
+// `#[cfg(feature = "ssr")]` est l'équivalent d'un `#ifdef` en C :
+// le code qu'il protège n'existe pas dans le bundle WASM.
+//
+// Pour lancer le serveur :
+//   cargo run --features ssr
+//
+// Pour lancer avec des logs détaillés :
+//   RUST_LOG=debug cargo run --features ssr
+
+#[cfg(feature = "ssr")]
+#[tokio::main]
+// `#[tokio::main]` est une macro qui transforme notre `fn main()` synchrone
+// en une fonction asynchrone, gérée par le runtime Tokio.
+// Sans ça, Rust ne saurait pas comment exécuter du code `async`.
+async fn main() {
+    use axum::Router;
+    use leptos::config::get_configuration;
+    use leptos_axum::{generate_route_list, LeptosRoutes};
+    use rust_ipam::{app::App, server::routes::not_found_handler};
+    use tower_http::services::ServeDir;
+
+    // Initialise le système de logs structurés.
+    // Les macros tracing::info!(), tracing::warn!(), tracing::error!()
+    // n'affichent rien sans cet initialisateur.
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            // Lire le niveau de log depuis la variable d'environnement RUST_LOG,
+            // ou utiliser "info" par défaut si elle n'est pas définie.
+            // `unwrap_or_else` est une alternative idiomatique à `unwrap()` :
+            // elle fournit une valeur de repli au lieu de paniquer.
+            std::env::var("RUST_LOG").unwrap_or_else(|_| "info".to_string()),
+        )
+        .init();
+
+    tracing::info!("Démarrage du serveur Rust IPAM...");
+
+    // Charge la configuration Leptos.
+    // Leptos peut lire un fichier `Leptos.toml` ou utiliser des valeurs par défaut.
+    // On utilise `.expect()` car le serveur ne peut pas fonctionner sans configuration.
+    // La chaîne passée à expect() est affichée si la valeur est Err ou None.
+    // Note : get_configuration() est synchrone en Leptos 0.7 — pas de .await ici.
+    let conf = get_configuration(None)
+        .expect("Impossible de charger la configuration Leptos");
+    let leptos_options = conf.leptos_options;
+    let addr = leptos_options.site_addr;
+
+    // Analyse statiquement tous les composants `<Route>` dans `App`
+    // pour construire la liste des URLs que Leptos doit gérer.
+    let routes = generate_route_list(App);
+
+    // Construit le routeur Axum avec le pattern builder.
+    // Chaque méthode retourne un nouveau Router modifié — c'est du chaînage fonctionnel.
+    let app = Router::new()
+        // Sert les fichiers statiques compilés par trunk (WASM, CSS, JS...).
+        // `trunk build` les place dans `target/site/pkg/`.
+        // Les navigateurs les demandent via des URLs comme `/pkg/rust-ipam.wasm`.
+        .nest_service("/pkg", ServeDir::new("target/site/pkg"))
+        // Branche toutes les routes Leptos dans Axum.
+        // Pour chaque URL dans `routes`, Axum rend le composant App() en HTML.
+        .leptos_routes(&leptos_options, routes, App)
+        // Handler de repli : toute URL non reconnue retourne une 404.
+        .fallback(not_found_handler)
+        // Partage les options Leptos avec tous les handlers via le système d'état Axum.
+        .with_state(leptos_options);
+
+    // Crée un listener TCP sur l'adresse configurée (par défaut 127.0.0.1:3000).
+    let listener = tokio::net::TcpListener::bind(&addr)
+        .await
+        .expect(&format!("Impossible d'écouter sur l'adresse {}", addr));
+
+    tracing::info!("Serveur disponible sur http://{}", addr);
+
+    // Lance le serveur. Cette ligne bloque jusqu'à un Ctrl+C.
+    axum::serve(listener, app)
+        .await
+        .expect("Erreur critique du serveur");
 }
+
+// Ce bloc vide est nécessaire pour que le compilateur trouve un `fn main()`
+// quand on compile en mode WASM (où la feature "ssr" n'est pas activée).
+// En WASM, le vrai point d'entrée est la fonction `hydrate()` dans lib.rs.
+#[cfg(not(feature = "ssr"))]
+fn main() {}
--- a/src/server/mod.rs
+++ b/src/server/mod.rs
@@ -0,0 +1,12 @@
+// server/mod.rs — Module serveur
+//
+// Contient tout le code qui s'exécute uniquement côté serveur :
+//   - Handlers HTTP additionnels (routes.rs)
+//   - Fonctions serveur Leptos : accès à la base de données, authentification...
+//   - Logique métier qui ne doit JAMAIS être exposée dans le bundle WASM
+//
+// Les "server functions" Leptos (marquées #[server]) sont déclarées ici.
+// Elles apparaissent comme des appels asynchrones normaux côté client,
+// mais s'exécutent exclusivement sur le serveur — transparence totale.
+
+pub mod routes;
--- a/src/server/routes.rs
+++ b/src/server/routes.rs
@@ -0,0 +1,26 @@
+// server/routes.rs — Handlers HTTP Axum additionnels
+//
+// Ces handlers complètent les routes gérées par Leptos.
+// Exemples d'usages futurs :
+//   - Endpoints API REST (/api/...)
+//   - Exports de fichiers (CSV, PDF...)
+//   - Webhooks entrants
+//   - Health check pour le monitoring (/health)
+//
+// `#[cfg(feature = "ssr")]` protège tout ce fichier :
+// Axum n'existe pas dans le bundle WASM, donc on ne compile ce code qu'en mode serveur.
+
+#[cfg(feature = "ssr")]
+use axum::{http::StatusCode, response::IntoResponse};
+
+// Handler 404 — utilisé comme fallback dans main.rs pour toute URL non reconnue.
+//
+// `impl IntoResponse` : Axum accepte n'importe quel type qui implémente ce trait.
+// Un tuple `(StatusCode, &str)` l'implémente automatiquement :
+// Axum en fait une réponse HTTP 404 avec le corps "Page introuvable".
+//
+// `async fn` est obligatoire pour les handlers Axum, même sans opération asynchrone.
+#[cfg(feature = "ssr")]
+pub async fn not_found_handler() -> impl IntoResponse {
+    (StatusCode::NOT_FOUND, "Page introuvable")
+}