Catch unhandledRejection and uncaughtException to drain cleanly instead of crashing dirty

[mikewheeleer]

Implement process-level handlers for unhandled rejections and uncaught exceptions

Description

src/index.ts installs SIGTERM/SIGINT handlers for a graceful 10 s drain, but there are no process.on("unhandledRejection") or process.on("uncaughtException") handlers. An unhandled promise rejection or a thrown error escaping the Express error handler will either crash the process abruptly (dropping in-flight requests with no log correlation) or, worse on older Node, leave it in an undefined state. For a billing gateway that must shut down cleanly to avoid losing unsettled usage, this is a gap. This issue adds last-resort process handlers that log and drain.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-backend only.
• Add process.on("unhandledRejection", ...) and process.on("uncaughtException", ...) handlers that log the error (structured, correlated where possible) and trigger the existing graceful shutdown path with a non-zero exit code.
• Reuse the existing shutdown(signal) drain logic rather than calling process.exit directly, so in-flight requests still get the 10 s window.
• Guard against re-entrancy (a second fault during drain must not restart the drain) and only install the handlers in the server-start branch, not when the module is imported for tests.
• Document the behaviour and the chosen exit codes.

Suggested execution

• Fork the repo and create a branch
• git checkout -b feature/observability-73-process-fault-handlers
• Implement changes
  • Write code in: the server-start block in src/index.ts, extending the shutdown wiring.
  • Write comprehensive tests in: new src/process-handlers.test.ts — handler installed only on start, drain triggered once, re-entrancy guarded (test the extracted handler function without exiting the test runner).
  • Add documentation: add a "Crash handling" note to README.md.
  • Add TSDoc on the handlers.
  • Validate security assumptions: error detail is logged, not exposed; no infinite restart loop.
• Test and commit

Test and commit

• Run npm test and npm run lint.
• Cover edge cases: rejection during normal run, exception during drain (re-entrancy), import path does not install handlers.
• Include the full npm test output in the PR description.

Example commit message

feat: handle unhandled rejections and uncaught exceptions with a clean drain

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the AgentPay community on Discord for questions, reviews, and faster merges: https://discord.gg/eXvRKkgcv
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.

[GBOYEE]

Hi team! Catch unhandledRejection and uncaughtException. Plan: add process-level handlers that log the error and drain connections before exiting, preventing silent crashes in production. Standard Node.js reliability pattern. Ready.