@ts-cloud/core 0.5.2 → 0.5.3

package/dist/bun-bootstrap

@@ -0,0 +1,5 @@
+#!/bin/sh
+# ts-cloud Bun custom-runtime entrypoint (provided.al2023).
+# Puts the bundled Bun binary on PATH and runs the shared Runtime API loop.
+export PATH="/opt/bin:$PATH"
+exec /opt/bin/bun /opt/runtime.mjs

package/dist/node-bootstrap

@@ -0,0 +1,5 @@
+#!/bin/sh
+# ts-cloud Node custom-runtime entrypoint (provided.al2023).
+# Puts the bundled Node binary on PATH and runs the shared Runtime API loop.
+export PATH="/opt/bin:$PATH"
+exec /opt/bin/node /opt/runtime.mjs

package/dist/runtime/adapter.ts

@@ -0,0 +1,287 @@
+/**
+ * Serverless runtime adapter (Node/Bun).
+ *
+ * This module is **bundled into the Lambda deployment artifact** and runs inside
+ * the AWS Lambda Node.js runtime, so it must rely only on globals available
+ * there: `Request`, `Response`, `Headers`, `URL`, `Buffer`, `atob`/`btoa`.
+ * It contains no AWS SDK calls and no Node-only filesystem access.
+ *
+ * It translates the three event sources of a Vapor-style serverless app into
+ * plain, framework-agnostic callbacks:
+ *   - HTTP  : API Gateway v2 (payload format 2.0) ⇄ WHATWG `Request`/`Response`
+ *   - Queue : SQS records → per-message job handler with partial-batch failures
+ *   - CLI   : `{ command, args }` → command handler (scheduler / migrations)
+ */
+
+// ── Event/response shapes (minimal subsets of the AWS types) ────────────────
+
+export interface ApiGatewayProxyEventV2 {
+  version: '2.0'
+  rawPath: string
+  rawQueryString?: string
+  cookies?: string[]
+  headers?: Record<string, string | undefined>
+  body?: string
+  isBase64Encoded?: boolean
+  requestContext: {
+    domainName?: string
+    http: {
+      method: string
+      path: string
+      protocol?: string
+      sourceIp?: string
+      userAgent?: string
+    }
+  }
+}
+
+export interface ApiGatewayProxyResultV2 {
+  statusCode: number
+  headers?: Record<string, string>
+  cookies?: string[]
+  body?: string
+  isBase64Encoded?: boolean
+}
+
+export interface SqsRecord {
+  messageId: string
+  receiptHandle?: string
+  body: string
+  attributes?: Record<string, string>
+  messageAttributes?: Record<string, unknown>
+  eventSourceARN?: string
+}
+
+export interface SqsEvent {
+  Records: SqsRecord[]
+}
+
+export interface SqsBatchResponse {
+  batchItemFailures: Array<{ itemIdentifier: string }>
+}
+
+export interface CliEvent {
+  command: string
+  args?: string[]
+}
+
+export interface CliResult {
+  statusCode: number
+  output: string
+}
+
+// ── Handler callback contracts ──────────────────────────────────────────────
+
+export type FetchHandler = (request: Request) => Response | Promise<Response>
+export type JobHandler = (payload: unknown, record: SqsRecord) => unknown | Promise<unknown>
+export type CommandHandler = (event: CliEvent) => CliResult | Promise<CliResult>
+
+/** Lambda handler invoked by API Gateway v2. */
+export type LambdaHttpHandler = (event: ApiGatewayProxyEventV2) => Promise<ApiGatewayProxyResultV2>
+/** Lambda handler invoked by an SQS event source mapping. */
+export type LambdaQueueHandler = (event: SqsEvent) => Promise<SqsBatchResponse>
+/** Lambda handler invoked by EventBridge / on-demand for CLI commands. */
+export type LambdaCliHandler = (event: CliEvent) => Promise<CliResult>
+
+export interface ServerlessApp {
+  fetch?: FetchHandler
+  queue?: JobHandler
+  cli?: CommandHandler
+}
+
+/**
+ * Normalize whatever the user's entry module exports into a {@link ServerlessApp}.
+ * Accepts a bare fetch function, an object with `fetch`/`queue`/`cli`, or a
+ * Bun.serve-style `{ default: { fetch } }`.
+ */
+export function resolveApp(mod: unknown): ServerlessApp {
+  const m = mod as Record<string, unknown>
+  const def = (m?.default ?? m) as Record<string, unknown>
+  if (typeof def === 'function') return { fetch: def as FetchHandler }
+  return {
+    fetch: (def?.fetch ?? m?.fetch) as FetchHandler | undefined,
+    queue: (def?.queue ?? m?.queue) as JobHandler | undefined,
+    cli: (def?.cli ?? m?.cli) as CommandHandler | undefined,
+  }
+}
+
+// ── Body / content helpers ──────────────────────────────────────────────────
+
+const TEXT_CONTENT = /^(?:text\/|application\/(?:json|xml|javascript|graphql|x-www-form-urlencoded|.*\+json|.*\+xml)|image\/svg)/i
+
+function isTextContentType(contentType: string | null): boolean {
+  // No declared type → treat as text (the common case for `new Response(str)`).
+  // Binary payloads in practice always carry an explicit content-type.
+  if (!contentType) return true
+  return TEXT_CONTENT.test(contentType)
+}
+
+// ── HTTP ────────────────────────────────────────────────────────────────────
+
+export interface HttpAdapterOptions {
+  /**
+   * Read maintenance state from the environment. When `MAINTENANCE_MODE` is
+   * truthy, requests get a 503 unless they carry the bypass secret in the
+   * `x-maintenance-bypass` header or a `tscloud_bypass` cookie.
+   */
+  maintenance?: {
+    enabled: boolean
+    bypassSecret?: string
+  }
+}
+
+function readMaintenance(opts?: HttpAdapterOptions): { enabled: boolean, bypassSecret?: string } {
+  if (opts?.maintenance) return opts.maintenance
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {}
+  return {
+    enabled: env.MAINTENANCE_MODE === '1' || env.MAINTENANCE_MODE === 'true',
+    bypassSecret: env.MAINTENANCE_BYPASS_SECRET,
+  }
+}
+
+/** Translate an API Gateway v2 event into a WHATWG `Request`. */
+export function eventToRequest(event: ApiGatewayProxyEventV2): Request {
+  const host = event.requestContext?.domainName ?? 'localhost'
+  const query = event.rawQueryString ? `?${event.rawQueryString}` : ''
+  const url = `https://${host}${event.rawPath || '/'}${query}`
+
+  const headers = new Headers()
+  for (const [key, value] of Object.entries(event.headers ?? {})) {
+    if (value !== undefined) headers.set(key, value)
+  }
+  if (event.cookies?.length) headers.set('cookie', event.cookies.join('; '))
+
+  const method = event.requestContext.http.method
+  let body: Uint8Array | undefined
+  if (event.body !== undefined && method !== 'GET' && method !== 'HEAD') {
+    body = event.isBase64Encoded
+      ? new Uint8Array(Buffer.from(event.body, 'base64'))
+      : new TextEncoder().encode(event.body)
+  }
+
+  return new Request(url, { method, headers, body })
+}
+
+/** Serialize a WHATWG `Response` into an API Gateway v2 result. */
+export async function responseToResult(response: Response): Promise<ApiGatewayProxyResultV2> {
+  const headers: Record<string, string> = {}
+  const cookies: string[] = []
+
+  // `getSetCookie` is available in the Lambda runtime's undici Headers.
+  const setCookies = typeof (response.headers as { getSetCookie?: () => string[] }).getSetCookie === 'function'
+    ? (response.headers as { getSetCookie: () => string[] }).getSetCookie()
+    : []
+  for (const c of setCookies) cookies.push(c)
+
+  response.headers.forEach((value, key) => {
+    if (key.toLowerCase() === 'set-cookie') return
+    headers[key] = value
+  })
+
+  const buffer = Buffer.from(await response.arrayBuffer())
+  const textual = isTextContentType(response.headers.get('content-type'))
+
+  return {
+    statusCode: response.status,
+    headers,
+    ...(cookies.length ? { cookies } : {}),
+    body: textual ? buffer.toString('utf-8') : buffer.toString('base64'),
+    isBase64Encoded: !textual,
+  }
+}
+
+/**
+ * Wrap a fetch-style handler into a Lambda HTTP handler for API Gateway v2.
+ * Honors maintenance mode (503 + bypass) before invoking the app.
+ */
+export function createHttpHandler(handler: FetchHandler | undefined, opts?: HttpAdapterOptions): LambdaHttpHandler {
+  return async (event: ApiGatewayProxyEventV2): Promise<ApiGatewayProxyResultV2> => {
+    // Warmer pings (from the scheduled keep-warm rule) just keep the container
+    // alive — short-circuit before treating the event as an HTTP request.
+    if ((event as unknown as { warmer?: boolean }).warmer) {
+      return { statusCode: 200, headers: { 'content-type': 'text/plain' }, body: 'warm', isBase64Encoded: false }
+    }
+
+    if (!handler) {
+      return { statusCode: 501, headers: { 'content-type': 'text/plain' }, body: 'No HTTP handler configured', isBase64Encoded: false }
+    }
+
+    const maintenance = readMaintenance(opts)
+    if (maintenance.enabled) {
+      const bypass = event.headers?.['x-maintenance-bypass']
+        ?? (event.cookies?.find(c => c.startsWith('tscloud_bypass='))?.split('=')[1])
+      if (!maintenance.bypassSecret || bypass !== maintenance.bypassSecret) {
+        return {
+          statusCode: 503,
+          headers: { 'content-type': 'text/plain', 'retry-after': '120' },
+          body: 'Service temporarily unavailable (maintenance mode)',
+          isBase64Encoded: false,
+        }
+      }
+    }
+
+    const request = eventToRequest(event)
+    const response = await handler(request)
+    return responseToResult(response)
+  }
+}
+
+// ── Queue ─────────────────────────────────────────────────────────────────--
+
+function parseRecordBody(body: string): unknown {
+  try {
+    return JSON.parse(body)
+  }
+  catch {
+    return body
+  }
+}
+
+/**
+ * Wrap a job handler into a Lambda SQS handler. Each record is processed
+ * individually; failures are reported via `batchItemFailures` so only failed
+ * messages are retried (requires `ReportBatchItemFailures` on the mapping).
+ */
+export function createQueueHandler(handler: JobHandler | undefined): LambdaQueueHandler {
+  return async (event: SqsEvent): Promise<SqsBatchResponse> => {
+    const batchItemFailures: Array<{ itemIdentifier: string }> = []
+    if (!handler) return { batchItemFailures }
+
+    for (const record of event.Records ?? []) {
+      try {
+        await handler(parseRecordBody(record.body), record)
+      }
+      catch {
+        batchItemFailures.push({ itemIdentifier: record.messageId })
+      }
+    }
+    return { batchItemFailures }
+  }
+}
+
+// ── CLI / scheduler ─────────────────────────────────────────────────────────
+
+/**
+ * Wrap a command handler into a Lambda CLI handler. Used by the EventBridge
+ * scheduler (`{ command: 'schedule:run' }`) and on-demand invocations
+ * (deploy hooks, migrations, `cloud command`).
+ */
+export function createCliHandler(handler: CommandHandler | undefined): LambdaCliHandler {
+  return async (event: CliEvent): Promise<CliResult> => {
+    if (!handler) return { statusCode: 501, output: 'No CLI handler configured' }
+    return handler(event)
+  }
+}
+
+/** Convenience: build all three Lambda handlers from a resolved app. */
+export function createHandlers(app: ServerlessApp, opts?: HttpAdapterOptions): {
+  http: LambdaHttpHandler
+  queue: LambdaQueueHandler
+  cli: LambdaCliHandler
+} {
+  return {
+    http: createHttpHandler(app.fetch, opts),
+    queue: createQueueHandler(app.queue),
+    cli: createCliHandler(app.cli),
+  }
+}

