@temporalio/lambda-worker 1.17.0

package/src/lambda-worker.ts

@@ -0,0 +1,190 @@
+import { setTimeout } from 'timers/promises';
+import type { Context } from 'aws-lambda';
+import type { WorkerDeploymentVersion, Logger } from '@temporalio/common';
+import {
+  type WorkerOptions,
+  type NativeConnectionOptions,
+  type RuntimeOptions,
+  NativeConnection,
+  Worker,
+  Runtime,
+} from '@temporalio/worker';
+import type { ClientConnectConfig } from '@temporalio/envconfig';
+import {
+  LAMBDA_WORKER_DEFAULTS,
+  DEFAULT_SHUTDOWN_DEADLINE_BUFFER_MS,
+  MINIMUM_WORK_TIME_MS,
+  WARN_WORK_TIME_MS,
+} from './defaults';
+import { loadLambdaClientConnectConfig } from './config';
+import { PowertoolsLoggerAdapter } from './json-logger';
+import { makePowertoolsLogger } from './logger-factory';
+import type { LambdaWorkerConfig, LambdaHandler } from './types';
+
+/**
+ * @internal Dependency injection interface for testing.
+ */
+export interface WorkerDeps {
+  connect: (options: NativeConnectionOptions) => Promise<{ close(): Promise<void> }>;
+  createWorker: (options: WorkerOptions) => Promise<{ runUntil(p: Promise<void>): Promise<void> }>;
+  loadConnectConfig: () => ClientConnectConfig;
+  installRuntime: (options: RuntimeOptions) => void;
+  getLogger: () => Logger;
+}
+
+const defaultDeps: WorkerDeps = {
+  connect: (opts) => NativeConnection.connect(opts),
+  createWorker: (opts) => Worker.create(opts),
+  loadConnectConfig: loadLambdaClientConnectConfig,
+  installRuntime: (opts) => Runtime.install(opts),
+  getLogger: () => Runtime.instance().logger,
+};
+
+/**
+ * Create an AWS Lambda handler that runs a Temporal Worker for the duration of each invocation.
+ *
+ * The handler connects to Temporal, creates a Worker, polls for tasks until the Lambda deadline
+ * approaches, then gracefully shuts down and runs any registered shutdown hooks.
+ *
+ * Calling this more than once will result in an error.
+ *
+ * @param version - The worker deployment version. Worker versioning is always enabled.
+ * @param configure - Callback to customize the pre-populated {@link LambdaWorkerConfig}.
+ *   Mutate the config object directly (e.g., set `config.workerOptions.taskQueue`).
+ * @returns A Lambda handler function.
+ *
+ * @example
+ * ```ts
+ * import { runWorker } from '@temporalio/lambda-worker';
+ * import * as activities from './activities';
+ *
+ * export const handler = runWorker(
+ *   { buildId: 'v1.0.0', deploymentName: 'my-service' },
+ *   (config) => {
+ *     config.workerOptions.taskQueue = 'my-task-queue';
+ *     config.workerOptions.workflowBundle = { code: require('./workflow-bundle.js') };
+ *     config.workerOptions.activities = activities;
+ *   },
+ * );
+ * ```
+ */
+export function runWorker(
+  version: WorkerDeploymentVersion,
+  configure: (config: LambdaWorkerConfig) => void
+): LambdaHandler {
+  return _runWorkerInternal(version, configure, defaultDeps);
+}
+
+/**
+ * @internal Testable implementation of runWorker with injected dependencies.
+ */
+export function _runWorkerInternal(
+  version: WorkerDeploymentVersion,
+  configure: (config: LambdaWorkerConfig) => void,
+  deps: WorkerDeps
+): LambdaHandler {
+  const config: LambdaWorkerConfig = {
+    workerOptions: {
+      ...LAMBDA_WORKER_DEFAULTS,
+      workerDeploymentOptions: {
+        defaultVersioningBehavior: 'PINNED',
+      },
+    },
+    runtimeOptions: {
+      logger: makePowertoolsLogger(),
+      shutdownSignals: [],
+    },
+    shutdownHooks: [],
+  };
+
+  const envTaskQueue = process.env['TEMPORAL_TASK_QUEUE'];
+  if (envTaskQueue) {
+    config.workerOptions.taskQueue = envTaskQueue;
+  }
+
+  const connectConfig = deps.loadConnectConfig();
+  config.connectionOptions = { ...connectConfig.connectionOptions };
+  config.namespace = connectConfig.namespace || 'default';
+
+  configure(config);
+
+  const taskQueue = config.workerOptions.taskQueue;
+  if (!taskQueue) {
+    throw new Error(
+      'taskQueue is required: set config.workerOptions.taskQueue in the configure callback ' +
+        'or set the TEMPORAL_TASK_QUEUE environment variable'
+    );
+  }
+
+  // Install the Runtime with the (possibly user-modified) options
+  deps.installRuntime(config.runtimeOptions);
+
+  const shutdownDeadlineBufferMs = config.shutdownDeadlineBufferMs ?? DEFAULT_SHUTDOWN_DEADLINE_BUFFER_MS;
+
+  const runtimeLogger = config.runtimeOptions.logger;
+
+  return async (_event: unknown, context: Context): Promise<void> => {
+    if (runtimeLogger instanceof PowertoolsLoggerAdapter) {
+      runtimeLogger.addContext(context);
+    }
+
+    const logger = deps.getLogger();
+    const remainingMs = context.getRemainingTimeInMillis();
+    const workTimeMs = remainingMs - shutdownDeadlineBufferMs;
+
+    if (workTimeMs <= MINIMUM_WORK_TIME_MS) {
+      throw new Error(
+        `Insufficient time for Lambda worker: ${remainingMs}ms remaining, ` +
+          `${shutdownDeadlineBufferMs}ms shutdown buffer, only ${workTimeMs}ms work time ` +
+          `(minimum: ${MINIMUM_WORK_TIME_MS}ms)`
+      );
+    }
+    if (workTimeMs < WARN_WORK_TIME_MS) {
+      logger.warn('Low work time available for Lambda worker', {
+        remainingMs,
+        shutdownDeadlineBufferMs,
+        workTimeMs,
+      });
+    }
+
+    const identity = `${context.awsRequestId}@${context.invokedFunctionArn}`;
+
+    let connection;
+    try {
+      connection = await deps.connect(config.connectionOptions ?? {});
+      const workerOptions: WorkerOptions = {
+        ...config.workerOptions,
+        taskQueue,
+        connection: connection as NativeConnection,
+        namespace: config.namespace,
+        identity,
+        workerDeploymentOptions: {
+          version,
+          useWorkerVersioning: true,
+          defaultVersioningBehavior:
+            config.workerOptions.workerDeploymentOptions?.defaultVersioningBehavior ?? 'PINNED',
+        },
+      };
+
+      const worker = await deps.createWorker(workerOptions);
+
+      await worker.runUntil(setTimeout(workTimeMs));
+    } finally {
+      for (const hook of config.shutdownHooks) {
+        try {
+          await hook();
+        } catch (err) {
+          logger.error('Lambda worker shutdown hook failed', { error: err });
+        }
+      }
+
+      try {
+        if (connection) {
+          await connection.close();
+        }
+      } catch (err) {
+        logger.error('Failed to close Temporal connection', { error: err });
+      }
+    }
+  };
+}

