Queues, workers et traitement asynchrone
Queues, workers et traitement asynchrone
Guide pratique pour enfilement, suivi et gestion des traitements sources
Comprend : enfilement via la file “projectSourceQueue”, workers de traitement, respect de la concurrence et des délais, observabilité et stratégies de retry/échec.
Ce que couvre cette page
Enqueue & Workers
Comment les sources (repo, site, upload) sont ajoutées à la file (projectSourceQueue) et prises en charge par des workers.
Concurrence & délais
Comportement du traitement simultané, limites de concurrence et temporisation pour respecter les quotas externes.
Observabilité & notifications
Suivi en temps réel des étapes, affichage de progression, persistance locale et logique de reconnexion.
Retries & gestion d’échec
Stratégies de retry exponentiel, backoff, et paths de reprise après erreur.
Annulation et nettoyage
Comment annuler une opération en cours et les limites de l’annulation (opérations externes).
Workflows courants
Étapes concrètes pour enfilement d’un repository, d’un site, et d’un fichier uploadé.
Introduction Ce guide explique, pour les utilisateurs et administrateurs non‑techniques, comment fonctionnent les files de traitement et les workers liés au pipeline d’ajout de sources projet (repositories, sites, uploads). Vous apprendrez :
- ce que vous devez faire côté interface pour démarrer un traitement ;
- comment suivre la progression en temps réel depuis l’interface ;
- quelles règles s’appliquent (concurrence, délais, retries) ;
- comment annuler un traitement et quelles sont les limites de l’annulation ;
- bonnes pratiques pour projets petits et gros.
Rappel rapide
Les travaux sont asynchrones : une fois que vous ajoutez une source, elle est mise en file d’attente. Un worker la prendra quand des ressources seront disponibles. La complétion dépend de la charge et des limites imposées par les fournisseurs externes (ex. services Git, hébergeurs).
Workflow : Enfilement d'un repository (ex. ajout d'un dépôt Git)
Étape 1 — Initiation depuis l'UI
Dans l’interface projet, choisissez « ajouter un repository » puis saisissez l’URL et les informations demandées (optionnel : token / méthode d’authentification si demandée). Validez l’ajout.
Étape 2 — Le job est enqueued
Dès la validation, un job est placé dans la file nommée « projectSourceQueue ». L’interface crée un élément d’attente visible immédiatement (état “pending”) pour vous donner un retour instantané.
Étape 3 — Affichage immédiat de l'état pending
L’UI initialise une entrée “pending” (libellé du repo, progression 0%) pour que vous voyiez que le travail a bien été pris en compte, même si le traitement réel n’a pas commencé.
Étape 4 — Notification en temps réel
La page établit (ou réutilise) une connexion de notifications temps réel. Dès qu’un worker commence à traiter le job, l’UI reçoit des mises à jour (avancement, messages intermédiaires, erreurs).
Étape 5 — Traitement par le worker
Un worker prend le job quand il y a de la capacité — il effectue les étapes d’analyse/import. L’UI met à jour la barre de progression et les messages étape par étape.
Étape 6 — Fin et triggers post‑traitement
Quand toutes les étapes internes sont complètes, le job signale la complétion. Des actions automatiques possibles (ex. génération de documentation de site) peuvent être enchaînées.
Étape 7 — Historique et persistance locale
L’état visible peut être conservé temporairement côté client (pour reprise après reload). Une fois tous les jobs terminés, l’UI nettoie les états locaux.
Étape 8 — Que faire en cas d'échec
Si le job échoue, le système applique une stratégie de retry (voir section dédiée). L’UI vous montre l’erreur et les actions recommandées (réessayer manuellement, vérifier accès externes).
Astuce : préparer vos accès avant d'ajouter un repo
Avant d’enclencher l’ajout, vérifiez que le projet a les identifiants/droits nécessaires pour lire le dépôt (token ou installation). Cela réduit les erreurs de permission et les retries inutiles.
Workflow : Enfilement d'un site web (scraping / import)
Étape 1 — Saisie de l'URL
Dans l’UI du projet, choisissez « ajouter un site » puis entrez l’URL publique et options éventuelles (sitemaps, path à ignorer).
Étape 2 — Mise en file et pending local
Le job d’import est créé et apparaît en “pending” pour le retour immédiat côté UI.
Étape 3 — Priorisation et quotas
Les imports de sites peuvent être plus lourds ; le système respecte des limites de charge et des délais entre requêtes vers le même domaine pour éviter d’être bloqué par l’hébergeur.
Étape 4 — Progrès et messages
L’UI affichera le nombre de pages traitées, les warnings (pages ignorées) et l’avancement global. En cas de rate limit côté hébergeur, le job peut être retardé automatiquement.
Étape 5 — Completion & post‑actions
À la fin, l’import génère une synthèse (nombre de pages indexées, erreurs, durée). Vous pouvez lancer des actions complémentaires (indexation RAG, génération de docs).
Astuce : découper les gros sites
Pour les sites volumineux, enfilez par lot (p.ex. sous‑dossiers ou sitemap partiel). Cela réduit la probabilité de timeouts et facilite la reprise sur erreurs.
Workflow : Enfilement d'un upload (fichier)
Étape 1 — Upload depuis l'UI
Sélectionnez le fichier et déclenchez l’upload. L’UI montre un état d’upload et, à réception côté serveur, un job est enqueued pour traiter le fichier.
Étape 2 — Pending & information immédiate
Un job pending est ajouté (nom du fichier, taille approximative), vous avez un retour immédiat avant que le traitement commence.
Étape 3 — Priorité et concurrency
Les uploads légers sont traités plus rapidement ; les fichiers lourds peuvent être mis en file d’attente et traités selon la capacité disponible.
Étape 4 — Progrès et erreurs
Progression par étapes (ingestion, extraction, indexation). En cas d’erreur (format non supporté, corruption), le système notifie et propose un retry.
Étape 5 — Nettoyage après succès
À la fin, vous obtenez un récapitulatif et les artefacts générés (index, extraits). L’UI met fin à l’état pending et supprime les traces temporaires côté client.
Limite d'annulation
L’annulation tente d’empêcher les jobs non encore démarrés et marque les jobs actifs comme « annulés ». Toutefois, si un sous‑appel externe (ex. API d’un fournisseur) a déjà démarré, cette action peut ne pas interrompre l’opération côté fournisseur. Attendez la confirmation d’annulation dans l’UI avant d’effectuer des opérations dépendantes.
Workflow : Annulation d’un traitement et nettoyage (ce que vous pouvez faire)
Étape 1 — Demander l'annulation depuis l'UI
Cliquez sur « Annuler » pour le projet en cours. L’interface stoppe la réception des mises à jour et envoie la demande d’annulation au serveur.
Étape 2 — Suppression des jobs en attente
Les jobs encore en attente sont supprimés de la file ; vous verrez le nombre de jobs annulés dans le feedback.
Étape 3 — Marquer les jobs actifs comme
Les jobs déjà en cours sont marqués comme annulés pour que le worker s’arrête proprement dès que possible. L’UI vous indique lesquels ont été marqués.
Étape 4 — Nettoyage local
L’état local (pending, jobsOnProgress) est nettoyé et les clés temporaires côté client sont supprimées.
Étape 5 — Vérifier les conséquences externes
Pour les actions déclenchées vers des services externes (ex. création de webhooks, appels API), vérifiez manuellement que ces services n’ont pas finalisé une opération que vous souhaitiez interrompre.
Workflow : Suivi & observabilité (ce que l'utilisateur voit et doit faire)
Étape 1 — Ouverture du panneau de progression
Ouvrez la section de progression projet : vous verrez la liste des jobs en cours et leur % d’avancement.
Étape 2 — Réception de messages étape par étape
Chaque étape majeure du job envoie un message : démarrage d’une phase, réussite d’un sous‑traitement, avertissement ou erreur.
Étape 3 — Persist/Restore après reload
Si vous rechargez la page, l’UI restaure l’état connu (pending et jobs en cours) depuis un stockage local pour éviter de perdre le fil.
Étape 4 — Reconnexion automatique
Si la connexion de notifications est coupée, l’UI tente une reconnexion automatique et demande au serveur l’état actuel des jobs pour synchroniser l’affichage.
Étape 5 — Demande d'état serveur
Si l’UI a des jobs en local mais pas de mises à jour, elle demande l’état des jobs au serveur pour corriger les écarts (jobs complétés ou abandonnés).
Conseil : toujours surveiller les messages d’étape
Les messages intermédiaires sont précieux : ils indiquent si un job est ralenti par un fournisseur externe (rate limit) ou s’il attend une ressource (auth, accès). En cas d’erreur répétée, consultez ces messages avant de relancer.
Workflow : Retry et stratégie en cas d'échec
Étape 1 — Détection de l'erreur
Quand une étape échoue, le système enregistre le type d’erreur (transitoire vs permanent) et le message à destination de l’UI.
Étape 2 — Tentative automatique (backoff)
Pour les erreurs transitoires (p.ex. timeouts, rate limits), des tentatives automatiques sont programmées avec un délai croissant entre chaque essai.
Étape 3 — Arrêt après seuil
Après un certain nombre d’essais échoués, le job est marqué comme failed définitif. L’UI propose alors des actions manuelles (relancer, modifier paramètres, contacter le support).
Étape 4 — Reprise manuelle
Vous pouvez relancer un job manuellement depuis l’interface après avoir corrigé la cause racine (permissions, configuration, token).
Étape 5 — Notifications & audit
Les erreurs critiques génèrent une notification et un log consultable pour le diagnostic. Pensez à vérifier ces informations avant de relancer.
Séquentiel (par défaut)
- Facile à raisonner.
- Moins de risques de contention sur des ressources externes.
- Idéal pour imports lourds et ordonnés.
Parallèle (concurrence élevée)
- Traite plus vite plusieurs sources.
- Peut atteindre les limites de rate des fournisseurs.
- Requiert gestion stricte des délais/retries.
Pour 1–3 sources : privilégiez le traitement parallèle léger (concurrence faible). Enfilez tout et surveillez la progression. Les retries ne devraient pas intervenir souvent.
Gotcha : rechargement et duplication de jobs
Si vous lancez l’ajout de sources et rechargez plusieurs fois l’interface sans attendre la confirmation, vous pouvez créer plusieurs jobs similaires. Attendez le retour “enqueued” ou vérifiez la liste des jobs en attente avant de relancer.
Frequently Asked Questions
Bonnes pratiques résumées
- Vérifiez permissions et tokens avant d’enfiler des sources.
- Découpez les gros imports en lots.
- Surveillez les messages d’étape et attendez le signal de complétion avant de lancer des actions dépendantes.
- Utilisez l’annulation si nécessaire, mais vérifiez manuellement les opérations externes si elles étaient engagées.
Besoin d'aide ?
Si un job reste bloqué ou si vous observez des erreurs répétées, contactez le support avec les identifiants du projet et la description des étapes déjà tentées.