package/dist/runtime-assets/bootstrap

@@ -0,0 +1,39 @@
+#!/bin/sh
+# ts-cloud PHP custom runtime bootstrap for AWS Lambda (provided.al2023).
+#
+# Selects the runtime mode from TSCLOUD_LAMBDA_MODE:
+#   http  -> start php-fpm and run the FastCGI bridge loop (runtime.php)
+#   queue -> SQS worker loop (cli-runtime.php)
+#   cli   -> scheduler / on-demand artisan commands (cli-runtime.php)
+#
+# The PHP binary + extensions + these scripts are provided by the ts-cloud PHP
+# runtime layer mounted at /opt.
+set -e
+
+export PATH="/opt/bin:/opt/php/bin:/opt/php/sbin:${PATH}"
+export LD_LIBRARY_PATH="/opt/php/lib:${LD_LIBRARY_PATH}"
+# The relocated PHP's compiled-in ini path points at the build-time SCL location,
+# so point it at the layer's ini (sets extension_dir + loads every extension).
+export PHPRC="/opt/php/etc/php.ini"
+
+# Only /tmp is writable on Lambda; pre-create Laravel's runtime directories.
+mkdir -p \
+  /tmp/storage/framework/cache/data \
+  /tmp/storage/framework/sessions \
+  /tmp/storage/framework/views \
+  /tmp/storage/logs \
+  /tmp/bootstrap/cache
+
+MODE="${TSCLOUD_LAMBDA_MODE:-http}"
+
+if [ "$MODE" = "http" ]; then
+  if [ "${TSCLOUD_OCTANE:-0}" = "1" ]; then
+    # Persistent mode: boot Laravel once, serve in-process (no php-fpm).
+    exec php /opt/tscloud/octane-runtime.php
+  fi
+  # Launch php-fpm (listening on a unix socket in /tmp) then run the bridge loop.
+  php-fpm --nodaemonize --fpm-config /opt/tscloud/php-fpm.conf &
+  exec php /opt/tscloud/runtime.php
+else
+  exec php /opt/tscloud/cli-runtime.php
+fi