package/src/logger-factory.ts

@@ -0,0 +1,27 @@
+import type { Logger } from '@temporalio/worker';
+import { PowertoolsLoggerAdapter } from './json-logger';
+
+/**
+ * Create a Powertools-based logger for the Lambda worker.
+ *
+ * If `@aws-lambda-powertools/logger` is installed, returns a
+ * {@link PowertoolsLoggerAdapter} wrapping a Powertools Logger.
+ * Otherwise, returns `undefined`, causing the Runtime to fall back
+ * to its default logger.
+ */
+export function makePowertoolsLogger(): Logger | undefined {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { Logger: PtLogger } = require('@aws-lambda-powertools/logger');
+    return new PowertoolsLoggerAdapter(
+      new PtLogger({
+        serviceName: process.env['AWS_LAMBDA_FUNCTION_NAME'] ?? 'temporal-lambda-worker',
+      })
+    );
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'MODULE_NOT_FOUND') {
+      throw err;
+    }
+    return undefined;
+  }
+}

package/src/otel.ts

@@ -0,0 +1,127 @@
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
+import { Resource } from '@opentelemetry/resources';
+import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { OpenTelemetryPlugin } from '@temporalio/interceptors-opentelemetry';
+import type { LambdaWorkerConfig } from './types';
+
+/**
+ * Options for the batteries-included OTel setup.
+ */
+export interface OtelOptions {
+  /**
+   * OTLP gRPC collector endpoint for Core SDK metrics and SDK trace span export.
+   * Defaults to `OTEL_EXPORTER_OTLP_ENDPOINT` env var, then `grpc://localhost:4317`.
+   */
+  endpoint?: string;
+
+  /**
+   * OTel service name. Falls back to `OTEL_SERVICE_NAME` env var,
+   * then `AWS_LAMBDA_FUNCTION_NAME`, then `'temporal-lambda-worker'`.
+   */
+  serviceName?: string;
+}
+
+/**
+ * Configure OpenTelemetry for a Lambda worker:
+ *
+ * - Registers Temporal SDK interceptors (`@temporalio/interceptors-opentelemetry`) for
+ *   tracing Workflow, Activity, and Nexus calls via the `OpenTelemetryPlugin`.
+ * - Configures Core-side telemetry so the Temporal Rust SDK exports its own metrics
+ *   (workflow/activity task latencies, poll counts, etc.) via OTLP.
+ *
+ * Node.js-side Lambda auto-instrumentation (root spans, HTTP calls, etc.) is handled
+ * by the ADOT JS Lambda layer — this function does not set up a separate `NodeSDK` or
+ * `TracerProvider` to avoid conflicting with the layer.
+ *
+ * **Required AWS setup**: attach both 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.
+ * 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 Core SDK metrics via OTLP on `localhost:4317` and forwarding them to
+ *    CloudWatch/X-Ray.
+ *
+ * Then set these environment variables:
+ *
+ * - `AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument`
+ * - `OPENTELEMETRY_COLLECTOR_CONFIG_URI=/var/task/otel-collector-config.yaml`
+ *
+ * **Important**: When pre-bundling Workflow code with `bundleWorkflowCode()`, you must
+ * pass `makeOtelPlugin()` so Workflow interceptor modules are included in the bundle.
+ * See {@link makeOtelPlugin}.
+ *
+ * @example
+ * ```ts
+ * import { runWorker } from '@temporalio/lambda-worker';
+ * import { applyDefaults } from '@temporalio/lambda-worker/otel';
+ *
+ * export const handler = runWorker(version, (config) => {
+ *   applyDefaults(config);
+ *   config.workerOptions.taskQueue = 'my-queue';
+ *   // ...
+ * });
+ * ```
+ */
+export function applyDefaults(config: LambdaWorkerConfig, options?: OtelOptions): void {
+  const endpoint = options?.endpoint ?? process.env['OTEL_EXPORTER_OTLP_ENDPOINT'] ?? 'grpc://localhost:4317';
+
+  // Configure Core-side telemetry so the Temporal Rust SDK exports its own
+  // metrics (workflow/activity task latencies, poll counts, etc.) to the
+  // standalone ADOT collector extension running as a Lambda layer.
+  config.runtimeOptions.telemetryOptions = {
+    ...config.runtimeOptions.telemetryOptions,
+    metrics: {
+      otel: {
+        url: endpoint,
+      },
+    },
+  };
+
+  // Set up the OpenTelemetry plugin for Temporal SDK interceptors.
+  // This traces Workflow, Activity, and Nexus calls.
+  const { plugin, spanProcessor } = makeOtelPlugin(endpoint, options?.serviceName);
+  config.workerOptions.plugins = [...(config.workerOptions.plugins ?? []), plugin];
+
+  config.shutdownHooks.push(async () => {
+    await spanProcessor.forceFlush();
+  });
+}
+
+// TODO: Spans don't automatically get parented to the lambda invocation span, and it's not clear
+// how we'd make that work, but is worth doing in the future if possible.
+/**
+ * Create the OpenTelemetry plugin for use with `Worker.create()` and
+ * `bundleWorkflowCode()`. When pre-bundling workflows, pass the returned plugin
+ * to `bundleWorkflowCode({ plugins: [plugin] })` so workflow interceptor modules
+ * are included in the bundle.
+ *
+ * @example
+ * ```ts
+ * import { bundleWorkflowCode } from '@temporalio/worker';
+ * import { makeOtelPlugin } from '@temporalio/lambda-worker/otel';
+ *
+ * const { plugin } = makeOtelPlugin();
+ * const bundle = await bundleWorkflowCode({
+ *   workflowsPath: require.resolve('./workflows'),
+ *   plugins: [plugin],
+ * });
+ * ```
+ */
+export function makeOtelPlugin(
+  endpoint?: string,
+  serviceName?: string
+): { plugin: OpenTelemetryPlugin; spanProcessor: SimpleSpanProcessor } {
+  const resolvedEndpoint = endpoint ?? process.env['OTEL_EXPORTER_OTLP_ENDPOINT'] ?? 'grpc://localhost:4317';
+  const resolvedServiceName =
+    serviceName ??
+    process.env['OTEL_SERVICE_NAME'] ??
+    process.env['AWS_LAMBDA_FUNCTION_NAME'] ??
+    'temporal-lambda-worker';
+
+  const resource = new Resource({ 'service.name': resolvedServiceName });
+  const traceExporter = new OTLPTraceExporter({ url: resolvedEndpoint });
+  const spanProcessor = new SimpleSpanProcessor(traceExporter);
+
+  return { plugin: new OpenTelemetryPlugin({ resource, spanProcessor }), spanProcessor };
+}

