İş Kuyruğu ve Worker Sistemi

Bu Proje Nedir?

Kayıt formuna basan kullanıcı, hoş geldin e-postası gönderilirken bekler. SMTP sunucusu yavaşsa 4 saniye bekler. SMTP sunucusu düşmüşse 30 saniye bekler ve sonunda bir hata sayfası görür — üstelik kaydı başarıyla oluşturulmuş olduğu hâlde.

Sorun e-postada değil, işin yanlış yerde yapılmasındadır. Kullanıcının isteği ile e-postanın gönderilmesi aynı anda olmak zorunda değildir. İkisini ayırırsanız istek milisaniyelerde biter, e-posta arka planda gider ve gitmezse tekrar denenir.

Bu proje o ayrımı MySQL üzerinde kurulmuş bir iş kuyruğuyla gösteriyor: jobs tablosuna bir satır bırakırsınız, ayrı bir süreç (worker) o satırı kapar, çalıştırır ve siler. Hata olursa iş üstel geri çekilmeyle yeniden denenir; deneme hakkı dolarsa failed_jobs tablosuna — ölü mektup kutusuna — düşer ve orada sizi bekler.

Kuyruğun zor kısmı iş çalıştırmak değildir; aynı işin iki kez çalışmamasını sağlamaktır. İki worker aynı satırı aynı anda görürse e-posta iki kez gider. Bu proje o yarışı, koşullu bir UPDATE ile — kilitsiz ve MySQL 5.7 uyumlu — çözer.

Kimler için uygun?

• Kayıt/sipariş sonrası e-posta, rapor veya bildirim gönderenler
• "Sayfa neden 8 saniye açılıyor?" sorusuyla boğuşanlar
• Redis kurmadan, elindeki MySQL ile kuyruk isteyenler
• Yeniden deneme, geri çekilme ve ölü mektup kutusunun neden gerekli olduğunu öğrenmek isteyenler
• Bootstrap 5 üzerine kurulu, tekrar kullanılabilir bir panel kalıbı arayanlar

Klonla, database.sql'i içe aktar, çalıştır. Başka hiçbir kurulum adımı yok. Composer yok, npm yok, Redis yok.

Bu proje, Çılgın Yazılım Kütüphanesi altında yayınlanan açıklamalı, üretime hazır örneklerden biridir.

---

Bir işin hayatı

  push()                    reserve()                 handle()
    │                          │                          │
    ▼                          ▼                          ▼
┌────────┐   zamanı geldi  ┌──────────┐   başarılı   ┌─────────┐
│BEKLİYOR│ ──────────────► │ ÇALIŞIYOR│ ───────────► │  SİLİN  │
└────────┘                 └──────────┘              └─────────┘
    ▲                          │
    │                          │ hata
    │                          ▼
    │                     deneme < max ?
    │                       │        │
    │  10 sn → 20 sn → 40sn │ evet   │ hayır
    └───────────────────────┘        ▼
       (üstel geri çekilme)    ┌──────────────┐
                               │ BAŞARISIZ    │  ölü mektup kutusu
                               │ failed_jobs  │  → "Yeniden dene" ile geri döner
                               └──────────────┘

  Worker çöktüyse:  ÇALIŞIYOR durumunda 5 dakikadan uzun kalan iş
                    TAKILMIŞ sayılır → recoverStuck() onu BEKLİYOR'a döndürür

Dört durum, iki sütundan okunur:

---

Kritik Kararlar

1. Aynı işi iki worker alamaz — kilit kullanmadan

En sık yapılan hata şudur:

// YANLIŞ: iki worker aynı satırı görebilir
$job = $db->query('SELECT * FROM jobs WHERE reserved_at IS NULL LIMIT 1')->fetch();
$db->exec("UPDATE jobs SET reserved_at = NOW() WHERE id = {$job['id']}");

İki worker SELECT'i aynı anda çalıştırırsa ikisi de aynı satırı alır ve e-posta iki kez gider. "Önce bak, sonra yaz" her zaman bir yarış koşuludur.

Doğrusu, kontrolü ve yazmayı tek ifadeye koymaktır:

