Garde-fous des flux de travail

Les flux de travail de type agent sont flexibles, mais ils facilitent aussi la création d’exécutions en double ou la production d’un volume de travail supérieur aux prévisions par un planificateur. Queuety fournit des garde-fous légers au niveau du flux de travail pour préserver cette flexibilité sans perdre le contrôle.

Pour en savoir plus sur le modèle général de gestion des ressources, qui couvre l’admission des travailleurs et les métadonnées de coût par tâche, consultez Gestion des ressources.

Versionner une définition de flux de travail

Utilisez version() pour associer une étiquette de version au niveau de l’application à une définition de flux de travail :

Queuety::workflow( 'research_run' )
    ->version( 'research.v2' )
    ->then( PlanResearchStep::class )
    ->then( DraftResearchSummaryStep::class )
    ->dispatch();

La version est stockée avec l’état du flux de travail, exposée via workflow_status(), affichée par wp queuety workflow status et incluse dans les exports du flux de travail.

Queuety stocke également un definition_hash déterministe pour chaque exécution du flux de travail. Le hachage est dérivé de la définition sérialisée du flux de travail et permet d’identifier précisément la structure de flux exécutée par une exécution en cours après un déploiement.

Rendre la répartition idempotente

Utilisez idempotency_key() lorsque les appelants sont susceptibles de réessayer la même requête :

Queuety::workflow( 'research_run' )
    ->idempotency_key( 'brief:42:research' )
    ->then( PlanResearchStep::class )
    ->dispatch( [ 'brief_id' => 42 ] );

Si un flux de travail est réparti à nouveau avec une clé déjà utilisée, Queuety renvoie l’identifiant du flux d’origine au lieu de créer une exécution en double. Les clés sont globales à tous les noms de flux de travail ; incluez donc le nom du flux dans la clé lorsque différents flux sont susceptibles d’en partager une.

C’est particulièrement utile pour :

• les points de terminaison API susceptibles d’être rappelés par des clients ou des passerelles
• les consommateurs de webhooks qui peuvent recevoir des livraisons en double
• les étapes du planificateur qui ne doivent créer qu’une seule exécution d’orchestration par entité externe

Les clés d’idempotence sont stockées dans la table queuety_workflow_dispatch_keys.

Définir des budgets de flux de travail

Utilisez des budgets de flux de travail pour faire échouer les exécutions qui dépassent les limites prévues :

Queuety::workflow( 'research_run' )
    ->max_transitions( 20 )
    ->max_for_each_items( 12 )
    ->max_state_bytes( 32768 )
    ->max_cost_units( 40 )
    ->max_started_workflows( 8 )
    ->then( PlanResearchStep::class )
    ->for_each( 'tasks', ExecuteResearchTask::class, 'results' )
    ->dispatch();

max_transitions()

Limite le nombre d’étapes du flux de travail qui peuvent se terminer avant l’échec de l’exécution. Cette limite protège les flux de travail qui créent des branches dynamiquement ou peuvent revenir à la même zone via _next_step.

max_for_each_items()

Limite le nombre d’éléments découverts à l’exécution qu’une étape for_each() peut développer. Cette limite est utile pour les systèmes planificateur/exécuteur où un agent pourrait découvrir beaucoup plus de travail de branche que prévu.

max_state_bytes()

Limite la taille encodée de l’état public du flux de travail. Cela évite que les flux de longue durée ne deviennent de gros blocs de données difficiles à examiner, à exporter ou à relancer.

max_cost_units()

Limite le nombre total d’unités de coût consommées par les étapes terminées. Les unités de coût proviennent des métadonnées de l’étape ou de la tâche que Queuety résout lors de la mise en file d’attente. Les tâches ordinaires des utilisateurs ont par défaut la valeur 1 ; les éléments d’orchestration fictifs, tels que les délais et les attentes, utilisent 0 ; et les gestionnaires peuvent définir une valeur positive supérieure via config() ou les propriétés de la tâche. Seul le cost_units d’une définition d’étape peut définir la valeur 0.

Cette limite est utile lorsqu’un flux de travail peut revenir à la même zone ou lorsqu’une boucle développe du travail coûteux pour des raisons que le simple nombre d’étapes ne reflète pas. Un planificateur qui relance sans cesse un appel coûteux à un modèle peut respecter max_transitions() tout en dépassant le budget prévu.

max_started_workflows()

Limite le nombre de flux de travail de premier niveau qu’une exécution peut démarrer via start_workflows() ou start_agents(). La limite est vérifiée avant la répartition des flux enfants, de sorte que le flux parent échoue sans créer partiellement un groupe qui dépasse déjà le budget.

Lorsqu’un budget est dépassé, Queuety fait immédiatement échouer le flux de travail au lieu de relancer l’étape. Exception : lorsque Queuety::signal() termine une attente et que la transition qui en résulte dépasse un budget, l’exception est renvoyée à l’appelant de signal(), l’insertion du signal est annulée et le flux de travail continue d’attendre.

Observer les garde-fous

L’état du flux de travail expose :

• definition_version
• definition_hash
• idempotency_key
• budget

La charge utile budget inclut les limites configurées et l’utilisation actuelle, notamment la taille actuelle de l’état public en octets.

Exemple :

$state = Queuety::workflow_status( $workflow_id );

$state->definition_version; // 'research.v2'
$state->definition_hash;    // '4c7a...'
$state->idempotency_key;    // 'brief:42:research'
$state->budget;             // [ 'max_transitions' => 20, ... ]