Hoppa till innehåll

Introduktion

Visa som Markdown Redigera på GitHub Dokumentation på 2cc7b2b

Queuety är ett WordPress-tillägg som erbjuder en snabb jobbkö, en beständig arbetsflödesmotor och en beständig körmiljö för tillståndsmaskiner. Arbetare hämtar jobb direkt från MySQL och behandlar dem i en långvarig WP-CLI-process. Körmiljön PHP som läser in WordPress och WP-CLI behöver antingen mysqli eller pdo_mysql.

Varför Queuety?

WordPress har inget riktigt system för bakgrundsjobb. wp_cron körs bara vid sidbesök. Standardköraren för Action Scheduler använder WP-Cron och lokala HTTP-förfrågningar, där varje omgång bearbetar jobb i högst 30 sekunder. Ett API-anrop som tar 60 sekunder avbryts av tidsgränsen på 30 sekunder i PHP. Det går inte att köra processer med flera steg som överlever krascher och fortsätter där de avbröts.

Queuety löser detta med tre grundfunktioner:

  1. Jobb för bakgrundsarbete som körs utan att invänta svar
  2. Arbetsflöden för beständiga processer i flera steg med kvarvarande tillstånd
  3. Tillståndsmaskiner för långlivade, händelsestyrda livscykler

Snabbexempel

Skicka iväg ett jobb med den moderna 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!' );

Eller använd den klassiska metoden med namn på hanterare:

PHP
use Queuety\Queuety;

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

Kör ett beständigt arbetsflöde:

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

Modellera en långvarig session med en tillståndsmaskin:

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

Starta en arbetare:

Shell
wp queuety work

Om du bygger ett system med agentarkitektur kan du börja med Agentorkestrering. Där visas hur planerare och utförare, granskningssteg för människor och väntan mellan arbetsflöden hänger ihop.

Om systemet är händelsestyrt och långlivat kan du börja med Tillståndsmaskiner tillsammans med arbetsflöden.

Om du vill se exempel på integration från början till slut kan du läsa Exempel, som nu innehåller mönster baserade på Neuron för byte av leverantör, strömning, upprepade granskningar med minnesstöd och beroende arbetsflöden.

Om du vill att arbetsflöden ska starta från domänhändelser i WordPress, till exempel save_post, kan du läsa Åtgärdsutlösare.

Om du vill använda den databaskopplade körmiljön utanför WordPress kan du läsa Fristående användning.

