Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
01502678bf4dfee39d446a50fcb0fdf34f3ef045
khadhroony-solana-project/deltas/0.1.3/pre.007.md
SinuS Von SifriduS 96753e4ba1 v0.1.3-pre.007
2026-08-15 20:57:13 +02:00

9.0 KiB
Raw Blame History

Delta 0.1.3-pre.007

Base requise

Livraison précédente validée :

0.1.3-pre.006

Version technique de cette base :

workspace.package.version = "0.1.3-pre.6"
Cargo.toml header version = 47

Validations utilisateur exécutées le 2026-08-15 :

cargo fmt --all                           OK
cargo check --workspace                   OK
cargo clippy --workspace --all-targets    OK
cargo test --workspace                    OK
cargo tree -p ksp-logging-lib             OK
cargo tree -p ksp-logging-lib -d          OK — aucune duplication
cargo tree -p ksp-logging-lib -e features OK

Les tranches Logging préalables au premier schema Config sont donc closes.

Objet de pre.007

Introduire la première surface JSON/JSON Schema réelle de ksp-config-lib sans ouvrir encore la résolution de profils, les composites ou l'environnement :

registry file_id
    -> resolved Config path
    -> JSON parse
    -> registered schema file_id
    -> schema parse + meta-schema validation
    -> document validation
    -> bounded document semantics

Le premier document concret est :

cfg.std.logging -> config/std.logging.json

validé par :

schema.std.logging -> config/schemas/std.logging.schema.json

Dépendances

Versions vérifiées au moment de l'ajout depuis les sources officielles crates.io / docs.rs :

serde       1.0.229 -> workspace constraint ^1.0
serde_json  1.0.151 -> workspace constraint ^1.0
jsonschema  0.49.9  -> workspace constraint ^0.49

jsonschema est déclaré avec :

default-features = false

La première surface KSP utilise un schema autonome avec références JSON Pointer internes uniquement ; aucune récupération HTTP/file de schemas distants n'est nécessaire.

Les trois dépendances sont déclarées uniquement sous [workspace.dependencies], puis consommées par ksp-config-lib avec .workspace = true.

Association document -> schema

ConfigFileDescriptor possède maintenant :

schema_file_id: Option<ConfigFileId>

Le mapping par défaut devient conceptuellement :

cfg.std.logging
    kind = Config
    filename = std.logging.json
    schema_file_id = schema.std.logging

schema.std.logging
    kind = Schema
    filename = std.logging.schema.json
    schema_file_id = none

Le registre valide :

  • qu'un schema référencé utilise le namespace schema.* ;
  • que son descriptor existe réellement ;
  • qu'il possède ConfigFileKind::Schema ;
  • qu'un descriptor Schema ne référence pas lui-même un schema Config.

Un --filemap change uniquement le filename physique et conserve cette association logique.

Aucun schema.composite n'est encore créé : il sera ajouté avec la tranche composite qui en a réellement besoin.

Moteur JSON générique

Nouvelle façade :

ConfigDocumentEngine
ConfigJsonDocument

ConfigDocumentEngine::load_validated_document(file_id) :

  1. vérifie que le file_id désigne un document Config ;
  2. résout son path via ConfigBootstrapOptions + ConfigFileRegistry ;
  3. lit et parse le JSON ;
  4. charge le schema associé par son propre file_id ;
  5. valide le schema contre son meta-schema ;
  6. valide le document contre le schema Draft 2020-12 ;
  7. exécute les invariants sémantiques actuellement connus pour ce type de document ;
  8. retourne le JSON validé sans transférer aux consumers la responsabilité de lecture/validation filesystem.

ConfigJsonDocument expose uniquement :

file_id
resolved path
validated serde_json::Value

Les autres crates restent interdites de lecture directe des fichiers Config.

Diagnostics

Les nouveaux codes Config distinguent :

config.json_file_read_failed
config.json_syntax_invalid
config.schema_invalid
config.schema_validation_failed
config.document_semantic_invalid

Les erreurs enregistrent le file_id et le path concernés, mais jamais le contenu JSON complet.

Premier schema Logging

config/schemas/std.logging.schema.json utilise JSON Schema Draft 2020-12 et couvre la surface Logging stabilisée en pre.004/.005/.006 :

format_version
logs_directory
default_profile
profiles[]
    profile_id
    default_filter
    span_events
    console
        enabled
        output
        ansi
        format
        filter.level
        filter.targets[]
        filter.domains[]
    files[]
        output_id
        enabled
        path
        rotation
        format
        ansi = false
        filter.level
        filter.targets[]
        filter.domains[]
    target_filters[]

