Skip to content

Latest commit

 

History

History
202 lines (157 loc) · 6.54 KB

EXTERNAL_CALLS_AUDIT.md

File metadata and controls

202 lines (157 loc) · 6.54 KB

External Calls Audit - Timeout Implementation

Summary

This document provides a comprehensive audit of all external calls in the codebase and their timeout implementations.

External Call Categories

1. Stellar Blockchain API Calls ✅ PROTECTED

File: src/services/StellarService.js

Method External Call Timeout Retry Status
loadAccount() server.loadAccount() 15s 3x ✅ Protected
submitTransaction() server.submitTransaction() 30s Network safety ✅ Protected
friendbot() server.friendbot().call() 15s 3x ✅ Protected
transaction() server.transaction().call() 15s 3x ✅ Protected
transactions() server.transactions().call() 15s 3x ✅ Protected
streamTransactions() server.transactions().stream() 60s inactivity Auto-reconnect ✅ Protected

Implementation Details:

  • All calls wrapped with withTimeout() via _executeWithRetry()
  • Exponential backoff: 200ms → 400ms → 800ms (max 2s)
  • TimeoutError treated as transient and retryable
  • Streaming has inactivity monitoring with automatic cleanup

2. Database Operations ✅ PROTECTED

File: src/utils/database.js

Method External Call Timeout Status
getConnection() new sqlite3.Database() 10s ✅ Protected
query() db.all() 10s ✅ Protected
run() db.run() 10s ✅ Protected
get() db.get() 10s ✅ Protected

Implementation Details:

  • All operations wrapped with withTimeout()
  • Automatic connection cleanup on timeout
  • Prevents connection leaks
  • Clear error messages with operation context

3. Background Services ✅ PROTECTED

RecurringDonationScheduler

File: src/services/RecurringDonationScheduler.js

Operation External Dependency Timeout Status
processSchedules() Database queries 10s ✅ Protected (via Database)
executeSchedule() stellarService.sendPayment() 30s ✅ Protected (via StellarService)
logExecution() Database writes 10s ✅ Protected (via Database)

Additional Protection:

  • Retry logic: 3 attempts with exponential backoff (1s → 2s → 4s, max 30s)
  • Duplicate execution prevention
  • Execution timeout tracking

TransactionReconciliationService

File: src/services/TransactionReconciliationService.js

Operation External Dependency Timeout Status
reconcile() Database queries 10s ✅ Protected (via Database)
reconcileTransaction() stellarService.verifyTransaction() 15s ✅ Protected (via StellarService)

Additional Protection:

  • 5-minute reconciliation interval
  • Concurrent reconciliation prevention
  • Promise.allSettled for parallel processing

TransactionSyncService

File: src/services/TransactionSyncService.js

Operation External Dependency Timeout Status
syncWalletTransactions() stellarService.getTransactionHistory() 15s ✅ Protected (via StellarService)
Database writes Database operations 10s ✅ Protected (via Database)

4. HTTP/Express Routes ✅ PROTECTED

All routes use services with timeout protection:

  • Donation routes → StellarService (protected)
  • Wallet routes → StellarService (protected)
  • Transaction routes → Database + StellarService (protected)

Timeout Configuration Matrix

Component Default Timeout Configurable Retry Notes
Stellar API 15s Yes 3x Standard operations
Stellar Submit 30s Yes Network safety Transaction submission
Stellar Stream 60s Yes Auto-reconnect Inactivity timeout
Database 10s No* No All DB operations

*Can be modified in TIMEOUT_DEFAULTS constant

Error Handling

TimeoutError Properties

{
  name: 'TimeoutError',
  message: 'Operation X timed out after Yms',
  operation: 'operation_name',
  timeoutMs: 15000,
  timestamp: '2026-02-26T...'
}

Logging Levels

  • DEBUG: Retry attempts
  • WARN: Timeout with retry available
  • ERROR: Final timeout failure
  • INFO: Successful recovery after timeout

Coverage Summary

✅ Fully Protected

  • All Stellar Horizon API calls
  • All database operations
  • All background service operations
  • Transaction streaming

⚠️ Inherently Bounded

  • Express request timeout (handled by Express/Node.js)
  • File system operations (OS-level timeouts)

❌ No External Calls Found

  • No unprotected external HTTP calls
  • No unprotected third-party API calls
  • No unprotected network sockets

Verification Checklist

  • All Stellar API calls have timeouts
  • All database operations have timeouts
  • Streaming connections monitored
  • Timeout errors logged clearly
  • Graceful error handling implemented
  • Connection cleanup on timeout
  • Retry logic for transient errors
  • Documentation complete
  • No syntax errors
  • Backward compatible

Testing Strategy

Unit Tests Needed

  1. timeoutHandler.js

    • Test withTimeout() enforcement
    • Test TimeoutError creation
    • Test executeWithTimeout() retry logic

  2. StellarService.js

    • Test timeout on slow API calls
    • Test retry on timeout
    • Test stream inactivity timeout

  3. database.js

    • Test query timeout
    • Test connection cleanup
    • Test timeout error handling

Integration Tests Needed

  1. End-to-end donation with simulated network delay
  2. Database timeout under load
  3. Stream reconnection after timeout
  4. Background service timeout handling

Load Tests Needed

  1. Concurrent operations under timeout
  2. Database connection pool under timeout
  3. Stellar API rate limiting with timeouts

Deployment Notes

Pre-deployment

  1. Review timeout values for production environment
  2. Set up monitoring for TimeoutError occurrences
  3. Configure alerting for high timeout rates
  4. Test with production-like network latency

Post-deployment

  1. Monitor timeout frequency
  2. Adjust timeout values if needed
  3. Track retry success rates
  4. Monitor for connection leaks

Maintenance

Regular Reviews

  • Monthly: Review timeout metrics
  • Quarterly: Adjust timeout values based on data
  • Annually: Audit for new external calls

When to Update

  • New external API integrations
  • New database operations
  • New streaming connections
  • Performance degradation observed