# Logs Reader — Spécification > Document dérivé du brief `.spec/spec.md`. > Statut : brouillon v1 — 2026-10-21. --- ## 1. Vue d'ensemble Logs Reader est une application web **locale et mono-utilisateur** qui permet à un développeur de : 1. enregistrer un ou plusieurs projets Laravel par leur chemin sur le disque ; 2. voir tous les fichiers de log de chaque projet et en lire les entrées ; 3. être prévenu, via le **favicon** et le titre de l'onglet, de toute nouvelle entrée apparue depuis sa dernière consultation ; 4. choisir l'intervalle de rafraîchissement. ### 1.1 Périmètre | Dans le périmètre | Hors périmètre (v1) | |---|---| | Fichiers de log sur le disque local | Logs distants (SSH, S3, Papertrail…) | | Format Monolog par défaut de Laravel (`single`, `daily`, channels custom en fichier) | Formats JSON, syslog, stderr | | Lecture seule des logs | Édition, suppression ou vidage des logs | | Un seul utilisateur, sans authentification | Comptes, rôles, partage | | Notification par favicon et titre d'onglet | E-mail, Slack, notifications natives de l'OS | --- ## 2. Glossaire | Terme | Définition | |---|---| | **Projet** | Un projet Laravel enregistré, identifié par son chemin racine **canonique** (absolu, symlinks résolus, sans `/` final). | | **Répertoire de logs** | `/storage/logs`. | | **Fichier de log** | Tout fichier `*.log` situé (récursivement) dans le répertoire de logs. | | **Entrée** | Une écriture de log. Elle commence par une ligne d'en-tête Monolog et contient toutes les lignes suivantes jusqu'à la prochaine ligne d'en-tête (stack trace comprise). | | **Ligne d'en-tête** | Ligne qui correspond à `^\[(\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[+-]\d{2}:?\d{2})?)\] (\w+)\.(\w+): ` → horodatage, environnement, niveau. | | **Niveau** | L'un des niveaux PSR-3 : `DEBUG`, `INFO`, `NOTICE`, `WARNING`, `ERROR`, `CRITICAL`, `ALERT`, `EMERGENCY`. | | **Entrée complète** | Une entrée suivie d'une autre ligne d'en-tête, ou, pour la dernière du fichier, terminée par `\n` dans un fichier non modifié depuis 1 s. | | **Offset de scan** | Position (en octets) jusqu'à laquelle le fichier a été lu et découpé en entrées complètes. | | **Curseur de lecture** | Position (en octets) de fin de la dernière entrée **consultée** par l'utilisateur, une par fichier. | | **Non-lu** | Une entrée complète qui commence à un offset ≥ curseur de lecture. | | **Intervalle** | Délai en secondes entre deux rafraîchissements côté client. | --- ## 3. Architecture ``` ┌──────────────── Navigateur ────────────────┐ │ Leptos (hydratation WASM) + Tailwind │ │ - poll unread_summary toutes les N s │ │ - dessine le favicon (canvas) + titre │ └──────────────▲─────────────────────────────┘ │ server functions Leptos (HTTP) ┌──────────────┴──────── Serveur ────────────┐ │ axum + leptos_axum (SSR) │ │ - Scanner : découverte + lecture │ │ incrémentale + parsing │ │ - Repository SQLite (sqlx, migrations) │ └──────┬───────────────────────────┬─────────┘ │ lecture seule │ /storage/logs/*.log data.sqlite ``` - **Build** : `cargo-leptos` (features `ssr` / `hydrate`), Tailwind CSS intégré via la config `tailwind-input-file` de cargo-leptos. - **Persistance** : SQLite via `sqlx`, migrations embarquées (`sqlx::migrate!`) appliquées au démarrage, `PRAGMA foreign_keys = ON`, mode WAL. - **Scan** : déclenché par chaque appel `unread_summary` (donc au rythme du polling). Les scans concurrents d'un même projet sont sérialisés (mutex par projet) ; un appel qui arrive pendant un scan attend son résultat au lieu d'en relancer un. - **Configuration** (variables d'environnement) : - `LOGS_READER_DATABASE_URL` — défaut `sqlite://./logs_reader.sqlite?mode=rwc` - `LOGS_READER_ADDR` — défaut `127.0.0.1:3000` ### 3.1 API (server functions) Chaque fonction est exposée en `POST /api/`. | Fonction | Entrée | Sortie | |---|---|---| | `add_project` | `path: String`, `name: Option` | `Project` | | `remove_project` | `project_id` | `()` | | `read_entries` | `file_id`, `limit` (≤ 2000), `levels: Vec`, `query: String` | `EntriesPage { entries, has_more, scan_offset, read_offset, levels }` | | `mark_read` | `file_id`, `up_to` | `()` | | `mark_all_read` | `project_id: Option<_>` | `()` | | `unread_summary` | — | `Summary { total, projects[{…, unread, files[{…, unread}]}] }` | | `get_settings` / `set_refresh_interval` | `seconds: String` | `Settings { refresh_interval_seconds, file_sort }` | | `set_paused` | `paused: bool` | `()` | | `set_file_sort` | `sort: "name" \| "modified"` | `()` | --- ## 4. Modèle de données ```sql CREATE TABLE projects ( id INTEGER PRIMARY KEY, name TEXT NOT NULL, root_path TEXT NOT NULL UNIQUE, -- chemin canonique created_at TEXT NOT NULL ); CREATE TABLE log_files ( id INTEGER PRIMARY KEY, project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE, relative_path TEXT NOT NULL, -- relatif à storage/logs file_identity TEXT, -- inode+device (Unix) / file index (Windows) size INTEGER NOT NULL DEFAULT 0, modified_at INTEGER, -- mtime, secondes Unix (tri) scan_offset INTEGER NOT NULL DEFAULT 0, entries_count INTEGER NOT NULL DEFAULT 0, -- entrées complètes ≤ scan_offset discovered_at TEXT NOT NULL, missing_since TEXT, -- NULL si le fichier existe last_error TEXT, UNIQUE (project_id, relative_path) ); CREATE TABLE log_entries_index ( -- index léger, pas le contenu log_file_id INTEGER NOT NULL REFERENCES log_files(id) ON DELETE CASCADE, start_offset INTEGER NOT NULL, end_offset INTEGER NOT NULL, logged_at TEXT NOT NULL, level TEXT NOT NULL, PRIMARY KEY (log_file_id, start_offset) ); CREATE TABLE read_cursors ( log_file_id INTEGER PRIMARY KEY REFERENCES log_files(id) ON DELETE CASCADE, read_offset INTEGER NOT NULL DEFAULT 0, updated_at TEXT NOT NULL ); CREATE TABLE settings ( key TEXT PRIMARY KEY, value TEXT NOT NULL ); -- valeurs initiales : ('refresh_interval_seconds', '5'), ('file_sort', 'name') ``` - Le **contenu** des entrées n'est pas stocké : il est relu dans le fichier à partir de `start_offset`/`end_offset`. L'index permet compteurs, filtres par niveau et pagination sans tout relire. - `unread(file) = SELECT COUNT(*) FROM log_entries_index WHERE log_file_id = ? AND start_offset >= read_offset`. --- ## 5. Règles métier ### 5.1 Ajout d'un projet 1. Le chemin saisi est nettoyé (trim) ; `~` en tête est remplacé par `$HOME`. 2. Il est canonicalisé (`std::fs::canonicalize`). 3. Il est valide si : c'est un répertoire, il contient un fichier `artisan` **et** un répertoire `storage/logs` lisible. 4. Le nom par défaut est le nom du dernier segment du chemin. 5. Les fichiers de log existants sont découverts et indexés. **Leur curseur de lecture est placé à la fin** (`read_offset = scan_offset`) : l'historique n'est pas compté comme non-lu. ### 5.2 Découverte des fichiers - Parcours récursif de `storage/logs`, à chaque scan. - Retenus : fichiers réguliers dont le nom se termine par `.log`. Ignorés : fichiers cachés (`.gitignore`…), répertoires, autres extensions (`.gz`…). - Liens symboliques : suivis uniquement si la cible canonique reste sous `storage/logs`. - Un fichier **apparu après l'ajout du projet** (ex. nouveau `laravel-2026-10-22.log` en mode daily) est créé avec `read_offset = 0` : tout son contenu est non-lu. - Un fichier disparu reçoit `missing_since` ; ses entrées ne comptent plus dans les non-lus ; il réapparaît normalement s'il revient (traité comme une rotation, cf. 5.4). ### 5.3 Lecture incrémentale et parsing - Le fichier est ouvert en **lecture seule**, lu à partir de `scan_offset` par blocs (ex. 64 Kio), sans jamais le charger en entier. - Les octets sont décodés en UTF-8 avec remplacement (`from_utf8_lossy`) ; les offsets restent des offsets d'octets. - Une ligne d'en-tête ouvre une nouvelle entrée. Toute autre ligne est rattachée à l'entrée courante. - Des lignes avant la première ligne d'en-tête du fichier forment une entrée de niveau `UNKNOWN`, horodatée à la date de modification du fichier. - La dernière entrée du fichier n'est indexée que si elle est **complète** : elle se termine par `\n` **et** le fichier n'a pas été modifié depuis au moins 1 s (sinon une stack trace à moitié écrite serait coupée en deux). Sinon `scan_offset` reste à son début et elle sera relue au scan suivant. - Taille maximale d'une entrée affichée : 1 Mio ; au-delà le contenu est tronqué à l'affichage avec la mention « entrée tronquée » (l'index garde les vrais offsets). ### 5.4 Rotation et troncature Au scan, si `taille actuelle < scan_offset` **ou** `file_identity` a changé : - l'index des entrées du fichier est purgé ; - `scan_offset = 0`, `read_offset = 0` ; - le fichier est relu depuis le début ; tout son contenu est non-lu. ### 5.5 Rafraîchissement et notification - Le client appelle `unread_summary` au chargement de la page puis toutes les `refresh_interval_seconds` secondes. - Le nouvel intervalle s'applique dès l'enregistrement, sans recharger la page (le timer est recréé). - Le favicon est un SVG 32×32 généré côté client (URL `data:`) : - `total = 0` → icône normale ; - `total ≥ 1` → icône + pastille rouge avec le nombre (`99+` au-delà de 99) ; - serveur injoignable → icône + pastille grise « ! » ; - lecture arrêtée → icône + pastille rouge avec le symbole pause (prioritaire sur les autres états). - Le titre de l'onglet devient `(N) Logs Reader` quand `N ≥ 1`, `Logs Reader` sinon. - Le favicon change même si l'onglet est en arrière-plan (les timers en arrière-plan peuvent être ralentis par le navigateur jusqu'à 1 fois par minute : comportement accepté). ### 5.6 Marquage comme lu - Ouvrir un fichier affiche ses entrées les plus récentes et appelle `mark_read(file, scan_offset_affiché)`. - Si la vue d'un fichier est ouverte et que de nouvelles entrées arrivent, elles sont ajoutées en haut, surlignées, et marquées lues **seulement si l'onglet est visible** (`document.visibilityState == "visible"`). - `mark_read` ne fait jamais reculer un curseur : `read_offset = max(read_offset, min(up_to_offset, scan_offset))`. - Bouton « Tout marquer comme lu » par projet et global. ### 5.7 Interface - **Barre latérale** : liste des projets, chacun dépliable en liste de fichiers (chemin relatif, taille, badge de non-lus). Fichiers manquants grisés. Un projet replié le reste aux rafraîchissements. - **Tri des fichiers** : par nom (alphabétique, défaut) ou par date de dernière modification (le plus récent en premier, sans date en dernier, nom en départage). Trié par date, l'ancienneté (« il y a 3 h ») remplace la taille. Le choix s'applique à tous les projets et est enregistré dans `settings` (`file_sort`). - **Formulaire d'ajout** : champ chemin + nom optionnel, message d'erreur sous le champ. - **Vue fichier** : entrées triées du plus récent au plus ancien, 50 par page, bouton « Charger plus ». Chaque entrée : date, niveau (badge coloré), environnement, première ligne ; le reste (stack trace) est repliable. Filtres par niveau (cases à cocher ; les niveaux absents du fichier sont grisés et désactivés, et se réactivent dès qu'une entrée de ce niveau apparaît) et recherche texte (insensible à la casse, sur le contenu complet de l'entrée). - **Bouton marche/arrêt de la lecture** : à gauche du titre. Lecture active : un engrenage qui tourne lentement (6 s par tour, immobile si l'utilisateur a demandé moins d'animations). Lecture arrêtée : un bouton rouge avec l'icône « power ». L'arrêt supprime le polling et le rafraîchissement au retour sur l'onglet ; « · lecture arrêtée » s'affiche en rouge à côté du compteur. L'état est enregistré dans `settings` (`paused`). À la reprise, un rafraîchissement part immédiatement. Les actions de l'utilisateur (ouvrir un fichier, marquer comme lu, charger la page) rafraîchissent toujours. - **Réglages** : intervalle en secondes (champ numérique, 1–3600). --- ## 6. User stories et critères d'acceptation Convention : `Given / When / Then`. « Écrire une entrée » signifie ajouter au fichier une ligne `[2026-10-21 10:00:00] local.ERROR: message\n`. Tous les délais s'entendent avec un intervalle de 1 s sauf mention contraire. ### US-01 — Ajouter un projet > En tant que développeur, je veux ajouter un projet Laravel en saisissant son chemin, afin de surveiller ses logs. - **AC-01.1** Given un répertoire `/tmp/app` avec `artisan` et `storage/logs/laravel.log`, When j'ajoute `/tmp/app`, Then le projet `app` apparaît dans la liste avec le fichier `laravel.log`. - **AC-01.2** Given le même répertoire, When j'ajoute `/tmp/app/` puis `/tmp/../tmp/app`, Then la 2ᵉ et la 3ᵉ tentative sont refusées avec « Ce projet est déjà enregistré ». - **AC-01.3** Given un lien `/tmp/link → /tmp/app` et `/tmp/app` déjà enregistré, When j'ajoute `/tmp/link`, Then l'ajout est refusé (même chemin canonique). - **AC-01.4** Given `laravel.log` contient 10 entrées, When j'ajoute le projet, Then le compteur de non-lus du projet vaut 0. - **AC-01.5** Given un nom saisi « Mon API », When j'ajoute le projet, Then il s'affiche sous le nom « Mon API ». - **AC-01.6** Given `~/code/app` valide, When je saisis `~/code/app`, Then le projet est enregistré avec le chemin absolu. ### US-02 — Lister tous les fichiers de log d'un projet > En tant que développeur, je veux voir tous les fichiers de log du projet, y compris les fichiers journaliers et les channels personnalisés. - **AC-02.1** Given `storage/logs` contient `laravel.log`, `laravel-2026-10-20.log`, `jobs/worker.log`, `.gitignore`, `old.log.gz`, When le projet est affiché, Then exactement `laravel.log`, `laravel-2026-10-20.log` et `jobs/worker.log` sont listés. - **AC-02.2** Given un projet enregistré, When un fichier `laravel-2026-10-22.log` est créé avec 2 entrées, Then il apparaît dans la liste avec 2 non-lus en ≤ 2 s. - **AC-02.3** Given un fichier listé, When il est supprimé du disque, Then il est affiché grisé « manquant » en ≤ 2 s et ses non-lus ne comptent plus dans le total. - **AC-02.4** Given `storage/logs/ext.log → /var/log/syslog` (lien hors de `storage/logs`), When le projet est scanné, Then `ext.log` n'est pas listé. ### US-03 — Consulter un fichier de log > En tant que développeur, je veux lire les entrées d'un fichier, des plus récentes aux plus anciennes, avec leur stack trace. - **AC-03.1** Given un fichier de 120 entrées, When je l'ouvre, Then les 50 plus récentes s'affichent, la première étant la dernière écrite ; « Charger plus » affiche les 50 suivantes puis les 20 dernières et disparaît. - **AC-03.2** Given une entrée `ERROR` suivie de 30 lignes de stack trace, When elle s'affiche, Then elle compte pour **une** entrée, la première ligne est visible et les 30 lignes sont repliées par défaut. - **AC-03.3** Given une entrée en cours d'écriture (sans `\n` final, ou fichier modifié il y a moins de 1 s), When le fichier est affiché, Then cette entrée n'apparaît pas ; When elle est terminée et le fichier inchangé depuis 1 s, Then elle apparaît au rafraîchissement suivant. - **AC-03.4** Given un fichier contenant des octets non UTF-8, When il est affiché, Then les entrées s'affichent avec le caractère `�` à la place des octets invalides, sans erreur. - **AC-03.5** Given un fichier de 1 Gio, When je l'ouvre, Then la première page s'affiche en < 2 s après l'indexation initiale et la mémoire du serveur reste < 200 Mio. ### US-04 — Configurer l'intervalle de rafraîchissement > En tant que développeur, je veux choisir la fréquence de lecture des logs, pour arbitrer entre réactivité et charge. - **AC-04.1** Given une première installation, When j'ouvre les réglages, Then l'intervalle vaut 5 s. - **AC-04.2** Given l'intervalle à 5 s, When je saisis 30 et j'enregistre, Then le client n'appelle plus `unread_summary` qu'une fois toutes les 30 s (± 1 s), sans rechargement de page. - **AC-04.3** When je saisis `0`, `3601`, `-5`, `abc` ou une valeur vide, Then l'enregistrement est refusé avec « L'intervalle doit être un entier entre 1 et 3600 secondes » et la valeur précédente est conservée. - **AC-04.4** Given l'intervalle à 30 s, When je redémarre le serveur, Then l'intervalle vaut toujours 30 s. ### US-05 — Être notifié des nouvelles entrées par le favicon > En tant que développeur, je veux voir dans l'onglet du navigateur s'il y a de nouveaux logs, sans avoir à regarder l'application. - **AC-05.1** Given 0 non-lu, When 3 entrées sont écrites dans un fichier suivi, Then en ≤ intervalle + 1 s le favicon porte une pastille « 3 » et le titre est `(3) Logs Reader`. - **AC-05.2** Given 2 non-lus dans `a.log` et 1 dans `b.log` (même projet ou non), Then la pastille affiche « 3 ». - **AC-05.3** Given 150 non-lus, Then la pastille affiche « 99+ » et le titre `(150) Logs Reader`. - **AC-05.4** Given des non-lus, When tout est marqué comme lu, Then le favicon redevient normal et le titre `Logs Reader` sans attendre le prochain poll. - **AC-05.5** Given le serveur arrêté, When un poll échoue, Then le favicon affiche la pastille grise « ! » ; When le serveur redémarre, Then au poll suivant le favicon reflète à nouveau le nombre de non-lus. - **AC-05.6** Given `laravel.log` vidé (`> laravel.log`) puis 2 entrées écrites, Then le fichier compte 2 non-lus. ### US-06 — Marquer comme lu > En tant que développeur, je veux que les entrées que j'ai consultées ne soient plus signalées. - **AC-06.1** Given `a.log` avec 4 non-lus, When j'ouvre `a.log`, Then son badge passe à 0 et le total diminue de 4. - **AC-06.2** Given `a.log` ouvert et l'onglet visible, When 2 entrées sont écrites, Then elles apparaissent surlignées en haut et le total reste à 0. - **AC-06.3** Given `a.log` ouvert et l'onglet en arrière-plan, When 2 entrées sont écrites, Then le total passe à 2 ; When je reviens sur l'onglet, Then il repasse à 0. - **AC-06.4** Given 2 projets avec des non-lus, When je clique « Tout marquer comme lu » sur le projet A, Then seuls les compteurs de A passent à 0. - **AC-06.5** Given deux onglets ouverts, When je marque lu dans l'onglet 1, Then l'onglet 2 reflète 0 non-lu au poll suivant. ### US-07 — Supprimer un projet > En tant que développeur, je veux retirer un projet que je ne surveille plus. - **AC-07.1** Given un projet avec 5 non-lus, When je le supprime et confirme, Then il disparaît de la liste, le total diminue de 5, et aucune ligne liée ne reste dans `log_files`, `log_entries_index`, `read_cursors`. - **AC-07.2** Given un projet supprimé, When je l'ajoute à nouveau, Then l'ajout réussit et les entrées existantes ne sont pas comptées comme non-lues (cf. AC-01.4). - **AC-07.3** When je supprime un projet, Then aucun fichier du projet sur le disque n'est modifié (mtime et contenu identiques). ### US-08 — Filtrer et rechercher > En tant que développeur, je veux isoler les erreurs ou retrouver un message précis. - **AC-08.1** Given 10 `INFO` et 3 `ERROR`, When je ne coche que `ERROR`, Then 3 entrées s'affichent. - **AC-08.2** Given une entrée contenant `SQLSTATE[23000]` dans sa stack trace, When je recherche `sqlstate`, Then elle est affichée. - **AC-08.3** Given des filtres actifs, Then les compteurs de non-lus ne sont pas affectés par les filtres. - **AC-08.4** Given `aaa.log` ne contient que des `INFO`, When je l'ouvre, Then seule la case `INFO` est active, les autres sont grisées et désactivées ; When une entrée `CRITICAL` y est écrite, Then la case `CRITICAL` devient active au rafraîchissement suivant. - **AC-08.5** Given tous les niveaux cochés, When je double-clique sur `ERROR`, Then seule la case `ERROR` est cochée et seules les entrées `ERROR` s'affichent ; When je double-clique à nouveau sur `ERROR`, Then tous les niveaux sont recochés. Un double-clic sur un niveau désactivé est sans effet. ### US-10 — Trier les fichiers > En tant que développeur, je veux trier les fichiers d'un projet par nom ou par date de modification, pour trouver vite le log actif. - **AC-10.1** Given `aaa.log` (modifié il y a 2 j), `laravel.log` (3 h), `zzz.log` (10 s), When je choisis « Nom », Then l'ordre est `aaa.log`, `laravel.log`, `zzz.log`. - **AC-10.2** Given les mêmes fichiers, When je choisis « Date », Then l'ordre est `zzz.log`, `laravel.log`, `aaa.log` et chaque ligne affiche son ancienneté. - **AC-10.3** Given le tri « Date », When je recharge la page ou redémarre le serveur, Then le tri « Date » est conservé. - **AC-10.4** Given un projet replié, When je change de tri, Then il reste replié. ### US-11 — Mettre la lecture en pause > En tant que développeur, je veux arrêter temporairement la lecture des logs, par exemple pendant une session de debug bruyante. - **AC-11.1** Given la lecture active (engrenage qui tourne), When je clique dessus, Then le bouton devient rouge, le favicon affiche la pastille rouge « pause », « · lecture arrêtée » est affiché, et aucun appel `unread_summary` n'est fait pendant 3 intervalles, même si des entrées sont écrites. - **AC-11.2** Given la lecture arrêtée, When je recharge la page, Then le bouton est toujours rouge, le favicon toujours en pause, et aucun polling ne reprend. - **AC-11.3** Given la lecture arrêtée et 1 entrée écrite entre-temps, When je clique sur le bouton rouge, Then l'engrenage réapparaît et le compteur et le favicon sont mis à jour en moins de 1 s. ### US-09 — Conserver l'état entre deux redémarrages > En tant que développeur, je veux retrouver mes projets et mes compteurs après un redémarrage. - **AC-09.1** Given 2 projets et 7 non-lus, When je redémarre le serveur, Then les 2 projets et les 7 non-lus sont retrouvés. - **AC-09.2** Given le serveur arrêté, When 3 entrées sont écrites puis le serveur redémarré, Then le total vaut 7 + 3 = 10. - **AC-09.3** Given le serveur arrêté, When `laravel.log` est roté (renommé puis recréé), Then au redémarrage la rotation est détectée et le nouveau fichier est relu depuis le début. --- ## 7. Cas d'erreur | # | Cas | Détection | Comportement attendu | Message utilisateur | |---|---|---|---|---| | E01 | Chemin vide | Validation client et serveur | Refus | « Veuillez saisir un chemin. » | | E02 | Chemin inexistant | `canonicalize` → `NotFound` | Refus, rien en base | « Le chemin `

