Skip to content

Latest commit

 

History

History
288 lines (231 loc) · 8.42 KB

IMPLEMENTATION.md

File metadata and controls

288 lines (231 loc) · 8.42 KB

PyRoxi Socket Implementation Summary

🎯 Implementation Overview

Successfully implemented high-speed, socket-based proxy connections for both SOCKS5 and HTTP proxies with binary networking protocols.

✅ Implemented Features

1. SOCKS5 Proxy Support (RFC 1928)

Binary Protocol Implementation

  • Handshake Phase: Binary greeting with authentication methods
  • Authentication: Username/password (RFC 1929) with struct packing
  • Connection Phase: Binary CONNECT request with address encoding
  • Address Types: IPv4, IPv6, and domain name support
  • Error Handling: Complete reply code parsing and error messages

Key Methods

  • _connect_socks5() - Main SOCKS5 connection handler
  • _socks5_authenticate() - Binary authentication packet builder
  • _socks5_send_connect_request() - Address encoding and connection request
  • _get_socks5_error_message() - Human-readable error messages

Binary Operations

# Greeting packet: VER + NMETHODS + METHODS
greeting = struct.pack('BB', SOCKS5_VERSION, len(auth_methods))
greeting += bytes(auth_methods)

# Auth packet: VER + ULEN + UNAME + PLEN + PASSWD
auth = struct.pack('B', 0x01)
auth += struct.pack('B', len(username)) + username_bytes
auth += struct.pack('B', len(password)) + password_bytes

# Connect request: VER + CMD + RSV + ATYP + DST.ADDR + DST.PORT
request = struct.pack('BBB', SOCKS5_VERSION, SOCKS5_CMD_CONNECT, 0x00)
request += struct.pack('B', address_type) + address_bytes
request += struct.pack('>H', port)  # Big-endian port

2. HTTP Proxy Support (RFC 7231)

HTTP CONNECT Tunneling

  • Request Building: Proper HTTP/1.1 CONNECT method
  • Authentication: Basic auth with Base64 encoding
  • Response Parsing: Line-by-line HTTP response reading
  • Status Handling: 200, 407, and other status codes
  • Header Management: Proper header formatting and parsing

Key Methods

  • _connect_http() - HTTP CONNECT tunnel establishment
  • Binary response reading with \r\n\r\n detection
  • Status line parsing and error extraction

Binary Operations

# HTTP CONNECT request
connect_request = "CONNECT host:port HTTP/1.1\r\n"
connect_request += "Host: host:port\r\n"
connect_request += "Proxy-Authorization: Basic {base64}\r\n"
connect_request += "\r\n"

# Response parsing - byte-by-byte reading until headers end
while not response_buffer.endswith(b"\r\n\r\n"):
    chunk = await socket.recv(1)
    response_buffer += chunk

3. High-Performance Socket Operations

Socket Optimizations

# TCP_NODELAY - Disable Nagle's algorithm for low latency
socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)

# SO_KEEPALIVE - Enable TCP keepalive
socket.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)

# Configurable timeout and buffer size
socket.settimeout(timeout)

Core Socket Helpers

  • _socket_send_all() - Ensures all bytes are sent (handles partial writes)
  • _socket_recv_exact() - Receives exact number of bytes (blocks until complete)
  • Proper error handling for timeout, broken connections, and socket errors

4. Data Transfer Methods

Basic Transfer

  • send_data(data: bytes) - Send raw binary data
  • receive_data(buffer_size) - Receive binary data with buffer
  • receive_all(timeout) - Receive until connection closes

Packet Framing

  • send_packet(packet: bytes) - Send with 4-byte length prefix
  • receive_packet() - Receive with length prefix
  • Format: [4 bytes length][N bytes data]
# Send packet: length (4 bytes big-endian) + data
length_prefix = struct.pack('>I', len(packet))
full_packet = length_prefix + packet

# Receive packet: read length, then read exact data
length_bytes = await _socket_recv_exact(4)
packet_length = struct.unpack('>I', length_bytes)[0]
packet = await _socket_recv_exact(packet_length)

HTTP Helper

  • send_http_request() - Complete HTTP request through tunnel
  • Builds proper HTTP/1.1 requests with headers
  • Handles request body and Content-Length
  • Returns complete response

5. Connection Management

Features

  • Context manager support (async with)
  • Connection state tracking
  • Graceful disconnect with shutdown()
  • Connection validation with SO_ERROR
  • Connection info dictionary

