Graceful Shutdown Logic Is Duplicated Across All Three Services

[therealjhay]

Category: Architecture & Refactoring
Difficulty: High

Description:
Graceful shutdown logic is manually implemented in every service:

• API Gateway: lines 949–968 (inline shutdown function with fastify.close() + prisma.$disconnect())
• FX Engine: lines 467–497 (inline shutdown function with fastify.close() + redis.quit())
• Settlement Engine: lines 638–702 (comprehensive shutdown with timeout, worker.close(), queue.close(), redis.quit(), prisma.$disconnect())
• Indexer: lines 547–553 (inline SIGTERM handler with prisma.$disconnect(), webhookQueue.close(), webhookWorker.close(), fastify.close())

Each implementation has subtle differences: the settlement engine has a 30-second force-exit timeout, the indexer doesn't, the gateway doesn't close Redis or BullMQ resources. This duplication means bug fixes to shutdown handling must be applied in 4 places. A shared gracefulShutdown(fastify, options) function should be extracted.

Location:
services/api-gateway/src/index.ts:949–968, services/fx-engine/src/index.ts:467–497, services/settlement-engine/src/index.ts:638–702, services/indexer/src/index.ts:547–553

Acceptance Criteria:

• Extract a gracefulShutdown function into @bettapay/validation/shutdown.ts
• The function should accept an options object: { fastify, prisma?, redis?, bullmq?: { worker?, queues? } }
• Enforce a configurable force-exit timeout (default 30s) matching the settlement engine's pattern
• Replace all 4 inline shutdown implementations with the shared function
• Write tests verifying the shutdown sequence (mock close methods, verify order)
• Ensure process.exit(0) is called after successful shutdown, process.exit(1) on failure

Technical Notes:

• Resource close order: server → accept new connections (fastify.close) → workers → queues → redis → prisma.
• Use Promise.allSettled to ensure all resources attempt close even if one fails.

[GBOYEE]

Hi — I can take this on. I can handle this one. I'll implement it to spec and add tests. Happy to submit a PR for this once the bot assigns it.

[madisonsc52-del]

Hi maintainer i can work on this, I'll make sure to work on the issue asap

[Babigdk]

Hi Maintainer! I'd like to work on this issue.

I have experience refactoring TypeScript backend services and improving shared infrastructure. I'll extract the duplicated shutdown logic into a reusable gracefulShutdown utility, preserve the correct resource shutdown order, implement configurable force-exit timeouts, replace the inline implementations across all services, and add comprehensive tests covering successful and failure scenarios. I'll ensure the refactor is backward-compatible and submit a clean PR that meets all the acceptance criteria.

[grantfox-oss]

🦊 GrantFox — @madisonsc52-del has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #254)
2. Your PR will be reviewed by the Betta-Pay maintainers

Good luck! Track your progress on GrantFox.