Johdanto

Queuety on WordPress-lisäosa, joka tarjoaa nopean työjonon, pysyvän työnkulkujärjestelmän ja pysyvän tilakoneympäristön. Työntekijät varaavat työt suoraan kohteesta MySQL ja käsittelevät ne pitkäkestoisessa WP-CLI-prosessissa. PHP-ympäristö, joka lataa WordPress ja WP-CLI, tarvitsee joko mysqli tai pdo_mysql.

Miksi Queuety?

WordPress-järjestelmässä ei ole varsinaista taustatyöjärjestelmää. wp_cron käynnistyy vain sivukäyntien yhteydessä. Action Schedulerin oletusajuri toimii WP-Cron- ja loopback-HTTP-pyyntöjen varassa, ja käsittelee erissä enintään 30 sekuntia kerrallaan. 60 sekuntia kestävä LLM-API-kutsu päättyy PHP:n 30 sekunnin aikakatkaisuun. Monivaiheisia prosesseja ei voi suorittaa niin, että ne selviäisivät kaatumisista ja jatkaisivat siitä, mihin jäivät.

Queuety ratkaisee tämän kolmella perusrakenteella:

1. Työt taustatyöhön, joka suoritetaan ilman odotusta
2. Työnkulut pysyviin, monivaiheisiin prosesseihin
3. Tilakoneet pitkäkestoisten, tapahtumaohjattujen elinkaaritilojen mallintamiseen

Pikaesimerkki

Lähetä työ suoritettavaksi nykyaikaisella API-tavalla:

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!' );

Tai käytä perinteistä käsittelijänimen määrittelyä:

use Queuety\Queuety;

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

Suorita pysyvä työnkulku:

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

Mallinna pitkäkestoinen istunto tilakoneella:

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

Käynnistä työntekijä:

wp queuety work

Jos rakennat agenttityyppistä järjestelmää, aloita Agenttien orkestroinnista. Siinä näytetään, miten suunnittelija- ja suorittajavirrat, ihmisen tekemän tarkistuksen vaiheet ja työnkulkujen väliset odotukset toimivat yhdessä.

Jos järjestelmä on tapahtumaohjattu ja pitkäikäinen, tutustu ensin Tilakoneisiin työnkulkujen rinnalla.

Jos haluat esimerkkejä päästä päähän -integraatioista, katso Esimerkit. Niihin sisältyy nyt Neuron-pohjaisia malleja palveluntarjoajan vaihtamiseen, suoratoistoon, muistia hyödyntäviin tarkistusten uusintoihin ja riippuvaisiin työnkulkuihin.

Jos haluat käynnistää työnkulkuja WordPress-toimialuetapahtumista, kuten save_post, katso Toimintojen käynnistimet.

Jos haluat käyttää tietokantapohjaista suoritusympäristöä WordPressn ulkopuolella, katso Itsenäinen käyttö.

Keskeiset erot