UPDATE jobs
   SET reserved_at = NOW(), reserved_by = :worker, attempts = attempts + 1
 WHERE id = :id
   AND reserved_at IS NULL        -- ◄── kritik satır

reserved_at IS NULL koşulu UPDATE'in içindedir; veritabanı satırı yazarken zaten kilitler. İki worker aynı satırı denerse yalnızca birinin rowCount() değeri 1 olur:

if ($claim->rowCount() === 0) {
    continue;   // başka bir worker önce davrandı, sıradakine geç
}

Uygulama önce 5 aday satır okur, sonra bunları sırayla kapmayı dener. Böylece iki worker çakışsa bile boş dönmez, listedeki bir sonrakine geçer.

2. SELECT ... FOR UPDATE SKIP LOCKED neden kullanılmadı?

Kullanılabilirdi ve MySQL 8.0'da daha zarif olurdu. Ama SKIP LOCKED, MySQL 5.7 ve MariaDB 10.5'ten önceki sürümlerde yoktur — paylaşımlı hosting'lerin büyük kısmı hâlâ orada.

Koşullu UPDATE yöntemi her sürümde çalışır, ek bir işlem (transaction) yönetimi gerektirmez ve aynı güvenceyi verir. Taşınabilirlik, buradaki zarafetten daha değerli görüldü.

3. Yeniden deneme üstel geri çekilmeyle yapılır

Hata alan işi hemen tekrar denemek, çoğu zaman zarar verir: düşmüş bir SMTP sunucusuna saniyede üç istek göndermek onu daha da boğar.

// app/Core/Queue.php — release()
$delay = min(3600, 10 * (2 ** ($attempts - 1)));

Bekleme süresi her denemede ikiye katlanır: 10 sn → 20 sn → 40 sn → … ve bir saatte tavanlanır. Tavan olmasaydı 20. deneme 60 gün sonraya düşerdi.

4. Deneme hakkı dolan iş silinmez, taşınır

Üç kez denenip başaramayan bir işi silmek, veriyi kaybetmektir. Bu iş failed_jobs tablosuna taşınır ve orada sizi bekler.

Neden ayrı tablo? Çünkü jobs tablosu worker'ın en sıcak sorgusudur; saniyede birkaç kez taranır. Başarısız işleri orada tutmak, o tabloyu asla temizlenmeyen ölü satırlarla şişirirdi.

Servisi düzelttiğinizde "Yeniden dene" düğmesi işi geri gönderir — kaybolmuş bir e-posta yerine, gönderilmeyi bekleyen bir e-postanız olur.

5. Hata metni saklanır, yığın izi saklanmaz

'error' VARCHAR(2000) NOT NULL DEFAULT ''

Yığın izi dosya yollarınızı, klasör yapınızı ve sınıf adlarınızı içerir. Veritabanı bir gün sızarsa saldırgana hazır bir harita vermiş olursunuz. Hata mesajı sorunu anlamaya yeter.

6. Takılmış iş ile çalışan iş ayrı gösterilir

Worker çökerse (sunucu yeniden başladı, bellek doldu, deploy sırasında kapatıldı) reserved_at dolu kalır ve iş sonsuza kadar "çalışıyor" görünür — oysa onu çalıştıran kimse yoktur.

Bu yüzden 5 dakikadan eski rezervasyonlar arayüzde ayrı bir Takılmış rozetiyle gösterilir. Eşik Queue::STUCK_AFTER sabitindedir ve hem rozet hem kurtarma sorgusu onu kullanır. İkisi ayrışsaydı, ekranda takılmış görünen bir işi kurtarma düğmesi bulamazdı.

7. Payload JSON, iş sınıfı ise tam sınıf adı

job_class:  App\Jobs\SendEmailJob
payload:    {"to":"...","subject":"..."}

İşin ne olduğu ile neyle çalışacağı ayrılır. Worker sınıfı yükler, Job sınıfından türediğini doğrular ve handle($payload, $db) çağırır:

if (!class_exists($class) || !is_subclass_of($class, Job::class)) {
    // tanınmayan sınıf çalıştırılmaz
}

