Multi protocol proxy

[abnegate]

Summary by CodeRabbit

• New Features

  • Multi-service Docker setup and runnable proxy examples; Resolver-based dynamic backend routing; read/write split for DB proxies with transaction pinning; TLS/mTLS termination for TCP.

• Documentation

  • Major README overhaul with Resolver/benchmark guidance; new benchmarks suite and runner docs; removed legacy PERFORMANCE.md.

• Tests

  • Extensive unit, integration, and performance test suites added.

• Chores

  • CI workflows (lint, static analysis, tests); environment example; PHP bumped to 8.4 and Swoole to 6.0.

[greptile-apps]

Greptile Summary

This PR is a comprehensive refactor and major feature expansion of the proxy library, renaming it from appwrite/protocol-proxy to utopia-php/proxy, bumping the minimum requirements to PHP 8.4 / Swoole 6.0, and adding multi-protocol support (HTTP, TCP, SMTP) with TLS/mTLS termination, a resolver-based routing architecture, connection pooling, byte tracking, and an extensive test suite.

The architecture is well thought out — the Resolver interface, Adapter base class, and protocol-specific servers are cleanly separated. However, several functional correctness issues were found:

• SMTP server drops all SMTP commands silently — package_eof is set without the required open_eof_check: true, so Swoole never splits data by \r\n. SMTP commands will be batched or split arbitrarily in onReceive, breaking the entire SMTP proxy.
• HTTP forwardRawRequest drops all backend response headers — Content-Type, Location, Cache-Control, cookies, etc. are never forwarded to the proxied client.
• HTTP forwardRawRequest returns truncated bodies for chunked responses — only the bytes already in the receive buffer are returned; the remaining chunks are never fetched.
• TCP adapter routing collisions for long first-packets — raw packet data is used as the Swoole Table routing cache key; keys over 64 bytes are silently truncated, which can cause distinct connections to resolve to the same cached backend.
• Uninitialized typed property $adapter — getStats() on the HTTP and SMTP Swoole servers will fatal before any worker has started (e.g. in tests or monitoring endpoints called from the master process).
• Routing cache TTL is ≤ 1 second — the cache is invalidated every second, making it nearly useless for reducing resolver round-trips under real workloads.

Confidence Score: 2/5

• Not safe to merge — the SMTP server is broken by a missing Swoole config option, the HTTP raw forwarder silently drops response headers, and chunked responses are truncated.
• Multiple P1 correctness bugs affect all three supported protocols: the SMTP proxy will misparse every command due to the missing open_eof_check; the HTTP raw path drops all response headers and truncates chunked bodies; the TCP routing cache can collide for real database clients. These are not edge cases — they affect core forwarding functionality on the default code paths.
• src/Server/SMTP/Swoole.php (open_eof_check missing), src/Server/HTTP/Swoole.php and src/Server/HTTP/SwooleCoroutine.php (forwardRawRequest header/chunked issues), src/Adapter/TCP.php (routing key truncation)

Important Files Changed

Filename	Overview
src/Adapter.php	New base adapter class with SSRF validation, Swoole Table routing cache, and byte tracking. Main concern: routing cache TTL is < 1 second (effectively per-second), making caching nearly ineffective under real workloads.
src/Adapter/TCP.php	TCP adapter routing using raw packet data as the Swoole Table cache key — keys exceeding 64 bytes are silently truncated, causing routing cache collisions between distinct connections with longer startup packets (e.g. PostgreSQL).
src/Server/HTTP/Swoole.php	HTTP proxy server with two issues in forwardRawRequest: (1) backend response headers are never forwarded to the client, (2) chunked responses return only the buffered partial body. Additionally, getStats() will fatal on uninitialized $adapter property before onWorkerStart is called.
src/Server/HTTP/SwooleCoroutine.php	Coroutine HTTP proxy server — similar forwardRawRequest path exists here and carries the same header-forwarding and chunked-response issues as the non-coroutine variant.
src/Server/SMTP/Swoole.php	SMTP proxy server with a critical misconfiguration: package_eof is set but open_eof_check is never enabled, so Swoole does not split incoming data by CRLF. getStats() also accesses the uninitialized $adapter property before onWorkerStart.
src/Server/TCP/Swoole.php	Event-driven TCP proxy server with TLS termination support. Handles PostgreSQL STARTTLS and MySQL SSL correctly. Bidirectional forwarding uses exportSocket() which is idiomatic for Swoole. Looks sound.
src/Server/TCP/TLS.php	TLS configuration with PostgreSQL/MySQL detection helpers. Cipher suite defaults are strong and modern; minimum TLS 1.2 is enforced. Validate() correctly checks file readability and CA requirement for mTLS.
src/Resolver.php	Clean interface definition with all expected lifecycle hooks (resolve, track, purge, onConnect, onDisconnect, getStats). No issues.

Comments Outside Diff (1)

1. src/Server/HTTP/Swoole.php, line 541-552 (link)

   Uninitialized typed property $adapter accessed in getStats()

   protected Adapter $adapter; is a typed property with no default value. It is only assigned inside onWorkerStart(). In the multi-worker Swoole process model the master/manager process never calls onWorkerStart, so getStats() called from the master process — or from a test before the server has started — will throw a fatal error:

   Typed property Swoole::$adapter must not be accessed before initialization

   Declare a nullable default or guard the access:

   The same issue exists in src/Server/SMTP/Swoole.php — $this->adapter->getStats() in getStats() will also fail before onWorkerStart has been called.

_{Reviews (1): Last reviewed commit: "(refactor): Use \go instead of Coroutine..." | Re-trigger Greptile}