` n'existe pas. » | | E03 | Chemin vers un fichier | `!is_dir()` | Refus | « `

` n'est pas un répertoire. » | | E04 | Pas un projet Laravel | `artisan` absent | Refus | « `

` ne semble pas être un projet Laravel (fichier `artisan` introuvable). » | | E05 | `storage/logs` absent | Absence du répertoire | Refus | « Répertoire `storage/logs` introuvable. » | | E06 | Permission refusée à l'ajout | `PermissionDenied` | Refus | « Accès refusé à `

`. » | | E07 | Projet déjà enregistré | Contrainte `UNIQUE(root_path)` après canonicalisation | Refus, projet existant mis en évidence | « Ce projet est déjà enregistré. » | | E08 | Aucun fichier `.log` | Découverte vide | Ajout accepté, liste vide | « Aucun fichier de log pour l'instant. » | | E09 | Projet supprimé/déplacé du disque après ajout | Racine introuvable au scan | Projet conservé, marqué en erreur, ses fichiers ne comptent plus ; reprise automatique si le chemin revient | « Projet introuvable sur le disque. » | | E10 | Fichier illisible (permissions changées) | `PermissionDenied` à l'ouverture | `last_error` renseigné, offsets inchangés, les autres fichiers continuent d'être scannés | Icône d'alerte sur le fichier + info-bulle | | E11 | Fichier supprimé entre deux scans | `NotFound` | `missing_since` renseigné (cf. 5.2) | « Fichier manquant » | | E12 | Fichier roté ou tronqué | Taille < `scan_offset` ou identité changée | Reset (cf. 5.4) | — | | E13 | Entrée partielle en fin de fichier | Pas de `\n` final | Non indexée, relue au scan suivant | — | | E14 | Octets non UTF-8 | Décodage | Remplacement par `�` | — | | E15 | Texte sans ligne d'en-tête valide | Regex | Entrée `UNKNOWN` (cf. 5.3) | — | | E16 | Fichier très volumineux | — | Lecture par blocs ; jamais de chargement complet | — | | E17 | Entrée gigantesque (> 1 Mio) | Taille `end - start` | Affichage tronqué | « Entrée tronquée (X Mio). » | | E18 | Intervalle invalide | Validation client et serveur | Refus, ancienne valeur conservée | cf. AC-04.3 | | E19 | `log_file_id` / `project_id` inconnu | Requête vide | Erreur 404 de la server function | « Élément introuvable, la liste a été rafraîchie. » | | E20 | Base SQLite inaccessible au démarrage | Échec de connexion/migration | Arrêt du processus, code de sortie ≠ 0 | Log console explicite avec le chemin | | E21 | Base verrouillée en cours d'exécution | `SQLITE_BUSY` | `busy_timeout` de 5 s, puis erreur renvoyée au client ; aucun état partiel (transaction) | « Base de données occupée, nouvel essai au prochain rafraîchissement. » | | E22 | Base corrompue | `PRAGMA quick_check` au démarrage | Arrêt du processus | Log console explicite | | E23 | Port déjà utilisé | `bind` échoue | Arrêt, code de sortie ≠ 0 | « L'adresse `` est déjà utilisée. » | | E24 | Serveur injoignable côté client | Échec réseau du poll | Favicon gris « ! », bandeau discret ; on continue de poller au même intervalle | « Serveur injoignable. » | | E25 | Scans simultanés (plusieurs onglets) | Mutex par projet | Un seul scan à la fois, résultats partagés ; pas de double indexation | — | --- ## 8. Invariants Ces propriétés doivent être vraies après toute opération et peuvent être vérifiées par tests (y compris tests de propriétés). - **INV-01 Lecture seule** — L'application n'ouvre jamais un fichier de projet en écriture ; elle ne crée, ne renomme, ne supprime ni ne modifie aucun fichier hors de sa propre base. - **INV-02 Ordre des offsets** — Pour tout fichier présent : `0 ≤ read_offset ≤ scan_offset ≤ size`. - **INV-03 Index cohérent** — Les entrées indexées d'un fichier sont disjointes, contiguës et triées : pour deux entrées consécutives `e1, e2`, `e1.end_offset = e2.start_offset` ; la dernière se termine à `scan_offset` ; `entries_count` = nombre de lignes d'index. - **INV-04 Aucune entrée partielle ni doublon** — Chaque entrée complète du fichier est indexée exactement une fois ; aucune entrée incomplète n'est indexée. - **INV-05 Calcul des non-lus** — `unread(f)` = nombre d'entrées indexées de `f` avec `start_offset ≥ read_offset` ; `unread(f) ≥ 0` ; `unread(f) = 0` si `f` est manquant ; `total = Σ unread(f)` sur les fichiers présents des projets accessibles. - **INV-06 Le curseur n'avance que par l'utilisateur** — Un scan ne fait jamais avancer `read_offset` ; seuls `mark_read`, `mark_all_read` et l'ajout initial d'un projet (5.1) le font avancer. Seule une rotation (5.4) le fait reculer (à 0). - **INV-07 Monotonie hors rotation** — En l'absence de rotation, `scan_offset` et `read_offset` sont croissants dans le temps. - **INV-08 Confinement** — Tout fichier suivi a un chemin canonique sous `/storage/logs`. - **INV-09 Unicité** — Un chemin canonique correspond à au plus un projet ; un couple (projet, chemin relatif) à au plus un fichier. - **INV-10 Cascade** — Après suppression d'un projet, aucune ligne de `log_files`, `log_entries_index` ou `read_cursors` ne le référence. - **INV-11 Bornes de l'intervalle** — `refresh_interval_seconds` stocké est toujours un entier dans `[1, 3600]`. - **INV-12 Persistance** — Sans changement des fichiers sur le disque, un redémarrage ne change aucun compteur de non-lus. - **INV-13 Idempotence du scan** — Deux scans successifs sans modification des fichiers produisent le même état en base. - **INV-14 Atomicité** — Le scan d'un fichier (mise à jour de l'index + `scan_offset`) est fait dans une seule transaction : un crash au milieu laisse l'état précédent. - **INV-15 Favicon fidèle** — Le nombre affiché par le favicon est égal au `total` de la dernière réponse `unread_summary` réussie (ou au résultat de la dernière action `mark_*`), borné à l'affichage à `99+`. --- ## 9. Exigences non fonctionnelles | Domaine | Exigence | |---|---| | Sécurité | Écoute par défaut sur `127.0.0.1` uniquement. Aucun contenu de log n'est injecté en HTML brut (échappement systématique par Leptos). | | Performance | `unread_summary` < 100 ms avec 10 projets / 50 fichiers sans nouvelle donnée. Indexation initiale d'un fichier de 1 Gio < 30 s, mémoire < 200 Mio. | | Robustesse | L'erreur d'un fichier ou d'un projet n'empêche jamais le scan des autres. | | Portabilité | Linux et macOS en priorité ; Windows : identité de fichier via file index, chemins non sensibles à la casse. | | Accessibilité | Le nombre de non-lus est aussi exposé en texte (titre + badges) et pas seulement par la couleur. | --- ## 10. Stratégie de test - **Unitaires** : parser (en-têtes valides/invalides, multi-lignes, entrée partielle, UTF-8 invalide, fuseaux horaires, microsecondes), détection de rotation, validation de chemin et d'intervalle, calcul de `mark_read` (non-régression du curseur). - **Propriétés** (`proptest`) : écrire des séquences aléatoires d'entrées en morceaux arbitraires, scanner entre chaque morceau, vérifier INV-02 à INV-05 et INV-13. - **Intégration** : serveur axum sur port aléatoire + SQLite temporaire + projet Laravel factice dans un `tempdir` ; dérouler les AC des US-01 à US-09 via les server functions. - **E2E** (Playwright) : AC-04.2, AC-05.1, AC-05.3, AC-05.4, AC-05.5, AC-06.2, AC-06.3 — lecture de `document.title` et de l'attribut `href` du ``. --- ## 11. Questions ouvertes 1. Faut-il une vue agrégée « toutes les nouvelles entrées, tous projets confondus » ? 2. Faut-il filtrer les non-lus par niveau (ex. ne notifier que `ERROR` et au-dessus) ? 3. Faut-il ajouter les notifications natives du navigateur (Notification API) en plus du favicon ? 4. Faut-il purger l'index des fichiers manquants depuis plus de N jours ? 5. Faut-il supporter le format JSON de Monolog (`JsonFormatter`) ?