package/dist/runtime-assets/cli-runtime.php

@@ -0,0 +1,148 @@
+<?php
+/**
+ * ts-cloud PHP Lambda CLI runtime — handles the queue, scheduler, and cli modes.
+ *
+ * Implements the Lambda Runtime API loop and dispatches based on the event:
+ *   - SQS event ({Records:[...]})        -> one artisan queue job per record
+ *   - EventBridge / {command:'schedule:run'} -> `php artisan schedule:run`
+ *   - {command:'<artisan command>'}      -> arbitrary artisan command
+ *
+ * Queue records are passed to a Laravel bridge command (default
+ * `tscloud:sqs-handle`, override via TSCLOUD_QUEUE_COMMAND) provided by the
+ * `tscloud/serverless` composer package. This avoids the double-delivery hazard
+ * of running stock `queue:work` (which would re-poll SQS alongside Lambda's own
+ * poller).
+ */
+
+$runtimeApi = getenv('AWS_LAMBDA_RUNTIME_API');
+$taskRoot = getenv('LAMBDA_TASK_ROOT') ?: '/var/task';
+$artisan = $taskRoot . '/artisan';
+$queueCommand = getenv('TSCLOUD_QUEUE_COMMAND') ?: 'tscloud:sqs-handle';
+
+while (true) {
+    $ctx = nextInvocation($runtimeApi);
+    if ($ctx === null) {
+        continue;
+    }
+    [$requestId, $event] = $ctx;
+
+    try {
+        $result = dispatch($event, $artisan, $queueCommand);
+        postResponse($runtimeApi, $requestId, $result);
+    } catch (\Throwable $e) {
+        postError($runtimeApi, $requestId, $e);
+    }
+}
+
+function dispatch(array $event, string $artisan, string $queueCommand): array
+{
+    // SQS queue event.
+    if (isset($event['Records']) && is_array($event['Records'])) {
+        $failures = [];
+        foreach ($event['Records'] as $record) {
+            $body = $record['body'] ?? '';
+            $messageId = $record['messageId'] ?? '';
+            $exit = runArtisan($artisan, [$queueCommand], ['TSCLOUD_SQS_RECORD' => $body], $out);
+            if ($exit !== 0) {
+                $failures[] = ['itemIdentifier' => $messageId];
+            }
+        }
+        return ['batchItemFailures' => $failures];
+    }
+
+    // Scheduler / arbitrary command.
+    $command = $event['command'] ?? 'schedule:run';
+
+    // Sub-minute scheduling: EventBridge fires once a minute, so loop
+    // `schedule:run` within the invocation (~every 10s for ~55s) to honor tasks
+    // scheduled more frequently than once a minute.
+    if ($command === 'schedule:run' && getenv('TSCLOUD_SCHEDULER') === 'sub-minute') {
+        $deadline = time() + 55;
+        $last = '';
+        do {
+            runArtisan($artisan, ['schedule:run'], [], $last);
+            if (time() < $deadline) {
+                sleep(10);
+            }
+        } while (time() < $deadline);
+        return ['statusCode' => 0, 'output' => $last];
+    }
+
+    $args = preg_split('/\s+/', trim($command));
+    $exit = runArtisan($artisan, $args, [], $out);
+    return ['statusCode' => $exit, 'output' => $out];
+}
+
+/**
+ * @param string[] $args
+ * @param array<string,string> $env
+ */
+function runArtisan(string $artisan, array $args, array $env, ?string &$out): int
+{
+    $cmd = array_merge(['php', $artisan], $args);
+    $descriptors = [1 => ['pipe', 'w'], 2 => ['pipe', 'w']];
+    $fullEnv = array_merge(getenv(), $env);
+    $proc = proc_open($cmd, $descriptors, $pipes, getenv('LAMBDA_TASK_ROOT') ?: '/var/task', $fullEnv);
+    if (!is_resource($proc)) {
+        $out = 'failed to start artisan';
+        return 1;
+    }
+    $stdout = stream_get_contents($pipes[1]);
+    $stderr = stream_get_contents($pipes[2]);
+    fclose($pipes[1]);
+    fclose($pipes[2]);
+    $exit = proc_close($proc);
+    $out = trim($stdout . "\n" . $stderr);
+    // Surface output to CloudWatch.
+    fwrite(STDERR, $out . "\n");
+    return $exit;
+}
+
+/**
+ * @return array{0:string,1:array}|null
+ */
+function nextInvocation(string $api): ?array
+{
+    $ch = curl_init("http://{$api}/2018-06-01/runtime/invocation/next");
+    $headers = [];
+    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+    curl_setopt($ch, CURLOPT_HEADERFUNCTION, function ($c, $h) use (&$headers) {
+        $parts = explode(':', $h, 2);
+        if (count($parts) === 2) {
+            $headers[strtolower(trim($parts[0]))] = trim($parts[1]);
+        }
+        return strlen($h);
+    });
+    $body = curl_exec($ch);
+    curl_close($ch);
+    if ($body === false) {
+        return null;
+    }
+    $requestId = $headers['lambda-runtime-aws-request-id'] ?? '';
+    $event = json_decode($body, true) ?: [];
+    return [$requestId, $event];
+}
+
+function postResponse(string $api, string $requestId, array $response): void
+{
+    $ch = curl_init("http://{$api}/2018-06-01/runtime/invocation/{$requestId}/response");
+    curl_setopt($ch, CURLOPT_POST, true);
+    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($response));
+    curl_exec($ch);
+    curl_close($ch);
+}
+
+function postError(string $api, string $requestId, \Throwable $e): void
+{
+    $ch = curl_init("http://{$api}/2018-06-01/runtime/invocation/{$requestId}/error");
+    curl_setopt($ch, CURLOPT_POST, true);
+    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
+    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
+        'errorType' => get_class($e),
+        'errorMessage' => $e->getMessage(),
+    ]));
+    curl_exec($ch);
+    curl_close($ch);
+}

