Files
logs_reader/.spec/specification.md
T

399 lines
31 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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** | `<racine>/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 │
<projet>/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/<nom>`.
| Fonction | Entrée | Sortie |
|---|---|---|
| `add_project` | `path: String`, `name: Option<String>` | `Project` |
| `remove_project` | `project_id` | `()` |
| `read_entries` | `file_id`, `limit` (≤ 2000), `levels: Vec<String>`, `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 `<p>` n'existe pas. » |
| E03 | Chemin vers un fichier | `!is_dir()` | Refus | « `<p>` n'est pas un répertoire. » |
| E04 | Pas un projet Laravel | `artisan` absent | Refus | « `<p>` 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é à `<p>`. » |
| 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 `<addr>` 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 `<root_path>/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 `<link rel="icon">`.
---
## 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`) ?