Configuration and Contract Examples

The examples below are illustrative. IDs, timestamps, and stream keys are placeholders unless explicitly stated otherwise.

Example Environment

Minimal local runtime:

NOTIFICATION_REDIS_MASTER_ADDR=127.0.0.1:6379
NOTIFICATION_REDIS_PASSWORD=integration
NOTIFICATION_POSTGRES_PRIMARY_DSN=postgres://notificationservice:notificationservice@127.0.0.1:5432/galaxy?search_path=notification&sslmode=disable
NOTIFICATION_INTERNAL_HTTP_ADDR=:8092
NOTIFICATION_USER_SERVICE_BASE_URL=http://127.0.0.1:8091

NOTIFICATION_GATEWAY_CLIENT_EVENTS_STREAM=gateway:client-events
NOTIFICATION_MAIL_DELIVERY_COMMANDS_STREAM=mail:delivery_commands

NOTIFICATION_ADMIN_EMAILS_GEO_REVIEW_RECOMMENDED=geo-admin@example.com
NOTIFICATION_ADMIN_EMAILS_GAME_GENERATION_FAILED=ops@example.com
NOTIFICATION_ADMIN_EMAILS_LOBBY_RUNTIME_PAUSED_AFTER_START=ops@example.com
NOTIFICATION_ADMIN_EMAILS_LOBBY_APPLICATION_SUBMITTED=admins@example.com

OTEL_TRACES_EXPORTER=none
OTEL_METRICS_EXPORTER=none

Probe HTTP Examples

Liveness:

curl http://127.0.0.1:8092/healthz

{
  "status": "ok"
}

Readiness:

curl http://127.0.0.1:8092/readyz

{
  "status": "ready"
}

User-Targeted Intent Example

redis-cli XADD notification:intents '*' \
  notification_type game.turn.ready \
  producer game_master \
  audience_kind user \
  recipient_user_ids_json '["user-1","user-2"]' \
  idempotency_key game-master:game-123:turn-54 \
  occurred_at_ms 1775121700000 \
  request_id request-123 \
  trace_id trace-123 \
  payload_json '{"game_id":"game-123","game_name":"Nebula Clash","turn_number":54}'

Expected effects:

Notification Service resolves both users through User Service
one push route and one email route are materialized per user
Gateway receives user-wide client events without device_session_id
Mail Service receives template-mode commands with template_id=game.turn.ready

Administrator Intent Example

redis-cli XADD notification:intents '*' \
  notification_type geo.review_recommended \
  producer geoprofile \
  audience_kind admin_email \
  idempotency_key geoprofile:user-123:review-true:1775121700001 \
  occurred_at_ms 1775121700001 \
  payload_json '{"user_id":"user-123","user_email":"pilot@example.com","observed_country":"DE","usual_connection_country":"PL","review_reason":"country_mismatch"}'

Expected effects:

Notification Service does not call User Service
recipients are read from NOTIFICATION_ADMIN_EMAILS_GEO_REVIEW_RECOMMENDED
only email routes are publishable; push route slots are skipped

Gateway Client Event Shape

Example stream entry appended by Notification Service:

redis-cli XADD gateway:client-events MAXLEN '~' 1024 '*' \
  user_id user-1 \
  event_type game.turn.ready \
  event_id '1775121700000-0/push:user:user-1' \
  payload_bytes '<flatbuffers-bytes>' \
  request_id request-123 \
  trace_id trace-123

Gateway derives timestamp_ms, computes payload_hash, signs the outgoing event, and delivers it to every active stream for user-1.

Mail Command Shape

Example stream entry appended by Notification Service:

redis-cli XADD mail:delivery_commands '*' \
  delivery_id '1775121700000-0/email:user:user-1' \
  source notification \
  payload_mode template \
  idempotency_key 'notification:1775121700000-0/email:user:user-1' \
  requested_at_ms 1775121700000 \
  request_id request-123 \
  trace_id trace-123 \
  payload_json '{"to":["pilot@example.com"],"cc":[],"bcc":[],"reply_to":[],"template_id":"game.turn.ready","locale":"en","variables":{"game_id":"game-123","game_name":"Nebula Clash","turn_number":54},"attachments":[]}'

Dead-Letter Replay

Replay a dead-lettered route by publishing a new compatible intent with a new producer-owned idempotency_key.

redis-cli XADD notification:intents '*' \
  notification_type game.turn.ready \
  producer game_master \
  audience_kind user \
  recipient_user_ids_json '["user-1"]' \
  idempotency_key game-master:game-123:turn-54:manual-replay-1 \
  occurred_at_ms 1775121700000 \
  payload_json '{"game_id":"game-123","game_name":"Nebula Clash","turn_number":54}'

Do not mutate existing notification_route, notification_dead_letter_entry, or notification:route_schedule records as a replay workflow.

4.3 KiB Raw Blame History