Introduction

Afficher au format Markdown Modifier sur GitHub Documentation de 2cc7b2b

Queuety est un plugin WordPress qui fournit une file de tâches rapide, un moteur de workflow durable et un moteur d'exécution de machines à états durables. Les workers récupèrent directement les tâches depuis MySQL et les traitent dans un processus WP-CLI de longue durée. L'environnement d'exécution PHP qui charge WordPress et WP-CLI nécessite mysqli ou pdo_mysql.

Pourquoi Queuety ?

WordPress ne dispose pas d'un véritable système de tâches en arrière-plan. wp_cron ne se déclenche que lors des visites de pages. Le lanceur par défaut d'Action Scheduler s'appuie sur WP-Cron et sur des requêtes HTTP de bouclage, en traitant chaque fois des lots pendant 30 secondes maximum. Un appel API à un LLM qui prend 60 secondes est interrompu par le délai d'expiration de 30 secondes de PHP. Il est impossible d'exécuter des processus en plusieurs étapes qui survivent aux pannes et reprennent là où ils se sont arrêtés.

Queuety résout ce problème grâce à trois primitives :

Tâches pour le traitement en arrière-plan sans suivi
Workflows pour les processus durables en plusieurs étapes avec état persistant
Machines à états pour les cycles de vie durables, pilotés par événements

Exemple rapide

Déclenchez une tâche avec la classe moderne API :

PHP

use Queuety\Contracts\Job;
use Queuety\Dispatchable;

readonly class SendEmailJob implements Job {
    use Dispatchable;

    public function __construct(
        public string $to,
        public string $subject,
        public string $body,
    ) {}

    public function handle(): void {
        wp_mail( $this->to, $this->subject, $this->body );
    }
}

SendEmailJob::dispatch( 'user@example.com', 'Welcome', 'Hello from Queuety!' );

Vous pouvez aussi utiliser l'approche classique avec le nom du gestionnaire :

PHP

use Queuety\Queuety;

Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] );

Exécutez un workflow durable :

PHP

Queuety::workflow( 'generate_report' )
    ->then( FetchDataHandler::class )
    ->then( CallLLMHandler::class )
    ->then( FormatOutputHandler::class )
    ->dispatch( [ 'user_id' => 42 ] );

Modélisez une session de longue durée avec une machine à états :

PHP

use Queuety\Enums\StateMachineStatus;