package/dist/runtime-assets/fastcgi-client.php

@@ -0,0 +1,118 @@
+<?php
+/**
+ * Minimal FastCGI client for the ts-cloud PHP Lambda runtime.
+ *
+ * Speaks just enough of the FastCGI protocol to send one request (params + stdin)
+ * to php-fpm over a unix socket and read the full stdout/stderr response. This is
+ * the bridge between the Lambda Runtime API loop and Laravel's public/index.php
+ * served by php-fpm.
+ */
+
+namespace TsCloud;
+
+final class FastCgiClient
+{
+    const FCGI_VERSION = 1;
+    const BEGIN_REQUEST = 1;
+    const END_REQUEST = 3;
+    const PARAMS = 4;
+    const STDIN = 5;
+    const STDOUT = 6;
+    const STDERR = 7;
+    const RESPONDER = 1;
+
+    private string $socketPath;
+
+    public function __construct(string $socketPath)
+    {
+        $this->socketPath = $socketPath;
+    }
+
+    /**
+     * @param array<string,string> $params FastCGI params (CGI environment)
+     * @return array{stdout:string,stderr:string}
+     */
+    public function request(array $params, string $stdin = ''): array
+    {
+        $conn = @stream_socket_client('unix://' . $this->socketPath, $errno, $errstr, 30);
+        if ($conn === false) {
+            throw new \RuntimeException("FastCGI connect failed: {$errstr} ({$errno})");
+        }
+
+        $requestId = 1;
+
+        // BEGIN_REQUEST (role=RESPONDER, flags=0 -> close connection when done).
+        $beginBody = pack('nCxxxxx', self::RESPONDER, 0);
+        fwrite($conn, $this->record(self::BEGIN_REQUEST, $requestId, $beginBody));
+
+        // PARAMS (name-value pairs), then an empty PARAMS record to terminate.
+        $paramsBody = '';
+        foreach ($params as $name => $value) {
+            $paramsBody .= $this->nameValuePair((string) $name, (string) $value);
+        }
+        if ($paramsBody !== '') {
+            fwrite($conn, $this->record(self::PARAMS, $requestId, $paramsBody));
+        }
+        fwrite($conn, $this->record(self::PARAMS, $requestId, ''));
+
+        // STDIN (body) then an empty STDIN record to terminate.
+        if ($stdin !== '') {
+            foreach (str_split($stdin, 65535) as $chunk) {
+                fwrite($conn, $this->record(self::STDIN, $requestId, $chunk));
+            }
+        }
+        fwrite($conn, $this->record(self::STDIN, $requestId, ''));
+
+        // Read the response records.
+        $stdout = '';
+        $stderr = '';
+        while (!feof($conn)) {
+            $header = fread($conn, 8);
+            if ($header === false || strlen($header) < 8) {
+                break;
+            }
+            $h = unpack('Cversion/Ctype/nrequestId/ncontentLength/CpaddingLength/Creserved', $header);
+            $content = '';
+            $remaining = $h['contentLength'];
+            while ($remaining > 0) {
+                $buf = fread($conn, $remaining);
+                if ($buf === false || $buf === '') {
+                    break;
+                }
+                $content .= $buf;
+                $remaining -= strlen($buf);
+            }
+            if ($h['paddingLength'] > 0) {
+                fread($conn, $h['paddingLength']);
+            }
+
+            if ($h['type'] === self::STDOUT) {
+                $stdout .= $content;
+            } elseif ($h['type'] === self::STDERR) {
+                $stderr .= $content;
+            } elseif ($h['type'] === self::END_REQUEST) {
+                break;
+            }
+        }
+
+        fclose($conn);
+
+        return ['stdout' => $stdout, 'stderr' => $stderr];
+    }
+
+    private function record(int $type, int $requestId, string $content): string
+    {
+        $length = strlen($content);
+        $header = pack('CCnnCx', self::FCGI_VERSION, $type, $requestId, $length, 0);
+        return $header . $content;
+    }
+
+    private function nameValuePair(string $name, string $value): string
+    {
+        $nlen = strlen($name);
+        $vlen = strlen($value);
+        $out = $nlen < 128 ? chr($nlen) : pack('N', $nlen | 0x80000000);
+        $out .= $vlen < 128 ? chr($vlen) : pack('N', $vlen | 0x80000000);
+        return $out . $name . $value;
+    }
+}