package/src/types.ts

@@ -0,0 +1,78 @@
+import type { Context } from 'aws-lambda';
+import type { VersioningBehavior } from '@temporalio/common';
+import type { WorkerOptions, NativeConnectionOptions, RuntimeOptions } from '@temporalio/worker';
+
+/**
+ * A function called after the worker stops on each invocation.
+ * Errors are caught, logged, and do not prevent subsequent hooks from running.
+ */
+export type ShutdownHook = () => Promise<void> | void;
+
+/**
+ * Configuration object passed to the {@link runWorker} configure callback.
+ *
+ * Pre-populated with Lambda-tuned defaults. You should set `workerOptions.taskQueue`, register
+ * activities/workflows, and override any defaults as needed.
+ */
+export interface LambdaWorkerConfig {
+  /**
+   * Worker options, pre-populated with Lambda-appropriate defaults.
+   *
+   * You must set at least `taskQueue` (or set the `TEMPORAL_TASK_QUEUE` env var). Typically you'll
+   * also set `activities` and `workflowBundle` (prefer pre-bundled workflows over `workflowsPath`
+   * to avoid bundling overhead on Lambda cold starts).
+   *
+   * The following fields are managed by settings elsewhere and will be overridden per-invocation:
+   * `connection`, `namespace`, `identity`.
+   */
+  workerOptions: Partial<Omit<WorkerOptions, 'connection' | 'namespace' | 'identity' | 'workerDeploymentOptions'>> & {
+    /**
+     * `version` and `useWorkerVersioning` are managed by `runWorker` and cannot be set here.
+     *
+     * @default { defaultVersioningBehavior: 'PINNED' }
+     */
+    workerDeploymentOptions?: {
+      defaultVersioningBehavior?: VersioningBehavior;
+    };
+  };
+
+  /**
+   * Connection options overrides, merged on top of values loaded via envconfig.
+   */
+  connectionOptions?: Partial<NativeConnectionOptions>;
+
+  /**
+   * Namespace override. Falls back to the envconfig-loaded value, then `"default"`.
+   */
+  namespace?: string;
+
+  /**
+   * Time in milliseconds before the Lambda invocation deadline at which the worker
+   * begins its shutdown sequence (graceful drain + shutdown hooks).
+   *
+   * @default 7000 (5s graceful shutdown + 2s margin)
+   */
+  shutdownDeadlineBufferMs?: number;
+
+  /**
+   * Options for the Temporal {@link Runtime} singleton, installed automatically by `runWorker`.
+   *
+   * Pre-populated with a Powertools JSON logger (if `@aws-lambda-powertools/logger` is installed)
+   * and `shutdownSignals: []` (Lambda manages its own lifecycle).
+   *
+   * Override `runtimeOptions.logger` to use a custom logger, or modify `runtimeOptions.telemetryOptions`
+   * to configure Core-side telemetry.
+   */
+  runtimeOptions: RuntimeOptions;
+
+  /**
+   * Hooks executed in order after the worker stops on each invocation.
+   * Each hook's errors are caught and logged without preventing subsequent hooks.
+   */
+  shutdownHooks: ShutdownHook[];
+}
+
+/**
+ * The Lambda handler function returned by {@link runWorker}.
+ */
+export type LambdaHandler = (event: unknown, context: Context) => Promise<void>;