[RESILIENCE]: Add timeout, retry, and circuit-breaker policies at external boundaries

[grantfox-oss]

Context

GrantFox depends on Supabase, PostgreSQL, Resend, PostHog, wallet providers, and Trustless Work/Stellar. Unbounded calls or indiscriminate retries can exhaust serverless execution time, duplicate side effects, and produce confusing UI states.

Scope

• Inventory external calls and classify them as read, idempotent write, or non-idempotent write.
• Add explicit deadlines/abort signals and typed error translation at adapter boundaries.
• Implement bounded exponential backoff with jitter only where safe.
• Add circuit breaking/bulkheads for degraded dependencies and define fallback behavior.
• Propagate correlation IDs through API handlers, jobs, and dependency calls.
• Surface recoverable versus terminal failures to clients.

Acceptance criteria

• Every outbound request has a documented timeout and retry policy.
• Non-idempotent writes are never blindly retried.
• Dependency degradation does not consume unbounded connections or function duration.
• Fault-injection tests cover latency, timeout, connection reset, 429, and 5xx.
• Metrics identify the failing dependency and circuit state.
• User-facing errors give a safe retry/recovery action.

Relevant areas

Escrow hooks/adapters, email service, Supabase/Prisma clients, PostHog, API route error handling.

[Justprotocol]

Hi Maintainer,

I would like to apply for this issue. I have solid experience implementing backend resilience patterns, timeout handling, and fault tolerance across external integrations.

My planned approach:

• External Call Inventory: Categorize all outbound calls across Supabase, Resend, PostHog, and Stellar/Trustless Work into read, idempotent write, and non-idempotent write operations to ensure non-idempotent endpoints are never blindly retried.

• Timeouts & Retries: Introduce AbortSignal-based deadlines for outbound HTTP/adapter boundaries and configure bounded exponential backoff with jitter exclusively for safe operations.

• Circuit Breaking & Observability: Implement circuit-breaker logic for degraded dependencies with clear fallback behaviors, propagate correlation IDs across handlers/jobs, and surface recoverable vs terminal error states to clients.

• Testing: Add fault-injection tests covering latency, connection resets, 429, and 5xx failures.

I am ready to start working on this right away. Please assign this issue to me!

[MerlinTheWhiz]

Hello, I'm MerlinThewhiz, a software engineer with a strong background in smart contract, and a couple years in my arsenal. Having read the task requirement, I'd love to work on this issue. Please assign.

[grantfox-oss]

🦊 GrantFox — @MerlinTheWhiz 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 #97)
2. Your PR will be reviewed by the Eduvault-stellar maintainers

Good luck! Track your progress on GrantFox.