package/dist/runtime-assets/octane-runtime.php

@@ -0,0 +1,184 @@
+<?php
+/**
+ * ts-cloud PHP Lambda HTTP runtime — Octane / persistent mode.
+ *
+ * Boots the Laravel application ONCE per cold start and serves each invocation
+ * in-process through the HTTP kernel (no php-fpm, no FastCGI hop), then resets
+ * request-scoped state between invocations. Lower latency than the FPM bridge at
+ * the cost of requiring an Octane-safe app. Selected when TSCLOUD_OCTANE=1.
+ */
+
+$runtimeApi = getenv('AWS_LAMBDA_RUNTIME_API');
+$taskRoot = getenv('LAMBDA_TASK_ROOT') ?: '/var/task';
+
+require $taskRoot . '/vendor/autoload.php';
+
+// Boot the application + HTTP kernel once.
+$app = require $taskRoot . '/bootstrap/app.php';
+$kernel = $app->make(\Illuminate\Contracts\Http\Kernel::class);
+
+$maintenance = getenv('MAINTENANCE_MODE') === '1';
+$bypassSecret = getenv('MAINTENANCE_BYPASS_SECRET') ?: '';
+
+while (true) {
+    $ctx = nextInvocation($runtimeApi);
+    if ($ctx === null) {
+        continue;
+    }
+    [$requestId, $event] = $ctx;
+
+    try {
+        $response = handle($event, $kernel, $maintenance, $bypassSecret);
+        postResponse($runtimeApi, $requestId, $response);
+    } catch (\Throwable $e) {
+        postError($runtimeApi, $requestId, $e);
+    }
+}
+
+function handle(array $event, $kernel, bool $maintenance, string $bypassSecret): array
+{
+    if (($event['warmer'] ?? false) === true) {
+        return ['statusCode' => 200, 'headers' => ['content-type' => 'text/plain'], 'body' => 'warm', 'isBase64Encoded' => false];
+    }
+
+    $http = $event['requestContext']['http'] ?? [];
+    $headers = $event['headers'] ?? [];
+
+    if ($maintenance) {
+        $bypass = $headers['x-maintenance-bypass'] ?? '';
+        if ($bypassSecret === '' || $bypass !== $bypassSecret) {
+            return ['statusCode' => 503, 'headers' => ['content-type' => 'text/plain', 'retry-after' => '120'], 'body' => 'Service temporarily unavailable (maintenance mode)', 'isBase64Encoded' => false];
+        }
+    }
+
+    $body = $event['body'] ?? '';
+    if (($event['isBase64Encoded'] ?? false) === true) {
+        $body = base64_decode($body);
+    }
+
+    $method = $http['method'] ?? 'GET';
+    $rawPath = $event['rawPath'] ?? '/';
+    $rawQuery = $event['rawQueryString'] ?? '';
+
+    // Build server vars + an Illuminate request.
+    $server = [
+        'REQUEST_METHOD' => $method,
+        'REQUEST_URI' => $rawQuery !== '' ? $rawPath . '?' . $rawQuery : $rawPath,
+        'QUERY_STRING' => $rawQuery,
+        'SERVER_NAME' => $event['requestContext']['domainName'] ?? 'localhost',
+        'SERVER_PORT' => '443',
+        'HTTPS' => 'on',
+        'REMOTE_ADDR' => $http['sourceIp'] ?? '127.0.0.1',
+    ];
+    foreach ($headers as $name => $value) {
+        $server['HTTP_' . strtoupper(str_replace('-', '_', $name))] = $value;
+        if (strtolower($name) === 'content-type') {
+            $server['CONTENT_TYPE'] = $value;
+        }
+    }
+
+    parse_str($rawQuery, $query);
+    $cookies = [];
+    foreach ($event['cookies'] ?? [] as $cookie) {
+        $parts = explode('=', $cookie, 2);
+        if (count($parts) === 2) {
+            $cookies[$parts[0]] = urldecode($parts[1]);
+        }
+    }
+
+    $request = new \Illuminate\Http\Request(
+        $query,
+        [],
+        [],
+        $cookies,
+        [],
+        $server,
+        $body
+    );
+    $request->setMethod($method);
+
+    $response = $kernel->handle($request);
+    $result = marshalResponse($response);
+    $kernel->terminate($request, $response);
+
+    return $result;
+}
+
+function marshalResponse($response): array
+{
+    $content = $response->getContent();
+    $headers = [];
+    $cookies = [];
+    foreach ($response->headers->allPreserveCase() as $name => $values) {
+        if (strtolower($name) === 'set-cookie') {
+            foreach ($values as $v) {
+                $cookies[] = $v;
+            }
+        } else {
+            $headers[$name] = implode(', ', $values);
+        }
+    }
+
+    $contentType = $headers['Content-Type'] ?? ($headers['content-type'] ?? 'text/html');
+    $isText = (bool) preg_match('#^(text/|application/(json|xml|javascript|x-www-form-urlencoded)|image/svg)#i', $contentType);
+
+    $out = [
+        'statusCode' => $response->getStatusCode(),
+        'headers' => $headers,
+        'isBase64Encoded' => !$isText,
+        'body' => $isText ? $content : base64_encode($content),
+    ];
+    if (!empty($cookies)) {
+        $out['cookies'] = $cookies;
+    }
+    return $out;
+}
+
+/**
+ * @return array{0:string,1:array}|null
+ */
+function nextInvocation(string $api): ?array
+{
+    $ch = curl_init("http://{$api}/2018-06-01/runtime/invocation/next");
+    $headers = [];
+    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+    curl_setopt($ch, CURLOPT_HEADERFUNCTION, function ($c, $h) use (&$headers) {
+        $parts = explode(':', $h, 2);
+        if (count($parts) === 2) {
+            $headers[strtolower(trim($parts[0]))] = trim($parts[1]);
+        }
+        return strlen($h);
+    });
+    $body = curl_exec($ch);
+    curl_close($ch);
+    if ($body === false) {
+        return null;
+    }
+    $requestId = $headers['lambda-runtime-aws-request-id'] ?? '';
+    $event = json_decode($body, true) ?: [];
+    return [$requestId, $event];
+}
+
+function postResponse(string $api, string $requestId, array $response): void
+{
+    $ch = curl_init("http://{$api}/2018-06-01/runtime/invocation/{$requestId}/response");
+    curl_setopt($ch, CURLOPT_POST, true);
+    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($response));
+    curl_exec($ch);
+    curl_close($ch);
+}
+
+function postError(string $api, string $requestId, \Throwable $e): void
+{
+    $ch = curl_init("http://{$api}/2018-06-01/runtime/invocation/{$requestId}/error");
+    curl_setopt($ch, CURLOPT_POST, true);
+    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
+    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
+        'errorType' => get_class($e),
+        'errorMessage' => $e->getMessage(),
+    ]));
+    curl_exec($ch);
+    curl_close($ch);
+}

