banks2ff/specs/debug-logging.md

Debug Logging Specification

Goal

Implement comprehensive HTTP request/response logging for debugging API interactions between banks2ff and external services (GoCardless and Firefly III).

Requirements

Output Format

Each HTTP request-response cycle generates a single text file with the following structure:

1. Curl Command (at the top in comments)

   • Full curl -v command that reproduces the exact request
   • Includes all headers, authentication tokens, and request body
   • Properly escaped for shell execution

2. Complete Request Data

   • HTTP method and URL
   • All request headers (including Host header)
   • Full request body (if present)

3. Complete Response Data

   • HTTP status code and reason
   • All response headers
   • Full response body

File Organization

• Files stored in ./debug_logs/{service_name}/ directories
• Timestamped filenames: YYYYMMDD_HHMMSS_REQUESTID.txt
• One file per HTTP request-response cycle
• Service-specific subdirectories (gocardless/, firefly/)

Data Visibility

• No filtering or masking of any data
• Complete visibility of all HTTP traffic including:
  • Authentication tokens and credentials
  • Financial transaction data
  • Personal account information
  • API keys and secrets

Activation

• Enabled via --debug command-line flag
• Files only created when debug mode is active
• No impact on normal operation when debug mode is disabled

Use Case

Human debugging of API integration issues where complete visibility of all HTTP traffic is required to diagnose problems with external service interactions. specs/debug-logging.md