khadhroony-solana-project/crates/ksp-app-backfill-desk/USAGE.md

Utilisation de ksp-app-backfill-desk

1. Lancement

Depuis la racine du workspace :

(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 :

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 :

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 :

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 :

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 :

(cd crates/ksp-app-backfill-desk && cargo tauri build)