package/dist/runtime-assets/runtime.php

@@ -0,0 +1,207 @@
+<?php
+/**
+ * ts-cloud PHP Lambda HTTP runtime (FPM mode).
+ *
+ * Implements the AWS Lambda Runtime API loop for the HTTP function: long-poll for
+ * the next invocation (an API Gateway v2 payload-format-2.0 event), bridge it to
+ * php-fpm over FastCGI (running Laravel's public/index.php), and post the response
+ * back in API Gateway v2 response shape.
+ */
+
+require __DIR__ . '/fastcgi-client.php';
+
+use TsCloud\FastCgiClient;
+
+$runtimeApi = getenv('AWS_LAMBDA_RUNTIME_API');
+$taskRoot = getenv('LAMBDA_TASK_ROOT') ?: '/var/task';
+$docRoot = $taskRoot . '/public';
+$socketPath = '/tmp/.tscloud-fpm.sock';
+
+$fpm = new FastCgiClient($socketPath);
+
+// Wait for php-fpm to create its socket (bounded).
+for ($i = 0; $i < 50 && !file_exists($socketPath); $i++) {
+    usleep(100000); // 100ms
+}
+
+$maintenance = getenv('MAINTENANCE_MODE') === '1';
+$bypassSecret = getenv('MAINTENANCE_BYPASS_SECRET') ?: '';
+
+while (true) {
+    // 1. Get the next invocation.
+    $ctx = nextInvocation($runtimeApi);
+    if ($ctx === null) {
+        continue;
+    }
+    [$requestId, $event] = $ctx;
+
+    try {
+        $response = handle($event, $fpm, $docRoot, $maintenance, $bypassSecret);
+        postResponse($runtimeApi, $requestId, $response);
+    } catch (\Throwable $e) {
+        postError($runtimeApi, $requestId, $e);
+    }
+}
+
+/**
+ * @return array{0:string,1:array}|null
+ */
+function nextInvocation(string $api): ?array
+{
+    $ch = curl_init("http://{$api}/2018-06-01/runtime/invocation/next");
+    $headers = [];
+    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+    curl_setopt($ch, CURLOPT_HEADERFUNCTION, function ($c, $h) use (&$headers) {
+        $parts = explode(':', $h, 2);
+        if (count($parts) === 2) {
+            $headers[strtolower(trim($parts[0]))] = trim($parts[1]);
+        }
+        return strlen($h);
+    });
+    $body = curl_exec($ch);
+    curl_close($ch);
+    if ($body === false) {
+        return null;
+    }
+    $requestId = $headers['lambda-runtime-aws-request-id'] ?? '';
+    $event = json_decode($body, true) ?: [];
+    return [$requestId, $event];
+}
+
+function handle(array $event, FastCgiClient $fpm, string $docRoot, bool $maintenance, string $bypassSecret): array
+{
+    // Warmer ping (scheduled keep-warm rule): keep the container alive, return fast.
+    if (($event['warmer'] ?? false) === true) {
+        return ['statusCode' => 200, 'headers' => ['content-type' => 'text/plain'], 'body' => 'warm', 'isBase64Encoded' => false];
+    }
+
+    $http = $event['requestContext']['http'] ?? [];
+    $method = $http['method'] ?? 'GET';
+    $rawPath = $event['rawPath'] ?? '/';
+    $rawQuery = $event['rawQueryString'] ?? '';
+    $headers = $event['headers'] ?? [];
+    $cookies = $event['cookies'] ?? [];
+
+    // Maintenance mode: 503 unless the bypass secret is presented.
+    if ($maintenance) {
+        $bypass = $headers['x-maintenance-bypass'] ?? '';
+        if ($bypassSecret === '' || $bypass !== $bypassSecret) {
+            return [
+                'statusCode' => 503,
+                'headers' => ['content-type' => 'text/plain', 'retry-after' => '120'],
+                'body' => 'Service temporarily unavailable (maintenance mode)',
+                'isBase64Encoded' => false,
+            ];
+        }
+    }
+
+    $body = $event['body'] ?? '';
+    if (($event['isBase64Encoded'] ?? false) === true) {
+        $body = base64_decode($body);
+    }
+
+    $params = [
+        'GATEWAY_INTERFACE' => 'CGI/1.1',
+        'REQUEST_METHOD' => $method,
+        'SCRIPT_FILENAME' => $docRoot . '/index.php',
+        'SCRIPT_NAME' => '/index.php',
+        'PATH_INFO' => $rawPath,
+        'REQUEST_URI' => $rawQuery !== '' ? $rawPath . '?' . $rawQuery : $rawPath,
+        'QUERY_STRING' => $rawQuery,
+        'DOCUMENT_ROOT' => $docRoot,
+        'SERVER_PROTOCOL' => $http['protocol'] ?? 'HTTP/1.1',
+        'SERVER_SOFTWARE' => 'ts-cloud-lambda',
+        'REMOTE_ADDR' => $http['sourceIp'] ?? '127.0.0.1',
+        'SERVER_NAME' => $event['requestContext']['domainName'] ?? 'localhost',
+        'SERVER_PORT' => '443',
+        'HTTPS' => 'on',
+        'CONTENT_LENGTH' => (string) strlen($body),
+    ];
+    if (isset($headers['content-type'])) {
+        $params['CONTENT_TYPE'] = $headers['content-type'];
+    }
+    if (!empty($cookies)) {
+        $headers['cookie'] = implode('; ', $cookies);
+    }
+    foreach ($headers as $name => $value) {
+        $key = 'HTTP_' . strtoupper(str_replace('-', '_', $name));
+        $params[$key] = $value;
+    }
+
+    $result = $fpm->request($params, $body);
+    return parseFpmResponse($result['stdout']);
+}
+
+function parseFpmResponse(string $raw): array
+{
+    // Split headers from body.
+    $pos = strpos($raw, "\r\n\r\n");
+    if ($pos === false) {
+        $pos = strpos($raw, "\n\n");
+        $headerBlock = $pos === false ? '' : substr($raw, 0, $pos);
+        $body = $pos === false ? $raw : substr($raw, $pos + 2);
+    } else {
+        $headerBlock = substr($raw, 0, $pos);
+        $body = substr($raw, $pos + 4);
+    }
+
+    $statusCode = 200;
+    $headers = [];
+    $cookies = [];
+    foreach (preg_split('/\r\n|\n/', $headerBlock) as $line) {
+        if (trim($line) === '') {
+            continue;
+        }
+        $parts = explode(':', $line, 2);
+        if (count($parts) !== 2) {
+            continue;
+        }
+        $name = strtolower(trim($parts[0]));
+        $value = trim($parts[1]);
+        if ($name === 'status') {
+            $statusCode = (int) substr($value, 0, 3);
+        } elseif ($name === 'set-cookie') {
+            $cookies[] = $value;
+        } else {
+            $headers[$name] = $value;
+        }
+    }
+
+    $contentType = $headers['content-type'] ?? 'text/html';
+    $isText = (bool) preg_match('#^(text/|application/(json|xml|javascript|x-www-form-urlencoded)|image/svg)#i', $contentType);
+
+    $response = [
+        'statusCode' => $statusCode,
+        'headers' => $headers,
+        'isBase64Encoded' => !$isText,
+        'body' => $isText ? $body : base64_encode($body),
+    ];
+    if (!empty($cookies)) {
+        $response['cookies'] = $cookies;
+    }
+    return $response;
+}
+
+function postResponse(string $api, string $requestId, array $response): void
+{
+    $ch = curl_init("http://{$api}/2018-06-01/runtime/invocation/{$requestId}/response");
+    curl_setopt($ch, CURLOPT_POST, true);
+    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($response));
+    curl_exec($ch);
+    curl_close($ch);
+}
+
+function postError(string $api, string $requestId, \Throwable $e): void
+{
+    $ch = curl_init("http://{$api}/2018-06-01/runtime/invocation/{$requestId}/error");
+    curl_setopt($ch, CURLOPT_POST, true);
+    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
+    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
+        'errorType' => get_class($e),
+        'errorMessage' => $e->getMessage(),
+    ]));
+    curl_exec($ch);
+    curl_close($ch);
+}

