{"id":1715,"library":"socksio","title":"socksio library","description":"socksio is a sans-I/O implementation of the SOCKS4, SOCKS4A, and SOCKS5 proxy protocols. It provides the state machines necessary for handling SOCKS proxy negotiation without performing any network I/O itself, making it ideal for integration into asynchronous network frameworks. Currently at version 1.0.0, it follows a stable release cadence with releases primarily for bug fixes or minor enhancements.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/sethmlarson/socksio","tags":["networking","proxy","socks","sans-io","asynchronous"],"install":[{"cmd":"pip install socksio","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Socks5Connection","correct":"from socksio import Socks5Connection"},{"symbol":"Socks5AuthMethods","correct":"from socksio import Socks5AuthMethods"},{"symbol":"SOCKS5_NO_AUTH","correct":"from socksio import SOCKS5_NO_AUTH"},{"symbol":"ConnectionState","correct":"from socksio import ConnectionState"},{"symbol":"BadSocksConnectionState","correct":"from socksio import BadSocksConnectionState"}],"quickstart":{"code":"from socksio import Socks5Connection, Socks5AuthMethods, SOCKS5_NO_AUTH, ConnectionState\n\n# This example demonstrates the SOCKS5 state machine, it does not perform actual network I/O.\n# In a real application, 'client_greeting_data' would be written to a socket,\n# and 'server_greeting_response' would be read from that socket.\n\n# 1. Initialize a SOCKS5 connection to a target host and port.\ntarget_host = \"example.com\"\ntarget_port = 80\nconn = Socks5Connection(target_host, target_port)\nprint(f\"Initial state: {conn.state}\") # Expected: ConnectionState.INIT\n\n# 2. Client sends greeting with supported authentication methods.\n# For SOCKS5, common is NO_AUTH.\nclient_greeting_data = conn.send(Socks5AuthMethods([SOCKS5_NO_AUTH]))\nprint(f\"\\nClient sends greeting ({len(client_greeting_data)} bytes): {client_greeting_data.hex()}\")\nprint(f\"State after sending greeting: {conn.state}\") # Expected: ConnectionState.WAITING_FOR_AUTH_METHOD_SELECTION\n\n# 3. Simulate server response to greeting.\n# A SOCKS5 server typically responds with version (0x05) and selected method (0x00 for NO_AUTH).\nserver_greeting_response = b'\\x05\\x00'\nconn.receive(server_greeting_response)\nprint(f\"\\nServer responds to greeting ({len(server_greeting_response)} bytes): {server_greeting_response.hex()}\")\nprint(f\"State after receiving greeting response: {conn.state}\") # Expected: ConnectionState.AUTH_SUCCESS\n\n# 4. Client sends connection request.\n# The `send()` method generates the connect request based on target_host/port.\nclient_connect_data = conn.send()\nprint(f\"\\nClient sends connect request ({len(client_connect_data)} bytes): {client_connect_data.hex()}\")\nprint(f\"State after sending connect request: {conn.state}\") # Expected: ConnectionState.WAITING_FOR_CONNECT_REPLY\n\n# 5. Simulate server response to connection request.\n# A successful SOCKS5 connect reply for IPv4 would be:\n# 0x05 (version) 0x00 (success) 0x00 (reserved) 0x01 (IPv4 address type)\n# followed by bound address (4 bytes, e.g., 127.0.0.1) and bound port (2 bytes, e.g., 80)\nserver_connect_response = b'\\x05\\x00\\x00\\x01\\x7f\\x00\\x00\\x01\\x00\\x50' # 127.0.0.1:80\nconn.receive(server_connect_response)\nprint(f\"\\nServer responds to connect request ({len(server_connect_response)} bytes): {server_connect_response.hex()}\")\nprint(f\"Final state: {conn.state}\") # Expected: ConnectionState.OPEN\n\nif conn.is_connected:\n    print(\"\\nSOCKS5 handshake successfully completed (simulated).\")\n    print(f\"Bound address: {conn.bound_address}, Bound port: {conn.bound_port}\")\nelse:\n    print(\"\\nSOCKS5 handshake failed (simulated).\")\n","lang":"python","description":"This quickstart demonstrates the core functionality of `socksio` by simulating a SOCKS5 proxy handshake. It shows how to initialize a connection, send client data, receive simulated server responses, and observe the state transitions. Remember that `socksio` handles only the protocol state machine, not actual network I/O."},"warnings":[{"fix":"Implement custom I/O logic using standard library `socket` or an asynchronous framework like `asyncio` to read from and write to the network based on `socksio`'s output and input.","message":"socksio explicitly does not perform any network I/O. Users must integrate `socksio`'s `send()` and `receive()` methods with their own socket or network transport layer (e.g., `asyncio`, `trio`, `socket`). This is a common source of confusion if expecting a full client.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"After the SOCKS handshake, transition your I/O loop to send and receive application-specific data directly over the underlying network connection, bypassing `socksio`.","message":"The library's scope is limited to the SOCKS proxy negotiation handshake. Once the `ConnectionState.OPEN` state is reached, `socksio` is no longer involved, and subsequent application data must be handled directly by the user's code via the established connection.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Wrap calls to `conn.receive()` and `conn.send()` in `try...except` blocks to catch specific `socksio` exceptions and handle them appropriately, such as logging the error and closing the connection.","message":"Protocol violations or unexpected server responses will raise exceptions (e.g., `BadSocksConnectionState`, `MalformedSocks5Reply`). Robust applications must catch and handle these errors to manage connection failures gracefully.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}