Lambda Worker contrib package (#1995)

Author: Sushisource

.gitignore

@@ -11,6 +11,7 @@ packages/core-bridge/releases
 packages/*/package-lock.json
 /sdk-node.iml
 *~
+.claude/settings.local.json
 
 # One test creates persisted SQLite DBs; they should normally be deleted automatically,
 # but may be left behind in some error scenarios.

packages/core-bridge/src/worker.rs

@@ -868,7 +868,7 @@ mod custom_slot_supplier {
                     }
                     Err(err) => {
                         warn!("Error reserving slot: {err:?}");
-                        tokio::time::sleep(std::time::Duration::from_millis(1000)).await;
+                        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
                     }
                 }
             }

packages/envconfig/src/index.ts

@@ -11,6 +11,7 @@ export {
   ClientConfig,
   ClientConfigProfile,
   ClientConfigTLS,
+  ClientConnectConfig,
   LoadClientConfigOptions,
   LoadClientProfileOptions,
   ClientConfigFromTomlOptions,

packages/lambda-worker/README.md

@@ -0,0 +1,158 @@
+# lambda-worker
+
+A wrapper for running [Temporal](https://temporal.io) workers inside AWS Lambda. A single
+`runWorker` call handles the full per-invocation lifecycle: connecting to the Temporal server,
+creating a worker with Lambda-tuned defaults, polling for tasks, and gracefully shutting down before
+the invocation deadline.
+
+## Quick start
+
+```typescript
+// handler.ts
+import { runWorker } from '@temporalio/lambda-worker';
+import * as activities from './activities';
+
+export const handler = runWorker({ deploymentName: 'my-service', buildId: 'v1.0' }, (config) => {
+  config.workerOptions.taskQueue = 'my-task-queue';
+  config.workerOptions.workflowBundle = { code: require('./workflow-bundle.js') };
+  config.workerOptions.activities = activities;
+});
+```
+
+Prefer `workflowBundle` (pre-bundled with `bundleWorkflowCode`) over `workflowsPath` to avoid
+webpack bundling overhead on Lambda cold starts.
+
+## Configuration
+
+Client connection settings (address, namespace, TLS, API key) are loaded automatically from a TOML
+config file and/or environment variables via `@temporalio/envconfig`. The config file is resolved in
+order:
+
+1. `TEMPORAL_CONFIG_FILE` env var, if set.
+2. `temporal.toml` in `$LAMBDA_TASK_ROOT` (typically `/var/task`).
+3. `temporal.toml` in the current working directory.
+
+The file is optional -- if absent, only environment variables are used.
+
+The configure callback receives a `LambdaWorkerConfig` object with fields pre-populated with
+Lambda-appropriate defaults. Override any field directly in the callback. The `taskQueue` in
+`workerOptions` is pre-populated from the `TEMPORAL_TASK_QUEUE` environment variable if set.
+
+## Lambda-tuned worker defaults
+
+The package applies conservative concurrency limits suited to Lambda's resource constraints:
+
+| Setting                                | Default            |
+| -------------------------------------- | ------------------ |
+| `maxConcurrentActivityTaskExecutions`  | 2                  |
+| `maxConcurrentWorkflowTaskExecutions`  | 10                 |
+| `maxConcurrentLocalActivityExecutions` | 2                  |
+| `maxConcurrentNexusTaskExecutions`     | 5                  |
+| `workflowTaskPollerBehavior`           | `SimpleMaximum(2)` |
+| `activityTaskPollerBehavior`           | `SimpleMaximum(1)` |
+| `nexusTaskPollerBehavior`              | `SimpleMaximum(1)` |
+| `shutdownGraceTime`                    | 5 seconds          |
+| `maxCachedWorkflows`                   | 30                 |
+
+Worker Deployment Versioning is always enabled. The default versioning behavior is `PINNED`; to
+change it, override `workerDeploymentOptions.defaultVersioningBehavior` in the configure callback:
+
+```typescript
+config.workerOptions.workerDeploymentOptions = {
+  defaultVersioningBehavior: 'AUTO_UPGRADE',
+};
+```
+
+## Logging
+
+The Temporal `Runtime` is installed automatically by `runWorker`. If
+[`@aws-lambda-powertools/logger`](https://docs.aws.amazon.com/powertools/typescript/latest/features/logger/)
+is installed, the runtime is configured with a `PowertoolsLoggerAdapter` that produces structured
+JSON output automatically parsed by CloudWatch Logs. If Powertools is not installed, the SDK's
+default human-readable logger is used.
+
+To customize the logger or other runtime options, modify `config.runtimeOptions` in the configure
+callback:
+
+```typescript
+export const handler = runWorker({ deploymentName: 'my-service', buildId: 'v1.0' }, (config) => {
+  config.workerOptions.taskQueue = 'my-task-queue';
+  // Use a custom logger
+  config.runtimeOptions.logger = myCustomLogger;
+  // Or configure telemetry
+  config.runtimeOptions.telemetryOptions = { ... };
+});
+```
+
+Shutdown signals are disabled by default (`shutdownSignals: []`) since Lambda manages its own
+lifecycle.
+
+## Observability
+
+Metrics and tracing are opt-in. The `otel` module provides convenience helpers for
+[AWS Distro for OpenTelemetry (ADOT)](https://aws-otel.github.io/docs/getting-started/lambda).
+
+Call `applyDefaults(config)` in your configure callback to:
+
+- Register Temporal SDK interceptors (`@temporalio/interceptors-opentelemetry`) for tracing
+  Workflow, Activity, and Nexus calls.
+- Configure the Temporal Core SDK (Rust) to export its own metrics (task latencies, poll counts,
+  etc.) via OTLP to the collector.
+
+```typescript
+import { runWorker } from '@temporalio/lambda-worker';
+import { applyDefaults } from '@temporalio/lambda-worker/otel';
+import * as activities from './activities';
+
+export const handler = runWorker({ deploymentName: 'my-service', buildId: 'v1.0' }, (config) => {
+  applyDefaults(config);
+  config.workerOptions.taskQueue = 'my-task-queue';
+  config.workerOptions.workflowBundle = { code: require('./workflow-bundle.js') };
+  config.workerOptions.activities = activities;
+});
+```
+
+**Important**: When pre-bundling Workflow code with `bundleWorkflowCode()`, pass `makeOtelPlugin()`
+so that Workflow interceptor modules are included in the bundle:
+
+```typescript
+import { bundleWorkflowCode } from '@temporalio/worker';
+import { makeOtelPlugin } from '@temporalio/lambda-worker/otel';
+
+const { plugin } = makeOtelPlugin();
+const { code } = await bundleWorkflowCode({
+  workflowsPath: require.resolve('./workflows'),
+  plugins: [plugin],
+});
+```
+
+### AWS setup
+
+Attach two Lambda layers:
+
+1. **[ADOT JavaScript layer](https://aws-otel.github.io/docs/getting-started/lambda/lambda-js)** —
+   auto-instruments the handler and exports Node.js-side traces (Lambda invocation spans, HTTP
+   calls, etc.) to X-Ray.
+2. **[ADOT Collector layer](https://aws-otel.github.io/docs/getting-started/lambda)**
+   (`aws-otel-collector-amd64`) — runs the OTel Collector as a Lambda extension, receiving
+   Temporal Core SDK metrics and SDK trace spans via OTLP gRPC on `localhost:4317`, then
+   forwarding them to CloudWatch/X-Ray via a custom collector config.
+
+Set these environment variables:
+
+```
+AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument
+OPENTELEMETRY_COLLECTOR_CONFIG_URI=/var/task/otel-collector-config.yaml
+```
+
+`AWS_LAMBDA_EXEC_WRAPPER` enables the JS layer's auto-instrumentation.
+`OPENTELEMETRY_COLLECTOR_CONFIG_URI` points the collector at a custom config file bundled in
+your deployment package — use this to route metrics to CloudWatch EMF, traces to X-Ray, or any
+other supported exporter.
+
+Enable X-Ray active tracing on the Lambda function (required for traces to appear):
+
+```bash
+aws lambda update-function-configuration --function-name <function-name> \
+  --tracing-config Mode=Active
+```

packages/lambda-worker/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@temporalio/lambda-worker",
+  "version": "1.15.0",
+  "description": "Temporal.io SDK AWS Lambda Worker",
+  "main": "lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./otel": {
+      "types": "./lib/otel.d.ts",
+      "default": "./lib/otel.js"
+    },
+    "./lib/*": {
+      "types": "./lib/*.d.ts",
+      "default": "./lib/*.js"
+    }
+  },
+  "scripts": {},
+  "keywords": [
+    "temporal",
+    "aws",
+    "lambda",
+    "worker"
+  ],
+  "author": "Temporal Technologies Inc. <sdk@temporal.io>",
+  "license": "MIT",
+  "dependencies": {
+    "@temporalio/common": "workspace:*",
+    "@temporalio/envconfig": "workspace:*",
+    "@temporalio/worker": "workspace:*"
+  },
+  "devDependencies": {
+    "@aws-lambda-powertools/logger": "^2.0.0",
+    "@types/aws-lambda": "^8.10.145"
+  },
+  "peerDependencies": {
+    "@aws-lambda-powertools/logger": "^2.0.0",
+    "@temporalio/interceptors-opentelemetry": "workspace:*",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.52.0",
+    "@opentelemetry/resources": "^1.25.1",
+    "@opentelemetry/sdk-trace-base": "^1.25.1",
+    "@types/aws-lambda": "^8.10.145"
+  },
+  "peerDependenciesMeta": {
+    "@aws-lambda-powertools/logger": {
+      "optional": true
+    },
+    "@temporalio/interceptors-opentelemetry": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-grpc": {
+      "optional": true
+    },
+    "@opentelemetry/resources": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    },
+    "@types/aws-lambda": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">= 20.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/temporalio/sdk-typescript/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/temporalio/sdk-typescript.git",
+    "directory": "packages/lambda-worker"
+  },
+  "homepage": "https://github.com/temporalio/sdk-typescript/tree/main/packages/lambda-worker",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "lib"
+  ]
+}

packages/lambda-worker/src/config.ts

@@ -0,0 +1,53 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  type ClientConnectConfig,
+  type LoadClientProfileOptions,
+  loadClientConnectConfig,
+} from '@temporalio/envconfig';
+
+/**
+ * Load client connection config with Lambda-aware config file resolution.
+ *
+ * Resolution order:
+ * 1. User-provided `configSource` in options (passthrough)
+ * 2. `TEMPORAL_CONFIG_FILE` env var (handled by envconfig)
+ * 3. `$LAMBDA_TASK_ROOT/temporal.toml`
+ * 4. `process.cwd()/temporal.toml`
+ * 5. Envconfig default (XDG paths / env-only)
+ */
+export function loadLambdaClientConnectConfig(options?: Partial<LoadClientProfileOptions>): ClientConnectConfig {
+  const resolvedOptions: LoadClientProfileOptions = { ...options };
+
+  // If the user provided a configSource or TEMPORAL_CONFIG_FILE is set, let envconfig handle it
+  if (!resolvedOptions.configSource && !process.env['TEMPORAL_CONFIG_FILE']) {
+    const lambdaConfigPath = findLambdaConfigFile();
+    if (lambdaConfigPath) {
+      resolvedOptions.configSource = { path: lambdaConfigPath };
+    }
+  }
+
+  return loadClientConnectConfig(resolvedOptions);
+}
+
+function findLambdaConfigFile(): string | undefined {
+  const candidates: string[] = [];
+
+  const lambdaTaskRoot = process.env['LAMBDA_TASK_ROOT'];
+  if (lambdaTaskRoot) {
+    candidates.push(path.join(lambdaTaskRoot, 'temporal.toml'));
+  }
+
+  candidates.push(path.join(process.cwd(), 'temporal.toml'));
+
+  for (const candidate of candidates) {
+    try {
+      fs.accessSync(candidate, fs.constants.R_OK);
+      return candidate;
+    } catch {
+      // File doesn't exist or isn't readable, try next
+    }
+  }
+
+  return undefined;
+}

packages/lambda-worker/src/defaults.ts

@@ -0,0 +1,30 @@
+import type { WorkerOptions } from '@temporalio/worker';
+
+/** Minimum work time in ms — error if less. */
+export const MINIMUM_WORK_TIME_MS = 1000;
+
+/** Low work time threshold in ms — warn if less. */
+export const WARN_WORK_TIME_MS = 5000;
+
+/**
+ * Default buffer in ms before the Lambda deadline to begin shutdown.
+ * Equals the default shutdownGraceTime (5s) + 2s margin.
+ */
+export const DEFAULT_SHUTDOWN_DEADLINE_BUFFER_MS = 7000;
+
+/**
+ * Lambda-tuned worker defaults. These are conservative values appropriate for
+ * Lambda's memory and CPU constraints. Users can override any of these via the
+ * configure callback.
+ */
+export const LAMBDA_WORKER_DEFAULTS: Partial<WorkerOptions> = {
+  maxConcurrentActivityTaskExecutions: 2,
+  maxConcurrentWorkflowTaskExecutions: 10,
+  maxConcurrentLocalActivityExecutions: 2,
+  maxConcurrentNexusTaskExecutions: 5,
+  shutdownGraceTime: '5s',
+  maxCachedWorkflows: 30,
+  workflowTaskPollerBehavior: { type: 'simple-maximum', maximum: 2 },
+  activityTaskPollerBehavior: { type: 'simple-maximum', maximum: 1 },
+  nexusTaskPollerBehavior: { type: 'simple-maximum', maximum: 1 },
+};

packages/lambda-worker/src/index.ts

@@ -0,0 +1,3 @@
+export { runWorker } from './lambda-worker';
+export { PowertoolsLoggerAdapter } from './json-logger';
+export type { LambdaWorkerConfig, LambdaHandler, ShutdownHook } from './types';