package/dist/runtime.mjs

@@ -0,0 +1,95 @@
+/**
+ * ts-cloud JS Lambda custom-runtime loop (provided.al2023).
+ *
+ * Shared by both the Node and Bun custom runtimes — it is plain ESM that runs
+ * under either `node /opt/runtime.mjs` or `bun /opt/runtime.mjs`. It implements
+ * the AWS Lambda Runtime API event loop and delegates each invocation to the
+ * handler exported by the deployment artifact (the ts-cloud serverless adapter
+ * already bundled `http`/`queue`/`cli` into `index.mjs`).
+ *
+ * The function's configured Handler (e.g. `index.http`) arrives as `_HANDLER`,
+ * so the same artifact + layer serve all three functions; only `_HANDLER`
+ * differs per function.
+ */
+
+const RUNTIME_API = process.env.AWS_LAMBDA_RUNTIME_API
+const BASE = `http://${RUNTIME_API}/2018-06-01/runtime`
+const TASK_ROOT = process.env.LAMBDA_TASK_ROOT ?? '/var/task'
+const HANDLER = process.env._HANDLER ?? 'index.http'
+
+async function resolveHandler() {
+  const lastDot = HANDLER.lastIndexOf('.')
+  const file = lastDot === -1 ? HANDLER : HANDLER.slice(0, lastDot)
+  const exportName = lastDot === -1 ? 'http' : HANDLER.slice(lastDot + 1)
+
+  let mod
+  for (const ext of ['.mjs', '.js', '.cjs', '']) {
+    try {
+      mod = await import(`${TASK_ROOT}/${file}${ext}`)
+      break
+    }
+    catch {
+      // try the next extension
+    }
+  }
+  if (!mod)
+    throw new Error(`Cannot load handler module "${file}" from ${TASK_ROOT}`)
+
+  const fn = mod[exportName] ?? mod.default?.[exportName] ?? mod.default
+  if (typeof fn !== 'function')
+    throw new TypeError(`Handler "${HANDLER}" did not resolve to a function`)
+  return fn
+}
+
+async function postInitError(err) {
+  await fetch(`${BASE}/init/error`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ errorType: err?.name ?? 'InitError', errorMessage: String(err?.message ?? err) }),
+  }).catch(() => {})
+}
+
+async function main() {
+  let handler
+  try {
+    handler = await resolveHandler()
+  }
+  catch (err) {
+    await postInitError(err)
+    process.exit(1)
+    return
+  }
+
+  // The Runtime API event loop: long-poll for the next invocation, run the
+  // handler, post the response (or error), repeat.
+  for (;;) {
+    const next = await fetch(`${BASE}/invocation/next`)
+    const requestId = next.headers.get('lambda-runtime-aws-request-id')
+    if (!requestId) continue
+
+    let event
+    try {
+      event = await next.json()
+    }
+    catch {
+      event = {}
+    }
+
+    try {
+      const result = await handler(event)
+      await fetch(`${BASE}/invocation/${requestId}/response`, {
+        method: 'POST',
+        body: result === undefined ? '' : JSON.stringify(result),
+      })
+    }
+    catch (err) {
+      await fetch(`${BASE}/invocation/${requestId}/error`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ errorType: err?.name ?? 'Error', errorMessage: String(err?.message ?? err) }),
+      }).catch(() => {})
+    }
+  }
+}
+
+main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-cloud/core",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "type": "module",
   "description": "Core CloudFormation generation library for ts-cloud",
   "author": "Chris Breuer <chris@stacksjs.com>",
@@ -31,7 +31,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@ts-cloud/aws-types": "0.5.2"
+    "@ts-cloud/aws-types": "0.5.3"
   },
   "devDependencies": {
     "typescript": "^5.9.3"