httpdbg: HTTP Debugging Proxy

Common errors

• Requests are not showing up in the httpdbg UI

  cause Your HTTP client is not configured to send requests through the httpdbg proxy.
  fix Make sure to set the `HTTP_PROXY` and `HTTPS_PROXY` environment variables to `http://127.0.0.1:5000` (or your custom port), or explicitly pass `proxies={'http': '...', 'https': '...'}` to your HTTP client library.

• OSError: [Errno 98] Address already in use

  cause Another application or process is already listening on the default httpdbg port (5000) or the port you specified.
  fix Stop the conflicting process, or start httpdbg on a different port using `httpdbg.start(port=XXXX)` from Python, or `httpdbg --port XXXX` from the command line.

• ModuleNotFoundError: No module named 'httpdbg'

  cause The `httpdbg` library is not installed in your current Python environment, or there's a local file/directory shadowing the installed package.
  fix Run `pip install httpdbg`. If already installed, check `pip list` and ensure there isn't a file named `httpdbg.py` or a directory named `httpdbg` in your current working directory or `PYTHONPATH` that might be conflicting.

Warnings

• breaking Version 2.0.0 introduced HTTP/2 support. While largely compatible, this major version bump could introduce subtle behavioral changes for applications or test suites that implicitly relied on HTTP/1.x characteristics or specific internal proxy behaviors. Always test thoroughly when upgrading to v2.0.0 or later.
  Fix: Review existing HTTP client configurations and test suites, especially those interacting with HTTP/2 endpoints, for unexpected behavior. Consult httpdbg documentation for any new configuration options related to HTTP/2.
• gotcha Requests are not appearing in the httpdbg UI because your application is not using the proxy.
  Fix: Ensure your HTTP client (e.g., `requests`, `httpx`, `urllib`) is explicitly configured to use the `httpdbg` proxy. This often involves setting `HTTP_PROXY` and `HTTPS_PROXY` environment variables to `http://127.0.0.1:5000` (or your chosen port), or passing a `proxies` dictionary to the client functions/sessions.
• gotcha The default port (5000) used by httpdbg is already in use, causing startup failures.
  Fix: If you encounter an 'Address already in use' error, start `httpdbg` on an alternative port, e.g., `httpdbg.start(port=8000)`. You will then need to configure your client to use this new port for the proxy.

Install

• pip install httpdbg Install httpdbg

Imports

• httpdbg

  from httpdbg import httpdbg

  The `httpdbg` module is typically imported to access its `start()` and `stop()` functions.

Quickstart

This quickstart demonstrates how to programmatically start and stop the httpdbg proxy, and then make a simple HTTP request using the `requests` library, ensuring it routes through the proxy for debugging. The environment variables are set to help other libraries (like `httpx`) automatically pick up the proxy.

import requests
from httpdbg import httpdbg
import os

# Start the httpdbg proxy
httpdbg.start()
print(f"httpdbg UI available at: http://127.0.0.1:{httpdbg.port}")

# Configure requests to use the proxy
proxies = {
    'http': f'http://127.0.0.1:{httpdbg.port}',
    'https': f'http://127.0.0.1:{httpdbg.port}'
}
os.environ['HTTP_PROXY'] = proxies['http'] # For clients that respect env vars
os.environ['HTTPS_PROXY'] = proxies['https']

try:
    # Make an HTTP request that will be captured
    print("Making a request...")
    response = requests.get('http://httpbin.org/get', proxies=proxies, timeout=5)
    response.raise_for_status()
    print(f"Request successful: {response.status_code}")
    print("Check the httpdbg UI for captured request details.")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")
finally:
    # Stop the httpdbg proxy
    httpdbg.stop()
    print("httpdbg stopped.")
    # Clean up environment variables
    del os.environ['HTTP_PROXY']
    del os.environ['HTTPS_PROXY']