- Chaque projet choisit sa fréquence de relecture (jamais, 5 s … 1 h) ; le serveur ne relit que les projets dus, le fichier affiché est toujours à jour. Le réglage global et sa page disparaissent (migration de l'ancien intervalle vers chaque projet). - Le nom du projet est obligatoire, proposé d'après le chemin. - Les fichiers non modifiés depuis N jours peuvent être masqués ; ils ne comptent plus dans les non-lus et réapparaissent dès qu'ils changent. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
45 KiB
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 :
- enregistrer un ou plusieurs projets (Laravel, Symfony, Node… : n'importe quel dossier) par leur chemin sur le disque et leurs dossiers de logs ;
- voir tous les fichiers de log de chaque projet et en lire les entrées, y compris les logs Apache du vhost du projet ;
- être prévenu, via le favicon et le titre de l'onglet, de toute nouvelle entrée apparue depuis sa dernière consultation ;
- choisir, pour chaque projet, la fréquence de relecture de ses logs.
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…) |
| Formats Monolog (Laravel, Symfony), erreurs Apache, accès Apache/nginx, et tout format texte (une ligne par entrée), détectés par fichier | Découpage des entrées JSON multi-lignes, syslog, stderr |
Logs Apache (ErrorLog, CustomLog) déclarés par le vhost d'un projet |
Fichiers rotés (.1, .gz), logs envoyés à un programme (|…) ou à syslog |
| 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 dossier enregistré, identifié par son chemin racine canonique (absolu, symlinks résolus, sans / final). |
| Dossier de logs | Sous-dossier du projet déclaré par l'utilisateur (storage/logs, var/log, logs…), relatif à la racine. |
| Format | Manière de découper un fichier en entrées : monolog, apache_error, access ou lines, détectée sur ses premières lignes (cf. 5.3). |
| Fichier de log | Tout fichier *.log situé (récursivement) dans un dossier de logs, ou déclaré par le vhost (cf. 5.8). |
| Entrée | Une écriture de log. Elle commence par une ligne d'en-tête (selon le format) et contient toutes les lignes suivantes jusqu'à la prochaine ligne d'en-tête (stack trace comprise). |
| Ligne d'en-tête Monolog | 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 entre deux relectures automatiques des logs d'un projet, choisi par projet : jamais, 5 s, 15 s, 30 s, 1 min, 5 min, 15 min, 30 min ou 1 h. |
| Vhost | Fichier de configuration Apache rattaché à un projet (au plus un), identifié par son chemin canonique. |
| Log Apache | Fichier déclaré par une directive ErrorLog (log d'erreurs) ou CustomLog/TransferLog (log d'accès) du vhost. |
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>/<dossiers>/*.log data.sqlite
- Build :
cargo-leptos(featuresssr/hydrate), Tailwind CSS intégré via la configtailwind-input-filede 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) pour les projets dont l'intervalle est écoulé (cf. 5.5), et parread_entriespour le projet du fichier affiché. 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éfautsqlite://./logs_reader.sqlite?mode=rwcLOGS_READER_ADDR— défaut127.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, name, refresh_seconds, hide_after_days (vide = aucun), log_dirs (un par ligne), vhost (vides = défaut / aucun) |
() |
update_project |
project_id, path, name, refresh_seconds, hide_after_days, log_dirs, vhost (vhost vide = retirer) |
() |
suggest_log_dirs |
path |
Vec<String> (cf. 5.1) |
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 |
— | Settings { file_sort, paused } |
set_paused |
paused: bool |
() |
set_file_sort |
sort: "name" | "modified" |
() |
4. Modèle de données
CREATE TABLE projects (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
root_path TEXT NOT NULL UNIQUE, -- chemin canonique
last_error TEXT, -- projet introuvable sur le disque
vhost_path TEXT, -- vhost Apache, chemin canonique
vhost_error TEXT, -- vhost illisible
log_dirs TEXT NOT NULL DEFAULT 'storage/logs', -- dossiers de logs, un par ligne
refresh_seconds INTEGER NOT NULL DEFAULT 5, -- 0 (jamais), 5, 15, 30, 60, 300, 900, 1800, 3600
hide_after_days INTEGER, -- masque les fichiers plus anciens ; NULL = aucun
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 à la racine ; absolu pour un log Apache
kind TEXT NOT NULL, -- origine : 'project' | 'apache_error' | 'apache_access'
format TEXT, -- 'monolog' | 'apache_error' | 'access' | 'lines' ; NULL = pas encore détecté
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 : ('file_sort', 'name' | 'modified'), ('paused', '0' | '1')
- 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
- Le chemin saisi est nettoyé (trim) ;
~en tête est remplacé par$HOME. - Il est canonicalisé (
std::fs::canonicalize). - Il est valide si c'est un répertoire (aucun fichier particulier n'est exigé).
- Le nom est obligatoire (« Veuillez saisir un nom. ») ; la fenêtre propose le dernier segment du chemin tant que l'utilisateur ne l'a pas saisi lui-même.
- Dossiers de logs : un par ligne (ou séparés par des virgules), relatifs à la racine ; espaces,
./en tête et/final retirés, doublons ignorés. Chacun doit être un sous-dossier (ni., ni.., ni chemin absolu) existant et lisible. - Proposition : quand le chemin est saisi (et tant que l'utilisateur n'a pas modifié le champ), la fenêtre propose les dossiers existants parmi :
storage/logssiartisanexiste (Laravel),var/logsibin/consoleexiste (Symfony), puisstorage/logs,var/log,var/logs,logs,log. - Un vhost Apache peut être indiqué (optionnel, cf. 5.8). Il faut au moins un dossier de logs ou un vhost. Si un champ est invalide, rien n'est enregistré.
- 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.1 bis Modification d'un projet
- Le nom, le chemin, les dossiers de logs et le vhost se modifient avec les mêmes règles qu'à l'ajout (nom obligatoire ; vhost vide → aucun vhost).
- Un nouveau chemin déjà enregistré par un autre projet est refusé (« Ce projet est déjà enregistré. »).
- Changer de chemin supprime les fichiers suivis de l'ancien chemin ; ceux du nouveau sont indexés avec leur curseur en fin de fichier. Retirer un dossier de logs supprime ses fichiers. Les fichiers qui deviennent suivis (nouveau chemin, nouveau dossier, nouveau vhost) ne comptent pas leur historique en non-lu ; les autres gardent leurs curseurs.
- La modification et le scan qui suit se font sous le verrou du scanner.
5.2 Découverte des fichiers
- Parcours récursif de chaque dossier de logs, à chaque scan ; rien d'autre du projet n'est parcouru (
vendor/,node_modules/… sont ignorés sauf s'ils sont déclarés). Deux dossiers imbriqués ne suivent un fichier qu'une fois. - 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 le même dossier de logs.
- Si la racine ou un dossier de logs disparaît, le projet est marqué en erreur et ses fichiers restent en l'état jusqu'au retour du dossier (E09).
- Un fichier apparu après l'ajout du projet (ex. nouveau
laravel-2026-10-22.logen mode daily) est créé avecread_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_offsetpar 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. - Détection du format : à la première lecture d'un fichier du projet (et après une rotation), sur ses 50 premières lignes complètes (64 Kio au plus) :
monologsi l'une est une ligne d'en-tête Monolog, sinonapache_errorsi l'une est un en-tête d'erreur Apache, sinonaccesssi l'une est une ligne de log d'accès (common/combined), sinonlines. Un fichier sans ligne complète non vide n'est pas indexé ; la détection est retentée au scan suivant. Les fichiers du vhost ont le format de leur directive. - Une ligne d'en-tête ouvre une nouvelle entrée. Toute autre ligne est rattachée à l'entrée courante.
- Format
lines: toute ligne non indentée ouvre une entrée ; une ligne qui commence par un espace ou une tabulation (stack trace Python, Java, Node…) est rattachée à la précédente. Date : la premièreYYYY-MM-DD[ T]HH:MM:SSdans les 40 premiers caractères, sinon la date de modification. Niveau : le premier motEMERGENCY,ALERT,CRITICAL/CRIT/FATAL,ERROR/ERR,WARNING/WARN,NOTICE,INFO,DEBUG/TRACEen majuscules, oulevel=…/"level":"…", sinonUNKNOWN. - 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
\net le fichier n'a pas été modifié depuis au moins 1 s (sinon une stack trace à moitié écrite serait coupée en deux). Sinonscan_offsetreste à 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_summaryau chargement de la page puis toutes les 5 s (le plus court des intervalles). - Le serveur ne relit que les projets dont l'intervalle est écoulé (marge de 1 s, pour qu'un poll un peu en avance ne fasse pas attendre un cycle de plus) ; les autres gardent leurs compteurs. Un projet réglé sur « jamais » n'est jamais relu ainsi. L'heure de la dernière relecture de chaque projet est tenue en mémoire : au démarrage du serveur, tous les projets (sauf « jamais ») sont relus au premier poll.
- Fichier affiché :
read_entriesrelit d'abord le projet du fichier, quel que soit son intervalle. Le fichier ouvert est donc à jour à chaque poll, y compris pour un projet « jamais ». - Un nouvel intervalle s'applique dès l'enregistrement du projet, sans recharger la page.
- 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 ReaderquandN ≥ 1,Logs Readersinon. - 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_readne 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 à la racine, ou au dossier de logs s'il n'y en a qu'un ; 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). - Fenêtre de projet (modale,
<dialog>natif) : ouverte par « + Ajouter un projet » ou par le bouton ✎ d'un projet (pré-remplie). Champs : chemin du projet, nom (obligatoire, proposé d'après le chemin), dossiers de logs (zone de texte, un par ligne, proposés d'après le chemin, cf. 5.1), vhost Apache (optionnel). En modification, un bouton « Retirer ce projet » en bas à gauche le supprime après confirmation (c'est le seul moyen de retirer un projet). Message d'erreur dans la fenêtre ; elle se ferme quand l'enregistrement ou le retrait réussit, par « Annuler », Échap ou un clic sur le fond. - 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. - Logs Apache : les logs Apache sont listés sous le titre « Apache », après les logs du projet, par nom de fichier suivi de leur rôle (« erreurs » ou « accès »), le chemin complet en info-bulle.
- Fichiers anciens : champ numérique « Masquer les fichiers non modifiés depuis (jours) » dans la fenêtre de projet, vide par défaut (aucun fichier masqué), sinon un entier ≥ 1 (« Le nombre de jours doit être un entier positif. »). Un fichier est masqué si sa dernière modification remonte à plus de N × 24 h ; un fichier sans date reste affiché. Les fichiers masqués ne sont ni listés ni comptés dans les non-lus, mais restent scannés : une nouvelle entrée change leur date et les fait réapparaître. Sous le projet, « N fichiers anciens masqués » les signale ; le message « Aucun fichier de log pour l'instant. » n'apparaît pas si des fichiers sont masqués.
- Rafraîchissement : liste déroulante dans la fenêtre de projet (« Jamais », « 5 s » … « 1 h », 5 s par défaut). Un projet réglé sur « jamais » porte un ⏸ dans la liste ; l'info-bulle de son nom rappelle l'intervalle. Il n'y a plus de page de réglages.
5.8 Logs Apache du vhost
- Le chemin saisi est nettoyé,
~remplacé par$HOME, puis canonicalisé. Il est valide si c'est un fichier lisible qui déclare au moins un log. - Le vhost est relu à chaque scan : un log ajouté au vhost est suivi, un log retiré du vhost n'est plus suivi (ses lignes sont supprimées). Si le vhost devient illisible,
vhost_errorest renseigné et ses fichiers connus restent en l'état. - Directives lues (insensibles à la casse, lignes commentées ignorées) :
ErrorLog→ log d'erreurs ;CustomLog,TransferLog→ log d'accès. Seul le premier argument compte (entre guillemets ou non). Ignorés :|programme,syslog…. Un même fichier déclaré deux fois (vhosts:80et:443) n'est suivi qu'une fois. - Les variables
${NOM}sont remplacées par lesexport NOM=…de/etc/apache2/envvars(une variable inconnue vaut la chaîne vide) ; un chemin relatif part de/etc/apache2. - À la configuration du vhost, le curseur des fichiers nouvellement suivis est placé à la fin : l'historique n'est pas non-lu. La mise à jour du vhost et ce premier scan se font sous le verrou du scanner.
- Log d'erreurs : une ligne d'en-tête correspond à
[Wed Oct 21 11:29:09.705795 2026] [module:niveau] [pid …] message(module facultatif). Les lignes suivantes sans en-tête sont rattachées à l'entrée. Niveaux :emerg→EMERGENCY,alert→ALERT,crit→CRITICAL,error→ERROR,warn→WARNING,notice→NOTICE,info→INFO,debugettrace1…trace8→DEBUG. Le module s'affiche à la place de l'environnement. - Log d'accès : chaque ligne est une entrée, complète dès son
\n(sans attendre 1 s). Formatscommon,combined,vhost_combined. Niveau selon le code HTTP : 5xx →ERROR, 4xx →WARNING, 1xx–3xx →INFO, autre ou ligne non reconnue →UNKNOWN. Affichage : client, puis « code requête », la ligne complète en détail repliable. - Non-lus : les entrées du log d'erreurs comptent comme celles des logs du projet. Celles d'un log d'accès (du vhost ou d'un dossier du projet, format
access) ne comptent jamais (une ligne par requête) ; à l'ouverture du fichier, les lignes arrivées depuis la dernière consultation sont tout de même surlignées. - Les dates Apache sont converties au format
YYYY-MM-DD HH:MM:SS(heure locale du log, sans fuseau).
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 projet rafraîchi toutes les 5 s sauf mention contraire.
US-01 — Ajouter un projet
En tant que développeur, je veux ajouter un projet en saisissant son chemin et ses dossiers de logs, afin de surveiller ses logs.
- AC-01.1 Given un répertoire
/tmp/appavecartisanetstorage/logs/laravel.log, When je saisis/tmp/app, Then le champ des dossiers proposestorage/logs; When j'ajoute le projet, Thenappapparaît dans la liste avec le fichierlaravel.log. - AC-01.7 Given un projet Node
/tmp/apiaveclogs/app.logetnode_modules/x/debug.log, When je l'ajoute avec le dossierlogs, Then seulapp.logest listé ; ses lignes… ERROR …sont des entréesERRORet ses lignes indentées sont rattachées à l'entrée précédente. - AC-01.8 When j'ajoute un projet sans dossier de logs ni vhost, Then l'ajout est refusé avec « Indiquez au moins un dossier de logs ou un vhost. » ; When je saisis le dossier
../x, Then il est refusé avec « « ../x » doit être un sous-dossier du projet. ». - 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/appet/tmp/appdéjà enregistré, When j'ajoute/tmp/link, Then l'ajout est refusé (même chemin canonique). - AC-01.4 Given
laravel.logcontient 10 entrées, When j'ajoute le projet, Then le compteur de non-lus du projet vaut 0. - AC-01.5 Given le chemin
/tmp/appsaisi, Then le nom proposé est « app » ; When je le remplace par « Mon API » et j'ajoute le projet, Then il s'affiche sous le nom « Mon API ». When le nom est vide, Then l'ajout est refusé avec « Veuillez saisir un nom. ». - AC-01.6 Given
~/code/appvalide, 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/logscontientlaravel.log,laravel-2026-10-20.log,jobs/worker.log,.gitignore,old.log.gz, When le projet est affiché, Then exactementlaravel.log,laravel-2026-10-20.logetjobs/worker.logsont listés. - AC-02.2 Given un projet enregistré, When un fichier
laravel-2026-10-22.logest 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 destorage/logs), When le projet est scanné, Thenext.logn'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
ERRORsuivie 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
\nfinal, 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-14 — Masquer les fichiers anciens
En tant que développeur, je veux ne pas voir les vieux logs journaliers d'un projet, pour trouver vite ceux qui vivent encore.
- AC-14.1 Given
laravel-2026-09-01.logmodifié il y a 50 j etlaravel.logmodifié il y a 1 h, When je règle « 30 » jours, Then seullaravel.logest listé, suivi de « 1 fichier ancien masqué ». - AC-14.2 Given le réglage à 30 j et 2 non-lus dans un fichier masqué, Then le total ne les compte pas ; When une entrée y est écrite, Then le fichier réapparaît avec 3 non-lus.
- AC-14.3 When je vide le champ, Then tous les fichiers sont à nouveau listés. When je saisis
0, Then l'enregistrement est refusé avec « Le nombre de jours doit être un entier positif. ».
US-04 — Choisir le rafraîchissement d'un projet
En tant que développeur, je veux régler la fréquence de relecture de chaque projet, pour suivre de près le projet sur lequel je travaille sans relire en permanence les autres.
- AC-04.1 Given un nouveau projet, When j'ouvre la fenêtre d'ajout, Then le rafraîchissement vaut « 5 s » et la liste propose Jamais, 5 s, 15 s, 30 s, 1 min, 5 min, 15 min, 30 min, 1 h.
- AC-04.2 Given un projet A à 5 s et un projet B à 1 min, When une entrée est écrite dans chacun, Then A la signale en ≤ 6 s et B en ≤ 61 s.
- AC-04.3 Given un projet réglé sur « Jamais », When des entrées sont écrites, Then ses compteurs ne changent pas et un ⏸ est affiché à côté de son nom ; When j'ouvre un de ses fichiers, Then les nouvelles entrées s'affichent.
- AC-04.4 When une valeur hors de la liste est envoyée à
add_projectouupdate_project, Then l'enregistrement est refusé avec « Intervalle de rafraîchissement invalide. ». - AC-04.5 Given un projet à 15 min, When je redémarre le serveur, Then il est toujours à 15 min. Les projets existants avant cette version prennent l'ancien intervalle global, arrondi au choix supérieur.
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 ≤ 6 s le favicon porte une pastille « 3 » et le titre est
(3) Logs Reader. - AC-05.2 Given 2 non-lus dans
a.loget 1 dansb.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 Readersans 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.logvidé (> 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.logavec 4 non-lus, When j'ouvrea.log, Then son badge passe à 0 et le total diminue de 4. - AC-06.2 Given
a.logouvert 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.logouvert 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 j'ouvre sa fenêtre (✎), clique « Retirer ce projet » 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
INFOet 3ERROR, When je ne coche queERROR, Then 3 entrées s'affichent. - AC-08.2 Given une entrée contenant
SQLSTATE[23000]dans sa stack trace, When je recherchesqlstate, 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.logne contient que desINFO, When je l'ouvre, Then seule la caseINFOest active, les autres sont grisées et désactivées ; When une entréeCRITICALy est écrite, Then la caseCRITICALdevient active au rafraîchissement suivant. - AC-08.5 Given tous les niveaux cochés, When je double-clique sur
ERROR, Then seule la caseERRORest cochée et seules les entréesERRORs'affichent ; When je double-clique à nouveau surERROR, 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 estaaa.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.loget 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_summaryn'est fait pendant 15 s, 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-12 — Consulter les logs Apache du vhost
En tant que développeur, je veux voir les logs Apache du vhost de mon projet à côté de ses autres logs, pour diagnostiquer une erreur 500 sans ouvrir un terminal.
- AC-12.1 Given un vhost déclarant
ErrorLog ${APACHE_LOG_DIR}/error.app.logetCustomLog ${APACHE_LOG_DIR}/access.app.log combined, When je l'enregistre sur le projet, Then les deux fichiers apparaissent sous « Apache » avec les rôles « erreurs » et « accès », et le total de non-lus ne change pas. - AC-12.2 Given le vhost enregistré, When une ligne
[php:error]est écrite dans le log d'erreurs, Then le total augmente de 1 ; When 10 requêtes sont faites, Then le total ne change pas. - AC-12.3 Given le log d'accès ouvert, Then chaque requête est une entrée, une 404 en
WARNINGet une 500 enERROR, et le filtre par niveau s'applique. - AC-12.4 When je saisis
/etc/hosts, Then l'enregistrement est refusé avec « Aucune directive ErrorLog ni CustomLog dans « /etc/hosts ». ». - AC-12.5 Given le vhost enregistré, When je vide le champ vhost du projet et j'enregistre, Then les fichiers Apache disparaissent de la liste et leurs non-lus ne comptent plus.
US-13 — Modifier un projet
En tant que développeur, je veux corriger le nom, le chemin ou le vhost d'un projet sans le supprimer, pour garder ses compteurs.
- AC-13.1 Given un projet « app », When je clique ✎, Then la fenêtre s'ouvre avec son chemin, son nom et son vhost.
- AC-13.2 Given 3 non-lus dans
laravel.log, When je renomme le projet en « API », Then il s'affiche « API » et garde ses 3 non-lus. - AC-13.3 Given deux projets A et B, When je donne à B le chemin de A, Then l'enregistrement est refusé avec « Ce projet est déjà enregistré. » et la fenêtre reste ouverte.
- AC-13.4 Given un projet, When je change son chemin vers un autre projet dont le dossier de logs contient 10 entrées, Then ses fichiers sont ceux du nouveau chemin et son compteur de non-lus vaut 0.
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.logest 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 | Dossier de logs hors du projet | ., .. ou chemin absolu |
Refus | « « <d> » doit être un sous-dossier du projet. » |
| E05 | Dossier de logs absent ou illisible | Absence du répertoire, PermissionDenied |
Refus | « Dossier « <d> » introuvable dans le projet. », « Accès refusé à « <d> ». » |
| E05 bis | Ni dossier de logs ni vhost | Champs vides | Refus | « Indiquez au moins un dossier de logs ou un vhost. » |
| 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 serveur (choix de la liste) | Refus, ancienne valeur conservée | cf. AC-04.4 |
| 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 toutes les 5 s | « Serveur injoignable. » |
| E25 | Scans simultanés (plusieurs onglets) | Mutex par projet | Un seul scan à la fois, résultats partagés ; pas de double indexation | — |
| E26 | Vhost inexistant, illisible ou sans directive de log | Validation serveur | Refus, vhost précédent conservé | « Le fichier « p » n'existe pas. », « Accès refusé à « p ». », « Aucune directive ErrorLog ni CustomLog dans « p ». » |
| E27 | Vhost supprimé ou illisible après configuration | Lecture au scan | vhost_error renseigné, fichiers Apache connus conservés en l'état |
Message sous le titre « Apache » |
| E28 | Log Apache illisible (droits root:adm 640) |
PermissionDenied |
Comme E10 ; l'utilisateur qui lance le serveur doit être dans le groupe adm |
Icône d'alerte sur le fichier |
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 defavecstart_offset ≥ read_offset;unread(f) ≥ 0;unread(f) = 0sifest manquant, masqué (trop ancien) ou est un log d'accès ;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; seulsmark_read,mark_all_readet 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_offsetetread_offsetsont croissants dans le temps. - INV-08 Confinement — Tout fichier du projet suivi a un chemin canonique sous l'un de ses dossiers de logs ; tout log Apache suivi est déclaré par le vhost du projet.
- 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_indexouread_cursorsne le référence. - INV-11 Intervalle valide —
refresh_secondsd'un projet est toujours l'un de 0, 5, 15, 30, 60, 300, 900, 1800, 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
totalde la dernière réponseunread_summaryréussie (ou au résultat de la dernière actionmark_*), 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 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.titleet de l'attributhrefdu<link rel="icon">.
11. Questions ouvertes
- Faut-il une vue agrégée « toutes les nouvelles entrées, tous projets confondus » ?
- Faut-il filtrer les non-lus par niveau (ex. ne notifier que
ERRORet au-dessus) ? - Faut-il ajouter les notifications natives du navigateur (Notification API) en plus du favicon ?
- Faut-il purger l'index des fichiers manquants depuis plus de N jours ?
- Faut-il supporter le format JSON de Monolog (
JsonFormatter) ?