Merge pull request #199 from Mkalbani/feat/network-timeout-handling-127

Feat/network timeout handling 127

Author: mijinummi

docs/NETWORK_TIMEOUT_HANDLING.md

@@ -0,0 +1,79 @@
+# Network Timeout Handling
+
+## Overview
+
+BridgeWise enforces hard request time limits to prevent hanging API calls and keeps reliability high by reusing existing retry/backoff behavior.
+
+## What is implemented
+
+- **Per-request timeout enforcement** for network calls.
+- **Timeout-aware retries** using existing retry logic (exponential backoff).
+- **Configurable timeout values** at both client and request levels.
+
+## Configuration
+
+### Global timeout (client)
+
+In `RateLimitedApiClient`:
+
+- `timeout` (ms): default per-request timeout.
+
+Example:
+
+```js
+const client = new RateLimitedApiClient({
+  timeout: 8000,
+  maxRetries: 3,
+  baseDelay: 800,
+});
+```
+
+### Request-level timeout override
+
+You can override timeout for a specific request:
+
+```js
+await client.get(
+  '/api/quote',
+  {},
+  {
+    group: 'quotes',
+    timeout: 3000,
+  },
+);
+```
+
+## Retry integration
+
+Timeouts are treated as retryable failures and follow the same retry policy:
+
+- Retry attempts: `maxRetries`
+- Delay strategy: exponential backoff (`baseDelay`, capped by `maxDelay`)
+- Metrics: `retriedRequests` increments on timeout retries
+
+## Error behavior
+
+When a timeout occurs, the client throws an error with:
+
+- `name: "TimeoutError"`
+- `code: "REQUEST_TIMEOUT"`
+- `timeoutMs: <configured timeout>`
+
+## Testing guidance (slow API simulation)
+
+To simulate an unresponsive API in tests:
+
+```js
+globalThis.fetch = vi.fn().mockImplementation(() => new Promise(() => {}));
+```
+
+Expected behavior:
+
+1. Request times out at configured timeout.
+2. Retry triggers (if retries remain).
+3. Final error is surfaced when retries are exhausted.
+
+## Affected files
+
+- `packages/adapters/stellar/src/rateLimitedApi.js`
+- `packages/adapters/stellar/src/rateLimitedApi.test.js`

docs/README.md

@@ -5,13 +5,15 @@ Welcome to the BridgeWise API documentation! This comprehensive guide covers eve
 ## 📚 Documentation Files
 
 ### Getting Started
+
 - **[QUICK_REFERENCE.md](./QUICK_REFERENCE.md)** ⭐ START HERE
   - Fastest way to get up and running
   - Common commands and examples
   - Quick troubleshooting
   - ~200 lines
 
 ### Comprehensive Guides
+
 - **[API_DOCUMENTATION.md](./API_DOCUMENTATION.md)** - MAIN GUIDE
   - Complete API overview
   - All 11 endpoints documented
@@ -30,6 +32,7 @@ Welcome to the BridgeWise API documentation! This comprehensive guide covers eve
   - ~500 lines
 
 ### Reference Materials
+
 - **[API_ERRORS.md](./API_ERRORS.md)** - ERROR REFERENCE
   - All error codes documented
   - HTTP status codes
@@ -46,27 +49,37 @@ Welcome to the BridgeWise API documentation! This comprehensive guide covers eve
   - Quality metrics
   - Next steps
 
+- **[NETWORK_TIMEOUT_HANDLING.md](./NETWORK_TIMEOUT_HANDLING.md)** - RELIABILITY
+  - Timeout limits for slow/unresponsive APIs
+  - Retry behavior on timeout failures
+  - Simulation/testing guidance
+
 ---
 
 ## 🚀 Quick Start
 
 ### 1. Install Dependencies
+
 ```bash
 npm install
 ```
 
 ### 2. Start Development Server
+
 ```bash
 npm run start:dev
 ```
 
 ### 3. Access Swagger UI
+
 Open your browser to:
+
 ```
 http://localhost:3000/api/docs
 ```
 
 ### 4. Make Your First Request
