v0.3.7-pre.016
This commit is contained in:
105
crates/ksp-app-backfill-desk/README.md
Normal file
105
crates/ksp-app-backfill-desk/README.md
Normal file
@@ -0,0 +1,105 @@
|
||||
<!-- file: crates/ksp-app-backfill-desk/README.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# `ksp-app-backfill-desk`
|
||||
|
||||
`ksp-app-backfill-desk` est l'application desktop spécialisée de contrôle d'un backfill historique `RawTransaction` KSP.
|
||||
|
||||
Elle reste une couche de composition Tauri : Config sélectionne les profils, Transport possède les endpoints/rôles/retry/rate-limit, Store possède la persistence et le backend, et `ksp-job-backfill-lib` possède découverte, hydratation, frontier/checkpoint et lifecycle du job.
|
||||
|
||||
## Package
|
||||
|
||||
```text
|
||||
package : ksp-app-backfill-desk
|
||||
lib : ksp_app_backfill_desk_lib
|
||||
bin : ksp-app-backfill-desk
|
||||
```
|
||||
|
||||
Le binaire est un launcher mince. La bibliothèque applicative possède le bootstrap, l'état Rust single-run, les DTOs Tauri, les commands et le bridge latest-value vers le frontend.
|
||||
|
||||
## Composition
|
||||
|
||||
```text
|
||||
ksp-config-lib -> composite, profils, secrets et runtime packagé
|
||||
ksp-core-lib -> erreurs, Pubkey et registre Program IDs
|
||||
ksp-onchain-transport-lib -> HTTP pool, rôles, admission, retry/rate-limit
|
||||
ksp-store-lib -> façade Store backend-neutral
|
||||
ksp-job-api -> lifecycle Job commun
|
||||
ksp-job-backfill-lib -> request/runtime/checkpoint/snapshots Backfill
|
||||
ksp-logging-lib -> logging/tracing applicatif
|
||||
ksp-app-backfill-desk -> orchestration Tauri + projections sûres
|
||||
```
|
||||
|
||||
L'application ne dépend pas directement de `ksp-store-api`, `ksp-store-postgres-lib`, `tokio-postgres`, `reqwest`, `tonic` ou `yellowstone-grpc-proto`.
|
||||
|
||||
## Capacités
|
||||
|
||||
La surface utilisateur comprend :
|
||||
|
||||
- quatre scopes : latest address, before address, after address et explicit signatures ;
|
||||
- engagements `finalized` et `confirmed` ;
|
||||
- sélection d'un rôle HTTP logique compatible avec `getSignaturesForAddress` et `getTransaction` ;
|
||||
- bornes page/candidats/concurrence validées côté Rust par le contrat Backfill ;
|
||||
- validation de la requête avant Start ;
|
||||
- un seul run actif ;
|
||||
- monitoring latest-value par événement `ksp-backfill-status` avec resynchronisation explicite ;
|
||||
- Cancel ciblé par JobId backend et idempotent ;
|
||||
- Resume in-session lorsqu'un checkpoint terminal est disponible ;
|
||||
- autocomplete libre des Program IDs provenant du registre canonique `ksp-core-lib`.
|
||||
|
||||
L'autocomplete n'est jamais une allow-list : une adresse Solana valide non enregistrée reste saisissable.
|
||||
|
||||
## Checkpoint et Resume
|
||||
|
||||
Le checkpoint concret ne traverse jamais IPC. Le backend conserve uniquement en mémoire Rust le dernier terminal compatible et la requête nécessaire à une reprise dans la même session.
|
||||
|
||||
Un Resume crée un nouveau JobId backend. `ksp-job-backfill-lib` valide le checkpoint contre la requête d'origine puis le réémet pour ce nouveau Job sans modifier le scope fingerprint ni la frontier. Il n'existe pas de checkpoint durable de Backfill Desk après redémarrage de l'application.
|
||||
|
||||
## Config et réseaux
|
||||
|
||||
Le composite dédié est :
|
||||
|
||||
```text
|
||||
cfg.composite.ksp-app-backfill-desk
|
||||
```
|
||||
|
||||
Les profils committed couvrent `mainnet`, `devnet` et `testnet`. Mainnet est le profil par défaut. Transport et Store doivent sélectionner exactement le même réseau avant que la composition soit déclarée ready.
|
||||
|
||||
Les profils Store committed utilisent actuellement TLS PostgreSQL `disabled`; cette politique de profil n'enlève pas le support `verify_full` du Store/schema.
|
||||
|
||||
Le frontend ne reçoit jamais URI Store, URL RPC, credential provider, secret Config ou backend physique.
|
||||
|
||||
## Monitoring et sécurité
|
||||
|
||||
Le monitoring expose des compteurs et codes sûrs : lifecycle, phase, boundary, candidats, entités/observations, missing/conflicts/holes, concurrence maximale, frontier contiguë, présence de checkpoint et éventuel domain/code d'échec.
|
||||
|
||||
Il n'expose pas :
|
||||
|
||||
- payload RAW ;
|
||||
- adresse ou signatures de campagne ;
|
||||
- checkpoint/cursor concret ;
|
||||
- endpoint URL ou credential ;
|
||||
- contexte d'erreur arbitraire.
|
||||
|
||||
Le frontend ne possède ni accès direct filesystem/réseau, ni persistence navigateur de données Backfill. Les capabilities Tauri guest restent `core:default` et `tracing:default`.
|
||||
|
||||
## Ports et développement
|
||||
|
||||
```text
|
||||
Vite HTTP : 1436
|
||||
Vite WS : 1437
|
||||
```
|
||||
|
||||
Lancement :
|
||||
|
||||
```bash
|
||||
(cd crates/ksp-app-backfill-desk && cargo tauri dev)
|
||||
```
|
||||
|
||||
Build production :
|
||||
|
||||
```bash
|
||||
(cd crates/ksp-app-backfill-desk && cargo tauri build)
|
||||
```
|
||||
|
||||
Voir également [`USAGE.md`](USAGE.md), [`../ksp-job-backfill-lib/README.md`](../ksp-job-backfill-lib/README.md), [`../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md`](../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md) et [`../../docs/validation/024-V0_3_7_BACKFILL_DESK.md`](../../docs/validation/024-V0_3_7_BACKFILL_DESK.md).
|
||||
145
crates/ksp-app-backfill-desk/USAGE.md
Normal file
145
crates/ksp-app-backfill-desk/USAGE.md
Normal file
@@ -0,0 +1,145 @@
|
||||
<!-- file: crates/ksp-app-backfill-desk/USAGE.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Utilisation de `ksp-app-backfill-desk`
|
||||
|
||||
## 1. Lancement
|
||||
|
||||
Depuis la racine du workspace :
|
||||
|
||||
```bash
|
||||
(cd crates/ksp-app-backfill-desk && cargo tauri dev)
|
||||
```
|
||||
|
||||
Le runtime charge le composite Backfill Desk via `ksp-config-lib`, construit le pool HTTP, ouvre Store puis vérifie que les deux surfaces utilisent le même réseau avant d'autoriser une campagne.
|
||||
|
||||
## 2. Choix du profil et readiness
|
||||
|
||||
Le composite `cfg.composite.ksp-app-backfill-desk` utilise Mainnet par défaut. Devnet et Testnet restent disponibles via la sélection Config du profil composite.
|
||||
|
||||
Avant Start, l'écran indique séparément :
|
||||
|
||||
```text
|
||||
Transport ready
|
||||
Store ready
|
||||
Network coherent
|
||||
Composition ready
|
||||
```
|
||||
|
||||
Une composition non ready doit être corrigée côté Config/runtime ; le frontend ne peut pas fournir une URL RPC, une URI Store ou un secret pour contourner ces contrôles.
|
||||
|
||||
## 3. Adresse et autocomplete Program IDs
|
||||
|
||||
Le champ adresse accepte toute Pubkey Solana valide. Le `datalist` propose en complément les Program IDs du registre canonique `ksp-core-lib` avec leurs metadata publiques.
|
||||
|
||||
Choisir une proposition remplit simplement le champ ; une adresse absente du dataset reste autorisée. Le dataset n'est pas une allow-list.
|
||||
|
||||
## 4. Scopes
|
||||
|
||||
Les scopes disponibles sont :
|
||||
|
||||
```text
|
||||
latest_address
|
||||
before_address
|
||||
after_address
|
||||
explicit_signatures
|
||||
```
|
||||
|
||||
`latest_address` recherche l'historique récent d'une adresse. `before_address` et `after_address` ajoutent une signature d'ancrage selon la sémantique Backfill. `explicit_signatures` traite une liste explicite de signatures et n'accepte pas `min_context_slot`.
|
||||
|
||||
Les signatures et adresses sont revalidées côté Rust ; leur présence dans le formulaire ne les rend pas persistantes dans le frontend.
|
||||
|
||||
## 5. Engagement, route HTTP et bornes
|
||||
|
||||
Les engagements disponibles sont `finalized` et `confirmed`.
|
||||
|
||||
Le sélecteur HTTP expose uniquement des rôles logiques que le backend a vérifiés compatibles avec les deux méthodes nécessaires au Backfill. Le rôle pool permet au Transport de choisir/rerouter entre endpoints selon ses propres règles ; les rôles ciblés permettent de sélectionner une route logique spécifique sans exposer l'URL physique.
|
||||
|
||||
Les bornes de campagne comprennent notamment :
|
||||
|
||||
```text
|
||||
page size
|
||||
max pages
|
||||
max candidates
|
||||
hydration concurrency
|
||||
min context slot
|
||||
```
|
||||
|
||||
Les limites maximales proviennent de `ksp-job-backfill-lib` et sont revalidées lors de la conversion vers `BackfillRequest`.
|
||||
|
||||
## 6. Valider puis démarrer
|
||||
|
||||
**Valider la requête** projette un résumé sûr de la campagne sans démarrer le job.
|
||||
|
||||
**Démarrer** crée ensuite un JobId backend et installe le handle de contrôle avant le spawn asynchrone. Un second Start est refusé tant qu'un run est actif, y compris pendant `cancelling`.
|
||||
|
||||
## 7. Monitoring latest-value
|
||||
|
||||
La carte de monitoring est alimentée par les snapshots latest-value du runtime. Le backend émet `ksp-backfill-status`; **Resynchroniser** appelle également `backfill_status` afin de récupérer explicitement le dernier état complet.
|
||||
|
||||
Les informations utiles incluent :
|
||||
|
||||
- lifecycle et phase ;
|
||||
- scope et discovery boundary ;
|
||||
- candidats selected/admitted/finished ;
|
||||
- entités et observations inserted/existing ;
|
||||
- purged/missing/conflicts/holes/cancelled candidates ;
|
||||
- maximum in flight ;
|
||||
- contiguous completed ;
|
||||
- présence d'un checkpoint ;
|
||||
- domain/code stable d'échec éventuel.
|
||||
|
||||
Le monitoring ne doit pas être interprété depuis les logs texte.
|
||||
|
||||
## 8. Annuler
|
||||
|
||||
**Annuler** envoie le JobId actuellement affiché. Cette cible protège un nouveau run contre une requête Cancel retardée destinée au run précédent.
|
||||
|
||||
Le premier Cancel pré-terminal demande une annulation coopérative. Une répétition est idempotente. Le lifecycle peut passer par `cancelling`; les opérations déjà admises vers la persistence ne sont pas présentées comme brutalement interrompues.
|
||||
|
||||
## 9. Reprendre
|
||||
|
||||
**Reprendre** est disponible uniquement lorsqu'un snapshot terminal retenu contient un checkpoint. La commande n'accepte aucun checkpoint ou payload de campagne depuis le frontend.
|
||||
|
||||
Le backend :
|
||||
|
||||
1. exige qu'aucun run ne soit actif ;
|
||||
2. récupère la requête terminale Rust-only ;
|
||||
3. revalide le réseau Store et le rôle HTTP courant ;
|
||||
4. génère un nouveau JobId ;
|
||||
5. demande à `ksp-job-backfill-lib` de réémettre le checkpoint pour ce JobId ;
|
||||
6. relance le même runtime/monitoring.
|
||||
|
||||
La reprise est limitée à la session courante. Fermer l'application supprime ce checkpoint applicatif en mémoire.
|
||||
|
||||
## 10. Fermeture de l'application
|
||||
|
||||
La fermeture de la fenêtre principale bloque d'abord tout nouveau Start, tente une annulation coopérative du run actif puis ferme Store avant l'exit.
|
||||
|
||||
Le shutdown applicatif n'est pas un mécanisme de checkpoint durable ou de reprise après crash.
|
||||
|
||||
## 11. Données qui ne traversent pas le frontend
|
||||
|
||||
Backfill Desk ne projette jamais :
|
||||
|
||||
```text
|
||||
URI Store
|
||||
URL RPC
|
||||
credentials/secrets
|
||||
payload RAW
|
||||
checkpoint/cursor concret
|
||||
handles Store/Transport/Job
|
||||
contexte d'erreur arbitraire
|
||||
```
|
||||
|
||||
Les actions utilisateur et transitions sont instrumentées via Logging KSP sans journaliser adresse, signature ou payload métier.
|
||||
|
||||
## 12. Runtime packagé
|
||||
|
||||
Le build Tauri embarque les documents Config/schemas enregistrés. `ksp-config-lib` prépare ensuite la racine KSP user-writable et conserve les Config utilisateur existantes ; `.env` n'est jamais embarqué.
|
||||
|
||||
Le build production est :
|
||||
|
||||
```bash
|
||||
(cd crates/ksp-app-backfill-desk && cargo tauri build)
|
||||
```
|
||||
Reference in New Issue
Block a user