fix: async newsletter emails, migration locking, webhook signature enforcement, DLQ metric

[Fidelis900]

Summary

This PR resolves four backend reliability and security issues across the email and migration subsystems.

---

fix(#677) — Newsletter confirmation email is now non-blocking

File: services/api/src/handlers.rs

The newsletter_subscribe handler was already enqueuing confirmation emails via email/queue.rs, but still returned 200 OK — implying the operation had completed synchronously. Changed the response to 202 Accepted so the status code accurately reflects that the email has been accepted for asynchronous processing, not sent inline. This also aligns the endpoint with REST semantics for async operations.

---

fix(#676) — Migrations are now serialized with a PostgreSQL advisory lock

File: services/api/src/migrations.rs

In a horizontally scaled deployment, multiple instances starting simultaneously could each call MigrationRunner::run() concurrently, resulting in duplicate or conflicting migration attempts.

run() now:

1. Acquires a session-level advisory lock via pg_try_advisory_lock on a stable key (0x707265646963_7471) before executing any migrations.
2. If the lock is already held by another instance, aborts immediately with a clear error — causing that instance's startup to fail rather than racing.
3. Always calls pg_advisory_unlock before the connection is returned to the pool (both on success and failure), preventing the lock from leaking across pool-reused connections.

The migration logic itself is extracted into a private run_inner() to keep the locking and execution concerns separate.

---

fix(#679) — Webhook HMAC signature verification is now enforced by default

File: services/api/src/security.rs

sendgrid_webhook_middleware determined whether to run in development mode (bypassing signature verification) via:

.unwrap_or(true) // default to dev if not set

If the ENVIRONMENT environment variable was absent — which is common in staging or misconfigured production deployments — the middleware silently skipped HMAC verification, allowing any party to forge webhook events. Changed the default to false so that signature verification is enforced unless ENVIRONMENT=development is explicitly set.

---

fix(#678) — DLQ size exposed as a Prometheus gauge

Files: services/api/src/metrics.rs, services/api/src/handlers.rs

The dead-letter queue (Redis key email:dead_letter) had no observability. Added an email_dlq_size IntGauge to the Metrics registry. The gauge is updated each time the GET /api/v1/email/queue/stats endpoint is called, reflecting the current DLQ cardinality from Redis.

The existing list_dead_letter (GET /api/v1/email/dead-letter) and requeue_dead_letter (POST /api/v1/email/dead-letter/:id/requeue) admin endpoints satisfy the inspect-and-replay acceptance criterion — no new endpoints were needed.

---

Closes

Closes #677
Closes #676
Closes #679
Closes #678

🤖 Generated with Claude Code

[drips-wave]

@Fidelis900 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits