@hyperdrive.bot/cli 1.0.12 → 1.0.16

package/dist/lib/lambda-warmer.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Lambda Warmer
+ *
+ * Pre-warms Lambdas after a stage deploy by invoking each function once.
+ * Mitigates the cold-start cliff users hit on the first request after deploy.
+ *
+ * AC contract (API-120):
+ *  - AC2: After all module Lambdas are launched, invoke each one once with a
+ *    synthetic warmup payload (e.g., `{"warmup": true}`).
+ *  - AC3: Lambda handlers do NOT need to recognize the warmup payload — a
+ *    vanilla invoke that returns any response counts as warmed.
+ *  - AC4: Concurrency-aware: never fire all warmups at once. Default cap = 10.
+ *  - AC5: Failures are reported but never fatal — warming is best-effort.
+ *
+ * Discovery
+ * ---------
+ * Lambdas are discovered via `ListFunctionsCommand` on each region, filtered
+ * by names that contain the stage slug as a hyphen-bounded segment
+ * (e.g. `api-foo-ss-12-handler` matches stage `ss-12`). This matches the
+ * naming convention used by `serverless-plugin-composer`-built modules
+ * across the workspace.
+ *
+ * Credentials
+ * -----------
+ * Uses the standard AWS SDK default credential provider chain. The user is
+ * expected to have credentials configured for the target account (via
+ * `AWS_PROFILE`, environment variables, or instance role) — the same way
+ * they would for any other CLI tool that hits AWS directly.
+ *
+ * If credentials are missing or the principal lacks `lambda:ListFunctions`
+ * / `lambda:InvokeFunction` on the discovered functions, warming is skipped
+ * with a warning. The stage-create flow is NEVER blocked.
+ */
+import { type LambdaClient } from '@aws-sdk/client-lambda';
+/** Default in-flight invocation cap (AC4) */
+export declare const DEFAULT_WARMUP_CONCURRENCY = 10;
+/** Default per-invocation timeout. Lambda invocations should warm in <30s. */
+export declare const DEFAULT_WARMUP_TIMEOUT_MS = 30000;
+/**
+ * Result of warming a single Lambda function.
+ */
+export interface WarmupResult {
+    durationMs: number;
+    error?: string;
+    functionName: string;
+    region: string;
+    /** HTTP status returned by the Invoke API (200 = OK, 4xx/5xx = error) */
+    statusCode?: number;
+    success: boolean;
+}
+/**
+ * Aggregate summary returned by `warmStage()`.
+ */
+export interface WarmupSummary {
+    failed: number;
+    /** Per-function results, in completion order. */
+    results: WarmupResult[];
+    skipped: number;
+    succeeded: number;
+    total: number;
+}
+/**
+ * Factory for `LambdaClient` instances. Injectable for tests.
+ */
+export type LambdaClientFactory = (region: string) => LambdaClient;
+/**
+ * Options for `warmStage()`.
+ */
+export interface WarmStageOptions {
+    /** Override the default in-flight cap (AC4). */
+    concurrency?: number;
+    /** Inject a custom Lambda client factory (used in tests). */
+    lambdaClientFactory?: LambdaClientFactory;
+    /** Optional logger (defaults to silent). */
+    logger?: (message: string) => void;
+    /** AWS regions to scan for Lambdas owned by this stage. */
+    regions: string[];
+    /** Stage slug (e.g. `ss-12`) — used to filter discovered functions. */
+    stageName: string;
+    /** Per-invocation timeout in ms. */
+    timeoutMs?: number;
+}
+/**
+ * Returns true when `functionName` belongs to `stageName`.
+ *
+ * Stage slugs appear as a hyphen-delimited segment in the deployed function
+ * name (e.g. `api-grants-ss-12-handler` belongs to `ss-12`). We require the
+ * slug to be hyphen-bounded so `ss-1` does NOT match `ss-12`.
+ */
+export declare function functionBelongsToStage(functionName: string, stageName: string): boolean;
+/**
+ * Lists all Lambda function names in `region` that belong to `stageName`.
+ * Paginates through `ListFunctionsCommand`.
+ */
+export declare function discoverStageFunctions(client: LambdaClient, stageName: string): Promise<string[]>;
+/**
+ * Invoke a single Lambda once with the warmup payload.
+ * Never throws — failures are encoded in the returned `WarmupResult`.
+ */
+export declare function warmFunction(client: LambdaClient, region: string, functionName: string, timeoutMs: number): Promise<WarmupResult>;
+/**
+ * Discover and warm every Lambda owned by `stageName` across `regions`.
+ *
+ * Best-effort — never throws. Returns a summary the caller can render.
+ */
+export declare function warmStage(opts: WarmStageOptions): Promise<WarmupSummary>;

