Přejít k obsahu

Úvod

Zobrazit jako Markdown Upravit na GitHub Dokumentace na 2cc7b2b

Queuety je plugin WordPress, který nabízí rychlou frontu úloh, trvalý nástroj pro pracovní postupy a běhové prostředí trvalých stavových automatů. Pracovní procesy přebírají úlohy přímo z MySQL a zpracovávají je v dlouho běžícím procesu WP-CLI. Běhové prostředí PHP, které načítá WordPress a WP-CLI, potřebuje buď mysqli, nebo pdo_mysql.

Proč Queuety?

WordPress nemá skutečný systém úloh na pozadí. wp_cron se spouští pouze při návštěvě stránky. Výchozí runner Action Scheduleru běží na WP-Cron a požadavcích loopback HTTP, přičemž každý zpracovává dávky nejvýše 30 sekund. Volání LLM API, které trvá 60 sekund, ukončí 30sekundový limit PHP. Nelze spouštět vícekrokové procesy, které přežijí pády a pokračují tam, kde skončily.

Queuety to řeší pomocí tří základních prvků:

  1. Úlohy pro asynchronní práci bez čekání na výsledek
  2. Workflow pro trvalé vícekrokové procesy s uchovávaným stavem
  3. Stavové automaty pro dlouhodobý stav životního cyklu řízený událostmi

Rychlý příklad

Odešlete úlohu pomocí moderního 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!' );

Nebo použijte klasický přístup s názvem obslužné rutiny:

PHP
use Queuety\Queuety;

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

Spusťte trvalý workflow:

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

Modelujte dlouhodobou relaci pomocí stavového automatu:

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 ] );

Spusťte worker:

Shell
wp queuety work

Pokud vytváříte systém ve stylu agenta, začněte u Orchestrace agentů. Ukazuje, jak spolu souvisejí toky plánovače a vykonavatele, kroky pro lidskou kontrolu a čekání napříč workflow.

Pokud je systém řízený událostmi a dlouhodobě běžící, začněte u Stavových automatů společně s workflow.

Pokud hledáte příklady integrace od začátku do konce, podívejte se na Příklady, které nyní zahrnují vzory založené na Neuron pro přepínání poskytovatelů, streamování, opakování kontroly s využitím paměti a závislá workflow.

Pokud chcete spouštět workflow na základě doménových událostí WordPress, například save_post, podívejte se na Spouštěče akcí.

Pokud chcete používat runtime s databázovým úložištěm mimo WordPress, podívejte se na Samostatné použití.