Configuration

connection = Connection(
    proxy_address="127.0.0.1",
    proxy_port=1080,
    proxy_type='socks5',  # or 'http'
    username="user",      # optional
    password="pass",      # optional
    timeout=30,           # seconds
    buffer_size=8192      # bytes
)

# Runtime adjustments
conn.set_timeout(60)
conn.set_buffer_size(16384)

# Connection info
info = conn.get_connection_info()

6. Error Handling

Exception Hierarchy

  • ProxyConnectionError - Connection issues
  • ProxyAuthenticationError - Auth failures

Detailed Error Messages

  • SOCKS5 reply codes with descriptions
  • HTTP status code parsing
  • Socket timeout and broken connection detection
  • Validation errors (packet size, credentials length)

7. Logging Support

import logging
logger = logging.getLogger(__name__)

# Debug logging throughout
logger.debug("Connecting to SOCKS5 proxy...")
logger.debug(f"Sent greeting: {greeting.hex()}")
logger.info(f"Successfully connected to {host}:{port}")

📊 Performance Features

Speed Optimizations

  1. Direct Socket API - No HTTP library overhead
  2. TCP_NODELAY - Immediate packet sending
  3. Binary Operations - Struct packing instead of string manipulation
  4. Async I/O - Non-blocking operations
  5. Configurable Buffer - Tunable for workload
  6. Connection Reuse - Keepalive enabled

Binary Networking Benefits

  • Smaller Packets - Binary vs text encoding
  • Faster Parsing - Struct unpacking vs string parsing
  • Precise Control - Exact byte operations
  • Protocol Compliance - RFC-compliant implementation

🧪 Example Usage

SOCKS5 Connection

async with Connection("127.0.0.1", 1080, 'socks5') as conn:
    await conn.connect("example.com", 80)
    await conn.send_data(b"GET / HTTP/1.1\r\n\r\n")
    response = await conn.receive_all()

HTTP Proxy with Auth

conn = Connection(
    "proxy.com", 8080, 'http',
    username="user", password="pass"
)
await conn.connect("api.example.com", 443)
await conn.send_data(tls_handshake_bytes)

Binary Packet Transfer

# Send with framing
binary_packet = b"\x00\x01\x02\x03"
await conn.send_packet(binary_packet)

# Receive with framing
received = await conn.receive_packet()

📝 Code Quality

Best Practices Implemented

  • ✅ Type hints throughout
  • ✅ Async/await patterns
  • ✅ Context managers
  • ✅ Comprehensive error handling
  • ✅ Logging support
  • ✅ Documentation strings
  • ✅ Binary protocol constants
  • ✅ Validation and sanitization

Security Considerations

  • Timeout protection
  • Max packet size validation (10MB limit)
  • Credential length validation
  • Socket error checking
  • Graceful shutdown

🎓 Technical Implementation Details

SOCKS5 Protocol Flow

  1. Greeting → Server chooses auth method
  2. Authentication → Username/password validation (if required)
  3. Connection Request → Target address + port
  4. Server Reply → Success or error code
  5. Data Transfer → Bidirectional communication

HTTP CONNECT Flow

  1. CONNECT Request → Target host:port
  2. Proxy Authentication → Basic auth header (if required)
  3. Response → 200 Connection Established
  4. Tunnel → Direct TCP forwarding

Binary Data Handling

  • All network data as bytes
  • Struct module for packing/unpacking
  • Big-endian for network byte order
  • Proper encoding for text (UTF-8)
  • Hex display for debugging

🚀 Next Steps / Future Enhancements

Potential additions:

  • Connection pooling
  • SOCKS4 support
  • UDP support for SOCKS5
  • SSL/TLS wrapping
  • Proxy chaining
  • Performance metrics
  • Retry logic
  • Rate limiting
  • Connection health checks

📚 References

  • RFC 1928 - SOCKS Protocol Version 5
  • RFC 1929 - Username/Password Authentication for SOCKS V5
  • RFC 7231 - HTTP/1.1 Semantics (CONNECT method)
  • Python socket documentation
  • Python struct documentation
  • Python asyncio documentation

✨ Summary

A complete, high-performance proxy library with:

  • Pure socket implementation
  • Binary networking protocols
  • Full SOCKS5 and HTTP proxy support
  • Authentication for both protocols
  • Optimized for speed and reliability
  • Production-ready error handling
  • Comprehensive examples and documentation