@develit-services/notification

v5.3.0

Published

9 days ago

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

0High
0Medium
0Low

mufdevelit

tonda.develit

kleinpetr

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, Klaviyo, SMTP, 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, Klaviyo, SMTP | 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.

Klaviyo (email)

Alternativni email provider, aktivuje se pres EMAIL_PROVIDER: 'klaviyo'. API klic (privatni klic pk_... se scope events:write) se cte ze Secrets Store (NOTIFICATION_SERVICE_EMAIL_API_KEY).

Klaviyo nema prime "send email" API - transakcni emaily se odesilaji pres Events API. Konektor vytvori event s metrikou Transactional Email a Klaviyo flow napojeny na tuto metriku sestavi a odesle samotny email.

Mapovani IEmail -> Klaviyo event:

to -> profil eventu; jeden event na kazdeho prijemce
subject, templateId (jako template_id), text, html -> event properties
templateVariables -> event properties (ve flow sablone dostupne jako {{ event.nazev_promenne }})

Nastaveni na strane Klaviyo:

Vytvorit flow spousteny metrikou Transactional Email (pri vice sablonach vetvit pres trigger split na template_id)
Oznacit flow emaily jako transakcni (schvaluje Klaviyo, cca 1 pracovni den)

Omezeni (konektor vraci VALID-N-03, status 422):

Prilohy nejsou podporovany (Klaviyo neumoznuje prilohy v emailech)
cc/bcc nejsou podporovany
from/replyTo se ignoruji - odesilatel a reply-to se konfiguruji na flow emailu v Klaviyo

SMTP (email)

Genericky email provider pro libovolny SMTP server (vlastni relay, Gmail, Amazon SES, ...), aktivuje se pres EMAIL_PROVIDER: 'smtp'. Implementovan pres worker-mailer (SMTP nad cloudflare:sockets). Heslo se cte ze Secrets Store (NOTIFICATION_SERVICE_EMAIL_API_KEY); pokud neni nastavene, konektor se pripoji bez autentizace.

Podporovane formaty EMAIL_SMTP_HOST:

| Format | Vyznam | |--------|--------| | mail.example.com | port 587, STARTTLS, login jako EMAIL_SENDER_EMAIL | | mail.example.com:2525 | vlastni port, STARTTLS | | smtp://user%[email protected]:587 | explicitni uzivatelske jmeno (URL-encoded) | | smtps://mail.example.com | implicitni TLS, vychozi port 465 |

Podporuje text i html (multipart/alternative), cc, replyTo, from a prilohy (base64). Autentizace: plain / login / CRAM-MD5 podle nabidky serveru. Predmety a jmena s diakritikou se koduji dle RFC 2047.

Omezeni:

Port 25 je na Cloudflare Workers blokovan (SYS-N-04) - pouzit 587 (STARTTLS) nebo 465 (smtps://)
templateId/templateVariables nejsou podporovany - SMTP nema sablony, obsah je nutne predat vyrenderovany v text/html (VALID-N-04)
bcc neni podporovan (VALID-N-04) - worker-mailer 1.2.1 zapisuje BCC hlavicku primo do zpravy, prijemci by tak skryte kopie videli
Heslo nikdy nepatri do EMAIL_SMTP_HOST URL - konektor ho odmitne (SYS-N-04)

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 | | CONN-N-08 | 502 | Klaviyo: failed to send event email | | CONN-N-09 | 502 | SMTP: failed to connect or send email | | VALID-N-01 | 404 | Unsupported email provider | | VALID-N-02 | 404 | Unsupported SMS provider | | VALID-N-03 | 422 | Klaviyo: unsupported email fields (attachments, cc/bcc) or no recipient | | VALID-N-04 | 422 | SMTP: unsupported email fields (templates, bcc), missing content or recipient | | SYS-N-01 | 501 | Push notifications not implemented | | SYS-N-02 | 500 | Webhook signing key not configured |