# Pendahuluan

Queuety adalah plugin WordPress yang menyediakan antrean job cepat, mesin workflow persisten, dan runtime mesin status persisten. Worker mengambil job langsung dari MySQL dan memprosesnya dalam proses WP-CLI yang berjalan lama. Runtime PHP yang memuat WordPress dan WP-CLI memerlukan `mysqli` atau `pdo_mysql`.

## Mengapa Queuety?

WordPress tidak memiliki sistem job latar belakang yang sesungguhnya. `wp_cron` hanya berjalan saat halaman dikunjungi. Runner bawaan Action Scheduler berjalan melalui WP-Cron dan permintaan HTTP loopback, masing-masing memproses batch selama paling lama 30 detik. Pemanggilan API LLM yang memakan waktu 60 detik akan dihentikan oleh batas waktu 30 detik milik PHP. Tidak ada cara untuk menjalankan proses multi-langkah yang tetap bertahan saat terjadi crash dan melanjutkan dari titik terakhir.

Queuety mengatasi ini dengan tiga primitif:

1. **Job** untuk pekerjaan latar belakang yang dijalankan tanpa menunggu hasil
2. **Workflow** untuk proses multi-langkah persisten dengan status yang disimpan
3. **Mesin status** untuk status siklus hidup berbasis event yang berlangsung lama

## Contoh singkat

Kirim job menggunakan API modern:

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

Atau gunakan pendekatan nama handler klasik:

```php
use Queuety\Queuety;

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

Jalankan workflow persisten:

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

Modelkan sesi jangka panjang dengan mesin status:

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

Mulai worker:

```bash
wp queuety work
```

Jika Anda membangun sistem bergaya agen, mulailah dengan [Orkestrasi Agen](https://queuety.inline0.dev/id/docs/workflows/agent-orchestration). Bagian ini menunjukkan bagaimana alur planner/executor, gerbang tinjauan manusia, dan penantian lintas workflow saling terhubung.

Jika sistem Anda berbasis event dan berumur panjang, mulailah dengan [Mesin Status](https://queuety.inline0.dev/id/docs/state-machines) bersama workflow.

Jika Anda menginginkan contoh integrasi menyeluruh, lihat [Contoh](https://queuety.inline0.dev/id/docs/examples), yang kini mencakup pola berbasis Neuron untuk pergantian penyedia, streaming, pengulangan tinjauan berbasis memori, dan workflow yang saling bergantung.

Jika Anda ingin workflow dimulai dari event domain WordPress seperti `save_post`, lihat [Pemicu Aksi](https://queuety.inline0.dev/id/docs/features/action-triggers).

Jika Anda ingin menggunakan runtime berbasis DB di luar WordPress, lihat [Penggunaan Mandiri](https://queuety.inline0.dev/id/docs/features/standalone-use).

## Pembeda utama

- **Eksekusi cepat.** Worker menggunakan akses langsung ke antrean MySQL dan menghindari pola cron per permintaan yang memperlambat pekerjaan latar belakang di WordPress.
- **Alur kerja tahan lama.** Proses multi-langkah dengan status persisten yang bertahan dari batas waktu PHP, crash, dan percobaan ulang. Setiap batas langkah adalah transaksi MySQL yang atomik.
- **Mesin status eksplisit.** Modelkan sesi chat, persetujuan, dan siklus hidup jangka panjang lainnya dengan status bernama, transisi yang dibatasi, tindakan masuk status yang diantrekan, dan linimasa peristiwa yang tahan lama.
- **Dispatch modern API.** Kelas job mandiri dengan trait `Dispatchable`, properti konstruktor bertipe sebagai payload, serta `$tries`/`$timeout`/`$backoff` yang dideklarasikan pada kelas. Kelas `readonly` tidak dapat memberikan nilai default untuk properti ini, jadi deklarasikan pada kelas biasa dengan properti konstruktor promoted readonly.
- **Pipeline middleware.** Middleware bergaya onion untuk pembatasan laju, pembatasan pengecualian, job unik, dan logika khusus. Dideklarasikan per job melalui metode `middleware()`.
- **Langkah streaming.** Antarmuka `StreamingStep` menghasilkan potongan yang langsung disimpan ke database. Saat dicoba ulang, potongan yang sebelumnya tersimpan diberikan agar stream dapat dilanjutkan dari bagian terakhir. Ideal untuk respons LLM dan unduhan besar.
- **Lapisan cache yang dapat dipasang.** `CacheFactory` mendeteksi APCu secara otomatis atau menggunakan cache dalam memori sebagai cadangan. Backend khusus mengimplementasikan `Contracts\Cache`. Digunakan secara internal untuk pencarian pembatas laju dan status antrean.
- **Batch dan rantai.** Dispatch kelompok job dengan callback `then`/`catch`/`finally` dan pelacakan progres, atau rangkai job secara berurutan sehingga setiap job bergantung pada penyelesaian job sebelumnya.
- **Penundaan dan penantian tahan lama.** `delay()` menambahkan penundaan yang aman saat proses dimulai ulang. `wait_for_signal()`, `wait_for_signals()`, `wait_for_approval()`, `wait_for_input()`, dan `wait_for_workflow()` memungkinkan alur kerja berhenti sementara menunggu peristiwa eksternal atau alur kerja lain tanpa menjaga PHP tetap hidup.
- **For-each dinamis.** `for_each()` memperluas pekerjaan cabang yang ditemukan saat runtime dari status alur kerja dan mendukung mode penyelesaian semua berhasil, berhasil pertama, dan kuorum.
- **Serah terima alur kerja asinkron.** `start_workflows()` mengubah item yang ditemukan saat runtime menjadi alur kerja tingkat atas yang independen dan dapat ditunggu kemudian.
- **Pemicu tindakan WordPress.** `on_action()` memetakan hook tindakan inti atau plugin ke dispatch alur kerja tahan lama dengan gating dan idempotensi.
- **Artefak tahan lama.** Simpan output alur kerja bernama di luar kantong status utama dan sertakan dalam pemeriksaan status, CLI, ekspor, dan pemutaran ulang.
- **Pagar pengaman alur kerja.** `version()`, hash definisi deterministik, kunci dispatch idempoten, dan anggaran alur kerja memudahkan pemeriksaan proses bergaya agen serta mengurangi risiko duplikasi atau berjalan tanpa kendali secara diam-diam.
- **Manajemen sumber daya.** Grup konkurensi, unit biaya, anggaran alur kerja, dan penerimaan worker membantu menjaga pekerjaan mahal bergaya agen tetap dalam batas yang ditentukan.
- **Kompensasi langkah.** `compensate_with()` dan `compensate_on_failure()` menyediakan hook rollback untuk langkah yang telah selesai saat alur kerja dibatalkan atau gagal.
- **Heartbeat.** Langkah yang berjalan lama mengirim heartbeat untuk mencegah sistem pemulihan job usang mengambil alih pekerjaan yang masih aktif.
- **Pelacakan alur kerja.** Setiap transisi langkah dicatat bersama input, output, status sebelum/sesudah, konteks, artefak, potongan, error, dan debugging perjalanan waktu melalui `workflow_state_at()`.
- **Langkah paralel.** Jalankan langkah secara bersamaan dan tunggu semuanya selesai sebelum melanjutkan.
- **Percabangan bersyarat.** Lewati ke langkah bernama berdasarkan status sebelumnya menggunakan `_next_step`.
- **Jalankan Alur Kerja.** Mulai alur kerja anak yang mengirimkan hasil kembali ke induknya.
- **Antrean prioritas.** Empat tingkat (Low, Normal, High, Urgent) melalui enum PHP yang aman terhadap tipe.
- **Worker multi-antrean.** Memproses beberapa antrean dengan urutan prioritas ketat dalam satu worker.
- **Pembatasan laju.** Batas eksekusi per handler dengan jendela geser.
- **Job berulang.** Penjadwalan berbasis interval dan berbasis cron dengan kebijakan tumpang tindih yang dapat dikonfigurasi (Allow, Skip, Buffer).
- **Pembatalan alur kerja.** Batalkan alur kerja yang berjalan dan picu handler pembersihan yang terdaftar.
- **Pemangkasan status.** Hapus output langkah lama secara otomatis agar status alur kerja besar tetap mudah dikelola.
- **Konkurensi worker.** `--workers=N` membuat beberapa proses dengan mulai ulang otomatis saat terjadi crash.
- **Observabilitas penuh.** Pencatatan database, metrik per handler, dan webhook peristiwa.
- **Utilitas pengujian.** `QueueFake` mencatat job dan batch yang di-dispatch untuk assertion dalam pengujian unit.
- **Atribut PHP.** `#[QueuetyHandler('name')]` untuk pendaftaran handler tanpa konfigurasi.

