Added a coroutine-aware RequestContextScope service that persists request metadata in the current coroutine while providing a synchronous fallback.

greenarmor · greenarmor · commit 9177a48da53a · 2025-09-30T08:42:06.000+08:00
Registered the scope in the application container, seeding it for each request, and updated the logging processor to pull request details from the coroutine-local scope.

Updated HTTP middleware to read and write request metadata through the new scope and refreshed tests to validate scope-based context resolution.
diff --git a/src/Core/Application.php b/src/Core/Application.php
@@ -4,6 +4,7 @@
 use Bamboo\Module\ModuleInterface;
 use Bamboo\Web\Kernel;
 use Bamboo\Web\RequestContext;
+use Bamboo\Web\RequestContextScope;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface as Request;
 
@@ -16,6 +17,7 @@ public function __construct(protected Config $config) {
     $this->singleton(Config::class, fn() => $config);
     $this->singleton('router', fn() => new Router());
     $this->singleton(Kernel::class, fn() => new Kernel($this->get(Config::class)));
+    $this->singleton(RequestContextScope::class, fn() => new RequestContextScope());
     $this->bootRoutes();
   }
   /**
@@ -42,8 +44,7 @@ public function handle(Request $request): ResponseInterface {
     $context->merge([
       'method' => $request->getMethod(),
     ]);
-    $this->instances[RequestContext::class] = $context;
-    $this->instances['request.context'] = $context;
+    $this->get(RequestContextScope::class)->set($context);
     $router = $this->get('router');
     $match = $router->match($request);
     $defaultSignature = sprintf('%s %s', $request->getMethod(), $request->getUri()->getPath());
diff --git a/src/Provider/AppProvider.php b/src/Provider/AppProvider.php
@@ -2,7 +2,7 @@
 namespace Bamboo\Provider;
 use Bamboo\Core\Application;
 use Bamboo\Web\ProblemDetailsHandler;
-use Bamboo\Web\RequestContext;
+use Bamboo\Web\RequestContextScope;
 use Bamboo\Web\View\Engine\TemplateEngineManager;
 use Monolog\Handler\StreamHandler;
 use Monolog\Level;
@@ -14,15 +14,20 @@ public function register(Application $app): void {
       $log = new \Monolog\Logger('bamboo');
       $log->pushHandler(new StreamHandler($app->config('app.log_file'), Level::Debug));
       $log->pushProcessor(function(LogRecord $record) use ($app) {
-        if (!$app->has(RequestContext::class)) {
+        if (!$app->has(RequestContextScope::class)) {
           return $record;
         }
-        $context = $app->get(RequestContext::class)->all();
+        $scope = $app->get(RequestContextScope::class);
+        $context = $scope->get();
         if (!$context) {
           return $record;
         }
+        $values = $context->all();
+        if ($values === []) {
+          return $record;
+        }
         $extra = $record->extra;
-        $extra['request'] = array_merge($extra['request'] ?? [], $context);
+        $extra['request'] = array_merge($extra['request'] ?? [], $values);
         return $record->with(extra: $extra);
       });
       return $log;
diff --git a/src/Web/Middleware/CircuitBreakerMiddleware.php b/src/Web/Middleware/CircuitBreakerMiddleware.php
@@ -6,7 +6,7 @@
 
 use Bamboo\Core\Config;
 use Bamboo\Observability\Metrics\CircuitBreakerMetrics;
-use Bamboo\Web\RequestContext;
+use Bamboo\Web\RequestContextScope;
 use Bamboo\Web\Resilience\CircuitBreakerRegistry;
 use Nyholm\Psr7\Response;
 use Psr\Http\Message\ResponseInterface;
@@ -19,7 +19,7 @@ final class CircuitBreakerMiddleware
 
     public function __construct(
         private Config $config,
-        private RequestContext $context,
+        private RequestContextScope $contextScope,
         private CircuitBreakerRegistry $registry,
         private CircuitBreakerMetrics $metrics,
         ?callable $clock = null,
@@ -29,7 +29,8 @@ public function __construct(
 
     public function handle(Request $request, \Closure $next): ResponseInterface
     {
-        $route = $this->context->get('route', sprintf('%s %s', $request->getMethod(), $request->getUri()->getPath()));
+        $context = $this->contextScope->getOrCreate();
+        $route = $context->get('route', sprintf('%s %s', $request->getMethod(), $request->getUri()->getPath()));
         $method = $request->getMethod();
         $settings = $this->resolveSettings($method, $route, $request);
 
diff --git a/src/Web/Middleware/HttpMetricsCollector.php b/src/Web/Middleware/HttpMetricsCollector.php
@@ -5,20 +5,21 @@
 namespace Bamboo\Web\Middleware;
 
 use Bamboo\Observability\Metrics\HttpMetrics;
-use Bamboo\Web\RequestContext;
+use Bamboo\Web\RequestContextScope;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface as Request;
 
 class HttpMetricsCollector
 {
-    public function __construct(private HttpMetrics $metrics, private RequestContext $context)
+    public function __construct(private HttpMetrics $metrics, private RequestContextScope $contextScope)
     {
     }
 
     public function handle(Request $request, \Closure $next): ResponseInterface
     {
+        $context = $this->contextScope->getOrCreate();
         $method = $request->getMethod();
-        $route = $this->context->get('route', sprintf('%s %s', $method, $request->getUri()->getPath()));
+        $route = $context->get('route', sprintf('%s %s', $method, $request->getUri()->getPath()));
 
         $this->metrics->incrementInFlight($method, $route);
         $timer = $this->metrics->startTimer($method, $route);
diff --git a/src/Web/Middleware/RequestId.php b/src/Web/Middleware/RequestId.php
@@ -1,15 +1,16 @@
 <?php
 namespace Bamboo\Web\Middleware;
 
-use Bamboo\Web\RequestContext;
+use Bamboo\Web\RequestContextScope;
 use Psr\Http\Message\ServerRequestInterface as Request;
 
 class RequestId {
-  public function __construct(private RequestContext $context) {}
+  public function __construct(private RequestContextScope $contextScope) {}
   public function handle(Request $request, \Closure $next) {
     $requestId = trim($request->getHeaderLine('X-Request-ID'));
     if ($requestId === '') { $requestId = $this->generateUuid(); }
-    $this->context->merge([
+    $context = $this->contextScope->getOrCreate();
+    $context->merge([
       'id' => $requestId,
       'method' => $request->getMethod(),
       'route' => sprintf('%s %s', $request->getMethod(), $request->getRequestTarget()),
diff --git a/src/Web/Middleware/TimeoutMiddleware.php b/src/Web/Middleware/TimeoutMiddleware.php
@@ -6,7 +6,7 @@
 
 use Bamboo\Core\Config;
 use Bamboo\Observability\Metrics\HttpMetrics;
-use Bamboo\Web\RequestContext;
+use Bamboo\Web\RequestContextScope;
 use Nyholm\Psr7\Response;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface as Request;
@@ -15,14 +15,15 @@ final class TimeoutMiddleware
 {
     public function __construct(
         private Config $config,
-        private RequestContext $context,
+        private RequestContextScope $contextScope,
         private HttpMetrics $metrics,
     ) {
     }
 
     public function handle(Request $request, \Closure $next): ResponseInterface
     {
-        $route = $this->context->get('route', sprintf('%s %s', $request->getMethod(), $request->getUri()->getPath()));
+        $context = $this->contextScope->getOrCreate();
+        $route = $context->get('route', sprintf('%s %s', $request->getMethod(), $request->getUri()->getPath()));
         $method = $request->getMethod();
         $threshold = $this->resolveThreshold($method, $route, $request);
 
@@ -36,13 +37,13 @@ public function handle(Request $request, \Closure $next): ResponseInterface
             $response = $next($request);
         } catch (\Throwable $exception) {
             $elapsed = microtime(true) - $start;
-            $this->context->set('timeout.elapsed', $elapsed);
+            $context->set('timeout.elapsed', $elapsed);
             throw $exception;
         }
 
         $elapsed = microtime(true) - $start;
-        $this->context->set('timeout.elapsed', $elapsed);
-        $this->context->set('timeout.threshold', $threshold);
+        $context->set('timeout.elapsed', $elapsed);
+        $context->set('timeout.threshold', $threshold);
 
         if ($elapsed > $threshold) {
             $this->metrics->incrementTimeout($method, $route);
diff --git a/src/Web/RequestContextScope.php b/src/Web/RequestContextScope.php
@@ -0,0 +1,108 @@
+<?php
+
+namespace Bamboo\Web;
+
+use ArrayAccess;
+
+class RequestContextScope
+{
+    private const CONTEXT_KEY = 'bamboo.request_context';
+
+    private ?RequestContext $fallbackContext = null;
+
+    public function set(RequestContext $context): void
+    {
+        $store = $this->fetchCoroutineContext();
+        if ($store !== null) {
+            $store[self::CONTEXT_KEY] = $context;
+            return;
+        }
+
+        $this->fallbackContext = $context;
+    }
+
+    public function get(): ?RequestContext
+    {
+        $store = $this->fetchCoroutineContext();
+        if ($store !== null) {
+            return $this->getFromStore($store);
+        }
+
+        return $this->fallbackContext;
+    }
+
+    public function getOrCreate(): RequestContext
+    {
+        $context = $this->get();
+        if ($context instanceof RequestContext) {
+            return $context;
+        }
+
+        $context = new RequestContext();
+        $this->set($context);
+
+        return $context;
+    }
+
+    public function has(): bool
+    {
+        $store = $this->fetchCoroutineContext();
+        if ($store !== null) {
+            return $this->getFromStore($store) instanceof RequestContext;
+        }
+
+        return $this->fallbackContext instanceof RequestContext;
+    }
+
+    public function clear(): void
+    {
+        $store = $this->fetchCoroutineContext();
+        if ($store !== null) {
+            if ($store instanceof ArrayAccess && $store->offsetExists(self::CONTEXT_KEY)) {
+                $store->offsetUnset(self::CONTEXT_KEY);
+            }
+            return;
+        }
+
+        $this->fallbackContext = null;
+    }
+
+    private function getFromStore(ArrayAccess $store): ?RequestContext
+    {
+        if (!$store->offsetExists(self::CONTEXT_KEY)) {
+            return null;
+        }
+
+        $value = $store->offsetGet(self::CONTEXT_KEY);
+        return $value instanceof RequestContext ? $value : null;
+    }
+
+    private function fetchCoroutineContext(): ?ArrayAccess
+    {
+        $class = $this->resolveCoroutineClass();
+        if ($class === null) {
+            return null;
+        }
+
+        try {
+            $context = $class::getContext();
+        } catch (\Throwable) {
+            return null;
+        }
+
+        return $context instanceof ArrayAccess ? $context : null;
+    }
+
+    private function resolveCoroutineClass(): ?string
+    {
+        if (class_exists('\\OpenSwoole\\Coroutine')) {
+            return '\\OpenSwoole\\Coroutine';
+        }
+
+        if (class_exists('\\Swoole\\Coroutine')) {
+            return '\\Swoole\\Coroutine';
+        }
+
+        return null;
+    }
+}
diff --git a/tests/Core/ApplicationPipelineTest.php b/tests/Core/ApplicationPipelineTest.php
@@ -9,7 +9,7 @@
 use Bamboo\Provider\MetricsProvider;
 use Bamboo\Provider\ResilienceProvider;
 use Bamboo\Web\Kernel;
-use Bamboo\Web\RequestContext;
+use Bamboo\Web\RequestContextScope;
 use Nyholm\Psr7\Response;
 use Nyholm\Psr7\ServerRequest;
 use PHPUnit\Framework\TestCase;
@@ -350,7 +350,9 @@ public function testKernelCachesSingleEntryForUnmatchedRoutes(): void {
     $responseOne = $app->handle(new ServerRequest('GET', '/missing-one'));
     $this->assertSame(404, $responseOne->getStatusCode());
 
-    $contextAfterFirst = $app->get(RequestContext::class);
+    $scope = $app->get(RequestContextScope::class);
+    $contextAfterFirst = $scope->get();
+    $this->assertInstanceOf(\Bamboo\Web\RequestContext::class, $contextAfterFirst);
     $this->assertSame('GET /missing-one', $contextAfterFirst->get('route'));
 
     $firstCache = $ref->getValue($kernel);
@@ -359,7 +361,8 @@ public function testKernelCachesSingleEntryForUnmatchedRoutes(): void {
     $responseTwo = $app->handle(new ServerRequest('GET', '/missing-two'));
     $this->assertSame(404, $responseTwo->getStatusCode());
 
-    $contextAfterSecond = $app->get(RequestContext::class);
+    $contextAfterSecond = $scope->get();
+    $this->assertInstanceOf(\Bamboo\Web\RequestContext::class, $contextAfterSecond);
     $this->assertSame('GET /missing-two', $contextAfterSecond->get('route'));
 
     $secondCache = $ref->getValue($kernel);
diff --git a/tests/Http/RequestIdMiddlewareTest.php b/tests/Http/RequestIdMiddlewareTest.php
@@ -7,7 +7,7 @@
 use Bamboo\Core\RouteDefinition;
 use Bamboo\Provider\AppProvider;
 use Bamboo\Provider\MetricsProvider;
-use Bamboo\Web\RequestContext;
+use Bamboo\Web\RequestContextScope;
 use Monolog\Handler\TestHandler;
 use Monolog\LogRecord;
 use Nyholm\Psr7\Response;
@@ -44,7 +44,9 @@ public function testPropagatesInboundRequestId(): void {
     $this->assertSame('abc-123', $response->getHeaderLine('X-Request-ID'));
     $this->assertSame('abc-123', $captured['request_id']);
     $this->assertSame('abc-123', $captured['correlation_id']);
-    $context = $app->get(RequestContext::class);
+    $scope = $app->get(RequestContextScope::class);
+    $context = $scope->get();
+    $this->assertInstanceOf(\Bamboo\Web\RequestContext::class, $context);
     $this->assertSame('abc-123', $context->get('id'));
     $this->assertSame('GET /context', $context->get('route'));
     $this->assertSame('fast', $response->getHeaderLine('X-Bamboo'));
diff --git a/tests/Roadmap/V0_4/CircuitBreakerMiddlewareTest.php b/tests/Roadmap/V0_4/CircuitBreakerMiddlewareTest.php
@@ -4,7 +4,7 @@
 
 use Bamboo\Observability\Metrics\CircuitBreakerMetrics;
 use Bamboo\Web\Middleware\CircuitBreakerMiddleware;
-use Bamboo\Web\RequestContext;
+use Bamboo\Web\RequestContextScope;
 use Bamboo\Web\Resilience\CircuitBreakerRegistry;
 use Nyholm\Psr7\Response;
 use Nyholm\Psr7\ServerRequest;
@@ -30,13 +30,13 @@ public function testCircuitBreakerOpensAfterFailureThreshold(): void {
 
     $registry = new CircuitBreakerRegistry();
     $metrics = new CircuitBreakerMetrics(new CollectorRegistry(new InMemory()), ['namespace' => 'test']);
-    $context = new RequestContext();
-    $context->merge(['route' => 'GET /unstable']);
+    $scope = new RequestContextScope();
+    $scope->getOrCreate()->merge(['route' => 'GET /unstable']);
 
     $now = 0.0;
     $clock = function() use (&$now): float { return $now; };
 
-    $middleware = new CircuitBreakerMiddleware($config, $context, $registry, $metrics, $clock);
+    $middleware = new CircuitBreakerMiddleware($config, $scope, $registry, $metrics, $clock);
     $request = new ServerRequest('GET', '/unstable');
 
     try {
@@ -86,13 +86,13 @@ public function testCircuitBreakerPublishesStateMetrics(): void {
     $collector = new CollectorRegistry(new InMemory());
     $metrics = new CircuitBreakerMetrics($collector, ['namespace' => 'test']);
     $registry = new CircuitBreakerRegistry();
-    $context = new RequestContext();
-    $context->merge(['route' => 'GET /metrics']);
+    $scope = new RequestContextScope();
+    $scope->getOrCreate()->merge(['route' => 'GET /metrics']);
 
     $now = 0.0;
     $clock = function() use (&$now): float { return $now; };
 
-    $middleware = new CircuitBreakerMiddleware($config, $context, $registry, $metrics, $clock);
+    $middleware = new CircuitBreakerMiddleware($config, $scope, $registry, $metrics, $clock);
     $request = new ServerRequest('GET', '/metrics');
 
     try {
diff --git a/tests/Roadmap/V0_4/TimeoutMiddlewareTest.php b/tests/Roadmap/V0_4/TimeoutMiddlewareTest.php

Original file line number	Diff line number	Diff line change
`@@ -5,20 +5,21 @@`
`5`	`5`	`namespace Bamboo\Web\Middleware;`
`6`	`6`
`7`	`7`	`use Bamboo\Observability\Metrics\HttpMetrics;`
`8`		`-use Bamboo\Web\RequestContext;`
	`8`	`+use Bamboo\Web\RequestContextScope;`
`9`	`9`	`use Psr\Http\Message\ResponseInterface;`
`10`	`10`	`use Psr\Http\Message\ServerRequestInterface as Request;`
`11`	`11`
`12`	`12`	`class HttpMetricsCollector`
`13`	`13`	`{`
`14`		`- public function __construct(private HttpMetrics $metrics, private RequestContext $context)`
	`14`	`+ public function __construct(private HttpMetrics $metrics, private RequestContextScope $contextScope)`
`15`	`15`	`{`
`16`	`16`	`}`
`17`	`17`
`18`	`18`	`public function handle(Request $request, \Closure $next): ResponseInterface`
`19`	`19`	`{`
	`20`	`+ $context = $this->contextScope->getOrCreate();`
`20`	`21`	`$method = $request->getMethod();`
`21`		`- $route = $this->context->get('route', sprintf('%s %s', $method, $request->getUri()->getPath()));`
	`22`	`+ $route = $context->get('route', sprintf('%s %s', $method, $request->getUri()->getPath()));`
`22`	`23`
`23`	`24`	`$this->metrics->incrementInFlight($method, $route);`
`24`	`25`	`$timer = $this->metrics->startTimer($method, $route);`