Bu kontrol güvenliğin parçasıdır: job_class alanına elle bir değer yazılsa bile rastgele bir sınıf örneklenip çalıştırılamaz.

8. Neden Redis yok?

Redis kuyruk için mükemmeldir ama bir bağımlılıktır: kurulacak, izlenecek, yedeklenecek ve paylaşımlı hosting'de çoğu zaman bulunmayan bir servistir.

Günde on binlerce işe kadar MySQL fazlasıyla yeter — özellikle idx_jobs_reserve bileşik indeksi varken. Üstelik işleriniz veritabanı yedeğinizin içinde durur; ayrıca yedeklemeniz gereken ikinci bir depo olmaz.

Milyonlarca işe çıktığınızda Redis'e geçin. O gün gelene kadar kurmayın.

---

Neler Var?

Kuyruk çekirdeği

• push() — iş bırak, gecikme verilebilir
• reserve() — yarışsız kapma (koşullu UPDATE)
• release() — üstel geri çekilmeyle iade
• fail() — ölü mektup kutusuna taşı
• recoverStuck() — çökmüş worker'ın kilidini aç
• Adlandırılmış kuyruklar (default, reports, …)
• İş başına ayarlanabilir deneme hakkı

Worker (CLI)

• --queue= belirli kuyruğu dinle
• --max=N N iş sonra dur
• --once tek iş çalıştır ve çık
• --sleep=N boşta bekleme süresi
• PHP_SAPI kontrolü — tarayıcıdan çalışmaz

Panel

• Dört canlı sayaç (bekleyen/çalışan/ertelenmiş/başarısız)
• Kuyruk listesi, dört durumlu rozet
• Başarısız işler sayfası, yeniden dene / unut
• Takılanları kurtar düğmesi
• Panelden iş bırakma (üç örnek iş türü)
• Worker çalışmıyorsa uyarı şeridi

Ortak altyapı

• Oturum girişi, "beni hatırla", hız sınırı, CSRF
• CSP (script-src 'self'), X-Frame-Options: DENY
• Açık / koyu tema, hesaba kayıtlı
• Mobilde alt navigasyon, yatay kaydırma yok
• Kullanıcılar sayfasında canlı filtre (JS kapalıysa da çalışır)
• Sıfır bağımlılık

---

Worker'ı çalıştırmak

İşler ancak bir worker çalışıyorken işlenir. Proje klasöründe ayrı bir terminal açın:

php bin/worker.php

Süreç kuyruğu dinlemeye başlar ve iş geldikçe çalıştırır. Durdurmak için Ctrl+C.

Seçenekler

Canlı sunucuda

Worker bir gün mutlaka ölür: bellek dolar, deploy sırasında kapatılır, sunucu yeniden başlar. Bu yüzden onu kendiliğinden yeniden başlatan bir yönetici altında çalıştırın.

systemd (/etc/systemd/system/cy-worker.service):

[Unit]
Description=CY Queue Worker
After=network.target mysql.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/uygulama
ExecStart=/usr/bin/php bin/worker.php
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now cy-worker

supervisor veya cPanel kullanıyorsanız: her dakika çalışan bir cron kurun ve --once verin.

* * * * * cd /var/www/uygulama && php bin/worker.php --once >> /dev/null 2>&1

Deploy sırasında: worker'ı önce durdurun, kodu güncelleyin, sonra başlatın. Aksi hâlde çalışan süreç eski kodu, yeni gelen işler yeni şemayı kullanır.

---

Kendi işinizi yazmak

Bir iş, Job sınıfından türeyen ve iki metot uygulayan bir sınıftır.

<?php
namespace App\Jobs;

use PDO;

final class SendSmsJob extends Job
{
    /** Arayüzde ve günlükte görünecek ad. */
    public static function label(): string
    {
        return 'SMS gönderimi';
    }

    /** Kaç kez denensin? (varsayılan 3) */
    public static function maxAttempts(): int
    {
        return 5;
    }

