Http Kernel Laravel Package

Getting Started

First Steps

1. Installation Add the package to your Laravel project via Composer:

   composer require drift/http-kernel
   

   Register the service provider in config/app.php under providers:

   Drift\HttpKernel\KernelServiceProvider::class,
   

2. Basic Setup Replace Laravel’s default Kernel class with Drift\HttpKernel by extending Drift\HttpKernel\Kernel in app/Http/Kernel.php:

   use Drift\HttpKernel\Kernel as BaseKernel;
   
   class Kernel extends BaseKernel
   {
       // Override middleware groups, routes, etc.
   }
   

3. First Async Use Case Wrap a synchronous middleware in an async promise for non-blocking execution:

   use Drift\HttpKernel\Middleware\AsyncMiddleware;
   use React\Promise\PromiseInterface;
   
   class AsyncExampleMiddleware extends AsyncMiddleware
   {
       public function handle(Request $request, Closure $next): PromiseInterface
       {
           return parent::handle($request, $next)
               ->then(function ($response) {
                   // Async post-processing
                   return $response;
               });
       }
   }
   

4. Key Files to Explore

   • config/drift.php: Kernel configuration (async settings, middleware groups).
   • app/Http/Kernel.php: Customize middleware and route handling.
   • vendor/drift/http-kernel/src/: Core classes (e.g., Kernel, AsyncMiddleware).

Implementation Patterns

Core Workflows

1. Async Middleware Pipeline Leverage AsyncMiddleware to chain async operations without blocking the event loop:

   // In Kernel.php
   protected function middleware(): array
   {
       return [
           \App\Http\Middleware\AsyncExampleMiddleware::class,
           // Other middleware...
       ];
   }
   

2. Promise-Based Request Handling Convert synchronous routes to async by wrapping them in Promise:

   Route::get('/async', function () {
       return \React\Promise\resolve('Async response');
   });
   

3. Event Loop Integration Use ReactPHP’s event loop for I/O-bound tasks (e.g., database queries, HTTP calls):

   use React\EventLoop\Factory;
   use React\Promise\Timer\Timeout;
   
   $loop = Factory::create();
   $loop->run();
   

4. Middleware Groups Define async-specific middleware groups in Kernel.php:

   protected $middlewareGroups = [
       'async' => [
           \Drift\HttpKernel\Middleware\AsyncMiddleware::class,
           // Async-only middleware...
       ],
   ];
   

Integration Tips

• Laravel Ecosystem: Combine with spatie/async or spatie/laravel-async for hybrid sync/async workflows.
• Database: Use react/promise-database for async DB queries with Eloquent.
• Queue Workers: Offload long-running tasks to async middleware instead of queues:

  Route::get('/process', function () {
      return \React\Promise\resolve()
          ->then(function () {
              // Heavy computation
          });
  });
  

Gotchas and Tips

Common Pitfalls

1. Blocking the Event Loop Avoid synchronous I/O (e.g., file_get_contents, sleep) in async middleware:

   // ❌ Blocks the loop
   $content = file_get_contents('http://example.com');
   
   // ✅ Async alternative
   use React\HttpClient\Client;
   $client = new Client();
   $promise = $client->get('http://example.com')->then(...);
   

2. Middleware Order Matters Async middleware must be placed before synchronous middleware to avoid deadlocks:

   // Correct order
   protected $middleware = [
       \App\Http\Middleware\AsyncAuth::class, // Async first
       \App\Http\Middleware\VerifyCsrfToken::class, // Sync second
   ];
   

3. Promise Rejection Handling Always handle rejected promises to prevent uncaught exceptions:

   $promise->then(function ($response) {
       // Success
   })->otherwise(function (\Throwable $e) {
       // Log or rethrow
       \Log::error($e);
       throw $e;
   });
   

4. Configuration Quirks

   • Ensure config/drift.php has async set to true:

     'async' => env('APP_ASYNC', false),
     

   • Disable Laravel’s default AppServiceProvider booting if using async bootstrapping.

Debugging Tips

• Log Promises: Use React\Promise\Timer\Timeout to log promise states:

  $promise->then(function () {
      \Log::debug('Promise resolved');
  })->otherwise(function () {
      \Log::debug('Promise rejected');
  });
  

• Event Loop Inspection: Attach a loop tracer:

  $loop->addPeriodicTimer(1, function () {
      \Log::debug('Loop active tasks:', $loop->getPendingTimers());
  });
  

• Test Async Code: Use React\Promise\Deferred for manual promise testing:

  $deferred = new \React\Promise\Deferred();
  $promise = $deferred->promise();
  // Simulate async resolution
  $deferred->resolve('test');
  

Extension Points

1. Custom Async Middleware Extend Drift\HttpKernel\Middleware\AsyncMiddleware to add async logic:

   class RateLimitMiddleware extends AsyncMiddleware
   {
       public function handle(Request $request, Closure $next): PromiseInterface
       {
           return \React\Promise\resolve()
               ->then(function () use ($request) {
                   // Async rate limiting logic
               })->then($next);
       }
   }
   

2. Override Kernel Methods Customize Drift\HttpKernel\Kernel methods like terminate() for async cleanup:

   public function terminate($request, $response)
   {
       parent::terminate($request, $response);
       // Async post-termination tasks
   }
   

3. ReactPHP Integration Use React\Promise\Timer\Timeout for async timeouts:

   use React\Promise\Timer\Timeout;
   
   $timeout = new Timeout($loop, 5.0); // 5-second timeout
   $promise = $timeout->promise();
   

4. Hybrid Sync/Async Routes Mix sync and async routes by conditionally wrapping handlers:

   Route::get('/hybrid', function () {
       if ($shouldBeAsync) {
           return \React\Promise\resolve('Async response');
       }
       return response()->json(['sync' => true]);
   });