feat: fix #814 stats routes, #824 webhook deliveries, #826 redis scan…

[peacebas]

Closes #814
Closes #824
Closes #826
Closes #834

1. Route Song & Artist Stats Endpoints

• Problem: SongStatsService provided comprehensive aggregation queries powering SongController.getSongStats and SongController.getArtistStats, but neither handler was routed. Artist dashboard analytics had no endpoints to query.
• Solution & Flow:
  • Mounted GET /api/song/:id/stats with optional authentication.
  • Mounted GET /api/song/artist/:artistId/stats and GET /api/artist/:id/stats for artist catalog analytics.
  • Enforced metric privacy: Public/unauthenticated callers and non-owners receive only public engagement metrics (plays and saves). Confidential financial metrics (revenueStroops, denominated in atomic Stellar stroops representing $10^{-7}$ XLM) and audience demographics (uniqueListeners) are strictly restricted to the verified song/artist owner, platform admins, and moderators.
  • Added time-window validation (24h, 7d, 30d, 90d, all-time) returning structured 400 Bad Request (INVALID_WINDOW) errors for unsupported values.
  • Added HTTP cache headers: Cache-Control: private, max-age=300 for creators and Cache-Control: public, max-age=300 for public metrics, combined with Vary: Authorization to prevent cache poisoning across intermediate proxies.
  • Documented OpenAPI schemas and added integration tests.

2. Record Webhook Delivery Attempts & Expose Redelivery Endpoint

• Problem: Failed webhook deliveries only left a log line. Integrators had no ability to inspect request payloads, response codes, or latency, or trigger redeliveries after fixing broken endpoints. Subscriptions that failed forever also continued receiving (and failing) events indefinitely.
• Solution & Flow:
  • Introduced the WebhookDelivery entity recording subscriptionId, eventId, eventType, attempt, status (pending|succeeded|failed), responseStatus, durationMs, error, and payload with database indexes on subscriptionId, createdAt, and eventId.
  • Added consecutiveFailures counter to WebhookSubscription and created database migration 1757700000000-AddWebhookDeliveriesAndFailureTracking.ts.
  • In WebhookService.deliver(), each HTTP attempt writes an audit row. Successful deliveries reset consecutiveFailures = 0.
  • Auto-disable circuit breaker: When all retry attempts for an event fail, consecutiveFailures increments. If consecutive failures reach the configurable threshold (WEBHOOK_MAX_CONSECUTIVE_FAILURES, default 5), the subscription is automatically disabled (isActive = false) and an alert notification is dispatched to the owner via NotificationService.
  • Mounted owner-only endpoints:
    • GET /api/webhooks/:id/deliveries (paginated, newest first).
    • POST /api/webhooks/:id/deliveries/:deliveryId/redeliver (triggers retry using original signed payload).
  • Implemented 30-day retention cleanup routine (cleanupOldDeliveries(30)) and standalone job src/jobs/WebhookRetentionJob.ts.
  • Added OpenAPI specs and test coverage.

3. Use SCAN Instead of KEYS in CacheService.invalidatePattern