+
 ```bash
 # Create a transaction
 curl -X POST http://localhost:3000/transactions \
@@ -88,18 +101,21 @@ curl -X POST http://localhost:3000/transactions \
 ## 📖 Learning Path
 
 ### For API Users
+
 1. Read [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) (5 min)
 2. Try endpoints in Swagger UI at `/api/docs` (10 min)
 3. Review relevant sections in [API_DOCUMENTATION.md](./API_DOCUMENTATION.md) (20 min)
 4. Check [API_ERRORS.md](./API_ERRORS.md) for error handling (10 min)
 
 ### For Developers
+
 1. Review [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md) (10 min)
 2. Check [OPENAPI_SPECIFICATION.md](./OPENAPI_SPECIFICATION.md) (15 min)
 3. Examine controller decorators in source code (20 min)
 4. Review DTOs with Swagger annotations (10 min)
 
 ### For DevOps/Integrations
+
 1. Review [API_DOCUMENTATION.md](./API_DOCUMENTATION.md) architecture section
 2. Check endpoints and rate limiting in [QUICK_REFERENCE.md](./QUICK_REFERENCE.md)
 3. Review CORS and security in [OPENAPI_SPECIFICATION.md](./OPENAPI_SPECIFICATION.md)
@@ -110,24 +126,28 @@ curl -X POST http://localhost:3000/transactions \
 ## 🔑 Key Features
 
 ✅ **Complete OpenAPI/Swagger Documentation**
+
 - All 11 endpoints fully documented
 - Interactive Swagger UI for testing
 - Request/response examples for every endpoint
 - Real-world use cases
 
 ✅ **Comprehensive Error Documentation**
+
 - 20+ error codes documented
 - HTTP status code mappings
 - Example error responses
 - Resolution guidance for each error
 
 ✅ **Adapter-Specific Annotations**
+
 - Stellar-specific fields clearly marked
 - LayerZero omnichain details
 - Hop Protocol bridge parameters
 - Example data for each blockchain
 
 ✅ **Example Responses**
+
 - Multiple examples for different scenarios
 - Success and error cases
 - Real network data examples
@@ -138,15 +158,18 @@ curl -X POST http://localhost:3000/transactions \
 ## 🌐 API Overview
 
 ### Base URLs
+
 - **Development**: `http://localhost:3000`
 - **Production**: `https://api.bridgewise.example.com`
 
 ### Supported Networks
+
 - **Stellar** - Direct blockchain payments
 - **LayerZero** - Omnichain bridging
 - **Hop Protocol** - Multi-chain liquidity bridges
 
 ### Core Operations
+
 - **Transactions** - Create, manage, track
 - **Fee Estimation** - Network fees across all chains
 - **Real-time Updates** - SSE or polling
@@ -155,38 +178,44 @@ curl -X POST http://localhost:3000/transactions \
 
 ## 📊 Documentation Statistics
 
-| Category | Count | Lines |
-|----------|-------|-------|
-| Endpoints | 11 | ~300 |
-| Error Codes | 20+ | ~400 |
-| Examples | 20+ | ~200 |
-| Adapters | 3 | ~100 |
-| **Total** | **~** | **~2000** |
+| Category    | Count | Lines     |
+| ----------- | ----- | --------- |
+| Endpoints   | 11    | ~300      |
+| Error Codes | 20+   | ~400      |
+| Examples    | 20+   | ~200      |
+| Adapters    | 3     | ~100      |
+| **Total**   | **~** | **~2000** |
 
 ---
 
 ## 🎯 Common Tasks
 
 ### Access Interactive Swagger UI
+
 ```
 http://localhost:3000/api/docs
 ```
 
 ### Get All Fee Estimates
+
 ```bash
 curl http://localhost:3000/api/v1/fees
 ```
 
 ### Create a Transaction
+
 See [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) or [API_DOCUMENTATION.md](./API_DOCUMENTATION.md)
 
 ### Monitor Transaction with SSE
+
 See Transaction Monitoring section in [API_DOCUMENTATION.md](./API_DOCUMENTATION.md)
 
 ### Handle Errors
+
 See [API_ERRORS.md](./API_ERRORS.md) for error codes and solutions
 
 ### Check Service Health
+
 ```bash
 curl http://localhost:3000/api/v1/fees/health
 ```
@@ -196,13 +225,15 @@ curl http://localhost:3000/api/v1/fees/health
 ## 🔗 Related Files
 
 ### Source Code
+
 - `src/app.controller.ts` - Health check endpoint
 - `src/transactions/transactions.controller.ts` - Transaction endpoints (6 endpoints)
 - `src/gas-estimation/fee-estimation.controller.ts` - Fee endpoints (3 endpoints)
 - `src/transactions/dto/create-transaction.dto.ts` - Transaction creation schema
 - `src/transactions/dto/update-transaction.dto.ts` - Transaction update schema
 
 ### Configuration