Le schema encode notamment :

  • niveaux off/error/warn/info/debug/trace ;
  • lifecycle off/new_and_close/full ;
  • formats human/compact/pretty/json ;
  • rotation never/hourly/daily ;
  • console stdout/stderr ;
  • targets KSP ou wildcard * ;
  • selectors uniques, wildcard utilisé seul ;
  • ANSI interdit pour les fichiers ;
  • ANSI + JSON console interdit.

Document runtime et exemple

Ajouts :

config/std.logging.json
config/schemas/std.logging.schema.json
config/examples/std.logging.example.json

Le runtime utilise déjà :

"logs_directory": "${KSP_LOGS_DIRECTORY:-logs}"

mais pre.007 ne résout encore aucune variable. Le placeholder reste une valeur source string valide jusqu'au resolver de pre.010.

Le runtime démontre :

  • console configurable ;
  • plusieurs fichiers ;
  • formats humain et JSON ;
  • filtres par level/target/domain ;
  • target overrides globaux ;
  • output_id distinct du file_id Config.

Validation sémantique de base

Après JSON Schema, Config vérifie déjà les invariants directement liés à la surface Logging :

  • format_version = 1 ;
  • chaînes globales requises non vides ;
  • output_id fichier conforme ;
  • output_id uniques dans un même profil ;
  • path fichier relatif à logs_directory, sans traversal ;
  • ANSI fichier interdit ;
  • ANSI + JSON console interdit ;
  • selectors non vides/uniques ;
  • wildcard seul ;
  • target selector et global target_prefix limités aux targets ksp-*.

Ne sont volontairement pas encore traités dans cette tranche :

  • unicité des profile_id ;
  • résolution de default_profile ;
  • sélection explicite d'un profil ;
  • construction d'une configuration effective globals + profil.

Ces responsabilités appartiennent à pre.008.

Tests ajoutés

Les tests unitaires Config couvrent :

  • document Logging runtime commité valide ;
  • fichier Config absent ;
  • syntaxe JSON invalide ;
  • schema lui-même invalide ;
  • document ne satisfaisant pas son schema ;
  • document schema-valide mais sémantiquement invalide ;
  • association document -> schema présente dans le registre ;
  • association vers schema absent refusée.

Le test d'API publique vérifie que ConfigDocumentEngine charge le vrai std.logging.json depuis les racines Config du workspace.

Hors scope

Cette tranche ne fait pas encore :

  • résolution globals/profils/default_profile ;
  • composite ;
  • .env ;
  • std::env ;
  • interpolation ${...} ;
  • classification secret/public/internal ;
  • redaction ;
  • adaptation vers ksp_logging_lib::LoggingSettings ;
  • mutation/persistence.

ksp-config-lib ne dépend donc toujours pas de ksp-logging-lib dans pre.007.

Version technique

La prerelease devient :

workspace.package.version = "0.1.3-pre.7"
Cargo.toml header version = 48

Fichiers ajoutés

config/std.logging.json
config/schemas/std.logging.schema.json
config/examples/std.logging.example.json
crates/ksp-config-lib/src/document.rs
crates/ksp-config-lib/unit_tests/document.rs
deltas/0.1.3/pre.007.md

Fichiers modifiés

Cargo.toml
crates/ksp-config-lib/Cargo.toml
crates/ksp-config-lib/src/error.rs
crates/ksp-config-lib/src/lib.rs
crates/ksp-config-lib/src/registry.rs
crates/ksp-config-lib/tests/public_api.rs
crates/ksp-config-lib/unit_tests/registry.rs
docs/plans/000-README.md
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md
docs/rules/FILE_CONTRACTS.md

Contrôles exécutés dans l'environnement de génération

Les fichiers JSON ont été parsés avec python -m json.tool.

Le schema Draft 2020-12 et le document runtime ont également été validés avec l'implémentation Python jsonschema disponible dans l'environnement de génération.

Aucune commande Cargo n'est disponible dans cet environnement ; aucune validation Rust n'est donc déclarée réussie ici.

Validations utilisateur à exécuter

cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test --workspace
cargo tree -p ksp-config-lib
cargo tree -p ksp-config-lib -d
cargo tree -p ksp-config-lib -e features

Une attention particulière doit être portée au graphe jsonschema avec default-features = false afin de confirmer qu'aucun stack HTTP/TLS de résolution distante n'est introduit inutilement.

Après validation de pre.007, la prochaine tranche est :

0.1.3-pre.008 — globals + profils + default_profile
Reference in New Issue View Git Blame Copy Permalink