{"id":4694,"library":"proxy-protocol","title":"PROXY Protocol Library for Asyncio","description":"The `proxy-protocol` library provides an implementation of the PROXY protocol, including an `asyncio` server implementation, for Python. It currently supports versions 0.11.3 and is actively maintained with regular minor releases, focusing on improvements, bug fixes, and broader platform support.","status":"active","version":"0.11.3","language":"python","source_language":"en","source_url":"https://github.com/icgood/proxy-protocol/","tags":["asyncio","networking","proxy-protocol","server","load-balancing","proxy"],"install":[{"cmd":"pip install proxy-protocol","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required Python version as specified by PyPI metadata.","package":"python>=3.8","optional":false},{"reason":"Optional dependency for PROXY protocol v2 checksum validation. If missing, v2 handling might raise exceptions or lack full validation.","package":"crc32c","optional":true}],"imports":[{"symbol":"ProxyProtocolDetect","correct":"from proxyprotocol.detect import ProxyProtocolDetect"},{"symbol":"ProxyProtocolReader","correct":"from proxyprotocol.reader import ProxyProtocolReader"},{"symbol":"SocketInfo","correct":"from proxyprotocol.sock import SocketInfo"},{"symbol":"ProxyProtocolVersion","correct":"from proxyprotocol.version import ProxyProtocolVersion"}],"quickstart":{"code":"import asyncio\nfrom asyncio import StreamReader, StreamWriter\nfrom proxyprotocol.detect import ProxyProtocolDetect\nfrom proxyprotocol.reader import ProxyProtocolReader\nfrom proxyprotocol.sock import SocketInfo\n\nasync def on_connection(reader: StreamReader, writer: StreamWriter, info: SocketInfo) -> None:\n    print(f\"Connection from: {info.family.name} {info.peername}\")\n    print(f\"Original client: {info.source_addr}:{info.source_port} -> {info.dest_addr}:{info.dest_port}\")\n    # Echo back received data (optional, for demonstration)\n    while True:\n        data = await reader.read(1024)\n        if not data: break\n        writer.write(data)\n        await writer.drain()\n    writer.close()\n    await writer.wait_closed()\n\nasync def main(host: str, port: int) -> None:\n    pp_detect = ProxyProtocolDetect()\n    callback = ProxyProtocolReader(pp_detect).get_callback(on_connection)\n    server = await asyncio.start_server(callback, host, port)\n    async with server:\n        await server.serve_forever()\n\nif __name__ == '__main__':\n    # To test, configure your proxy (e.g., HAProxy, NGINX) to send PROXY protocol\n    # to localhost:10007. Then connect to the proxy directly.\n    # Example with `netcat` after a proxy is set up:\n    # echo 'hello' | nc -q 1 localhost 10007\n    try:\n        asyncio.run(main('127.0.0.1', 10007))\n    except KeyboardInterrupt:\n        print(\"Server stopped.\")","lang":"python","description":"This example sets up an asyncio server that listens for incoming connections. It uses `ProxyProtocolDetect` to automatically detect PROXY protocol v1 or v2 headers. Once a connection is established and the header is parsed (if present), the `on_connection` callback receives a `SocketInfo` object containing the original client and destination address details, and then echoes any received data back to the client. This demonstrates how to integrate `proxy-protocol` with a standard `asyncio.start_server` setup."},"warnings":[{"fix":"Review code that interacts with `SocketInfo.family` or other address family-related attributes. Ensure compatibility with potentially updated or normalized `AF_*` values, especially if you manually handle socket families.","message":"Version 0.11.0 changed how address family (AF_*) constants are handled internally to enable support for Windows. This change 'Avoid using AF_* as proxy result type' might subtly affect applications that previously relied on specific `AF_*` values or behavior on non-Windows platforms, although it primarily enabled broader compatibility.","severity":"breaking","affected_versions":"0.11.0"},{"fix":"Consult the official release notes and documentation for 0.9.0 and later to understand the new API structure. Update import paths and method calls according to the new abstractions, particularly around `ProxyProtocolReader` and how callbacks are registered.","message":"Version 0.9.0 introduced a 'rework of the API with better abstractions.' This signifies significant changes to the library's interfaces and how components are used. Existing code written against older APIs will likely break.","severity":"breaking","affected_versions":"0.9.0"},{"fix":"For robust PROXY protocol v2 handling, especially in environments where checksum validation is critical, ensure `crc32c` is installed (`pip install crc32c`). If not installed, be aware that v2 checksums cannot be validated, even if the library handles the missing module gracefully.","message":"The `proxy-protocol` library, when handling PROXY protocol v2, can throw a 'bad exception' if the optional `crc32c` module is missing. While fixed in 0.11.2 to gracefully handle the absence, earlier versions might crash or behave unexpectedly. Even with the fix, performance or full checksum validation for v2 might be impacted without `crc32c`.","severity":"gotcha","affected_versions":"<0.11.2 (potential for hard crash), >=0.11.2 (graceful, but missing feature)"},{"fix":"Carefully configure `ProxyProtocolReader` or `ProxyProtocolVersion`. If you intend to detect and use PROXY protocol headers, use `ProxyProtocolVersion.get('detect')`, `ProxyProtocolVersion.get('v1')`, or `ProxyProtocolVersion.get('v2')` as appropriate, rather than `None`.","message":"Using `ProxyProtocolVersion.get(None)` or similar configurations for a `ProxyProtocolReader` explicitly disables PROXY protocol header detection. This means the server will treat all connections as direct, without parsing any PROXY headers, potentially leading to incorrect source IP information.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.11.3':29 'activ':32 'asyncio':5,20,47 'balanc':55 'broader':44 'bug':41 'current':26 'fix':42 'focus':38 'implement':13,22 'improv':40 'includ':18 'librari':3,10 'load':54 'load-balanc':53 'maintain':33 'minor':36 'network':48 'platform':45 'protocol':2,9,17,51 'provid':11 'proxi':1,8,16,50,56 'proxy-protocol':7,49 'python':24 'regular':35 'releas':37 'server':21,52 'support':27,46 'version':28","created_at":"2026-04-12T14:03:37.231353+00:00","updated_at":"2026-04-16T18:13:12.771504+00:00","problems":[{"fix":"Install the library using pip: `pip install proxy-protocol`","cause":"The `proxy-protocol` library has not been installed or the Python environment where the code is run does not have it installed.","error":"ModuleNotFoundError: No module named 'proxyprotocol'"},{"fix":"Ensure the library is correctly installed (`pip install proxy-protocol`) and verify the exact import path against the library's API reference or examples.","cause":"The specific submodule `detect` (or another submodule like `reader`, `sock`, `version`) cannot be found, possibly due to a typo in the import path or an incomplete installation.","error":"from proxyprotocol.detect import ProxyProtocolDetect\nModuleNotFoundError: No module named 'proxyprotocol.detect'"},{"fix":"Ensure the client connecting to the `proxy-protocol` server is configured to send valid PROXY protocol headers (either v1 or v2). If the client should not send PROXY protocol, configure the server to either not use `proxy-protocol` for that listener or handle non-PROXY protocol connections gracefully.","cause":"This error often occurs when an `asyncio` server using `proxy-protocol` expects a PROXY protocol header, but the connecting client either does not send one, sends a malformed one, or closes the connection prematurely. The server interprets the unexpected data (or lack thereof) as a protocol violation and closes the socket.","error":"ConnectionResetError: [WinError 10054] An existing connection was forcibly closed by the remote host"},{"fix":"When using `ProxyProtocolReader` with `asyncio.start_server`, you must provide the callback returned by `get_callback()`: `callback = ProxyProtocolReader(pp_detect).get_callback(on_connection)`","cause":"This error typically arises when attempting to use an instance of `ProxyProtocolReader` directly as a callback function for `asyncio.start_server`, instead of calling its `get_callback()` method.","error":"TypeError: 'ProxyProtocolReader' object is not callable"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.11.3","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/icgood/proxy-protocol","docs":null,"changelog":null,"pypi":"https://pypi.org/project/proxy-protocol/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}