Klíčové přednosti

  • Rychlé provádění. Workeři přistupují přímo k frontě MySQL a vyhýbají se vzoru cron pro každý požadavek, který zpomaluje práci na pozadí v WordPress.
  • Trvalá workflow. Vícekrokové procesy s uchovávaným stavem přežijí časové limity PHP, pády i opakované pokusy. Hranice každého kroku tvoří atomická transakce MySQL.
  • Explicitní stavové automaty. Modelujte chatové relace, schvalování a další dlouhodobé životní cykly pomocí pojmenovaných stavů, hlídaných přechodů, zařazených akcí při vstupu do stavu a trvalých časových os událostí.
  • Moderní API pro odesílání úloh. Samostatné třídy úloh s traitem Dispatchable, typovanými vlastnostmi konstruktoru jako payloadem a deklaracemi $tries/$timeout/$backoff přímo ve třídě. Třída readonly nemůže těmto vlastnostem přiřadit výchozí hodnoty, proto je deklarujte v běžné třídě s vlastnostmi konstruktoru povýšenými jako readonly.
  • Řetězec middleware. Middleware ve stylu cibule pro omezování četnosti, řízení výjimek, jedinečné úlohy a vlastní logiku. Deklaruje se pro každou úlohu pomocí metody middleware().
  • Kroky se streamováním. Rozhraní StreamingStep poskytuje části, které se ihned ukládají do databáze. Při opakovaném pokusu se zpřístupní dříve uložené části, aby stream mohl pokračovat tam, kde skončil. Ideální pro odpovědi LLM a velká stahování.
  • Vyměnitelná vrstva cache. CacheFactory automaticky zjistí APCu, případně použije paměťovou cache. Vlastní backendy implementují Contracts\Cache. Interně se používá pro vyhledávání v omezovači četnosti a stav fronty.
  • Dávky a řetězení. Odesílejte skupiny úloh s callbacky then/catch/finally a sledováním průběhu nebo řetězte úlohy za sebou, kdy každá závisí na dokončení předchozí.
  • Trvalá zpoždění a čekání. delay() přidává zpoždění bezpečná při restartu procesu. wait_for_signal(), wait_for_signals(), wait_for_approval(), wait_for_input() a wait_for_workflow() umožňují workflow pozastavit do příchodu externích událostí nebo dokončení jiných workflow, aniž by musel zůstat spuštěný PHP.
  • Dynamické zpracování položek. for_each() rozšiřuje práci na větvích zjištěnou za běhu podle stavu workflow a podporuje režimy dokončení při úspěchu všech, prvním úspěchu nebo dosažení kvóra.
  • Asynchronní předávání workflow. start_workflows() mění položky zjištěné za běhu na nezávislá workflow nejvyšší úrovně, na která lze později čekat.
  • Spouštěče akcí WordPress. on_action() převádí háčky akcí jádra nebo pluginů na trvalé spuštění workflow s podmínkami a idempotencí.
  • Trvalé artefakty. Ukládejte pojmenované výstupy workflow mimo hlavní úložiště stavu a zachovejte je při kontrole stavu, inspekci CLI, exportu a opětovném přehrání.
  • Ochranná pravidla workflow. version(), deterministický hash definice, idempotentní klíče odeslání a rozpočty workflow usnadňují kontrolu běhů ve stylu agenta a ztěžují jejich nechtěné zdvojení nebo tiché neomezené pokračování.
  • Správa zdrojů. Skupiny souběžnosti, nákladové jednotky, rozpočty workflow a přijímání workerů pomáhají udržet náročnou práci ve stylu agenta v definovaných mezích.
  • Kompenzace kroků. compensate_with() a compensate_on_failure() poskytují návratové háčky pro dokončené kroky při zrušení nebo selhání workflow.
  • Signály živosti. Dlouho běžící kroky odesílají signály živosti, které brání systému obnovy zastaralých úloh v převzetí aktivní práce.
  • Trasování workflow. Každý přechod mezi kroky se zaznamenává včetně vstupu, výstupu, stavu před a po změně, kontextu, artefaktů, částí streamu a chyb; ladění v čase je dostupné přes workflow_state_at().
  • Paralelní kroky. Spouštějte kroky souběžně a před pokračováním počkejte na dokončení všech.
  • Podmíněné větvení. Přeskakujte na pojmenované kroky podle předchozího stavu pomocí _next_step.
  • Spouštění workflow. Spouštějte podřízená workflow, která předávají výsledky zpět nadřazenému workflow.
  • Fronty s prioritou. Čtyři úrovně (Low, Normal, High, Urgent) prostřednictvím typově bezpečných enumů PHP.
  • Workeři s více frontami. Zpracovávejte více front v jediném workeru s přísným pořadím podle priority.
  • Omezování četnosti. Limity počtu spuštění pro každou obslužnou rutinu v posuvném časovém okně.
  • Opakované úlohy. Plánování podle intervalu a cron s nastavitelnými pravidly překryvu (Povolit, Přeskočit, Zařadit do fronty).
  • Zrušení workflow. Rušte běžící workflow a spouštějte registrované obslužné rutiny pro úklid.
  • Prořezávání stavu. Automaticky odstraňujte staré výstupy kroků, aby byl rozsáhlý stav workflow lépe spravovatelný.
  • Souběh workerů. --workers=N spouští více procesů s automatickým restartem po pádu.
  • Plná pozorovatelnost. Záznamy v databázi, metriky pro jednotlivé obslužné rutiny a webhooky událostí.
  • Testovací nástroje. QueueFake zaznamenává odeslané úlohy a dávky pro ověřování v jednotkových testech.
  • Atributy PHP. #[QueuetyHandler('name')] umožňuje registraci obslužných rutin bez konfigurace.

Jak to funguje

Workeři běží v dlouhodobém procesu WP-CLI a přebírají úlohy přímo z MySQL. Řádky fronty, stav workflow, protokoly, dávky, signály a části streamu jsou uloženy v MySQL, takže restarty workerů nezpůsobí ztrátu stavu orchestrace.

Workflow rozdělují dlouhotrvající práci na kroky. Výstup každého kroku se ukládá do sdíleného úložiště stavu v databázi. Pokud PHP během kroku skončí, worker tento krok zopakuje se zachováním veškerého předchozího stavu. Hranice kroku je jediná transakce MySQL: aktualizace stavu, dokončení úlohy a zařazení dalšího kroku do fronty proběhnou atomicky.

Kód
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

Požadavky

  • PHP 8.2 nebo novější
  • WordPress 6.4 nebo novější
  • MySQL 8.0+ nebo MariaDB 10.6+, protože workeři přebírají úlohy pomocí SELECT ... FOR UPDATE SKIP LOCKED
  • mysqli nebo pdo_mysql v runtime PHP, který načítá WordPress a WP-CLI
  • WP-CLI pro spouštění vyhrazených workerů s wp queuety work
  • Rozšíření pcntl a posix PHP pro pooly workerů (--workers, --min-workers, --max-workers)

Pokyny k instalaci najdete v části Začínáme.