@thms-rmb/nodejs-aws-lambda 0.9.0-0

package/README.md

@@ -0,0 +1,180 @@
+# nodejs-aws-lambda
+
+A Node.js port of the Perl [`AWS::Lambda`](https://metacpan.org/dist/AWS-Lambda)
+custom-runtime client (v0.9.0). It implements the
+[AWS Lambda Runtime API](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-custom.html)
+so a plain JavaScript handler can run on the OS-only `provided.*` runtime family.
+
+- **Zero runtime dependencies** — built only on Node's `node:http`, `JSON`, etc.
+- **Plain ESM** — no bundler, no build step.
+- **JSDoc-typed** — full editor IntelliSense.
+- Buffered **and** streaming responses.
+
+This port covers the runtime core (`Bootstrap`, `Context`, `ResponseWriter`,
+the `bootstrap` entry point). The Perl `AWS::Lambda::PSGI` web adapter and the
+`AL`/`AL2`/`AL2023` layer-ARN tables are intentionally out of scope.
+
+## Handler
+
+`_HANDLER` uses the `file.function` format. Given `_HANDLER=handler.handle` and
+`LAMBDA_TASK_ROOT` pointing at your code, the runtime imports `handler.js`
+(`.mjs`/`.cjs` also resolved) and calls its exported `handle`:
+
+```js
+// handler.js
+import { getCurrentContext } from '@thms-rmb/nodejs-aws-lambda';
+
+export function handle(payload, context) {
+  // context is a Context instance (also available via getCurrentContext()).
+  return { echo: payload, requestId: context.awsRequestId };
+}
+```
+
+The handler receives `(payload, context)` and may be `async`. Its return value
+is JSON-encoded and posted as the response. Throwing reports an invocation
+error and continues the loop.
+
+### Streaming responses
+
+Return a function to stream the response
+([response streaming](https://docs.aws.amazon.com/lambda/latest/dg/configuration-response-streaming.html)):
+
+```js
+export function handle(payload, context) {
+  return async (responder) => {
+    const writer = responder('application/json');
+    writer.write('{"foo":');
+    writer.write('"bar"}');
+    writer.close();
+  };
+}
+```
+
+## The `bootstrap` entry point
+
+`bin/bootstrap` is the executable Lambda invokes. It starts the event loop and
+reads the handler from `_HANDLER` (or its first CLI argument). Programmatically:
+
+```js
+import { bootstrap, Bootstrap } from '@thms-rmb/nodejs-aws-lambda';
+
+await bootstrap('handler.handle');            // convenience
+// or, for full control:
+await new Bootstrap({ handler: 'handler.handle' }).handleEvents();
+```
+
+## Context
+
+`Context` exposes the per-invocation fields from the Runtime API headers
+(`awsRequestId`, `invokedFunctionArn`, `traceId`, `tenantId`, `deadlineMs`),
+`getRemainingTimeInMillis()`, and environment-backed accessors (`functionName`,
+`functionVersion`, `memoryLimitInMb`, `logGroupName`, `logStreamName`).
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `_HANDLER` | `file.function` of the handler. |
+| `AWS_LAMBDA_RUNTIME_API` | `host:port` of the Runtime API. |
+| `LAMBDA_TASK_ROOT` | Directory containing the handler file. |
+| `AWS_LAMBDA_MAX_CONCURRENCY` | Optional; number of concurrent invocation loops (values > 1 have [gotchas](#concurrency-and-its-gotchas)). |
+| `_X_AMZN_TRACE_ID` | Set by the runtime per invocation from the trace header. |
+
+## Testing
+
+```sh
+npm test        # node --test over test/*.test.js — zero dependencies
+```
+
+## Notable differences from the Perl original
+
+- **Async throughout.** `node:http` is non-blocking, so `handleEvent`,
+  `lambdaNext`, etc. are `async`; handlers may be `async`.
+- **Concurrency.** `AWS_LAMBDA_MAX_CONCURRENCY > 0` runs N concurrent async
+  invocation loops (stopped by `SIGTERM`/`SIGHUP`) instead of Perl's
+  `Parallel::Prefork`. This changes the isolation guarantees — see
+  [Concurrency and its gotchas](#concurrency-and-its-gotchas) below.
+- **Streaming.** `ResponseWriter` uses `node:http` chunked encoding and native
+  trailers rather than hand-framing chunks.
+
+## Concurrency and its gotchas
+
+By default (`AWS_LAMBDA_MAX_CONCURRENCY` unset or `0`) the runtime handles **one
+invocation at a time** — this is classic Lambda behavior and has **no gotchas**;
+everything below applies only when you set concurrency above 1.
+
+Setting `AWS_LAMBDA_MAX_CONCURRENCY > 1` (used by
+[Lambda Managed Instances](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-custom.html))
+runs that many concurrent invocation loops. **The Perl original forks a separate
+OS process per worker, so every invocation gets its own memory, environment, and
+current context for free.** This port instead runs concurrent `async` loops in a
+**single process and thread**, so that per-process isolation does not exist.
+
+What that means in practice:
+
+| Behavior | Concurrency > 1 |
+|----------|-----------------|
+| Fetching, invoking, and responding to N invocations in parallel | ✅ works |
+| Response routing — each result posted to the correct request ID | ✅ works (payload and `context` are passed as **arguments**) |
+| Reading the `context` **argument** inside your handler | ✅ always correct |
+| `getCurrentContext()` after your handler `await`s | ⚠️ may return another concurrent invocation's context |
+| `process.env._X_AMZN_TRACE_ID` after your handler `await`s | ⚠️ may hold another concurrent invocation's trace id |
+
+The reason: `getCurrentContext()` and `_X_AMZN_TRACE_ID` are **process-global
+ambient state**. They are set correctly just before your handler runs, but once
+an `async` handler yields at an `await`, another worker can run and overwrite
+them. Synchronous handlers (and any code that reads these before its first
+`await`) are unaffected.
+
+**Guidance when running with concurrency > 1:**
+
+- Use the `context` **argument** your handler receives, not `getCurrentContext()`.
+- Don't rely on `_X_AMZN_TRACE_ID` being pinned to your invocation across
+  `await`s. (`process.env` is inherently process-wide; there is no per-async
+  environment, which is also why the AWS X-Ray SDK propagates trace context
+  itself rather than trusting that variable alone.)
+
+If you need a correct per-invocation `getCurrentContext()` under concurrency,
+`node:async_hooks`' `AsyncLocalStorage` is the zero-dependency way to add it.
+
+## Releasing
+
+**Versioning policy.** The `major.minor.patch` numbers mirror the upstream Perl
+[`AWS::Lambda`](https://metacpan.org/dist/AWS-Lambda) release this port tracks
+(currently `0.9.0`). Changes that are specific to this port and do **not**
+correspond to a new upstream release are published as **prereleases toward the
+next patch** — e.g. after `0.9.0`, port tweaks ship as `0.9.1-1`, `0.9.1-2`, …
+(a prerelease sorts *before* `0.9.1`, so it correctly reads as "on the way to
+the next version"). A clean `X.Y.Z` with no prerelease suffix is reserved for a
+release that faithfully matches upstream `X.Y.Z`.
+
+The publish workflow maps this to npm [dist-tags](https://docs.npmjs.com/cli/v10/commands/npm-dist-tag)
+automatically: a prerelease version (one containing a `-`) is published under
+`next`; a clean version is published under `latest`.
+
+**Cutting a release.** Version tags drive publishing — the
+[`publish` workflow](.github/workflows/publish.yml) runs on any `v*` tag push:
+
+```sh
+npm version 0.9.1-1 --no-git-tag-version   # or edit package.json by hand
+git commit -am "Release 0.9.1-1"
+git tag v0.9.1-1
+git push && git push --tag
+```
+
+The workflow verifies the tag matches `package.json`, runs the tests, and
+publishes. It uses npm **trusted publishing (OIDC)** — there is no `NPM_TOKEN`
+secret, and [provenance](https://docs.npmjs.com/generating-provenance-statements)
+is attached automatically.
+
+**One-time trusted-publishing setup** (on [npmjs.com](https://www.npmjs.com)):
+because the trusted-publisher setting lives under an existing package's
+settings, publish once manually to create the package —
+`npm publish` locally (this reads `publishConfig.access: public`) — then in the
+package's **Settings → Trusted Publisher** add a GitHub Actions publisher with
+repository `thms-rmb/nodejs-aws-lambda` and workflow filename `publish.yml`.
+Every subsequent release then flows through the tag-push workflow with no token.
+
+## License
+
+MIT (matching the upstream Perl distribution by ICHINOSE Shogo).

package/bin/bootstrap

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// AWS Lambda custom-runtime entry point.
+//
+// Lambda executes the file named `bootstrap` at the root of the deployment
+// package (or in a layer). This starts the Runtime API event loop. The handler
+// is read from the `_HANDLER` environment variable, or the first CLI argument
+// (which is what the container `CMD` provides), matching the Perl `bootstrap`.
+import { bootstrap } from '../src/index.js';
+
+bootstrap(process.argv[2]);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@thms-rmb/nodejs-aws-lambda",
+  "version": "0.9.0-0",
+  "description": "Node.js port of the Perl AWS::Lambda custom-runtime client. Zero runtime dependencies, plain ESM.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thms-rmb/nodejs-aws-lambda.git"
+  },
+  "homepage": "https://github.com/thms-rmb/nodejs-aws-lambda#readme",
+  "bugs": {
+    "url": "https://github.com/thms-rmb/nodejs-aws-lambda/issues"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "bootstrap": "bin/bootstrap"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "aws",
+    "lambda",
+    "custom-runtime",
+    "provided",
+    "serverless"
+  ]
+}

package/src/bootstrap.js

@@ -0,0 +1,347 @@
+/**
+ * Node.js port of `AWS::Lambda::Bootstrap` — the AWS Lambda custom-runtime
+ * event loop. It loads the handler, then repeatedly fetches the next
+ * invocation from the Runtime API, invokes the handler, and posts the
+ * response or error.
+ *
+ * @module bootstrap
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { Context } from './context.js';
+import { ResponseWriter } from './response-writer.js';
+import { request } from './http.js';
+import { errorMessage, errorType } from './errors.js';
+import { _setCurrentContext } from './current-context.js';
+
+const API_VERSION = '2018-06-01';
+
+/** Handler-file extensions tried, in order, when resolving `_HANDLER`. */
+const HANDLER_EXTENSIONS = ['.js', '.mjs', '.cjs'];
+
+/**
+ * A Lambda handler function. May be `async`. Returning a function selects
+ * {@link https://docs.aws.amazon.com/lambda/latest/dg/configuration-response-streaming.html response streaming}.
+ *
+ * @callback Handler
+ * @param {*} payload The invocation event, JSON-decoded.
+ * @param {Context} context The invocation {@link Context}.
+ * @returns {*|Promise<*>|StreamingHandler|Promise<StreamingHandler>}
+ */
+
+/**
+ * A response-streaming handler: the value a {@link Handler} returns when it
+ * wants to stream. It receives a `responder` and writes the body via the
+ * {@link ResponseWriter} the responder returns.
+ *
+ * @callback StreamingHandler
+ * @param {(contentType?: string) => ResponseWriter} responder
+ * @returns {void|Promise<void>}
+ */
+
+/**
+ * @typedef {object} BootstrapArgs
+ * @property {string} [handler] The handler in `file.function` form. Falls back
+ *   to `_HANDLER`.
+ * @property {string} [runtimeApi] The Runtime API host:port. Falls back to
+ *   `AWS_LAMBDA_RUNTIME_API`.
+ * @property {string} [taskRoot] The directory containing the handler file.
+ *   Falls back to `LAMBDA_TASK_ROOT`.
+ * @property {number|string} [maxWorkers] Number of concurrent invocation loops
+ *   to run. Falls back to `AWS_LAMBDA_MAX_CONCURRENCY`, then `0`.
+ */
+
+export class Bootstrap {
+  /**
+   * @param {BootstrapArgs} [args]
+   */
+  constructor(args = {}) {
+    const envHandler = args.handler ?? process.env._HANDLER;
+    if (envHandler === undefined) {
+      throw new Error('$_HANDLER is not found');
+    }
+    const runtimeApi = args.runtimeApi ?? process.env.AWS_LAMBDA_RUNTIME_API;
+    if (runtimeApi === undefined) {
+      throw new Error('$AWS_LAMBDA_RUNTIME_API is not found');
+    }
+    const taskRoot = args.taskRoot ?? process.env.LAMBDA_TASK_ROOT;
+    if (taskRoot === undefined) {
+      throw new Error('$LAMBDA_TASK_ROOT is not found');
+    }
+    const maxWorkers = args.maxWorkers ?? process.env.AWS_LAMBDA_MAX_CONCURRENCY ?? 0;
+    if (!/^\d+$/.test(String(maxWorkers))) {
+      throw new Error(`max_workers must be a non-negative integer, got: ${maxWorkers}`);
+    }
+
+    // Split "file.function" on the first dot, matching Perl's split(/[.]/, ..., 2).
+    const dot = envHandler.indexOf('.');
+    /** @type {string} The handler file name, without extension. */
+    this.file = dot === -1 ? envHandler : envHandler.slice(0, dot);
+    /** @type {string|undefined} The exported handler function name. */
+    this.functionName = dot === -1 ? undefined : envHandler.slice(dot + 1);
+
+    /** @type {string} */
+    this.taskRoot = taskRoot;
+    /** @type {string} */
+    this.runtimeApi = runtimeApi;
+    /** @type {string} */
+    this.apiVersion = API_VERSION;
+    /** @type {string} */
+    this.nextEventUrl = `http://${runtimeApi}/${API_VERSION}/runtime/invocation/next`;
+    /** @type {number} */
+    this.maxWorkers = Number(maxWorkers);
+    /** @type {Handler|undefined} The resolved handler function. */
+    this.function = undefined;
+    /** @type {boolean} Set by SIGTERM/SIGHUP to stop the worker loops. */
+    this._stop = false;
+  }
+
+  /**
+   * Import the handler module and resolve the exported function, once. On
+   * failure, report an initialization error, install a no-op, and return
+   * `null` so the caller can stop.
+   *
+   * @returns {Promise<Handler|null>}
+   */
+  async _init() {
+    if (this.function) {
+      return this.function;
+    }
+    try {
+      const module = await this._importHandler();
+      const fn = this.functionName === undefined ? undefined : module[this.functionName];
+      if (typeof fn !== 'function') {
+        throw new Error(`handler ${this.functionName} is not found`);
+      }
+      this.function = fn;
+      return fn;
+    } catch (error) {
+      await this.lambdaInitError(error);
+      this.function = () => {};
+      return null;
+    }
+  }
+
+  /**
+   * Dynamically import the handler file, resolving its extension.
+   *
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  async _importHandler() {
+    const base = join(this.taskRoot, this.file);
+    let file = `${base}.js`;
+    for (const ext of HANDLER_EXTENSIONS) {
+      if (existsSync(base + ext)) {
+        file = base + ext;
+        break;
+      }
+    }
+    return import(pathToFileURL(file).href);
+  }
+
+  /**
+   * Handle a single invocation: fetch the next event, invoke the handler, and
+   * post the response, streaming response, or error.
+   *
+   * @returns {Promise<boolean|undefined>} `true` on a normal response,
+   *   otherwise a falsy value.
+   */
+  async handleEvent() {
+    if (!(await this._init())) {
+      return undefined;
+    }
+    const [payload, context] = await this.lambdaNext();
+
+    let result;
+    const previousTraceId = process.env._X_AMZN_TRACE_ID;
+    try {
+      if (context?.traceId === undefined) {
+        delete process.env._X_AMZN_TRACE_ID;
+      } else {
+        process.env._X_AMZN_TRACE_ID = context.traceId;
+      }
+      _setCurrentContext(context);
+      result = await /** @type {Handler} */ (this.function)(payload, context);
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? (error.stack ?? error.message) : error}\n`);
+      await this.lambdaError(error, context);
+      return undefined;
+    } finally {
+      _setCurrentContext(undefined);
+      if (previousTraceId === undefined) {
+        delete process.env._X_AMZN_TRACE_ID;
+      } else {
+        process.env._X_AMZN_TRACE_ID = previousTraceId;
+      }
+    }
+
+    if (typeof result === 'function') {
+      await this.lambdaResponseStreaming(result, context);
+    } else {
+      await this.lambdaResponse(result, context);
+    }
+    return true;
+  }
+
+  /**
+   * Fetch the next invocation and build its {@link Context} from the response
+   * headers.
+   *
+   * @returns {Promise<[unknown, Context]>} `[payload, context]`.
+   */
+  async lambdaNext() {
+    const response = await request(this.nextEventUrl);
+    if (!response.success) {
+      throw new Error(`failed to retrieve the next event: ${response.status}`);
+    }
+    const h = response.headers;
+    const payload = JSON.parse(response.body);
+    const context = new Context({
+      deadlineMs: /** @type {string} */ (h['lambda-runtime-deadline-ms']),
+      awsRequestId: /** @type {string} */ (h['lambda-runtime-aws-request-id']),
+      invokedFunctionArn: /** @type {string} */ (h['lambda-runtime-invoked-function-arn']),
+      traceId: /** @type {string} */ (h['lambda-runtime-trace-id']),
+      tenantId: /** @type {string} */ (h['lambda-runtime-aws-tenant-id']),
+    });
+    return [payload, context];
+  }
+
+  /**
+   * Post a buffered handler response to the Runtime API.
+   *
+   * @param {unknown} response The handler's return value.
+   * @param {Context} context
+   * @returns {Promise<void>}
+   */
+  async lambdaResponse(response, context) {
+    const url = `http://${this.runtimeApi}/${this.apiVersion}/runtime/invocation/${context.awsRequestId}/response`;
+    const result = await request(url, { method: 'POST', body: JSON.stringify(response) });
+    if (!result.success) {
+      throw new Error(`failed to response of execution: ${result.status}`);
+    }
+  }
+
+  /**
+   * Stream a handler response to the Runtime API.
+   *
+   * @param {StreamingHandler} response The streaming callback the handler
+   *   returned.
+   * @param {Context} context
+   * @returns {Promise<void>}
+   */
+  async lambdaResponseStreaming(response, context) {
+    const url = `http://${this.runtimeApi}/${this.apiVersion}/runtime/invocation/${context.awsRequestId}/response`;
+    /** @type {ResponseWriter|undefined} */
+    let writer;
+    try {
+      await response((contentType) => {
+        writer = new ResponseWriter({ responseUrl: url, contentType });
+        writer._request(contentType);
+        return writer;
+      });
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? (error.stack ?? error.message) : error}\n`);
+      if (writer) {
+        writer._closeWithError(error);
+      } else {
+        await this.lambdaError(error, context);
+      }
+    }
+    if (writer) {
+      const result = await writer._handleResponse();
+      if (!result.success) {
+        throw new Error(`failed to response of execution: ${result.status}`);
+      }
+    }
+  }
+
+  /**
+   * Report an invocation error to the Runtime API.
+   *
+   * @param {unknown} error
+   * @param {Context} context
+   * @returns {Promise<void>}
+   */
+  async lambdaError(error, context) {
+    const url = `http://${this.runtimeApi}/${this.apiVersion}/runtime/invocation/${context.awsRequestId}/error`;
+    const result = await request(url, {
+      method: 'POST',
+      body: JSON.stringify({ errorMessage: errorMessage(error), errorType: errorType(error) }),
+    });
+    if (!result.success) {
+      throw new Error(`failed to send error of execution: ${result.status}`);
+    }
+  }
+
+  /**
+   * Report an initialization error to the Runtime API.
+   *
+   * @param {unknown} error
+   * @returns {Promise<void>}
+   */
+  async lambdaInitError(error) {
+    const url = `http://${this.runtimeApi}/${this.apiVersion}/runtime/init/error`;
+    const result = await request(url, {
+      method: 'POST',
+      body: JSON.stringify({ errorMessage: errorMessage(error), errorType: errorType(error) }),
+    });
+    if (!result.success) {
+      throw new Error(`failed to send error of execution: ${result.status}`);
+    }
+  }
+
+  /**
+   * The inner invocation loop. Runs until {@link Bootstrap#_stop} is set.
+   *
+   * @returns {Promise<void>}
+   */
+  async _handleEvents() {
+    while (!this._stop) {
+      await this.handleEvent();
+    }
+  }
+
+  /**
+   * Initialize the handler and process events. With `maxWorkers > 0`, run that
+   * many concurrent invocation loops (the Node analog of Perl's
+   * `Parallel::Prefork`), stopping on SIGTERM/SIGHUP.
+   *
+   * @returns {Promise<void>}
+   */
+  async handleEvents() {
+    if (!(await this._init())) {
+      return;
+    }
+    if (this.maxWorkers > 0) {
+      const stop = () => {
+        this._stop = true;
+      };
+      process.on('SIGTERM', stop);
+      process.on('SIGHUP', stop);
+      try {
+        await Promise.all(Array.from({ length: this.maxWorkers }, () => this._handleEvents()));
+      } finally {
+        process.removeListener('SIGTERM', stop);
+        process.removeListener('SIGHUP', stop);
+      }
+    } else {
+      await this._handleEvents();
+    }
+  }
+}
+
+/**
+ * Construct a {@link Bootstrap} for `handler` and run its event loop. The
+ * convenience entry point used by the `bootstrap` executable.
+ *
+ * @param {string} [handler] The handler in `file.function` form. Falls back to
+ *   `_HANDLER`.
+ * @returns {Promise<void>}
+ */
+export async function bootstrap(handler) {
+  const instance = new Bootstrap({ handler });
+  await instance.handleEvents();
+}

package/src/context.js

@@ -0,0 +1,158 @@
+/**
+ * Node.js port of `AWS::Lambda::Context`.
+ *
+ * @module context
+ */
+
+/**
+ * @typedef {object} ContextArgs
+ * @property {number|string} deadlineMs The date (in Unix epoch milliseconds)
+ *   by which the function must exit. Required.
+ * @property {string} [awsRequestId] The identifier of the invocation request.
+ * @property {string} [invokedFunctionArn] The ARN used to invoke the function.
+ * @property {string} [traceId] The AWS X-Ray tracing header.
+ * @property {string} [tenantId] The tenant id for the function.
+ */
+
+/**
+ * The Lambda context object, passed to the handler as its second argument.
+ *
+ * Per-invocation fields come from the response headers of the "next
+ * invocation" call; the remaining accessors read process environment
+ * variables that Lambda sets once per execution environment.
+ */
+export class Context {
+  /**
+   * @param {ContextArgs} args
+   */
+  constructor(args = /** @type {ContextArgs} */ ({})) {
+    if (args.deadlineMs === undefined || args.deadlineMs === null) {
+      throw new Error('deadline_ms is required');
+    }
+
+    /**
+     * The date (in Unix epoch milliseconds) by which the function must exit.
+     * @type {number}
+     */
+    this.deadlineMs = Number(args.deadlineMs);
+
+    /**
+     * The ARN used to invoke the function.
+     * @type {string}
+     */
+    this.invokedFunctionArn = args.invokedFunctionArn ?? '';
+
+    /**
+     * The identifier of the invocation request.
+     * @type {string}
+     */
+    this.awsRequestId = args.awsRequestId ?? '';
+
+    /**
+     * The AWS X-Ray tracing header.
+     * @type {string|undefined}
+     */
+    this.traceId = args.traceId;
+
+    /**
+     * The tenant id for the function.
+     * @type {string|undefined}
+     */
+    this.tenantId = args.tenantId;
+  }
+
+  /**
+   * The number of milliseconds left before the execution times out.
+   *
+   * @returns {number}
+   */
+  getRemainingTimeInMillis() {
+    return this.deadlineMs - Date.now();
+  }
+
+  /**
+   * The name of the Lambda function (`AWS_LAMBDA_FUNCTION_NAME`).
+   *
+   * @returns {string}
+   * @throws {Error} if the environment variable is not set.
+   */
+  get functionName() {
+    return required('AWS_LAMBDA_FUNCTION_NAME', 'function_name');
+  }
+
+  /**
+   * The version of the function (`AWS_LAMBDA_FUNCTION_VERSION`).
+   *
+   * @returns {string}
+   * @throws {Error} if the environment variable is not set.
+   */
+  get functionVersion() {
+    return required('AWS_LAMBDA_FUNCTION_VERSION', 'function_version');
+  }
+
+  /**
+   * The amount of memory configured on the function, in MB
+   * (`AWS_LAMBDA_FUNCTION_MEMORY_SIZE`).
+   *
+   * @returns {number}
+   * @throws {Error} if the environment variable is not set.
+   */
+  get memoryLimitInMb() {
+    return Number(required('AWS_LAMBDA_FUNCTION_MEMORY_SIZE', 'memory_limit_in_mb'));
+  }
+
+  /**
+   * The log group for the function (`AWS_LAMBDA_LOG_GROUP_NAME`).
+   *
+   * @returns {string}
+   * @throws {Error} if the environment variable is not set.
+   */
+  get logGroupName() {
+    return required('AWS_LAMBDA_LOG_GROUP_NAME', 'log_group_name');
+  }
+
+  /**
+   * The log stream for the function instance (`AWS_LAMBDA_LOG_STREAM_NAME`).
+   *
+   * @returns {string}
+   * @throws {Error} if the environment variable is not set.
+   */
+  get logStreamName() {
+    return required('AWS_LAMBDA_LOG_STREAM_NAME', 'log_stream_name');
+  }
+
+  /**
+   * Cognito identity information. Not implemented (matches the Perl port).
+   *
+   * @returns {undefined}
+   */
+  get identity() {
+    return undefined; // TODO
+  }
+
+  /**
+   * Client context sent by the mobile SDK. Not implemented (matches the Perl
+   * port).
+   *
+   * @returns {undefined}
+   */
+  get clientContext() {
+    return undefined; // TODO
+  }
+}
+
+/**
+ * Read a required environment variable, throwing with the Perl-compatible
+ * "<label> is not found" message when it is absent.
+ *
+ * @param {string} name
+ * @param {string} label
+ * @returns {string}
+ */
+function required(name, label) {
+  const value = process.env[name];
+  if (value === undefined) {
+    throw new Error(`${label} is not found`);
+  }
+  return value;
+}

package/src/current-context.js

@@ -0,0 +1,33 @@
+/**
+ * The context of the invocation currently being handled.
+ *
+ * This mirrors the Perl library's global `$AWS::Lambda::context`, which is
+ * localized for the duration of each handler call. A handler can read it via
+ * {@link getCurrentContext} instead of receiving it as an argument.
+ *
+ * @module current-context
+ */
+
+/** @type {import('./context.js').Context | undefined} */
+let current;
+
+/**
+ * Return the {@link Context} of the invocation currently being handled, or
+ * `undefined` when no invocation is in flight.
+ *
+ * @returns {import('./context.js').Context | undefined}
+ */
+export function getCurrentContext() {
+  return current;
+}
+
+/**
+ * Set the current invocation context. Internal: called by `Bootstrap` around
+ * each handler invocation.
+ *
+ * @param {import('./context.js').Context | undefined} context
+ * @returns {void}
+ */
+export function _setCurrentContext(context) {
+  current = context;
+}

package/src/errors.js

@@ -0,0 +1,29 @@
+/**
+ * Helpers that reproduce the Perl library's error reporting shape. The Perl
+ * code uses `"$error"` for the message and `blessed($error) // "Error"` for
+ * the type; the JS analog inspects `Error` instances.
+ *
+ * @module errors
+ */
+
+/**
+ * The human-readable error message reported to Lambda.
+ *
+ * @param {unknown} error
+ * @returns {string}
+ */
+export function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * The error type reported to Lambda. For `Error` instances this is the
+ * constructor name (e.g. `TypeError`, or a custom subclass name); otherwise
+ * it is `"Error"` — matching Perl's `blessed($error) // "Error"`.
+ *
+ * @param {unknown} error
+ * @returns {string}
+ */
+export function errorType(error) {
+  return error instanceof Error ? (error.constructor?.name ?? 'Error') : 'Error';
+}

package/src/http.js

@@ -0,0 +1,76 @@
+/**
+ * A tiny buffered HTTP client built on `node:http` — the Node analog of the
+ * Perl library's use of `HTTP::Tiny`. Kept intentionally minimal: only what
+ * the Lambda Runtime API client needs (a long-polling GET and a POST with a
+ * string body). Streaming responses use `node:http` directly, see
+ * {@link module:response-writer}.
+ *
+ * @module http
+ */
+
+import http from 'node:http';
+import https from 'node:https';
+
+/**
+ * @typedef {object} HttpResponse
+ * @property {number} status The HTTP status code.
+ * @property {import('node:http').IncomingHttpHeaders} headers Response headers
+ *   (lower-cased keys, as Node provides them).
+ * @property {string} body The response body decoded as UTF-8.
+ * @property {boolean} success Whether the status is a 2xx.
+ */
+
+/**
+ * @typedef {object} RequestOptions
+ * @property {string} [method] HTTP method. Defaults to `GET`.
+ * @property {Record<string, string>} [headers] Request headers.
+ * @property {string} [body] Request body, sent as UTF-8.
+ * @property {number} [timeout] Socket timeout in milliseconds. Omit to disable
+ *   (used for the long-poll "next invocation" request).
+ */
+
+/**
+ * Perform a buffered HTTP request and resolve once the whole response body has
+ * been read.
+ *
+ * @param {string} url
+ * @param {RequestOptions} [options]
+ * @returns {Promise<HttpResponse>}
+ */
+export function request(url, options = {}) {
+  const { method = 'GET', headers = {}, body, timeout } = options;
+  return new Promise((resolve, reject) => {
+    const target = new URL(url);
+    const lib = target.protocol === 'https:' ? https : http;
+
+    /** @type {Record<string, string|number>} */
+    const outHeaders = { ...headers };
+    if (body !== undefined && body !== null && outHeaders['content-length'] === undefined) {
+      outHeaders['content-length'] = Buffer.byteLength(body, 'utf8');
+    }
+
+    const req = lib.request(target, { method, headers: outHeaders }, (res) => {
+      /** @type {Buffer[]} */
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => {
+        const status = res.statusCode ?? 0;
+        resolve({
+          status,
+          headers: res.headers,
+          body: Buffer.concat(chunks).toString('utf8'),
+          success: Math.trunc(status / 100) === 2,
+        });
+      });
+    });
+
+    req.on('error', reject);
+    if (timeout !== undefined) {
+      req.setTimeout(timeout, () => req.destroy(new Error(`request timed out after ${timeout}ms`)));
+    }
+    if (body !== undefined && body !== null) {
+      req.write(body);
+    }
+    req.end();
+  });
+}

package/src/index.js

@@ -0,0 +1,17 @@
+/**
+ * Node.js port of the Perl `AWS::Lambda` distribution: a client for the AWS
+ * Lambda custom-runtime (the OS-only `provided.*` runtime family).
+ *
+ * @example
+ * // handler.js, deployed with a `bootstrap` entry point
+ * export function handle(payload, context) {
+ *   return { ok: true, requestId: context.awsRequestId };
+ * }
+ *
+ * @module aws-lambda
+ */
+
+export { Bootstrap, bootstrap } from './bootstrap.js';
+export { Context } from './context.js';
+export { ResponseWriter } from './response-writer.js';
+export { getCurrentContext } from './current-context.js';

package/src/response-writer.js

@@ -0,0 +1,154 @@
+/**
+ * Node.js port of `AWS::Lambda::ResponseWriter`.
+ *
+ * Writes a Lambda response-streaming body to the Runtime API using HTTP/1.1
+ * chunked transfer encoding. The Perl version hand-frames chunks and trailers
+ * on top of `HTTP::Tiny` internals; Node's `http.ClientRequest` performs chunk
+ * framing and trailer emission natively, so this implementation delegates to
+ * it.
+ *
+ * @module response-writer
+ */
+
+import http from 'node:http';
+import https from 'node:https';
+
+import { errorMessage, errorType } from './errors.js';
+
+/**
+ * @typedef {object} ResponseWriterArgs
+ * @property {string} responseUrl The Runtime API invocation-response URL.
+ *   Required.
+ * @property {string} [contentType] Default content type. Defaults to
+ *   `application/json`.
+ */
+
+/**
+ * @typedef {object} StreamingResult
+ * @property {number} status The HTTP status code returned by the Runtime API.
+ * @property {import('node:http').IncomingHttpHeaders} headers Response headers.
+ * @property {string} body The response body decoded as UTF-8.
+ * @property {boolean} success Whether the status is a 2xx.
+ */
+
+export class ResponseWriter {
+  /**
+   * @param {ResponseWriterArgs} args
+   */
+  constructor(args) {
+    if (!args || !args.responseUrl) {
+      throw new Error('response_url is required');
+    }
+
+    /** @type {string} */
+    this.responseUrl = args.responseUrl;
+    /** @type {string} */
+    this.contentType = args.contentType ?? 'application/json';
+    /** @type {import('node:http').ClientRequest | undefined} */
+    this.request = undefined;
+    /** @type {boolean} */
+    this.closed = false;
+    /** @type {Promise<import('node:http').IncomingMessage> | undefined} */
+    this._responsePromise = undefined;
+  }
+
+  /**
+   * Open the chunked POST request to the Runtime API and send the request
+   * headers. Internal: called by `Bootstrap.lambdaResponseStreaming`.
+   *
+   * @param {string} [contentType]
+   * @returns {void}
+   */
+  _request(contentType = this.contentType) {
+    const target = new URL(this.responseUrl);
+    const lib = target.protocol === 'https:' ? https : http;
+    const req = lib.request(target, {
+      method: 'POST',
+      headers: {
+        'content-type': contentType,
+        'transfer-encoding': 'chunked',
+        trailer: 'Lambda-Runtime-Function-Error-Type, Lambda-Runtime-Function-Error-Body',
+        'lambda-runtime-function-response-mode': 'streaming',
+      },
+    });
+
+    this.request = req;
+    this._responsePromise = new Promise((resolve, reject) => {
+      req.on('response', resolve);
+      req.on('error', reject);
+    });
+  }
+
+  /**
+   * Write a chunk of the response body. Empty data is a no-op.
+   *
+   * @param {string|Buffer} data
+   * @returns {boolean} `true` once the chunk has been queued.
+   */
+  write(data) {
+    if (this.closed) {
+      throw new Error('write failed: already closed');
+    }
+    if (data === undefined || data === null || data.length === 0) {
+      return true;
+    }
+    this.request?.write(data);
+    return true;
+  }
+
+  /**
+   * Finish the response by writing the terminating chunk. Idempotent.
+   *
+   * @returns {void}
+   */
+  close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.request?.end();
+  }
+
+  /**
+   * Abort the stream by attaching error trailers, then finish the request.
+   * Used when the handler throws after streaming has started. Idempotent.
+   *
+   * @param {unknown} error
+   * @returns {void}
+   */
+  _closeWithError(error) {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.request?.addTrailers({
+      'Lambda-Runtime-Function-Error-Type': errorType(error),
+      'Lambda-Runtime-Function-Error-Body': Buffer.from(errorMessage(error), 'utf8').toString('base64'),
+    });
+    this.request?.end();
+  }
+
+  /**
+   * Close the request if needed and read the Runtime API's response.
+   *
+   * @returns {Promise<StreamingResult>}
+   */
+  async _handleResponse() {
+    if (!this.closed) {
+      this.close();
+    }
+    const res = await /** @type {Promise<import('node:http').IncomingMessage>} */ (this._responsePromise);
+    /** @type {Buffer[]} */
+    const chunks = [];
+    for await (const chunk of res) {
+      chunks.push(chunk);
+    }
+    const status = res.statusCode ?? 0;
+    return {
+      status,
+      headers: res.headers,
+      body: Buffer.concat(chunks).toString('utf8'),
+      success: Math.trunc(status / 100) === 2,
+    };
+  }
+}