Queues / Async-job — webhook-delivery háttér-feldolgozó

D1-backed job-queue exponential-backoff retry-policy-val + HMAC-aláírt webhook-delivery. Email-küldés, PDF-gen, Stripe-handler, AI-pipeline.

A Queues plugin egy webhook-delivery-alapú async-job-runner: beküldesz egy JSON-payload-ot REST-en, mi POST-oljuk a saját webhook-URL-edre exponential-backoff retry-policy-val és opcionális HMAC-aláírással.

1. Mire jó?

Email-küldés: ne blokkold a request-et az SMTP-vel — push job-ot, válasz instant
PDF-generálás: bonyolult layout 5-10 mp, queue-be tedd, callback-re dolgozz fel
Stripe-webhook-handling: idempotens replay, ha a saját feldolgozód lassul
AI-pipeline: chunked LLM-feldolgozás, retry, dead-letter
Kampány-batch: 10 000 user → 10 000 job, fokozatosan POST-olva 25/perc

2. Aktiválás

/app/plugins → Queues / Async-job → ”+ Aktiválom”. Free: 1 queue / 100k job/hó · start 990 Ft 5q/1M · pro 4990 Ft 25q/10M.

3. Új queue

/app/queues → ”➕ Új queue”:

Név (UI-only): “Email küldés”
Webhook-URL (https-only): a saját feldolgozó-endpoint
HMAC-titok (opcionális): SHA-256 aláírás X-PromNET-Signature header-ben
Max retry: 0-10, default 3

⚠️ Tiltott webhook-host-ok: localhost, 169.254.169.254 (CF metadata), RFC1918 IP-k, .internal/.local TLD — SSRF-védelem.

4. Job beküldés

PAT-tokennel (scope: queues:write):

curl -X POST https://promnet.hu/api/queues/<queue_id>/jobs \
  -H "Authorization: Bearer promnet_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {"to":"[email protected]","subject":"Hello"},
    "delay_seconds": 0
  }'

Válasz: {"ok":true,"job":{"id":"qjob_...","status":"pending","scheduled_at":1730890000}}

A delay_seconds opcionális (max 86400 = 1 nap), így ütemezett-job is megy.

5. Mit kap a webhook-ed?

POST request, HTTPS:

POST https://your-app.com/queue-worker
Content-Type: application/json
X-PromNET-Job-Id: qjob_...
X-PromNET-Attempt: 1
X-PromNET-Signature: sha256=<hex>   (ha HMAC-titok beállítva)

{"to":"[email protected]","subject":"Hello"}

Sikeres = HTTP 2xx. Bármi más → retry.

6. HMAC-aláírás verifikálás (Node.js példa)

import crypto from 'crypto';

function verifyPromNetSignature(rawBody, signatureHeader, secret) {
  const sig = signatureHeader?.replace('sha256=', '') ?? '';
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex'));
}

app.post('/queue-worker', (req, res) => {
  const raw = req.rawBody.toString('utf8');
  if (!verifyPromNetSignature(raw, req.header('X-PromNET-Signature'), process.env.QUEUE_SECRET)) {
    return res.status(401).send('invalid signature');
  }
  // feldolgozás...
  res.status(200).send('ok');
});

7. Retry-policy

Sikeres (2xx) → completed státusz, kész
Hiba (non-2xx vagy network-fail) → retry exponential backoff:
- 1. retry: 1 perc múlva (2^1 × 30s = 60s)
- 1. retry: 2 perc
- 1. retry: 4 perc
- 1. retry: 8 perc
- … max 1 óra (cap)
Max retry után → dead (dead-letter), nem próbáljuk újra

8. Drainer

A cron-runner percenként 25 job-ot dolgoz fel queue-tól függetlenül. Throughput-cap: ~1500 job/perc / fiók.

9. Job-list szűrés

A /app/queues/<id> oldalon 4-bucket statisztika (pending / in_flight / completed / dead) + szűrhető lista. Részletek: payload + last_error.

10. Limit-ek

Payload-méret: 64 KB / job
Webhook-protokoll: https-only
Max-retries: 10
Havi job-quota: tier szerint (100k / 1M / 10M)

← Felhő tárhely Frissítve: 2026. 05. 07.