    /**
     * İşin kendisi. İstisna fırlatırsa iş başarısız sayılır ve
     * geri çekilmeyle yeniden denenir.
     */
    public function handle(array $payload, PDO $db): void
    {
        $numara = (string) ($payload['numara'] ?? '');

        if ($numara === '') {
            // Kalıcı hata: tekrar denemenin anlamı yok.
            throw new \InvalidArgumentException('Numara boş.');
        }

        // ... SMS sağlayıcısına istek ...
    }
}

Kuyruğa bırakmak:

(new Queue($pdo))->push(SendSmsJob::class, ['numara' => '5xx…']);

// 10 dakika sonra çalışsın:
(new Queue($pdo))->push(SendSmsJob::class, ['numara' => '5xx…'], Queue::DEFAULT, 600);

// Ayrı bir kuyruğa:
(new Queue($pdo))->push(SendSmsJob::class, [...], 'sms');

İki kural:

1. handle() yeniden çalıştırılabilir olsun. İş, ağ koptuğu için tam bittiği anda da başarısız sayılabilir ve tekrar denenir. "Bu işi ikinci kez çalıştırırsam ne olur?" sorusunun cevabı zararsız olmalıdır — sipariş iki kez oluşturulmamalıdır.
2. Payload'a nesne değil, kimlik koyun. ['user_id' => 42] yazın, kullanıcı nesnesinin tamamını değil. İş çalıştığında veri değişmiş olabilir; taze hâlini handle() içinde okuyun.

---

Güvenlik: Neyi, Nasıl Kapattık?

---

Yapılandırma

APP_DEBUG=true          # silerseniz: yerelde açık, canlıda kapalı
APP_URL=
APP_PRETTY_URLS=true    # false → /index.php?r=queue

DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=cy_queue_worker
DB_USER=root
DB_PASS=
••••••••

Kuyruk davranışını belirleyen sabitler koddadır:

| Sabit | Yeri | Varsayılan | Ne yapar |
|---|---|---|---|
| `Queue::DEFAULT` | `app/Core/Queue.php` | `'default'` | Kuyruk adı verilmezse kullanılan |
| `Queue::STUCK_AFTER` | `app/Core/Queue.php` | `300` | Kaç saniye sonra iş "takılmış" sayılır |
| `Job::maxAttempts()` | `app/Jobs/Job.php` | `3` | Deneme hakkı (iş sınıfında değiştirilebilir) |
| geri çekilme | `Queue::release()` | `10 · 2ⁿ`, tavan `3600` | Yeniden deneme aralığı |

> **`STUCK_AFTER`'ı işlerinize göre ayarlayın.** İşleriniz dakikalarca sürüyorsa 300 saniye çok kısadır: hâlâ çalışan bir iş "takılmış" sayılıp ikinci kez kuyruğa girebilir.

---

## Dosya Yapısı

