Relay Core Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require dbp/relay-core-bundle
   

   Register it in config/bundles.php:

   return [
       // ...
       DigitalBlueprint\RelayCoreBundle\RelayCoreBundle::class => ['all' => true],
   ];
   

2. First Use Case: API Gateway Initialization The bundle provides a RelayCore service to bootstrap the API gateway. Inject it into your controller or command:

   use DigitalBlueprint\RelayCoreBundle\Service\RelayCore;
   
   class MyController extends AbstractController
   {
       public function __construct(private RelayCore $relayCore) {}
   
       public function index()
       {
           $this->relayCore->initialize(); // Bootstraps the gateway
           // Proceed with API logic
       }
   }
   

3. Configuration Publish the default config:

   php artisan config:publish dbp/relay-core-bundle
   

   Key settings are in config/packages/dbp_relay_core.yaml (e.g., api_prefix, middleware).

Implementation Patterns

Core Workflows

1. Request Routing Use the RelayCore service to dynamically route requests to downstream services:

   $response = $this->relayCore->routeRequest($request, 'service_name');
   return new JsonResponse($response);
   

2. Middleware Integration Attach custom middleware via the relay.middleware config:

   relay:
       middleware:
           - App\Middleware\AuthMiddleware
           - App\Middleware\LoggingMiddleware
   

3. Service Discovery Register downstream services in config/packages/dbp_relay_core.yaml:

   services:
       user_service:
           url: 'http://users-api:8000'
           timeout: 30
   

Common Patterns

• Proxying Requests Forward requests to external APIs with headers/transformations:

  $this->relayCore->forward(
      $request,
      'user_service',
      ['X-API-KEY' => 'your_key']
  );
  

• Response Handling Normalize responses from downstream services:

  $normalized = $this->relayCore->normalizeResponse($rawResponse);
  

• Event Listeners Subscribe to RelayCoreEvents (e.g., REQUEST_ROUTED, RESPONSE_NORMALIZED):

  use DigitalBlueprint\RelayCoreBundle\Event\RelayCoreEvents;
  
  $dispatcher->addListener(RelayCoreEvents::REQUEST_ROUTED, function ($event) {
      // Log routed requests
  });
  

Gotchas and Tips

Pitfalls

1. Configuration Overrides

   • Avoid overriding relay.core config keys directly; use the config/packages/ structure.
   • Fix: Publish and extend the config:

     php artisan config:publish dbp/relay-core-bundle --tag=config
     

2. Circular Dependencies

   • The bundle assumes linear request flow. Circular routes (e.g., A -> B -> A) may cause infinite loops.
   • Fix: Add cycle detection middleware or use relayCore->isRequestProcessed($request).

3. Middleware Order

   • Middleware defined in relay.middleware runs after Laravel’s global middleware.
   • Fix: Use Kernel::prependMiddleware() for early execution.

Debugging

• Enable Verbose Logging Set relay.debug: true in config to log raw requests/responses to var/log/relay.log.

• Check Service Health Use the relay:health command to validate downstream services:

  php artisan relay:health user_service
  

Extension Points

1. Custom Request Transformers Extend DigitalBlueprint\RelayCoreBundle\Transformer\RequestTransformerInterface:

   class MyTransformer implements RequestTransformerInterface
   {
       public function transform(Request $request, string $service): Request
       {
           $request->headers->set('X-Custom-Header', 'value');
           return $request;
       }
   }
   

   Register in services.yaml:

   services:
       DigitalBlueprint\RelayCoreBundle\Transformer\RequestTransformerInterface:
           class: App\Transformer\MyTransformer
   

2. Response Decorators Wrap responses with metadata:

   $decorated = $this->relayCore->decorateResponse($response, [
       'cache_ttl' => 3600,
       'source' => 'user_service'
   ]);
   

3. Event-Driven Extensions Listen for RelayCoreEvents::SERVICE_UNAVAILABLE to implement fallbacks:

   $dispatcher->addListener(RelayCoreEvents::SERVICE_UNAVAILABLE, function ($event) {
       $event->setFallbackResponse(new Response('Service unavailable, using cache.'));
   });
   

Pro Tips

• Rate Limiting Use relay.rate_limits to enforce per-service quotas:

  rate_limits:
      user_service:
          limit: 100
          period: 60
  

• Caching Responses Enable relay.cache.enabled and configure relay.cache.driver (e.g., redis):

  cache:
      enabled: true
      driver: redis
      ttl: 300
  

• Testing Mock RelayCore in tests:

  $mockRelay = $this->createMock(RelayCore::class);
  $mockRelay->method('routeRequest')->willReturn(new Response('Mocked'));
  $this->container->set(RelayCore::class, $mockRelay);