+
 - `src/main.ts` - Swagger/OpenAPI setup
 - `package.json` - Dependencies (@nestjs/swagger, swagger-ui-express)
 
@@ -211,43 +242,54 @@ curl http://localhost:3000/api/v1/fees/health
 ## ❓ FAQ
 
 ### Where do I start?
+
 → Begin with [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) for a 5-minute overview.
 
 ### How do I test the API?
+
 → Use the interactive Swagger UI at `/api/docs` or use curl commands in [QUICK_REFERENCE.md](./QUICK_REFERENCE.md).
 
 ### What are the supported networks?
+
 → Stellar, LayerZero, and Hop Protocol. See [API_DOCUMENTATION.md](./API_DOCUMENTATION.md) for details.
 
 ### How do I handle errors?
+
 → See [API_ERRORS.md](./API_ERRORS.md) for all error codes and resolution steps.
 
 ### Where is the OpenAPI spec?
+
 → Automatically served at `http://localhost:3000/api/docs` or see [OPENAPI_SPECIFICATION.md](./OPENAPI_SPECIFICATION.md).
 
 ### How do I monitor transactions in real-time?
+
 → Use Server-Sent Events (SSE) at `/transactions/{id}/events` or polling at `/transactions/{id}/poll`.
 
 ### What are the rate limits?
+
 → 10 requests per 60 seconds per IP. See [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) for details.
 
 ### Is authentication required?
+
 → Currently no. Authentication may be added in future versions (see IMPLEMENTATION_SUMMARY.md).
 
 ---
 
 ## 📞 Support
 
 ### Documentation
+
 - **Main Guide**: [API_DOCUMENTATION.md](./API_DOCUMENTATION.md)
 - **Quick Help**: [QUICK_REFERENCE.md](./QUICK_REFERENCE.md)
 - **Errors**: [API_ERRORS.md](./API_ERRORS.md)
 
 ### Interactive Tools
+
 - **Swagger UI**: http://localhost:3000/api/docs (after starting server)
 - **OpenAPI JSON**: http://localhost:3000/api-json
 
 ### Contact
+
 - **Email**: [email protected]
 - **Docs Site**: https://docs.bridgewise.example.com
 - **Status**: https://status.bridgewise.example.com
@@ -272,6 +314,7 @@ curl http://localhost:3000/api/v1/fees/health
 ## 🎉 What's New (v1.0.0)
 
 ✅ **Initial Release Features**
+
 - Complete OpenAPI 3.0.0 specification
 - 11 fully documented endpoints
 - Server-Sent Events (SSE) support
@@ -285,14 +328,14 @@ curl http://localhost:3000/api/v1/fees/health
 
 ## 📝 Document Versions
 
-| Document | Version | Updated |
-|----------|---------|---------|
-| API_DOCUMENTATION.md | 1.0.0 | 2026-01-29 |
-| QUICK_REFERENCE.md | 1.0.0 | 2026-01-29 |
-| API_ERRORS.md | 1.0.0 | 2026-01-29 |
-| OPENAPI_SPECIFICATION.md | 1.0.0 | 2026-01-29 |
-| IMPLEMENTATION_SUMMARY.md | 1.0.0 | 2026-01-29 |
-| README.md (this file) | 1.0.0 | 2026-01-29 |
+| Document                  | Version | Updated    |
+| ------------------------- | ------- | ---------- |
+| API_DOCUMENTATION.md      | 1.0.0   | 2026-01-29 |
+| QUICK_REFERENCE.md        | 1.0.0   | 2026-01-29 |
+| API_ERRORS.md             | 1.0.0   | 2026-01-29 |
+| OPENAPI_SPECIFICATION.md  | 1.0.0   | 2026-01-29 |
+| IMPLEMENTATION_SUMMARY.md | 1.0.0   | 2026-01-29 |
+| README.md (this file)     | 1.0.0   | 2026-01-29 |
 
 ---
 
@@ -316,6 +359,6 @@ For error handling, check [API_ERRORS.md](./API_ERRORS.md).
 
 ---
 
-*Generated: 2026-01-29*  
-*API Version: 1.0.0*  
-*Documentation Version: 1.0.0*
+_Generated: 2026-01-29_  
+_API Version: 1.0.0_  
+_Documentation Version: 1.0.0_