@develit-services/notification

v4.0.0

Published

5 days ago

Microsluzba pro odesilani notifikaci (email, SMS, Slack, push). Postavena na Cloudflare Workers s D1 databazi.

0High
0Medium
0Low

kleinpetr

ffdevelit

Notification Service

Microsluzba pro odesilani notifikaci (email, SMS, Slack, push). Postavena na Cloudflare Workers s D1 databazi.

Obsah

Architektura

Sluzba se sklada z:

Akce (Actions) - RPC endpointy pro odesilani notifikaci
Queue handler - Asynchronni zpracovani notifikaci z fronty
Konektory - Abstrakce nad API externich sluzeb (Ecomail, Twilio, Slack)
Audit log - Zaznamenani vsech odeslanych notifikaci do D1

Bindings:

NOTIFICATION_D1 - Cloudflare D1 databaze
NOTIFICATIONS_QUEUE - Fronta pro asynchronni zpracovani
SECRETS_STORE - Service binding na secrets store
SLACK_WEBHOOK - Webhook URL pro Slack notifikace

Kanaly notifikaci

| Kanal | Konektor | Stav | |-------|----------|------| | Email | Ecomail | Aktivni | | SMS | Twilio | Aktivni | | Slack | Slack Webhook | Aktivni | | Webhook | WebhookConnector | Aktivni | | Push | - | Neimplementovano |

Queue processing

Notifikace lze odesilat synchronne (primo) nebo asynchronne (pres frontu).

Async flow (vychozi)

public-send-email / public-send-sms
  │
  ▼
NOTIFICATIONS_QUEUE
  │
  ▼
Queue handler (switch dle type)
  ├─ email   → _sendEmail()
  ├─ sms     → _sendSms()
  ├─ slack   → sendSlackNotification()
  ├─ webhook → _sendWebhook()
  └─ push    → _sendPushNotification() (501)
  │
  ├─ success → message.ack()
  └─ error   → message.retry() (exponential backoff, base 60s)

Sync flow

public-send-email-sync vola _sendEmail() primo bez fronty.

Queue message

{
  type: 'email' | 'sms' | 'pushNotification' | 'slack' | 'webhook'
  metadata: {
    userAgent?: string
    ip?: string
    initiator: { service: string, userId?: string }
  }
  payload: {
    email?: IEmail
    sms?: ISms
    pushNotification?: IPushNotification
    slack?: ISlack
    webhook?: IWebhook
  }
}

Konektory

Ecomail (email)

Provider pro transakcni emaily. Podporuje:

Plain text a HTML emaily (/transactional/send-message)
Template emaily s merge vars (/transactional/send-template)
Prilohy (base64, max 10 priloh, celkem 25MB)
CC, BCC, Reply-To

Omezeni: Ecomail odmita emaily s localhost v template variables - connector automaticky nahradi localhost za origin.

Twilio (SMS)

Provider pro SMS pres Twilio Messaging Service.

Slack (webhook)

Odesilani notifikaci pres Slack Incoming Webhook. Timeout 3s.

Webhook (HTTP callback)

Odesilani podepsanych HTTP POST callbacku na URL zadanou callerem. Timeout 10s.

Kazdy webhook je automaticky podepsan RSA-PKCS1-v1_5 (SHA-256) podpisem. Privatni klic se nacita ze Secrets Store (NOTIFICATION_SERVICE_WEBHOOK_SIGNING_KEY). Podpis se odesila v hlavicce X-Webhook-Signature (base64).

Generovani klicu

Privatni klic musi byt ve formatu base64(PKCS8 DER) — crypto.subtle.importKey('pkcs8', ...) nepracuje s PEM ani s PKCS1. Nasledujici jednorazovy skript vygeneruje oba klice naraz (funguje na Linuxu i macOS, bash i zsh):

PRIVATE_KEY=$(openssl genrsa 4096 2>/dev/null | openssl pkcs8 -topk8 -nocrypt -outform DER 2>/dev/null | base64 | tr -d '\n')
PUBLIC_KEY=$(echo "$PRIVATE_KEY" | base64 -d | openssl rsa -inform DER -pubout 2>/dev/null | base64 | tr -d '\n')

