Proxy.py

Warnings

• deprecated Usage of `ssl.wrap_socket` is deprecated in favor of `SSLContext.wrap_socket` for better security and future compatibility.
  Fix: If implementing custom SSL handling, migrate to `SSLContext.wrap_socket`. The library's internal components generally handle this automatically in recent versions.
• gotcha TLS (HTTPS) interception requires the `cryptography` Python package and a functional `openssl` command-line utility in your system's PATH. Certificate management (generating root CA, signing server certificates) is also crucial and must be properly configured.
  Fix: Ensure `pip install proxy.py[tls]` is used. Verify `openssl` is installed and accessible. For production, manage certificates securely and consider the `--insecure-tls-interception` flag only for development/testing.
• gotcha The library heavily relies on a pluggable architecture. To implement custom logic (e.g., modifying requests, logging, authentication), you must create and register plugins correctly. Misconfigured or missing plugins can lead to unexpected proxy behavior or unhandled requests.
  Fix: Familiarize yourself with the plugin API (e.g., `HttpProxyPlugin`, `WebServerPlugin`, `GroutPlugin`). Ensure plugins are listed correctly in the `--plugins` argument or passed programmatically when initializing `Proxy`.
• gotcha The Grout feature, which offers ngrok-like functionality for exposing local services, requires specific configuration and understanding of its tunneling mechanics. Improper setup can expose services insecurely or fail to establish tunnels.
  Fix: Review the Grout documentation thoroughly. Ensure correct hostnames, ports, and (if applicable) authentication are configured. Be mindful of security implications when exposing local services to the internet.
• gotcha Many features (e.g., dashboard, metrics, SSH proxy) are gated behind optional `extras` during installation. If functionality is missing or imports fail, it's often due to not installing the required extras.
  Fix: Always install with the necessary extras, e.g., `pip install proxy.py[dashboard,tls]`, to ensure all desired features and their dependencies are available.

Install

• pip install proxy.py Basic Install
• pip install proxy.py[dashboard,tls,grout,ssh] Install with All Extras

Imports

• Proxy

  from proxy.py import Proxy

• HttpProxyPlugin

  from proxy.py.http.proxy import HttpProxyPlugin

  Plugin paths changed over time; always refer to the specific module path, e.g., `proxy.py.http.proxy.HttpProxyPlugin`
• http

  from proxy.py import http

  Provides access to core HTTP components and utilities.

Quickstart

This quickstart demonstrates how to programmatically start a basic HTTP forward proxy on `127.0.0.1:8899` using `proxy.py`. The `Proxy.main()` method is used with a list of arguments, mimicking command-line input. The `with` statement ensures proper resource management. The `time.sleep` loop keeps the main thread alive while the proxy runs in its own threads, allowing it to handle requests until a `KeyboardInterrupt` (Ctrl+C) is received.

import os
from proxy.py import Proxy

if __name__ == '__main__':
    # Example: Run a basic HTTP proxy on localhost:8899
    args = [
        '--hostname', '127.0.0.1',
        '--port', '8899',
        '--num-workers', '1', # For a simple quickstart
        '--disable-web-server', # Disable built-in web server if only proxy is needed
        '--plugins', 'proxy.py.http.proxy.HttpProxyPlugin' # Explicitly enable HTTP proxy
    ]

    print(f"Starting HTTP proxy on 127.0.0.1:8899...")
    print("Use Ctrl+C to stop.")

    try:
        # Proxy.main() takes arguments similar to command-line execution
        with Proxy.main(args):
            # The proxy runs in separate worker threads within the context manager.
            # Keep the main thread alive to allow the proxy to run.
            import time
            while True:
                time.sleep(1) 
    except KeyboardInterrupt:
        print("\nProxy stopped.")
    except Exception as e:
        print(f"An error occurred: {e}")