Queuety::machine( 'agent_session' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( PlanSessionAction::class )
    ->on( 'planned', 'completed' )
    ->state( 'completed', StateMachineStatus::Completed )
    ->dispatch( [ 'thread_id' => 42 ] );

Démarrez un worker :

Shell

wp queuety work

Si vous créez un système de type agent, commencez par Orchestration d'agents. Vous y découvrirez comment s'articulent les flux planificateur/exécuteur, les étapes de validation humaine et les attentes entre workflows.

Si votre système est piloté par événements et de longue durée, commencez par Machines à états, en complément des workflows.

Pour des exemples d'intégration de bout en bout, consultez Exemples, qui incluent désormais des modèles basés sur Neuron pour le changement de fournisseur, la diffusion, les nouvelles tentatives de validation avec mémoire et les workflows dépendants.

Pour déclencher des workflows à partir d'événements de domaine WordPress tels que save_post, consultez Déclencheurs d'action.

Pour utiliser l'environnement d'exécution adossé à une base de données en dehors de WordPress, consultez Utilisation autonome.

Principales différences

Exécution rapide. Les workers accèdent directement à la file MySQL et évitent le modèle cron par requête qui ralentit le traitement en arrière-plan dans WordPress.
Workflows durables. Les processus en plusieurs étapes avec état persistant résistent aux délais d'expiration PHP, aux pannes et aux nouvelles tentatives. Chaque limite d'étape correspond à une transaction atomique MySQL.
Machines à états explicites. Modélisez les sessions de discussion, les approbations et autres cycles de vie de longue durée avec des états nommés, des transitions protégées, des actions en file d'attente à l'entrée d'un état et des chronologies d'événements durables.
Tâches modernes déclenchables API. Classes de tâches autonomes avec le trait Dispatchable, des propriétés de constructeur typées comme données utiles et les éléments $tries/$timeout/$backoff déclarés sur la classe. Une classe readonly ne peut pas attribuer de valeurs par défaut à ces propriétés ; déclarez-les donc dans une classe ordinaire avec des propriétés promues en lecture seule dans le constructeur.
Pipeline de middleware. Middleware en couches pour limiter le débit, limiter les exceptions, garantir l'unicité des tâches et ajouter une logique personnalisée. Déclaré pour chaque tâche via une méthode middleware().
Étapes de diffusion. L'interface StreamingStep produit des fragments qui sont immédiatement enregistrés dans la base de données. En cas de nouvelle tentative, les fragments déjà enregistrés sont fournis afin que la diffusion reprenne là où elle s'était arrêtée. Idéal pour les réponses des LLM et les téléchargements volumineux.
Couche de cache enfichable. CacheFactory détecte automatiquement APCu ou utilise un cache en mémoire. Les systèmes de stockage personnalisés implémentent Contracts\Cache. Cette couche sert en interne aux recherches du limiteur de débit et à l'état des files.
Traitement par lots et chaînage. Déclenchez des groupes de tâches avec les fonctions de rappel then/catch/finally et le suivi de progression, ou enchaînez les tâches séquentiellement, chacune dépendant de l'achèvement de la précédente.
Délais et attentes durables. delay() ajoute des délais sûrs en cas de redémarrage du processus. wait_for_signal(), wait_for_signals(), wait_for_approval(), wait_for_input() et wait_for_workflow() permettent aux workflows d'attendre des événements externes ou d'autres workflows sans maintenir PHP en vie.
Boucle dynamique. for_each() développe les branches détectées à l'exécution à partir de l'état du workflow et prend en charge les modes d'achèvement « tous réussis », « premier succès » et « quorum ».
Transferts asynchrones entre workflows. start_workflows() transforme les éléments détectés à l'exécution en workflows indépendants de premier niveau, auxquels il est possible d'attendre ultérieurement.
Déclencheurs d'action WordPress. on_action() associe les hooks d'action du cœur ou des plugins au déclenchement de workflows durables, avec contrôle préalable et idempotence.
Artefacts durables. Stockez les résultats nommés des workflows en dehors du conteneur d'état principal et conservez-les lors de l'inspection de l'état, CLI, de l'exportation et de la relecture.
Garde-fous des workflows. version(), une empreinte déterministe de définition, des clés de déclenchement idempotentes et des budgets de workflow facilitent l'inspection des exécutions de type agent et limitent les doublons ou les dérives silencieuses.
Gestion des ressources. Les groupes de concurrence, les unités de coût, les budgets de workflow et l'admission des workers aident à maintenir les traitements coûteux de type agent dans des limites définies.
Compensation des étapes. compensate_with() et compensate_on_failure() fournissent des hooks de restauration pour les étapes terminées lorsque les workflows sont annulés ou échouent.
Signaux d'activité. Les étapes de longue durée envoient des signaux pour empêcher le système de récupération des tâches obsolètes de reprendre un travail en cours.
Traçage des workflows. Chaque transition d'étape est enregistrée avec les entrées, les sorties, l'état avant et après, le contexte, les artefacts, les fragments, les erreurs et le débogage temporel via workflow_state_at().
Étapes parallèles. Exécutez les étapes simultanément et attendez leur achèvement à toutes avant de poursuivre.
Branchement conditionnel. Passez à des étapes nommées selon l'état précédent avec _next_step.
Exécution de workflows. Démarrez des workflows enfants qui renvoient leurs résultats au parent.
Files à priorité. Quatre niveaux (faible, normal, élevé, urgent) via les énumérations à typage sûr PHP.
Workers à files multiples. Traitez plusieurs files avec un ordre de priorité strict dans un seul worker.
Limitation de débit. Limites d'exécution par gestionnaire avec fenêtre glissante.
Tâches récurrentes. Planification par intervalle et selon cron, avec politiques de chevauchement configurables (autoriser, ignorer, mettre en tampon).
Annulation des workflows. Annulez les workflows en cours et déclenchez les gestionnaires de nettoyage enregistrés.
Élagage de l'état. Supprimez automatiquement les anciennes sorties d'étapes pour gérer les états volumineux des workflows.
Concurrence des workers. --workers=N lance plusieurs processus et les redémarre automatiquement en cas de panne.
Observabilité complète. Journalisation dans la base de données, métriques par gestionnaire et webhooks d'événements.
Outils de test. QueueFake enregistre les tâches et les lots déclenchés pour les assertions des tests unitaires.
Attributs PHP. #[QueuetyHandler('name')] pour enregistrer les gestionnaires sans configuration.

Fonctionnement

Les workers s'exécutent dans un processus WP-CLI de longue durée et récupèrent directement les tâches depuis MySQL. Les lignes de file d'attente, l'état des workflows, les journaux, les lots, les signaux et les fragments diffusés résident tous dans MySQL ; les redémarrages des workers ne font donc pas perdre l'état de l'orchestration.

Les workflows décomposent les traitements de longue durée en étapes. Chaque étape enregistre sa sortie dans un conteneur d'état partagé dans la base de données. Si PHP s'arrête au milieu d'une étape, le worker réessaie cette étape avec tout l'état antérieur intact. La limite de l'étape correspond à une transaction unique MySQL : la mise à jour de l'état, la fin de la tâche et la mise en file de l'étape suivante ont lieu de manière atomique.

Code

Workflow: generate_report (3 steps)

Step 0: fetch_data     -> state: {user_data: {...}}
Step 1: call_llm       -> PHP dies -> retry -> state: {user_data: {...}, llm_response: "..."}
Step 2: format_output  -> state: {user_data: {...}, llm_response: "...", report_url: "/reports/42.pdf"}

Workflow: completed

Prérequis

PHP 8.2 ou version ultérieure
WordPress 6.4 ou version ultérieure
MySQL 8.0+ ou MariaDB 10.6+, car les workers récupèrent les tâches avec SELECT ... FOR UPDATE SKIP LOCKED
mysqli ou pdo_mysql dans l'environnement d'exécution PHP qui charge WordPress et WP-CLI
WP-CLI pour exécuter des workers dédiés avec wp queuety work
Les extensions pcntl et posix PHP pour les pools de workers (--workers, --min-workers, --max-workers)

Consultez Bien démarrer pour l'installation.