printf 'NOTIFICATION_SERVICE_WEBHOOK_SIGNING_KEY (ulozit do Secrets Store):\n%s\n\n' "$PRIVATE_KEY"
printf 'Public key (poskytnout prijemcum webhooku):\n%s\n' "$PUBLIC_KEY"

Rychla kontrola: base64 PKCS8 klic vzdy zacina na MII...QIBADAN (ASN.1 SEQUENCE + version 0 + rsaEncryption OID). Pokud zacina na Ls, je to omylem zakodovany PEM text — importKey spadne na Invalid PKCS8 input.

Overeni podpisu na strane prijemce

Podpis je RSA-PKCS1-v1_5 se SHA-256, odeslany v hlavicce X-Webhook-Signature jako base64 string. Overeni:

# Ulozit raw body requestu do souboru
echo -n '{"type":"payment.created","data":{...}}' > body.json

# Dekodovat podpis z hlavicky
echo -n "<hodnota X-Webhook-Signature>" | base64 -d > signature.bin

# Overit
openssl dgst -sha256 -verify webhook_public.pem -signature signature.bin body.json
# Vystup: "Verified OK" nebo "Verification Failure"

Nebo programove (Node.js):

const crypto = require('crypto')

function verifyWebhook(rawBody, signatureBase64, publicKeyBase64) {
  const publicKey = Buffer.from(publicKeyBase64, 'base64').toString('utf-8')
  const verifier = crypto.createVerify('RSA-SHA256')
  verifier.update(rawBody)
  return verifier.verify(publicKey, signatureBase64, 'base64')
}

RPC akce

Notification service je RPC worker - vsechny akce dostupne pres Cloudflare Worker binding.

Verejne akce

| Akce | Popis | |------|-------| | public-send-email | Zaradi email do fronty (async) | | public-send-email-sync | Odesle email primo (sync) | | public-send-sms | Zaradi SMS do fronty (async) | | send-slack-notification | Odesle Slack notifikaci (sync) | | send-webhook | Zaradi webhook do fronty (async) |

Interni akce

| Akce | Popis | |------|-------| | private-send-email | Odesle email pres konektor + audit log | | private-send-sms | Odesle SMS pres konektor + audit log | | private-send-webhook | Odesle webhook pres konektor + audit log | | send-push-notification | Neimplementovano (501) |

Vstupy

Vsechny akce vyzaduji metadata objekt:

metadata: {
  userAgent?: string
  ip?: string        // IPv4 nebo IPv6
  initiator: {
    service: string  // nazev volajici sluzby
    userId?: string
  }
}

Email podporuje: to, cc, bcc, replyTo, from, subject, text, html, templateId, templateVariables, attachments.

SMS podporuje: message, to.

Slack podporuje: message.

Webhook podporuje: url, payload (libovolny JSON objekt), headers (volitelne custom HTTP headers).

Audit logging

Kazdy uspesne odeslany email a SMS se zaznamenava do audit logu.

Zaznamenavane udaje: event type, IP adresa, user agent, popis (JSON vstupu), initiator service, initiator user ID.

Databazove schema

audit_log

| Sloupec | Typ | Popis | |---------|-----|-------| | id | text | UUID | | createdAt | timestamp | Cas vytvoreni | | event | text | EMAIL | SMS | PUSH_NOTIFICATION | SLACK | | ip | text | IP adresa (nullable) | | userAgent | text | User agent (nullable) | | description | text | JSON dump vstupu (nullable) | | initiatorService | text | Nazev volajici sluzby | | initiatorUserId | text | ID uzivatele (nullable) |

Error Codes

Format: {CATEGORY}-N-{NUMBER}

| Code | Status | Popis | |------|--------|-------| | CONN-N-01 | 502 | Ecomail: failed to send email | | CONN-N-02 | 502 | Ecomail: failed to send template email | | CONN-N-03 | 502 | Twilio: failed to send SMS | | CONN-N-04 | 502 | Slack: failed to send notification | | CONN-N-05 | 504 | Slack: request timed out | | CONN-N-06 | 502 | Webhook: delivery failed | | CONN-N-07 | 504 | Webhook: request timed out | | VALID-N-01 | 404 | Unsupported email provider | | VALID-N-02 | 404 | Unsupported SMS provider | | SYS-N-01 | 501 | Push notifications not implemented | | SYS-N-02 | 500 | Webhook signing key not configured |