• Nopea suoritus. Työntekijät käyttävät jonoa suoraan kohteesta MySQL ja välttävät pyyntökohtaisen cron-mallin, joka hidastaa taustatyötä kohteessa WordPress.
• Pysyvät työnkulut. Monivaiheiset prosessit, joiden pysyvä tila säilyy PHP-aikakatkaisujen, kaatumisten ja uudelleenyritysten yli. Jokainen vaiheraja on atominen MySQL-tapahtuma.
• Eksplisiittiset tilakoneet. Mallinna keskusteluistuntoja, hyväksyntöjä ja muita pitkäkestoisia elinkaaria nimetyillä tiloilla, vartioiduilla siirtymillä, jonotetuilla tilaan siirtymisen toiminnoilla ja pysyvillä tapahtuma-aikajanoilla.
• Nykyaikainen työn lähetys API. Itsenäiset työluokat, joissa on Dispatchable-ominaisuus, tyypitetyt konstruktoriominaisuudet hyötykuormana sekä luokassa määritellyt $tries/$timeout/$backoff. readonly-luokka ei voi antaa näille ominaisuuksille oletusarvoja, joten määritä ne tavallisessa luokassa readonly-merkityillä ylennetyillä konstruktoriominaisuuksilla.
• Väliohjelmistoputki. Kerrosmallinen väliohjelmisto nopeusrajoitukseen, poikkeusten rajoittamiseen, yksilöllisiin töihin ja mukautettuun logiikkaan. Määritetään työkohtaisesti middleware()-metodilla.
• Suoratoistovaiheet. StreamingStep-rajapinta tuottaa osia, jotka tallennetaan heti tietokantaan. Uudelleenyrityksen yhteydessä aiemmin tallennetut osat annetaan, jotta suoratoistoa voidaan jatkaa keskeytyskohdasta. Ihanteellinen LLM-vastauksille ja suurille latauksille.
• Liitettävä välimuistikerros. CacheFactory tunnistaa automaattisesti APCu:n tai käyttää muistissa olevaa välimuistia. Mukautetut taustajärjestelmät toteuttavat Contracts\Cache-rajapinnan. Tätä käytetään sisäisesti nopeusrajoittimen hakuihin ja jonotilaan.
• Eräkäsittely ja ketjutus. Lähetä työryhmiä then/catch/finally-takaisinkutsuilla ja edistymisen seurannalla tai ketjuta työt niin, että kukin riippuu edellisen valmistumisesta.
• Pysyvät viiveet ja odotukset. delay() lisää prosessin uudelleenkäynnistyksistä selviävät viiveet. wait_for_signal(), wait_for_signals(), wait_for_approval(), wait_for_input() ja wait_for_workflow() antavat työnkulkujen odottaa ulkoisia tapahtumia tai muita työnkulkuja pitämättä PHP-prosessia käynnissä.
• Dynaaminen for-each. for_each() laajentaa ajon aikana työnkulun tilasta löytyvät haaratöiksi ja tukee kaikkien onnistumista, ensimmäistä onnistumista ja kiintiön täyttymistä odottavia suoritustiloja.
• Asynkroniset työnkulun siirrot. start_workflows() muuntaa ajon aikana löytyvät kohteet itsenäisiksi ylimmän tason työnkuluiksi, joita voi odottaa myöhemmin.
• WordPress-toimintojen käynnistimet. on_action() yhdistää ytimen tai lisäosan toimintokoukut pysyvien työnkulkujen lähetyksiin ja sisältää portitusehdot sekä idempotenssin.
• Pysyvät artefaktit. Tallenna nimetyt työnkulun tulosteet päätilasäiliön ulkopuolelle ja sisällytä ne tila-, CLI-tarkastelu-, vienti- ja toistotoimintoihin.
• Työnkulkujen suojamekanismit. version(), deterministinen määritelmän tiiviste, idempotentit lähetysavaimet ja työnkulkujen budjetit tekevät agenttityyppisten suoritusten tarkastelusta helpompaa ja vähentävät niiden toistumisen tai huomaamattoman hallitsemattoman jatkumisen riskiä.
• Resurssienhallinta. Samanaikaisuusryhmät, kustannusyksiköt, työnkulkubudjetit ja työntekijöiden hyväksyntä auttavat pitämään kalliit agenttityyppiset työt määritellyissä rajoissa.
• Vaiheiden kompensointi. compensate_with() ja compensate_on_failure() tarjoavat valmistuneiden vaiheiden palautuskoukut työnkulkujen peruuntuessa tai epäonnistuessa.
• Sykesignaalit. Pitkäkestoiset vaiheet lähettävät sykesignaaleja, jotta vanhentuneiden töiden palautusjärjestelmä ei varaa aktiivisia töitä uudelleen.
• Työnkulkujen jäljitys. Jokainen vaihesiirtymä tallennetaan syötteineen, tuloksineen, edeltävine ja seuraavine tiloineen, asiayhteyksineen, artefakteineen, osineen ja virheineen. Aikamatkavirheenkorjaus käyttää toimintoa workflow_state_at().
• Rinnakkaiset vaiheet. Suorita vaiheet samanaikaisesti ja odota kaikkien valmistumista ennen etenemistä.
• Ehdollinen haarautuminen. Siirry nimettyihin vaiheisiin aiemman tilan perusteella käyttämällä toimintoa _next_step.
• Työnkulkujen suorittaminen. Käynnistä alityönkulkuja, jotka palauttavat tulokset päätyönkululle.
• Prioriteettijonot. Neljä tasoa (Low, Normal, High, Urgent) tyypiturvallisten PHP-enumeraatioiden avulla.
• Monijonotyöntekijät. Käsittele useita jonoja yhdessä työntekijässä tiukassa prioriteettijärjestyksessä.
• Nopeusrajoitus. Käsittelijäkohtaiset suorituksen rajat liukuvalla ikkunalla.
• Toistuvat työt. Väliin ja cron-pohjaiseen aikataulutukseen mukautettavilla päällekkäisyyskäytännöillä (Allow, Skip, Buffer).
• Työnkulkujen peruutus. Peru käynnissä olevia työnkulkuja ja käynnistä rekisteröidyt siivouskäsittelijät.
• Tilan karsinta. Poista vanhoja vaihetuloksia automaattisesti, jotta suurten työnkulkujen tilat pysyvät hallittavina.
• Työntekijöiden rinnakkaisuus. --workers=N käynnistää useita prosesseja ja käynnistää kaatuneen prosessin automaattisesti uudelleen.
• Kattava havainnointi. Tietokantalokit, käsittelijäkohtaiset mittarit ja tapahtumien webhookit.
• Testausapuohjelmat. QueueFake tallentaa lähetetyt työt ja erät yksikkötestien väittämiä varten.
• PHP-attribuutit. #[QueuetyHandler('name')] käsittelijöiden rekisteröintiin ilman määrityksiä.

Näin se toimii

Työntekijät toimivat pitkäkestoisessa WP-CLI-prosessissa ja varaavat työt suoraan kohteesta MySQL. Jonorivit, työnkulkujen tila, lokit, erät, signaalit ja suoratoiston osat sijaitsevat kaikki kohteessa MySQL, joten työntekijöiden uudelleenkäynnistykset eivät kadota orkestroinnin tilaa.

Työnkulut jakavat pitkäkestoisen työn vaiheisiin. Kunkin vaiheen tulos tallennetaan tietokannan yhteiseen tilasäiliöön. Jos PHP pysähtyy kesken vaiheen, työntekijä yrittää samaa vaihetta uudelleen aiemman tilan säilyessä. Vaiheraja on yksi MySQL-tapahtuma: tilan päivitys, työn valmistuminen ja seuraavan vaiheen jonotus tapahtuvat atomisesti.

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

Vaatimukset

• PHP 8.2 tai uudempi
• WordPress 6.4 tai uudempi
• MySQL 8.0+ tai MariaDB 10.6+, koska työntekijät varaavat töitä käyttämällä toimintoa SELECT ... FOR UPDATE SKIP LOCKED
• mysqli tai pdo_mysql suoritusaikaansa, joka lataa WordPress ja WP-CLI, varten: PHP
• WP-CLI erillisten työntekijöiden suorittamiseen käyttäen toimintoa wp queuety work
• Työntekijäpooleja varten pcntl- ja posix-laajennukset PHP (--workers, --min-workers, --max-workers)

Katso asennusohjeet osiosta Aloittaminen.