v0.1.2-pre.004
This commit is contained in:
301
deltas/0.1.2/pre.004.md
Normal file
301
deltas/0.1.2/pre.004.md
Normal file
@@ -0,0 +1,301 @@
|
||||
<!-- file: deltas/0.1.2/pre.004.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.1.2-pre.004
|
||||
|
||||
## Base requise
|
||||
|
||||
Livraison précédente validée :
|
||||
|
||||
```text
|
||||
0.1.2-pre.003-fix.001
|
||||
```
|
||||
|
||||
La base de développement validée porte :
|
||||
|
||||
```text
|
||||
workspace.package.version = "0.1.2-pre.3.fix.1"
|
||||
Cargo.toml header version = 30
|
||||
```
|
||||
|
||||
Les validations remontées avant l'ouverture de cette tranche sont propres :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
## Objectif
|
||||
|
||||
Compléter le runtime Logging avec les sorties réellement retenues pour `0.1.2` :
|
||||
|
||||
- ajouter `tracing-appender` ;
|
||||
- rendre console et fichier non bloquants pour le caller ;
|
||||
- posséder les `WorkerGuard` jusqu'au reload/shutdown approprié ;
|
||||
- exposer les dropped-line counters ;
|
||||
- activer le fichier `Never/Hourly/Daily` avec construction fallible ;
|
||||
- supprimer les séquences ANSI avant persistence ;
|
||||
- conserver le takeover et le hot reload transactionnel établis par `pre.003-fix.001`.
|
||||
|
||||
## Version Cargo
|
||||
|
||||
`workspace.package.version` passe de :
|
||||
|
||||
```text
|
||||
0.1.2-pre.3.fix.1
|
||||
```
|
||||
|
||||
à :
|
||||
|
||||
```text
|
||||
0.1.2-pre.4
|
||||
```
|
||||
|
||||
L'identifiant de livraison est :
|
||||
|
||||
```text
|
||||
0.1.2-pre.004
|
||||
```
|
||||
|
||||
Le header du `Cargo.toml` racine passe de version 30 à 31.
|
||||
|
||||
## Dépendance `tracing-appender`
|
||||
|
||||
L'audit du 2026-08-14 confirme `tracing-appender 0.2.5`, publié le 2026-04-17, dans la génération `^0.2`.
|
||||
|
||||
La dépendance est centralisée sous `[workspace.dependencies]` :
|
||||
|
||||
```toml
|
||||
tracing-appender = { version = "^0.2", default-features = false }
|
||||
```
|
||||
|
||||
`ksp-logging-lib` la consomme avec :
|
||||
|
||||
```toml
|
||||
tracing-appender.workspace = true
|
||||
```
|
||||
|
||||
Aucune feature optionnelle n'est activée. Le backend expose `NonBlockingBuilder`, `WorkerGuard`, `ErrorCounter` et `RollingFileAppender` sans feature supplémentaire.
|
||||
|
||||
## Console non bloquante
|
||||
|
||||
La console n'utilise plus directement `stdout`/`stderr` dans le formatter.
|
||||
|
||||
Chaque sink console construit :
|
||||
|
||||
```text
|
||||
Stdout | Stderr
|
||||
-> NonBlockingBuilder(lossy = true)
|
||||
-> fmt layer
|
||||
+ WorkerGuard
|
||||
+ ErrorCounter
|
||||
```
|
||||
|
||||
Le mode lossy est explicite : lorsque la queue est saturée, un log peut être abandonné au lieu de bloquer le thread appelant.
|
||||
|
||||
Le thread worker console est nommé :
|
||||
|
||||
```text
|
||||
ksp-logging-console
|
||||
```
|
||||
|
||||
## Fichier et rotation
|
||||
|
||||
`FileSettings` est maintenant réellement consommé par le runtime.
|
||||
|
||||
Le mapping est :
|
||||
|
||||
```text
|
||||
FileRotation::Never -> Rotation::NEVER
|
||||
FileRotation::Hourly -> Rotation::HOURLY
|
||||
FileRotation::Daily -> Rotation::DAILY
|
||||
```
|
||||
|
||||
Le runtime utilise uniquement :
|
||||
|
||||
```text
|
||||
RollingFileAppender::builder()
|
||||
.rotation(...)
|
||||
.filename_prefix(...)
|
||||
.build(directory)
|
||||
```
|
||||
|
||||
La forme builder retourne un `Result`; aucune API de construction qui panique n'est utilisée par KSP.
|
||||
|
||||
Un échec retourne :
|
||||
|
||||
```text
|
||||
logging.file_output_initialization_failed
|
||||
```
|
||||
|
||||
avec le directory, le file-name prefix et l'erreur `InitError` externe conservés dans le contrat Core.
|
||||
|
||||
## Stripping ANSI
|
||||
|
||||
Le fichier est composé comme suit :
|
||||
|
||||
```text
|
||||
fmt layer
|
||||
-> NonBlocking queue
|
||||
-> StripAnsiWriter
|
||||
-> RollingFileAppender
|
||||
```
|
||||
|
||||
Le stripping est donc effectué par le thread logging et non par le caller.
|
||||
|
||||
`StripAnsiWriter` conserve un état entre les appels `Write` afin de retirer correctement une séquence terminal coupée entre plusieurs buffers. La première surface couvre :
|
||||
|
||||
- CSI (`ESC [` ... final byte) ;
|
||||
- OSC terminé par BEL ou ST ;
|
||||
- autres chaînes terminal ESC de type DCS/SOS/PM/APC terminées par ST.
|
||||
|
||||
Ce mécanisme est générique et n'introduit aucune dépendance Tauri.
|
||||
|
||||
## Formatter humain
|
||||
|
||||
Console et fichier partagent le formatter humain KSP avec :
|
||||
|
||||
- timestamp standard `tracing-subscriber` ;
|
||||
- niveau ;
|
||||
- target ;
|
||||
- champs/message ;
|
||||
- source file ;
|
||||
- line number ;
|
||||
- ANSI du formatter désactivé ;
|
||||
- lifecycle de spans selon `SpanEvents`.
|
||||
|
||||
La ponctuation exacte du formatter reste hors contrat public.
|
||||
|
||||
## Ownership et reload
|
||||
|
||||
`LoggingGuard` possède désormais les outputs actifs :
|
||||
|
||||
```text
|
||||
LoggingGuard
|
||||
├── reload handle
|
||||
├── current LoggingSettings
|
||||
├── active console WorkerGuard/ErrorCounter
|
||||
├── active file WorkerGuard/ErrorCounter
|
||||
└── cumulative retired dropped-line counters
|
||||
```
|
||||
|
||||
`reinitialize()` :
|
||||
|
||||
1. valide les nouveaux settings ;
|
||||
2. construit entièrement le nouveau file appender et tous les nouveaux non-blocking writers/guards ;
|
||||
3. construit les nouveaux layers ;
|
||||
4. remplace le `Vec` reloadable ;
|
||||
5. mémorise les dropped lines des anciens sinks ;
|
||||
6. remplace les outputs actifs ;
|
||||
7. détruit les anciens `WorkerGuard`, provoquant leur flush borné par le backend.
|
||||
|
||||
Une erreur avant le swap détruit uniquement les nouveaux outputs préparés et laisse l'ancienne configuration active.
|
||||
|
||||
## Dropped lines
|
||||
|
||||
Nouvelle surface publique :
|
||||
|
||||
```text
|
||||
DroppedLines
|
||||
LoggingGuard::dropped_lines() -> DroppedLines
|
||||
```
|
||||
|
||||
`DroppedLines` expose :
|
||||
|
||||
```text
|
||||
console()
|
||||
file()
|
||||
total()
|
||||
```
|
||||
|
||||
Les valeurs sont cumulées pour toute la durée de vie du `LoggingGuard`, y compris après plusieurs hot reloads. Les `ErrorCounter` de `tracing-appender` ne sont pas exposés directement aux consumers.
|
||||
|
||||
## Tests
|
||||
|
||||
### Unitaires
|
||||
|
||||
- mapping `Never/Hourly/Daily` ;
|
||||
- runtime sans sink ;
|
||||
- console préparée avec filter séparé, non-blocking output et guard ;
|
||||
- addition saturante des dropped-line counters ;
|
||||
- stripping CSI ;
|
||||
- stripping d'une CSI coupée entre deux writes ;
|
||||
- stripping OSC terminé par BEL/ST.
|
||||
|
||||
### Intégration runtime global
|
||||
|
||||
Le test global vérifie désormais :
|
||||
|
||||
1. initialisation silencieuse sans sink ;
|
||||
2. hot reload console non bloquante ;
|
||||
3. takeover KSP et silence `sqlx` ;
|
||||
4. erreur de création d'un file appender sur un chemin invalide ;
|
||||
5. conservation des settings précédents après cet échec ;
|
||||
6. hot reload vers un fichier `Never` ;
|
||||
7. émission d'un message contenant des codes ANSI ;
|
||||
8. retrait du sink fichier par reload, donc drop/flush de son guard ;
|
||||
9. présence du message KSP dans le fichier ;
|
||||
10. absence des codes ANSI persistés ;
|
||||
11. absence du message externe `sqlx` ;
|
||||
12. présence du target et de la source ;
|
||||
13. lecture de la statistique cumulée ;
|
||||
14. refus d'un second `initialize()`.
|
||||
|
||||
La saturation déterministe avec une queue artificiellement petite est reportée à `pre.005`, où un writer de test injecté pourra être utilisé sans rendre la capacité de queue publique dans `LoggingSettings`.
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
- `crates/ksp-logging-lib/src/writer.rs`
|
||||
- `crates/ksp-logging-lib/unit_tests/writer.rs`
|
||||
- `deltas/0.1.2/pre.004.md`
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
- `Cargo.toml`
|
||||
- `crates/ksp-logging-lib/Cargo.toml`
|
||||
- `crates/ksp-logging-lib/src/error.rs`
|
||||
- `crates/ksp-logging-lib/src/lib.rs`
|
||||
- `crates/ksp-logging-lib/src/runtime.rs`
|
||||
- `crates/ksp-logging-lib/unit_tests/runtime.rs`
|
||||
- `crates/ksp-logging-lib/tests/runtime.rs`
|
||||
- `crates/ksp-logging-lib/tests/public_api.rs`
|
||||
- `docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`
|
||||
|
||||
## Validations exécutées pendant la préparation
|
||||
|
||||
- revérification documentaire officielle de `tracing-appender 0.2.5` ;
|
||||
- vérification de la sémantique lossy de `NonBlockingBuilder` ;
|
||||
- vérification de `WorkerGuard` et `ErrorCounter::dropped_lines()` ;
|
||||
- vérification du builder fallible de `RollingFileAppender` ;
|
||||
- contrôle TOML des manifests ;
|
||||
- contrôle des headers `file:` / `version:` ;
|
||||
- contrôle de la centralisation de `tracing-appender` sous `[workspace.dependencies]` ;
|
||||
- contrôle que le code production ajouté n'utilise ni `unwrap`, ni `expect`, ni `panic`, ni opérateur `?`, ni `unsafe` ;
|
||||
- contrôle que les usages directs de `tracing-appender` restent dans `ksp-logging-lib`.
|
||||
|
||||
## Validations à exécuter dans le workspace
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo test --workspace
|
||||
cargo tree -p ksp-logging-lib
|
||||
cargo tree -p ksp-logging-lib -d
|
||||
cargo tree -p ksp-logging-lib -e features
|
||||
```
|
||||
|
||||
Aucune validation Cargo non exécutable dans l'environnement de préparation n'est déclarée réussie.
|
||||
|
||||
## Suite
|
||||
|
||||
Après validation de `pre.004`, passer à `0.1.2-pre.005` :
|
||||
|
||||
- concurrence/reloads répétés ;
|
||||
- saturation déterministe et dropped lines ;
|
||||
- audits de façade et usages directs de la stack tracing ;
|
||||
- audits Cargo/features/doublons ;
|
||||
- mesure grossière de l'overhead du reload/runtime ;
|
||||
- compléments de tests et documentation de crate avant la tranche finale.
|
||||
Reference in New Issue
Block a user