package/dist/lib/lambda-warmer.js

@@ -0,0 +1,189 @@
+/**
+ * Lambda Warmer
+ *
+ * Pre-warms Lambdas after a stage deploy by invoking each function once.
+ * Mitigates the cold-start cliff users hit on the first request after deploy.
+ *
+ * AC contract (API-120):
+ *  - AC2: After all module Lambdas are launched, invoke each one once with a
+ *    synthetic warmup payload (e.g., `{"warmup": true}`).
+ *  - AC3: Lambda handlers do NOT need to recognize the warmup payload — a
+ *    vanilla invoke that returns any response counts as warmed.
+ *  - AC4: Concurrency-aware: never fire all warmups at once. Default cap = 10.
+ *  - AC5: Failures are reported but never fatal — warming is best-effort.
+ *
+ * Discovery
+ * ---------
+ * Lambdas are discovered via `ListFunctionsCommand` on each region, filtered
+ * by names that contain the stage slug as a hyphen-bounded segment
+ * (e.g. `api-foo-ss-12-handler` matches stage `ss-12`). This matches the
+ * naming convention used by `serverless-plugin-composer`-built modules
+ * across the workspace.
+ *
+ * Credentials
+ * -----------
+ * Uses the standard AWS SDK default credential provider chain. The user is
+ * expected to have credentials configured for the target account (via
+ * `AWS_PROFILE`, environment variables, or instance role) — the same way
+ * they would for any other CLI tool that hits AWS directly.
+ *
+ * If credentials are missing or the principal lacks `lambda:ListFunctions`
+ * / `lambda:InvokeFunction` on the discovered functions, warming is skipped
+ * with a warning. The stage-create flow is NEVER blocked.
+ */
+import { InvokeCommand, LambdaClient as DefaultLambdaClient, ListFunctionsCommand, } from '@aws-sdk/client-lambda';
+/** Default in-flight invocation cap (AC4) */
+export const DEFAULT_WARMUP_CONCURRENCY = 10;
+/** Default per-invocation timeout. Lambda invocations should warm in <30s. */
+export const DEFAULT_WARMUP_TIMEOUT_MS = 30_000;
+/** Default factory uses the SDK default credential provider chain. */
+const defaultFactory = (region) => new DefaultLambdaClient({ region });
+/**
+ * Returns true when `functionName` belongs to `stageName`.
+ *
+ * Stage slugs appear as a hyphen-delimited segment in the deployed function
+ * name (e.g. `api-grants-ss-12-handler` belongs to `ss-12`). We require the
+ * slug to be hyphen-bounded so `ss-1` does NOT match `ss-12`.
+ */
+export function functionBelongsToStage(functionName, stageName) {
+    if (!functionName || !stageName)
+        return false;
+    // Anchor on hyphen boundaries so `ss-1` does not collide with `ss-12`.
+    // Matches: `...-<stageName>-...` or `...-<stageName>` (suffix).
+    const escaped = stageName.replaceAll(/[$()*+.?[\\\]^{|}]/g, '\\$&');
+    const re = new RegExp(`(^|-)${escaped}(-|$)`);
+    return re.test(functionName);
+}
+/**
+ * Lists all Lambda function names in `region` that belong to `stageName`.
+ * Paginates through `ListFunctionsCommand`.
+ */
+export async function discoverStageFunctions(client, stageName) {
+    const names = [];
+    let marker;
+    do {
+        const out = await client.send(new ListFunctionsCommand({ Marker: marker, MaxItems: 50 }));
+        for (const fn of out.Functions ?? []) {
+            const name = fn.FunctionName;
+            if (name && functionBelongsToStage(name, stageName)) {
+                names.push(name);
+            }
+        }
+        marker = out.NextMarker;
+    } while (marker);
+    return names;
+}
+/**
+ * Concurrency-bounded `Promise.all` — runs at most `limit` workers in parallel.
+ * Avoids pulling in a `p-limit` dependency for one use site.
+ */
+async function runWithConcurrency(items, limit, worker) {
+    const results = Array.from({ length: items.length });
+    let nextIndex = 0;
+    const lanes = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (true) {
+            const i = nextIndex++;
+            if (i >= items.length)
+                return;
+            results[i] = await worker(items[i]);
+        }
+    });
+    await Promise.all(lanes);
+    return results;
+}
+/**
+ * Invoke a single Lambda once with the warmup payload.
+ * Never throws — failures are encoded in the returned `WarmupResult`.
+ */
+export async function warmFunction(client, region, functionName, timeoutMs) {
+    const startedAt = Date.now();
+    try {
+        const cmd = new InvokeCommand({
+            FunctionName: functionName,
+            InvocationType: 'RequestResponse',
+            Payload: new TextEncoder().encode(JSON.stringify({ warmup: true })),
+        });
+        const out = await client.send(cmd, {
+            // The AWS SDK respects AbortSignal for command-level timeouts.
+            abortSignal: AbortSignal.timeout(timeoutMs),
+        });
+        const durationMs = Date.now() - startedAt;
+        // AC3: any response counts as warmed. The Lambda may have returned a
+        // FunctionError (`Unhandled` / `Handled`) — that's fine, the runtime is
+        // now hot. We only flag transport-level failures as `success: false`.
+        return {
+            durationMs,
+            functionName,
+            region,
+            statusCode: out.StatusCode,
+            success: true,
+        };
+    }
+    catch (error) {
+        return {
+            durationMs: Date.now() - startedAt,
+            error: error.message ?? String(error),
+            functionName,
+            region,
+            success: false,
+        };
+    }
+}
+/**
+ * Discover and warm every Lambda owned by `stageName` across `regions`.
+ *
+ * Best-effort — never throws. Returns a summary the caller can render.
+ */
+export async function warmStage(opts) {
+    const concurrency = Math.max(1, opts.concurrency ?? DEFAULT_WARMUP_CONCURRENCY);
+    const timeoutMs = Math.max(1000, opts.timeoutMs ?? DEFAULT_WARMUP_TIMEOUT_MS);
+    const log = opts.logger ?? (() => { });
+    const factory = opts.lambdaClientFactory ?? defaultFactory;
+    const summary = {
+        failed: 0,
+        results: [],
+        skipped: 0,
+        succeeded: 0,
+        total: 0,
+    };
+    // Discover functions per region in parallel (cheap network calls).
+    const discoveries = await Promise.all(opts.regions.map(async (region) => {
+        const client = factory(region);
+        try {
+            const names = await discoverStageFunctions(client, opts.stageName);
+            return { client, names, region };
+        }
+        catch (error) {
+            log(`⚠️  Warm-up discovery failed in ${region}: ${error.message ?? String(error)}`);
+            // AC5: never fatal. Surface as `skipped`.
+            return { client, error: error, names: [], region };
+        }
+    }));
+    const tasks = [];
+    for (const d of discoveries) {
+        if ('error' in d && d.error) {
+            summary.skipped += 1;
+            continue;
+        }
+        for (const name of d.names) {
+            tasks.push({ client: d.client, functionName: name, region: d.region });
+        }
+    }
+    summary.total = tasks.length;
+    if (tasks.length === 0) {
+        log(`ℹ️  No Lambdas matched stage '${opts.stageName}' in any of: ${opts.regions.join(', ')}`);
+        return summary;
+    }
+    log(`🔥 Warming ${tasks.length} Lambda(s) (concurrency=${concurrency})...`);
+    const results = await runWithConcurrency(tasks, concurrency, async (task) => warmFunction(task.client, task.region, task.functionName, timeoutMs));
+    for (const r of results) {
+        summary.results.push(r);
+        if (r.success) {
+            summary.succeeded += 1;
+        }
+        else {
+            summary.failed += 1;
+        }
+    }
+    return summary;
+}