• Problem: CacheService.invalidatePattern executed redis.keys(pattern). KEYS is a blocking $\mathcal{O}(N)$ command over the entire key space that freezes the single-threaded Redis event loop, stalling rate limiters, session lookups, and token verifications. Additionally, AccountDeletionService invoked CacheService.invalidatePattern('song:*'), scanning and dropping all song cache keys across the entire platform whenever any single user deleted their account.
• Solution & Flow:
  • Reimplemented CacheService.invalidatePattern using non-blocking cursor iteration via redis.scanStream({ match: pattern, count: 500 }).
  • Batched matching keys and deleted them via redis.unlink(...keys) in chunks of 500. UNLINK removes keys from the keyspace in $\mathcal{O}(1)$ time and lazily deallocates memory in background threads without blocking concurrent commands.
  • Refactored AccountDeletionService to selectively query the deleting artist's songs (await songRepo.find({ where: { artistId: user.id }, select: ['id'] })) and surgically clear only their keys via CacheService.clearSong(song.id).
  • Verified 0 occurrences of redis.keys( remain in src/. Added unit tests with mocked scan streams.

4. Run Jest with --detectOpenHandles in CI & Fix Leaking Timers

• Problem: Unref'd setInterval and setTimeout timers initialized at module import or constructor time in PrivySessionService, DatabaseConnectionManager, DbPoolMonitor, and JobQueueWorker, as well as background Redis socket reconnect timers, kept Node.js event loops alive. Jest test suites could not exit cleanly, leading to hanging workers or masking leaks via --forceExit.
• Solution & Flow:
  • Removed top-level and constructor-time timers from PrivySessionService; introduced explicit start(), stop(), and .unref() handling.
  • Added stopConnectionStateLogger() and made circuit breaker health check intervals opt-in (autoStart = false) in DatabaseConnectionManager.
  • Configured test-mode Redis options in src/config/redis.ts (lazyConnect: true, retryStrategy: () => null) to prevent background socket connection loops during tests.
  • Added global Jest teardown in tests/setup/jestTeardown.ts to stop remaining background timers and disconnect Redis sockets cleanly.
  • Updated CI workflow .github/workflows/ci.yml to execute npm test -- --detectOpenHandles without --forceExit.

Changed

• Route song and artist stats endpoints #814: Mounted GET /api/song/:id/stats, GET /api/song/artist/:artistId/stats, and GET /api/artist/:id/stats with optionalAuth in src/routes/SongRoutes.ts and src/routes/artistRoutes.ts.
• Route song and artist stats endpoints #814: Enforced metric field filtering in src/controllers/SongController.ts, stripping uniqueListeners and revenueStroops for public consumers and non-owners.
• Route song and artist stats endpoints #814: Added time-window query parameter validation throwing AppError.validation (400 Bad Request) on invalid windows.
• Route song and artist stats endpoints #814: Added caching headers (Cache-Control: private/public, max-age=300, Vary: Authorization).
• Record webhook delivery attempts and expose a redeliver endpoint #824: Created WebhookDelivery entity in src/entities/WebhookDelivery.ts and registered it in src/config/db.ts.
• Record webhook delivery attempts and expose a redeliver endpoint #824: Added consecutiveFailures tracking column to src/entities/WebhookSubscription.ts and created database migration src/migrations/1757700000000-AddWebhookDeliveriesAndFailureTracking.ts.
• Record webhook delivery attempts and expose a redeliver endpoint #824: Updated src/services/WebhookService.ts to log per-attempt deliveries, auto-disable subscriptions exceeding consecutive failure thresholds, and notify owners via NotificationService.
• Record webhook delivery attempts and expose a redeliver endpoint #824: Exposed GET /api/webhooks/:id/deliveries and POST /api/webhooks/:id/deliveries/:deliveryId/redeliver in src/controllers/WebhookController.ts and src/routes/webhookRoutes.ts.
• Record webhook delivery attempts and expose a redeliver endpoint #824: Added cleanupOldDeliveries(days = 30) in WebhookService and created src/jobs/WebhookRetentionJob.ts for automated pruning.
• Use SCAN instead of KEYS in CacheService.invalidatePattern #826: Replaced blocking redis.keys() in src/services/CacheService.ts with redis.scanStream({ match, count: 500 }) and batch redis.unlink().
• Use SCAN instead of KEYS in CacheService.invalidatePattern #826: Optimized src/services/AccountDeletionService.ts to clear only the specific deleted user's songs instead of global song:*.
• Run Jest with --detectOpenHandles in CI and fix leaking timers #834: Converted background timers in PrivySessionService, DatabaseConnectionManager, DbPoolMonitor, and JobQueueWorker to explicit start()/stop() lifecycles with .unref().
• Run Jest with --detectOpenHandles in CI and fix leaking timers #834: Configured lazyConnect: true and retryStrategy: () => null in test mode for src/config/redis.ts.
• Run Jest with --detectOpenHandles in CI and fix leaking timers #834: Implemented tests/setup/jestTeardown.ts and configured jest.config.js with setupFilesAfterEnv.
• Run Jest with --detectOpenHandles in CI and fix leaking timers #834: Updated .github/workflows/ci.yml test command to run npm test -- --detectOpenHandles without --forceExit.
• Route song and artist stats endpoints #814 & Record webhook delivery attempts and expose a redeliver endpoint #824: Updated docs/openapi.yaml with OpenAPI 3.0 path and component schemas.
• Route song and artist stats endpoints #814, Record webhook delivery attempts and expose a redeliver endpoint #824, Use SCAN instead of KEYS in CacheService.invalidatePattern #826, Run Jest with --detectOpenHandles in CI and fix leaking timers #834: Added unit and integration test suites in src/__tests__/SongArtistStatsRoutes.test.ts, src/__tests__/WebhookDeliveriesRoutes.test.ts, and src/__tests__/CacheService.test.ts.

[drips-wave]

@peacebas 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