queue-worker-system/
│
├── index.php Ön denetleyici — TEK giriş noktası
├── database.sql Şema + örnek kuyruk verisi
├── .env.example
│
├── bin/
│ ├── worker.php ★ Kuyruk işçisi (CLI)
│ └── .htaccess Web erişimine kapalı
│
├── app/
│ ├── Core/
│ │ ├── Queue.php ★ push · reserve · release · fail · recoverStuck
│ │ ├── Worker.php ★ Döngü, sinyal yakalama, sınıf doğrulama
│ │ ├── Auth.php Giriş, "beni hatırla"
│ │ ├── Session.php Sertleştirilmiş oturum
│ │ ├── Csrf.php Jeton + hash_equals
│ │ ├── RateLimiter.php Giriş denemesi sınırı
│ │ ├── Database.php PDO (EMULATE_PREPARES = false)
│ │ ├── Env.php .env okuyucu + isLocalHost()
│ │ └── ...
│ │
│ ├── Jobs/
│ │ ├── Job.php ★ Soyut taban: handle() · label() · maxAttempts()
│ │ ├── SendEmailJob.php Örnek: e-posta gönderimi
│ │ ├── ReportJob.php Örnek: rapor üretimi (dosyaya yazar)
│ │ └── FlakyJob.php Örnek: %70 hata veren "kararsız" iş
│ │
│ ├── Http/Controllers/ Auth · Dashboard · Queue · User
│ ├── Repositories/ JobRepository · UserRepository · ActivityRepository
│ └── Support/helpers.php
│
├── storage/ Worker çıktıları (web'e kapalı)
├── views/ Düzenler, kuyruk ve başarısız iş sayfaları
├── assets/ css · js · images
├── config/config.php
├── routes/web.php
└── docs/screenshots/

---

## Nasıl Çalışıyor?

WEB İSTEĞİ AYRI SÜREÇ (worker)
────────── ───────────────────
Kullanıcı "Kaydet"e basar php bin/worker.php
│ │
▼ ▼
Queue::push(SendEmailJob::class, [...]) ┌─► reserve('default', $workerId)
│ │ │
│ INSERT INTO jobs (...) │ │ 1) 5 aday satır SELECT
│ available_at = NOW() + gecikme │ │ WHERE reserved_at IS NULL
│ │ │ AND available_at <= NOW()
▼ │ │
Yanıt DÖNER (milisaniyeler) │ │ 2) her aday için koşullu UPDATE
Kullanıcı beklemez │ │ SET reserved_at = NOW()
│ │ WHERE id=? AND reserved_at IS NULL
│ │
│ │ rowCount() === 1 ?
│ │ hayır → sıradaki adaya geç
│ │ evet → iş benim
│ ▼
│ Job::handle($payload, $db)
│ │
│ ├─ başarılı → Queue::delete()
│ │
│ └─ istisna → deneme < max ?
│ │ │
│ evet │ │ hayır
│ ▼ ▼
│ Queue::release() Queue::fail()
│ available_at = failed_jobs'a
│ NOW() + 10·2ⁿ TAŞINIR
│ │
└─────────────┘
(kuyruğa geri döner)

---

## Veritabanı Şeması

### `jobs` — bekleyen ve çalışan işler

| Sütun | Tip | İşi |
|---|---|---|
| `id` | BIGINT UNSIGNED | Birincil anahtar |
| `queue` | VARCHAR(60) | Kuyruk adı; farklı önceliklere ayrı worker atanabilir |
| `job_class` | VARCHAR(190) | Çalıştırılacak sınıf (`App\Jobs\SendEmailJob`) |
| `payload` | TEXT | İşin verisi (JSON) |
| `attempts` / `max_attempts` | SMALLINT | Kaç kez denendi / en fazla kaç kez |
| `available_at` | DATETIME | "Bu zamandan önce çalıştırma" — gecikme **ve** geri çekilme |
| `reserved_at` / `reserved_by` | DATETIME / VARCHAR | Kapan worker ve kapma anı; `NULL` = boşta |
| `last_error` | VARCHAR(1000) | Son hata; iş hâlâ kuyrukta ama sorunlu |
| `created_at` | DATETIME | Bırakılma anı |

**Tek indeks, en sıcak sorgu için:**

