Goridge Laravel Package

## Getting Started

### Minimal Setup
1. **Install the package**:
   ```bash
   composer require spiral/goridge

2. Basic RPC call (TCP example):

   use Spiral\Goridge\RPC\RPC;
   use Spiral\Goridge\Relay;
   
   $rpc = new RPC(Relay::create('tcp://127.0.0.1:6001'));
   $response = $rpc->call('Service.Method', ['arg1', 'arg2']);
   

3. Unix socket or pipes:

   $unixRPC = new RPC(Relay::create('unix:///tmp/rpc.sock'));
   $streamRPC = new RPC(Relay::create('pipes://stdin:stdout'));
   

First Use Case: Calling Go Services

• Validate Go service compatibility: Ensure the Go service uses net/rpc or goridge protocol.
• Test connectivity: Use ping/pong flags (v4.1.0+) for liveness checks:

  $rpc->call('Service.Ping', [], ['flags' => RPC::FLAG_PING]);
  

Implementation Patterns

Core Workflows

1. Synchronous RPC Calls

   $result = $rpc->call('User.Get', ['id' => 123]);
   

   • Supports JSON (default) or MsgPack (binary) payloads via Relay configuration.

2. Streaming Large Payloads

   $rpc->call('File.Upload', ['data' => $binaryData], ['codec' => 'msgpack']);
   

   • Use []byte for binary data (e.g., file uploads, protobuf messages).

3. Multi-Relay Async (v4.2.0+)

   $multiRPC = new MultiRPC([
       Relay::create('tcp://127.0.0.1:6001'),
       Relay::create('unix:///tmp/backup.sock')
   ]);
   $promise = $multiRPC->callAsync('Service.Method', []);
   

4. Error Handling

   try {
       $rpc->call('Failing.Method');
   } catch (ServiceException $e) {
       // Service-level error (e.g., invalid args).
   } catch (TransportException $e) {
       // Network/connection issue.
   }
   

Integration Tips

• RoadRunner Integration:

  $rpc = RPC::fromEnvironment(); // Auto-detects RoadRunner's relay.
  

  • Configure in roadrunner.json:

    {
      "rpc": {
        "listen": "tcp://127.0.0.1:6001"
      }
    }
    

• Custom Codecs:

  $relay = Relay::create('tcp://127.0.0.1:6001', new ProtobufCodec());
  $rpc = new RPC($relay);
  

• Protobuf Support (v3.1.0+):

  $rpc->call('Proto.Method', $protobufMessage, ['codec' => 'protobuf']);
  

Gotchas and Tips

Pitfalls

1. Protocol Mismatch:

   • Ensure PHP and Go use the same protocol version (e.g., goridge vs. net/rpc).
   • Debug with RPC::FLAG_DEBUG (logs raw frames):

     $rpc->call('Service.Method', [], ['flags' => RPC::FLAG_DEBUG]);
     

2. Unix Socket Permissions:

   • On Linux, set socket permissions:

     chmod 777 /tmp/rpc.sock
     

   • Windows: Requires OS Build 17056+ for AF_UNIX support.

3. Binary Data Quirks:

   • Large []byte payloads may trigger BYTE10_STOP (v4.0.0+). Split chunks if needed:

     $rpc->call('Service.Process', array_chunk($data, 1024 * 1024));
     

4. Deprecated Methods:

   • Avoid RPC::fromGlobals() (deprecated in v3.2.1). Use Relay::create() instead.

Debugging

• Enable Verbose Logging:

  $relay = Relay::create('tcp://127.0.0.1:6001', null, [
      'logger' => new StreamHandler('php://stderr', Logger::DEBUG)
  ]);
  

• Check Sequence IDs:
  • Multi-RPC instances (v4.2.0+) require unique sequence IDs per relay.

Extension Points

1. Custom Relays:

   class CustomRelay implements RelayInterface {
       public function send(string $data): void { /* ... */ }
       public function recv(): string { /* ... */ }
   }
   

2. Protocol Extensions:
   • Extend Frame class to add custom flags (e.g., FLAG_CUSTOM).
3. Performance Tuning:
   • For high throughput, use MsgPack instead of JSON:

     $relay = Relay::create('tcp://127.0.0.1:6001', new MsgpackCodec());
     

Config Quirks

• RoadRunner Compatibility:
  • Ensure roadrunner.json matches the Go service’s expected relay (e.g., unix:// vs. tcp://).
• Windows-Specific:
  • Use pipes://stdin:stdout for local testing (avoids socket permission issues).

Pro Tips

• Batch Calls:

  $rpc->call('Batch.Process', [$data1, $data2], ['batch' => true]);
  

• Health Checks:

  $rpc->call('Service.Health', [], ['flags' => RPC::FLAG_PING]);
  

• PHP 8.1+ Features:
  • Use named arguments for clarity:

    $rpc->call('User.Create', ['name' => 'Alice', 'email' => '[email protected]']);
    

---