Add API Gateway request timestamp to server variables

This PR adds support for extracting the original request timestamp from the API Gateway event (`requestContext.requestTimeEpoch` or `requestContext.timeEpoch`) and exposes it in the `$_SERVER` array as `AWS_API_GATEWAY_REQUEST_TIME`.

This enables more accurate request duration tracking and allows downstream code to calculate cold start latency by comparing the API Gateway arrival time to actual execution time.

The timestamp is derived directly from the incoming event and kept within the request context rather than being set as a global environment variable.
This keeps the data scoped to the request lifecycle and avoids side effects across concurrent executions.

If preferred, I’m happy to revise this to expose it via an environment variable or another mechanism.

Author: mortenhauberg

src/Runtime/Request.php

@@ -79,6 +79,10 @@ public static function fromLambdaEvent(array $event, array $serverVariables = []
             $serverVariables['SCRIPT_FILENAME'] = $handler;
         }
 
+        if ($timestamp = self::extractRequestTimestamp($event)) {
+            $serverVariables['AWS_API_GATEWAY_REQUEST_TIME'] = $timestamp;
+        }
+
         [$headers, $serverVariables] = static::ensureContentTypeIsSet(
             $event, $headers, $serverVariables
         );
@@ -266,4 +270,22 @@ protected static function ensureSourceIpAddressIsSet(array $event, array $header
 
         return $headers;
     }
+
+    /**
+     * Extracts the time (millisecond epoch) when the request was received by the API Gateway.
+     *
+     * @param  array  $event
+     *
+     * @return int|null
+     */
+    protected static function extractRequestTimestamp(array $event)
+    {
+        if (! isset($event['requestContext'])) {
+            return null; // No requestContext, so no timestamp available
+        }
+
+        return $event['requestContext']['requestTimeEpoch'] // REST API (V1)
+            ?? $event['requestContext']['timeEpoch']        // HTTP API (V2)
+            ?? null; // ELB doesn't add a timestamp
+    }
 }

tests/Unit/FpmRequestTest.php

@@ -2,12 +2,20 @@
 
 namespace Laravel\Vapor\Tests\Unit;
 
+use Carbon\Carbon;
 use Laravel\Vapor\Runtime\Fpm\FpmRequest;
 use Mockery;
 use PHPUnit\Framework\TestCase;
 
 class FpmRequestTest extends TestCase
 {
+    public function setUp(): void
+    {
+        parent::setUp();
+
+        Carbon::setTestNow('2021-01-01 00:00:00');
+    }
+
     protected function tearDown(): void
     {
         Mockery::close();
@@ -182,4 +190,41 @@ public function test_request_content_length_is_numeric()
 
         $this->assertSame(0, $request->getContentLength());
     }
+
+    public function test_api_gateway_v1_request_time_is_set()
+    {
+        $epoch = Carbon::now()->getPreciseTimestamp(3);
+
+        $request = FpmRequest::fromLambdaEvent([
+            'httpMethod' => 'GET',
+            'requestContext' => [
+                'requestTimeEpoch' => $epoch,
+            ],
+        ]);
+
+        $this->assertSame($epoch, $request->serverVariables['AWS_API_GATEWAY_REQUEST_TIME']);
+    }
+
+    public function test_api_gateway_v2_request_time_is_set()
+    {
+        $epoch = Carbon::now()->getPreciseTimestamp(3);
+
+        $request = FpmRequest::fromLambdaEvent([
+            'httpMethod' => 'GET',
+            'requestContext' => [
+                'timeEpoch' => $epoch,
+            ],
+        ]);
+
+        $this->assertSame($epoch, $request->serverVariables['AWS_API_GATEWAY_REQUEST_TIME']);
+    }
+
+    public function test_elb_request_time_is_not_set()
+    {
+        $request = FpmRequest::fromLambdaEvent([
+            'httpMethod' => 'GET',
+        ]);
+
+        $this->assertArrayNotHasKey('AWS_API_GATEWAY_REQUEST_TIME', $request->serverVariables);
+    }
 }