Viktiga skillnader

  • Snabb exekvering. Arbetare använder direktåtkomst till MySQL-kön och undviker cron-mönstret per begäran som gör bakgrundsarbete långsammare i WordPress.
  • Beständiga arbetsflöden. Processer i flera steg med beständigt tillstånd som överlever PHP-tidsgränser, krascher och omförsök. Varje steggräns är en atomär MySQL-transaktion.
  • Explicita tillståndsmaskiner. Modellera chattsessioner, godkännanden och andra långlivade livscykler med namngivna tillstånd, villkorade övergångar, köade åtgärder vid tillståndsinträde och beständiga händelsetidslinjer.
  • Modern dispatch API. Fristående jobbklasser med Dispatchable-trait, typade konstruktorsegenskaper som payload och $tries/$timeout/$backoff deklarerade i klassen. En readonly-klass kan inte ge dessa egenskaper standardvärden, så deklarera dem i en vanlig klass med readonly-promoverade konstruktorsegenskaper.
  • Middleware-pipeline. Middleware i lökliknande lager för hastighetsbegränsning, undantagsbegränsning, unika jobb och anpassad logik. Deklareras per jobb via en middleware()-metod.
  • Strömningssteg. Gränssnittet StreamingStep ger segment som sparas omedelbart i databasen. Vid omförsök skickas tidigare sparade segment med så att strömmen kan fortsätta där den avbröts. Perfekt för LLM-svar och stora nedladdningar.
  • Utbytbar cache. CacheFactory identifierar automatiskt APCu eller använder en cache i minnet som reserv. Anpassade backends implementerar Contracts\Cache. Används internt för uppslagningar av hastighetsbegränsare och köstatus.
  • Batchning och kedjning. Skicka grupper av jobb med återanropen then/catch/finally och följ förloppet, eller kedja jobb sekventiellt så att varje jobb väntar på att föregående jobb slutförs.
  • Beständiga fördröjningar och väntelä­gen. delay() lägger till fördröjningar som tål omstart av processen. wait_for_signal(), wait_for_signals(), wait_for_approval(), wait_for_input() och wait_for_workflow() låter arbetsflöden pausa i väntan på externa händelser eller andra arbetsflöden utan att hålla PHP vid liv.
  • Dynamisk for-each. for_each() utökar arbetsgrenar som upptäcks vid körning utifrån arbetsflödestillståndet och stöder slutförandelägena alla lyckas, första lyckade och kvorum.
  • Asynkrona överlämningar mellan arbetsflöden. start_workflows() omvandlar objekt som upptäcks vid körning till fristående arbetsflöden på toppnivå som kan inväntas senare.
  • Utlösare för WordPress-åtgärder. on_action() mappar åtgärdshooks från kärnan eller pluginer till beständiga arbetsflödesanrop med villkorsstyrning och idempotens.
  • Beständiga artefakter. Lagra namngivna utdata från arbetsflöden utanför den huvudsakliga tillståndssamlingen och ta med dem vid statuskontroll, inspektion med CLI, export och återuppspelning.
  • Skyddsräcken för arbetsflöden. version(), en deterministisk definitionshash, idempotenta dispatch-nycklar och arbetsflödesbudgetar gör agentliknande körningar enklare att granska och minskar risken för dubbletter eller att de löper iväg obemärkt.
  • Resurshantering. Samtidighetsgrupper, kostnadsenheter, arbetsflödesbudgetar och styrning av arbetaråtkomst hjälper till att hålla kostsamt agentliknande arbete inom fastställda gränser.
  • Kompensering av steg. compensate_with() och compensate_on_failure() tillhandahåller återställningshooks för slutförda steg när arbetsflöden avbryts eller misslyckas.
  • Hjärtslag. Långvariga steg skickar hjärtslag för att hindra systemet för återställning av inaktuella jobb från att ta över aktivt arbete.
  • Spårning av arbetsflöden. Varje stegövergång registreras med indata, utdata, tillstånd före och efter, kontext, artefakter, segment, fel och felsökning genom tidsresor via workflow_state_at().
  • Parallella steg. Kör steg samtidigt och vänta tills alla har slutförts innan arbetsflödet går vidare.
  • Villkorsstyrd förgrening. Hoppa till namngivna steg utifrån tidigare tillstånd med _next_step.
  • Kör arbetsflöden. Starta underordnade arbetsflöden som skickar resultaten tillbaka till det överordnade arbetsflödet.
  • Prioritetsköer. Fyra nivåer (Low, Normal, High, Urgent) med typsäkra enum-värden i PHP.
  • Arbetare med flera köer. Behandla flera köer med strikt prioritetsordning i en och samma arbetare.
  • Hastighetsbegränsning. Begränsa körningar per hanterare med ett glidande fönster.
  • Återkommande jobb. Schemaläggning baserad på intervall och cron, med konfigurerbara principer för överlappning (Allow, Skip, Buffer).
  • Avbryta arbetsflöden. Avbryt arbetsflöden som körs och utlös registrerade rensningshanterare.
  • Tillståndsrensning. Ta automatiskt bort gamla stegutdata så att stora arbetsflödestillstånd förblir hanterbara.
  • Samtidighet för arbetare. --workers=N förgrenar flera processer och startar om dem automatiskt vid krasch.
  • Full insyn. Loggning i databasen, mätvärden per hanterare och webhookar för händelser.
  • Testverktyg. QueueFake registrerar utskickade jobb och batchar för påståenden i enhetstester.
  • PHP-attribut. #[QueuetyHandler('name')] för registrering av hanterare utan konfiguration.

Så fungerar det

Arbetare körs i en långlivad WP-CLI-process och hämtar jobb direkt från MySQL. K�rader, arbetsflödestillstånd, loggar, batchar, signaler och strömningssegment lagras alla i MySQL, så omstarter av arbetare gör inte att orkestreringstillstånd går förlorat.

Arbetsflöden delar upp långvarigt arbete i steg. Varje steg sparar sitt resultat i en gemensam tillståndspåse i databasen. Om PHP avslutas mitt i ett steg försöker arbetaren köra om det steget med alla tidigare tillstånd intakta. Steggränsen är en enda MySQL-transaktion: tillståndsuppdatering, slutförande av jobb och köläggning av nästa steg sker atomiskt.

Kod
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

Krav

  • PHP 8.2 eller senare
  • WordPress 6.4 eller senare
  • MySQL 8.0+ eller MariaDB 10.6+, eftersom arbetare hämtar jobb med SELECT ... FOR UPDATE SKIP LOCKED
  • mysqli eller pdo_mysql i körmiljön PHP som läser in WordPress och WP-CLI
  • WP-CLI för att köra dedikerade arbetare med wp queuety work
  • Tilläggen pcntl och posix PHP för arbetarpooler (--workers, --min-workers, --max-workers)

Se Kom igång för installationen.