```sql
KEY idx_jobs_reserve (queue, reserved_at, available_at)

Worker saniyede birkaç kez şunu sorar:

WHERE queue = ? AND reserved_at IS NULL AND available_at <= NOW() ORDER BY id

Bu indeks olmadan her sorgu tüm tabloyu tarar; kuyruk büyüdükçe sistem yavaşlar. Sütun sırası rastgele değildir: önce eşitlik (queue), sonra NULL kontrolü, en sonda aralık karşılaştırması.

failed_jobs — ölü mektup kutusu

---

SSS

Worker'ı sürekli açık tutmak zorunda mıyım?

Hayır, iki seçeneğiniz var.

Sürekli süreç (önerilen): php bin/worker.php bir kez başlar ve dinler. İşler saniyeler içinde işlenir. systemd veya supervisor ile yeniden başlatılmasını garanti edin.

Cron ile: her dakika php bin/worker.php --once çalıştırın. Kurulumu daha kolaydır ama işler en fazla bir dakika bekler. Paylaşımlı hosting'de genellikle tek seçenek budur.

Aynı e-posta iki kez gitti, neden?

Neredeyse her zaman şu sebeptendir: iş, gönderimi bitirdikten sonra ama satır silinmeden önce başarısız oldu (ağ koptu, süreç öldürüldü). Kuyruk onu bitmemiş sayar ve tekrar dener.

Bu, kuyrukların yapısal bir gerçeğidir: "en az bir kez" teslim garantisi verilir, "tam olarak bir kez" değil. Çözüm işin kendisindedir — handle() yeniden çalıştırıldığında zararsız olmalıdır. Gönderdiğiniz her e-postaya bir kimlik verip "bu kimlik daha önce gönderildi mi?" diye bakmak en yaygın yöntemdir.

Birden fazla worker çalıştırabilir miyim?

Evet, tasarım buna göre yapıldı. İki worker aynı satırı alamaz; koşullu UPDATE bunu garanti eder.

Farklı kuyruklara farklı worker atamak da yaygındır:

php bin/worker.php --queue=default     # hızlı işler
php bin/worker.php --queue=reports     # uzun süren raporlar

Böylece 4 dakika süren bir rapor, hoş geldin e-postasını bekletmez.

İşler birikiyor ama işlenmiyor

Sırayla kontrol edin:

1. Worker gerçekten çalışıyor mu? (ps aux | grep worker.php)
2. Doğru kuyruğu mu dinliyor? İşi reports kuyruğuna bırakıp default dinliyorsanız hiçbir şey olmaz.
3. İşler Ertelenmiş mi görünüyor? available_at gelecekteyse worker onları görmez.
4. Hepsi Takılmış mı? Bir worker çökmüş olabilir; "Takılanları kurtar" düğmesine basın.

Neden SKIP LOCKED kullanmadınız?

MySQL 5.7 ve MariaDB 10.5'ten önceki sürümlerde yoktur; paylaşımlı hosting'lerin büyük kısmı hâlâ orada.

Koşullu UPDATE yöntemi her sürümde çalışır ve aynı garantiyi verir. MySQL 8 kullandığınızdan eminseniz reserve() metodunu SKIP LOCKED ile değiştirebilirsiniz; arayüzün geri kalanı hiç değişmez.

Ölü mektup kutusu ne zaman temizlenir?

Kendiliğinden temizlenmez ve bu bilerek böyledir: başarısız bir iş, birinin bakması gereken bir olaydır.

Panelden tek tek "Unut" diyebilir veya belirli bir yaştan eskileri silen bir görev yazabilirsiniz. Silmeden önce neden başarısız olduklarına bakın; genellikle orada tek bir kök sebep vardır.

---

Canlı Ortama Alırken

• [ ] .env içinde APP_DEBUG=false (veya satırı tümüyle silin)
• [ ] Worker'ı systemd/supervisor altında çalıştırın; Restart=always olsun
• [ ] Deploy sırasında worker'ı önce durdurun, sonra başlatın
• [ ] STUCK_AFTER değerini en uzun işinizden büyük seçin
• [ ] bin/ klasörünün web'den erişilemediğini doğrulayın (403 dönmeli)
• [ ] storage/ klasörünün web'den erişilemediğini doğrulayın
• [ ] failed_jobs tablosunu izleyin — büyüyorsa bir şey bozuktur
• [ ] Veritabanı için root olmayan bir kullanıcı açın
• [ ] HTTPS zorunlu olsun
• [ ] Demo hesaplarının parolalarını değiştirin veya hesapları silin

---

Sorun Giderme

---

Yol Haritası

• [ ] İş öncelikleri (aynı kuyruk içinde sıralama)
• [ ] Zincirleme işler (biri bitince diğeri)
• [ ] Toplu iş (batch) ve ilerleme yüzdesi
• [ ] Başarısız iş sayısı eşiği aşınca e-posta uyarısı
• [ ] MySQL 8 için SKIP LOCKED sürücüsü (isteğe bağlı)

---

Katkı

Hata bildirimi ve öneriler için issue açabilirsiniz.

Lisans

MIT — ticari projelerinizde de özgürce kullanabilirsiniz.

---