pproxy - A Powerful Regex-Based Proxy Server

Common errors

• Address already in use

  cause The specified listening port (e.g., 8080) is already occupied by another process on your system.
  fix Choose a different port for pproxy to listen on, or identify and terminate the process currently using the desired port.

• No module named 'pproxy'

  cause The `pproxy` package is not installed in the currently active Python environment, or the environment is not correctly configured.
  fix Install the package using `pip install pproxy`. If using virtual environments, ensure you activate the correct one before running.

• ValueError: Invalid URL format for listen address: ...

  cause The argument provided for a listen (`-l`) or remote (`-r`) address does not conform to the expected URL-like format, often missing a protocol scheme.
  fix Ensure that all listen and remote addresses are prefixed with their respective protocol schemes, e.g., `http://:8080`, `socks5://127.0.0.1:1080`.

• Connection refused

  cause This typically occurs when a client tries to connect to the pproxy server but the server is not running, or when pproxy tries to connect to a remote server that is unreachable, blocked by a firewall, or not running.
  fix Verify that the `pproxy` server is running and accessible on the specified port. Check firewall rules on both the proxy host and the remote host. Ensure the remote server is active and listening.

Warnings

• gotcha pproxy migrated to asyncio in version 2.0.0. While the command-line interface remains consistent, programmatic users integrating `pproxy.main()` into existing blocking codebases might encounter unexpected behavior or need to adapt their environment to run `asyncio` event loops.
  Fix: Ensure your application's main loop or context is compatible with asyncio when embedding `pproxy.main()`. If you are running `main()` directly, it will handle the event loop.
• gotcha The `-l` (listen) and `-r` (remote) arguments require specific URL-like formats (e.g., `http://:8080`, `socks5://user:pass@host:port`). Omitting the scheme (e.g., just `:8080`) or providing an incorrect format is a common mistake that leads to parsing errors.
  Fix: Always include the protocol scheme (e.g., `http://`, `https://`, `socks5://`) when specifying listen and remote addresses. Consult the documentation for exact syntax.
• gotcha The `-r` (remote) rules use full Python regular expressions to match incoming requests against defined patterns. Users often expect simple wildcard matching (e.g., `*`) and are surprised by the full regex syntax, leading to misconfigured routing.
  Fix: Familiarize yourself with Python's `re` module syntax when defining complex remote rules. Test your regex patterns thoroughly to ensure they match traffic as intended.

Install

• pip install pproxy Install pproxy

Imports

• main

  from pproxy import main

  The primary programmatic entry point for pproxy, typically used to run the server with simulated command-line arguments.

Quickstart

This quickstart demonstrates how to programmatically start a pproxy server using its `main` function. It configures the proxy to listen for HTTP connections on port 8080 and forward them to a remote SOCKS5 proxy running on localhost:1080. This mimics command-line invocation for embedded use.

import sys
from pproxy import main

# Configure pproxy to listen on HTTP port 8080
# and forward all requests to a SOCKS5 proxy at 127.0.0.1:1080.
# This simulates running: python -m pproxy -l http://:8080 -r socks5://127.0.0.1:1080

sys.argv = ['pproxy', '-l', 'http://:8080', '-r', 'socks5://127.0.0.1:1080']
print("Starting pproxy server on http://:8080, forwarding to socks5://127.0.0.1:1080...")
print("Press Ctrl+C to stop.")

try:
    main()
except KeyboardInterrupt:
    print("\npproxy server stopped.")