Socks React Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require clue/socks-react
   

   Add to composer.json if using Laravel:

   "require": {
       "clue/socks-react": "^1.0"
   }
   

2. Basic Usage:

   use Clue\React\Socks\Client;
   use React\Socket\Connector;
   
   // Initialize SOCKS client
   $proxy = new Client('socks://your-proxy-host:port');
   
   // Wrap in ReactPHP Connector
   $connector = new Connector(['tcp' => $proxy, 'dns' => false]);
   
   // Use with HTTP client (e.g., Guzzle or ReactPHP HTTP)
   $browser = new React\Http\Browser($connector);
   $browser->get('https://example.com')->then(...);
   

3. First Use Case: Route Laravel HTTP client requests through a SOCKS proxy:

   $proxy = new Client('socks://proxy.example.com:1080');
   $connector = new Connector(['tcp' => $proxy, 'dns' => false]);
   
   $client = new React\Http\Browser($connector);
   $response = $client->get('https://api.example.com/data');
   

Where to Look First

• README.md: Focus on the Quickstart example and Usage sections.
• Examples: Clone the repo and inspect examples/ for practical implementations.
• API Docs: Check the ConnectorInterface for integration patterns.

Implementation Patterns

Core Workflows

1. Proxy-Aware HTTP Requests

Replace Laravel’s default HTTP client (Guzzle) with a SOCKS-aware ReactPHP HTTP client:

// In a Laravel service provider
public function register()
{
    $proxy = new Client('socks://proxy.example.com:1080');
    $connector = new Connector(['tcp' => $proxy, 'dns' => false]);
    $this->app->singleton('react.http.client', function () use ($connector) {
        return new React\Http\Browser($connector);
    });
}

Use Case: Scrape websites or access geo-restricted APIs anonymously.

2. TCP-Level Proxying

Proxy raw TCP connections (e.g., for custom protocols like SMTP/IMAP):

$proxy = new Client('socks://proxy.example.com:1080');
$proxy->connect('tcp://mail.example.com:25')->then(function ($connection) {
    $connection->write("EHLO example.com\r\n");
    // Handle response...
});

Use Case: Route Laravel queue workers (e.g., tcp://) through a proxy.

3. Proxy Chaining

Chain multiple proxies (e.g., SOCKS → Tor → Destination):

$innerProxy = new Client('socks://tor-exit-node:9050');
$outerProxy = new Client('socks://your-proxy:1080', new Connector(['tcp' => $innerProxy]));

Use Case: Multi-layer anonymization for sensitive operations.

4. Server-Side Proxy

Implement a custom SOCKS server in Laravel (e.g., for internal routing):

$socks = new \Clue\React\Socks\Server();
$socket = new \React\Socket\SocketServer('0.0.0.0:1080');
$socks->listen($socket);

Use Case: Route internal traffic through a local proxy for logging/monitoring.

Integration Tips

Laravel-Specific

1. Service Container Binding: Bind the SOCKS client to Laravel’s container for dependency injection:

   $this->app->bind(Client::class, function () {
       return new Client(config('proxy.socks_uri'));
   });
   

2. Configurable Proxy: Store proxy settings in config/proxy.php:

   return [
       'socks_uri' => env('SOCKS_PROXY', 'socks://proxy.example.com:1080'),
       'timeout' => 10.0,
   ];
   

3. Middleware for Proxy Routing: Create middleware to route specific requests through the proxy:

   public function handle($request, Closure $next)
   {
       if ($request->isProxyRoute()) {
           $connector = new Connector(['tcp' => app(Client::class)]);
           $client = new React\Http\Browser($connector);
           return $client->get($request->url());
       }
       return $next($request);
   }
   

ReactPHP Patterns

1. Promise Chaining: Chain promises for sequential proxy operations:

   $proxy->connect('tcp://target:port')
         ->then(function ($conn) {
             return $conn->write('DATA');
         })
         ->then(function () use ($conn) {
             return $conn->end();
         });
   

2. Event-Driven Workflows: Use ReactPHP’s event loop for async proxy operations:

   $loop = React\EventLoop\Factory::create();
   $proxy = new Client('socks://proxy:1080');
   $loop->run();
   

3. Custom DNS Resolution: Override DNS resolution for proxy-specific domains:

   $connector = new Connector([
       'tcp' => $proxy,
       'dns' => function ($host) {
           return $host === 'proxy.example.com' ? '192.168.1.100' : null;
       }
   ]);
   

Gotchas and Tips

Pitfalls

1. DNS Leaks:

   • Issue: SOCKS4(a) may leak DNS queries if the proxy doesn’t support remote resolution.
   • Fix: Use SOCKS5 (socks5://) or configure the proxy to handle DNS.
   • Debug: Check logs for EHOSTUNREACH errors.

2. Timeout Handling:

   • Issue: Default timeouts may be too short for slow proxies.
   • Fix: Configure timeouts in the Connector:

     $connector = new Connector([
         'tcp' => $proxy,
         'timeout' => 30.0, // seconds
     ]);
     

3. TLS Handshake Failures:

   • Issue: Some proxies interfere with TLS negotiation.
   • Fix: Disable peer verification (temporarily for testing):

     $connector = new Connector([
         'tls' => ['verify_peer' => false],
         'tcp' => $proxy,
     ]);
     

4. Proxy Authentication:

   • Issue: SOCKS5 auth may fail silently.
   • Fix: Explicitly set credentials:

     $proxy = new Client('socks://user:pass@proxy.example.com:1080');
     

5. IPv6 Limitations:

   • Issue: SOCKS4(a) doesn’t support IPv6.
   • Fix: Use SOCKS5 (socks5://) for IPv6 targets.

Debugging

1. Enable Verbose Logging:

   $proxy = new Client('socks://proxy:1080', null, [
       'debug' => true,
   ]);
   

2. Packet Inspection: Use Wireshark or tcpdump to inspect SOCKS traffic:

   tcpdump -i any -w socks_traffic.pcap port 1080
   

3. Promise Errors: Always handle promise rejections:

   $proxy->connect('tcp://target')
         ->then(...)
         ->otherwise(function (Exception $e) {
             \Log::error('Proxy failed: ' . $e->getMessage());
         });
   

Extension Points

1. Custom Proxy URI Parsing: Extend the Client to support custom URI schemes:

   $proxy = new Client('custom://user:pass@proxy:1080');
   

2. Proxy Rotation: Implement a rotating proxy pool:

   $proxies = ['socks://p1:1080', 'socks://p2:1080'];
   $currentProxy = new Client($proxies[array_rand($proxies)]);
   

3. Server-Side Extensions: Extend the Server class to add custom auth logic:

   $socks = new class extends \Clue\React\Socks\Server {
       protected function onAuthenticate($username, $password) {
           return $username === 'admin' && $password === 'secret';
       }
   };
   

4. Protocol Extensions: Add support for UDP (not natively supported):

   // Requires custom implementation (