## Cara kerjanya

Worker berjalan di dalam proses WP-CLI yang berumur panjang dan mengambil job langsung dari MySQL. Baris antrean, status alur kerja, log, batch, sinyal, dan potongan streaming semuanya tersimpan di MySQL, sehingga mulai ulang worker tidak menghilangkan status orkestrasi.

Alur kerja membagi pekerjaan yang berjalan lama menjadi beberapa langkah. Setiap langkah menyimpan outputnya ke kantong status bersama di database. Jika PHP mati di tengah langkah, worker akan mencoba ulang langkah tersebut dengan semua status sebelumnya tetap utuh. Batas langkah merupakan satu transaksi MySQL: pembaruan status, penyelesaian job, dan pengantrean langkah berikutnya semuanya terjadi secara atomik.

```
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
```

## Persyaratan

- PHP 8.2 atau yang lebih baru
- WordPress 6.4 atau yang lebih baru
- MySQL 8.0+ atau MariaDB 10.6+, karena worker mengambil job dengan `SELECT ... FOR UPDATE SKIP LOCKED`
- `mysqli` atau `pdo_mysql` di runtime PHP yang memuat WordPress dan WP-CLI
- WP-CLI untuk menjalankan worker khusus dengan `wp queuety work`
- Ekstensi `pcntl` dan `posix` PHP untuk kumpulan worker (`--workers`, `--min-workers`, `--max-workers`)

Lihat [Memulai](https://queuety.inline0.dev/id/docs/getting-started) untuk instalasi.