Resilience and Testability Improvements

[Jenola344]

Resilience and Testability Improvements

Closes #974 Closes #973 Closes #975

Improves resilience and testability across RPC health checks, wallet connections, and the mock client. These changes address transient service failures, stalled connection handshakes, and mock responses that were difficult to control and reproduce in tests.

---

Table of Contents

• Overview
• Features
  • Resilient RPC Fetching
  • Stellar Error Formatting
  • Wallet Connection Handling
  • Mock Client Testing Tools
• Usage
• Testing

---

Overview

Area	Problem	Solution
RPC health checks	Transient failures caused unreliable probes	Shared fetch wrapper with retries, backoff, and jitter
Stellar errors	Horizon result codes were lost in user-facing messages	Error formatter that preserves operation result codes
Wallet connections	Handshakes could stall indefinitely	15-second timeout with exponential backoff between attempts
Mock client	Responses were hard to control and reproduce	Failure injection, manual clock, and seeded generation

---

Usage

The snippet below is illustrative. Adjust names and signatures to match the actual API.

// Script two failures followed by success for a named operation
client.setFailureSequence("getAccount", [
  new Error("503 Service Unavailable"),
  new Error("503 Service Unavailable"),
]);
// Move the mock clock forward by 5 seconds

client.advanceTime(5_000);

---

Testing

Tests cover the following:

• Retry behavior for the RPC fetch wrapper
• Failure sequences that end in success
• Timestamp behavior driven by advanceTime(ms)
• Matching responses from independently created clients that share a seed

# Resilience and Testability Improvements

Improves resilience and testability across RPC health checks, wallet connections, and the mock client. These changes address transient service failures, stalled connection handshakes, and mock responses that were difficult to control and reproduce in tests.

---

Table of Contents

• [Overview](#overview)
• [Features](#features)
  • [Resilient RPC Fetching](#resilient-rpc-fetching)
  • [Stellar Error Formatting](#stellar-error-formatting)
  • [Wallet Connection Handling](#wallet-connection-handling)
  • [Mock Client Testing Tools](#mock-client-testing-tools)
• [Usage](#usage)
• [Testing](#testing)

---

Overview

Area	Problem	Solution
RPC health checks	Transient failures caused unreliable probes	Shared fetch wrapper with retries, backoff, and jitter
Stellar errors	Horizon result codes were lost in user-facing messages	Error formatter that preserves operation result codes
Wallet connections	Handshakes could stall indefinitely	15-second timeout with exponential backoff between attempts
Mock client	Responses were hard to control and reproduce	Failure injection, manual clock, and seeded generation

---

Features

Resilient RPC Fetching

A shared RPC fetch wrapper now handles transient failures automatically.

• Retries on HTTP 429, 502, 503, and 504 responses
• Retries on network dropouts
• Uses exponential backoff with jitter
• Used by the network switcher and banner health probes

Stellar Error Formatting

Stellar errors now keep the detail users need to diagnose a failure.

• Preserves Horizon extras.result_codes.operations in user-facing errors
• Surfaces codes such as op_underfunded and op_bad_auth

Wallet Connection Handling

ClientAdapter is more robust during wallet connection handshakes.

• Timeout: each handshake is limited to 15 seconds
• Backoff: exponential delay between failed attempts
• Ledger errors: recognized Ledger errors stop retrying and return actionable guidance, including instructions for 0x6804

Mock Client Testing Tools

The mock client now supports deterministic, reproducible tests.

Capability	API	Description
Failure injection	setFailureSequence	Script errors followed by success, for a named operation or across all operations
Manual clock	advanceTime(ms)	History and event timestamps follow the client's controllable clock instead of runner time
Seeded generation	Per-client seed	Independently created clients with the same seed produce identical responses

---

Usage

The snippet below is illustrative. Adjust names and signatures to match the actual API.

// Script two failures followed by success for a named operation
client.setFailureSequence("getAccount", [
  new Error("503 Service Unavailable"),
  new Error("503 Service Unavailable"),
]);

// Move the mock clock forward by 5 seconds
client.advanceTime(5_000);

---

Testing

Tests cover the following:

• Retry behavior for the RPC fetch wrapper
• Failure sequences that end in success
• Timestamp behavior driven by advanceTime(ms)
• Matching responses from independently created clients that share a seed

[drips-wave]

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