@aws-blocks/core 0.3.0 → 0.5.0

package/src/index.cdk.ts

@@ -18,18 +18,28 @@ export {
 	type ValueKind,
 } from '@aws-blocks/hosting';
 export { type ApiHandler, ApiNamespace, type BlocksContext } from './api.js';
+export type { BlocksVpcOptions, ScopeOptions, SubnetRole, VpcContext, VpcRequirements } from './cdk/index.js';
 export {
 	BlocksBackend,
 	type BlocksBackendProps,
 	type BlocksDefaults,
 	BlocksPresets,
 	BlocksStack,
+	type BlocksThrottling,
+	BuildingBlockScope,
 	blocksNodejsBundling,
 	type CoreBlocksBackendProps,
 	type CoreBlocksStackProps,
 	DEFAULT_NODE_RUNTIME,
+	ensureApiGatewayAccount,
 	finalizeConfigRegistry,
+	finalizeDashboards,
+	finalizeTracing,
+	getConfigLocation,
+	getVpcContext,
 	registerConfig,
+	registerDashboardFinalizer,
+	registerTracer,
 	SandboxDisableDeletionProtection,
 	Scope,
 	SHARED_HANDLER_TIMEOUT_SECONDS,
@@ -44,7 +54,7 @@ export {
 	registerSdkIdentifiers,
 } from './common/sdk-registry.js';
 export { BLOCKS_AUTH_PREFIX, BLOCKS_RPC_PREFIX } from './constants.js';
-export { ApiError, DEFAULT_API_ERROR_NAME, hasAuthError, isBlocksError } from './errors.js';
+export { ApiError, blocksError, DEFAULT_API_ERROR_NAME, hasAuthError, isBlocksError } from './errors.js';
 export {
 	type BlocksStackApi,
 	type ComputeConfig,

package/src/index.ts

@@ -25,7 +25,7 @@ export {
 	registerSdkIdentifiers,
 } from './common/sdk-registry.js';
 export { BLOCKS_AUTH_PREFIX, BLOCKS_RPC_PREFIX } from './constants.js';
-export { ApiError, DEFAULT_API_ERROR_NAME, hasAuthError, isBlocksError } from './errors.js';
+export { ApiError, blocksError, DEFAULT_API_ERROR_NAME, hasAuthError, isBlocksError } from './errors.js';
 export {
 	clearRouteRegistry,
 	getRegisteredRoutes,

package/src/lambda-handler.test.ts

@@ -3,10 +3,11 @@
 
 import { describe, it, beforeEach } from 'node:test';
 import assert from 'node:assert';
-import { createLambdaHandler, _resetCorsPatterns, requestCookies, isApiGatewayHttpEvent, computeHttpDeadlineMs, classifyEvent, buildEventUrl, isLoopbackForwardedHost } from './lambda-handler.js';
+import { createLambdaHandler, _resetCorsPatterns, requestCookies, isApiGatewayHttpEvent, computeHttpDeadlineMs, classifyEvent, buildEventUrl, isLoopbackForwardedHost, TransientConfigError } from './lambda-handler.js';
 import type { LambdaContext } from './lambda-handler.js';
-import { registerRoute, clearRouteRegistry } from './raw-route.js';
+import { registerRoute, clearRouteRegistry, getRegisteredRoutes } from './raw-route.js';
 import { decodeRpcResponse } from './rpc.js';
+import { _resetConfigCache, _setS3Fetcher } from './common/config.js';
 import type { BlocksContext } from './api.js';
 
 beforeEach(() => {
@@ -29,6 +30,145 @@ async function invoke(backend: any, event: any): Promise<any> {
   return handler(event) as any;
 }
 
+// ── init self-heal (retry on failed initialization) ─────────────────────────
+
+describe('createLambdaHandler — init self-heal', () => {
+  it('retries initialize() on a later request instead of caching a failed init', async () => {
+    let initCalls = 0;
+    const backend = {
+      api: (_ctx: BlocksContext) => ({
+        async echo(msg: string) {
+          return { msg };
+        },
+      }),
+    };
+    // Fail the first initialization (e.g. config not readable yet in the brief post-deploy
+    // window), then succeed. The SAME handler instance must recover — a cached rejected
+    // initPromise would poison the container and fail every subsequent request.
+    const backendFactory = async () => {
+      initCalls++;
+      if (initCalls === 1) throw new Error('transient init failure');
+      return backend;
+    };
+    const handler = createLambdaHandler(backendFactory);
+
+    // 1st request: init fails, so the handler rejects.
+    await assert.rejects(() => handler(makeEvent()) as any, /transient init failure/);
+
+    // 2nd request: init is retried and succeeds → 200 (not a re-thrown cached rejection).
+    const res = (await handler(makeEvent())) as any;
+    assert.strictEqual(res.statusCode, 200);
+    assert.strictEqual(initCalls, 2, 'initialize() must be retried on the next request, not cached');
+  });
+
+  it('recovers from a transient-empty (post-deploy 404) config load on the next request', async () => {
+    // Reproduces the poisoned-container bug: the first S3 load hits the transient
+    // post-deploy window (NoSuchKey), so config resolves empty; the handler must
+    // NOT lock in that empty config, and the NEXT request must re-fetch and pick
+    // up the now-present config.
+    _resetConfigCache();
+    process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+    process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+    delete process.env.SELFHEAL_KEY;
+
+    let fetchCall = 0;
+    const notFound = new Error('The specified key does not exist.');
+    (notFound as any).name = 'NoSuchKey';
+    _setS3Fetcher(async () => {
+      fetchCall++;
+      if (fetchCall === 1) throw notFound; // config not readable yet
+      return JSON.stringify({ SELFHEAL_KEY: 'ready' });
+    });
+
+    let backendImports = 0;
+    const handler = createLambdaHandler(async () => {
+      backendImports++;
+      return {
+        api: (_ctx: BlocksContext) => ({
+          async echo(msg: string) { return { msg, cfg: process.env.SELFHEAL_KEY }; },
+        }),
+      };
+    });
+
+    try {
+      // 1st request: transient-empty load → initialize() throws TransientConfigError
+      // BEFORE importing the backend (so we never lock in empty config), and the
+      // request rejects.
+      await assert.rejects(() => handler(makeEvent()) as any, TransientConfigError);
+      assert.strictEqual(backendImports, 0, 'backend must NOT be imported while config is unresolved');
+
+      // 2nd request: config now present → initialize() re-runs, re-fetches, and
+      // injects the config into process.env before importing the backend.
+      const res = (await handler(makeEvent())) as any;
+      assert.strictEqual(res.statusCode, 200);
+      const body = JSON.parse(res.body);
+      assert.strictEqual(body.result.cfg, 'ready', 'now-present config was injected on the retry');
+      assert.strictEqual(backendImports, 1, 'backend imported exactly once, on the successful retry');
+      assert.strictEqual(fetchCall, 2, 'S3 was re-fetched on the retry (transient miss is not cached)');
+    } finally {
+      _resetConfigCache();
+      delete process.env.BLOCKS_CONFIG_BUCKET;
+      delete process.env.BLOCKS_CONFIG_KEY;
+      delete process.env.SELFHEAL_KEY;
+    }
+  });
+
+  it('does NOT re-init for a config-less app (no bucket, local dev) — initialize runs once', async () => {
+    _resetConfigCache();
+    delete process.env.BLOCKS_CONFIG_BUCKET;
+    delete process.env.BLOCKS_CONFIG_KEY;
+
+    let backendImports = 0;
+    const handler = createLambdaHandler(async () => {
+      backendImports++;
+      return { api: (_ctx: BlocksContext) => ({ async echo(msg: string) { return { msg }; } }) };
+    });
+
+    try {
+      const r1 = (await handler(makeEvent())) as any;
+      const r2 = (await handler(makeEvent())) as any;
+      assert.strictEqual(r1.statusCode, 200);
+      assert.strictEqual(r2.statusCode, 200);
+      assert.strictEqual(backendImports, 1, 'no re-init for a genuinely config-less (local dev) app');
+    } finally {
+      _resetConfigCache();
+    }
+  });
+
+  it('does NOT re-init or spin for a genuinely-empty ({}) S3 config', async () => {
+    // A real, readable empty config must be treated as resolved — distinct from
+    // the transient 404 miss — so the container does not throw/retry forever nor
+    // re-fetch S3 on every request.
+    _resetConfigCache();
+    process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+    process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+
+    let fetchCall = 0;
+    _setS3Fetcher(async () => { fetchCall++; return JSON.stringify({}); });
+
+    let backendImports = 0;
+    const handler = createLambdaHandler(async () => {
+      backendImports++;
+      return { api: (_ctx: BlocksContext) => ({ async echo(msg: string) { return { msg }; } }) };
+    });
+
+    try {
+      const r1 = (await handler(makeEvent())) as any;
+      const r2 = (await handler(makeEvent())) as any;
+      const r3 = (await handler(makeEvent())) as any;
+      assert.strictEqual(r1.statusCode, 200);
+      assert.strictEqual(r2.statusCode, 200);
+      assert.strictEqual(r3.statusCode, 200);
+      assert.strictEqual(backendImports, 1, 'genuinely-empty config resolves; no re-init');
+      assert.strictEqual(fetchCall, 1, 'S3 fetched once and cached — no per-request re-fetch spin');
+    } finally {
+      _resetConfigCache();
+      delete process.env.BLOCKS_CONFIG_BUCKET;
+      delete process.env.BLOCKS_CONFIG_KEY;
+    }
+  });
+});
+
 // ── RPC body tests ──────────────────────────────────────────────────────────
 
 describe('createLambdaHandler — RPC body handling', () => {
@@ -274,6 +414,84 @@ describe('createLambdaHandler — RawRoute body handling', () => {
 
 // ── Cookie extraction tests ─────────────────────────────────────────────────
 
+// ── Unmatched RawRoute diagnostics ──────────────────────────────────────────
+//
+// A request that matches no RawRoute used to return 404 without a trace in
+// CloudWatch, which is what made the duplicate-core-copy bug invisible.
+
+describe('createLambdaHandler — unmatched RawRoute diagnostics', () => {
+  /** Run `fn` with console.error captured; returns the collected lines. */
+  async function captureErrors(fn: () => Promise<void>): Promise<string[]> {
+    const lines: string[] = [];
+    const original = console.error;
+    console.error = (...args: unknown[]) => {
+      lines.push(args.map((a) => String(a)).join(' '));
+    };
+    try {
+      await fn();
+    } finally {
+      console.error = original;
+    }
+    return lines;
+  }
+
+  it('logs method, path and route count when no RawRoute matches', async () => {
+    registerRoute({ method: 'GET', path: '/known', handler: async (ctx) => ctx.response.send({ ok: true }) });
+
+    let result: any;
+    const logged = await captureErrors(async () => {
+      result = await invoke({}, makeEvent({ httpMethod: 'GET', path: '/unknown', body: null }));
+    });
+
+    assert.strictEqual(result.statusCode, 404);
+    // The count must match the registry the dispatcher actually consulted —
+    // a "0 routes registered" line is the fingerprint of a split registry.
+    const expectedCount = getRegisteredRoutes().length;
+    assert.ok(expectedCount > 0, 'precondition: routes are registered');
+    assert.ok(
+      logged.some(
+        (line) =>
+          line.includes('No RawRoute matched GET /unknown') &&
+          line.includes(`${expectedCount} routes registered`),
+      ),
+      `expected a diagnostic for the unmatched route, got: ${JSON.stringify(logged)}`,
+    );
+  });
+
+  it('does not log when a RawRoute matches', async () => {
+    registerRoute({ method: 'GET', path: '/known', handler: async (ctx) => ctx.response.send({ ok: true }) });
+
+    const logged = await captureErrors(async () => {
+      const result = await invoke({}, makeEvent({ httpMethod: 'GET', path: '/known', body: null }));
+      assert.strictEqual(result.statusCode, 200);
+    });
+
+    assert.deepStrictEqual(logged, []);
+  });
+
+  it('names duplicate core copies as the likely cause when more than one is loaded', async () => {
+    const REGISTRY_KEY = '__AWS_BLOCKS_RAW_ROUTE_REGISTRY_V1__';
+    const state = (globalThis as typeof globalThis & { [REGISTRY_KEY]?: { copies: number } })[REGISTRY_KEY];
+    assert.ok(state, `route registry state must live on globalThis['${REGISTRY_KEY}']`);
+
+    const originalCopies = state.copies;
+    state.copies = 2;
+    try {
+      const logged = await captureErrors(async () => {
+        const result = await invoke({}, makeEvent({ httpMethod: 'GET', path: '/unknown', body: null }));
+        assert.strictEqual(result.statusCode, 404);
+      });
+
+      assert.ok(
+        logged.some((line) => line.includes('2 copies of @aws-blocks/core are loaded')),
+        `expected the copy count in the diagnostic, got: ${JSON.stringify(logged)}`,
+      );
+    } finally {
+      state.copies = originalCopies;
+    }
+  });
+});
+
 describe('createLambdaHandler — cookie extraction', () => {
   it('extracts cookies from lowercase "cookie" header (API Gateway v2)', async () => {
     let capturedCookies = '';

package/src/lambda-handler.ts

@@ -5,9 +5,9 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { ApiError } from './errors.js';
 import { BLOCKS_RPC_PREFIX } from './constants.js';
-import { matchRoute, lockRouteRegistry } from './raw-route.js';
+import { matchRoute, lockRouteRegistry, getRegisteredRoutes, getLoadedCoreCopies } from './raw-route.js';
 import { registerBuiltinRoutes } from './builtin-routes.js';
-import { loadConfigToProcessEnv } from './common/config.js';
+import { loadConfigToProcessEnv, isConfigResolved } from './common/config.js';
 import {
   parseRpcRequest,
   successResponse,
@@ -297,6 +297,26 @@ export function createLambdaHandler(backendFactory: () => Promise<any>) {
   async function initialize() {
     await loadConfigToProcessEnv();
 
+    // If the app has config coordinates (BLOCKS_CONFIG_BUCKET/KEY set) but the
+    // load didn't actually resolve the config, we're in the transient post-deploy
+    // S3 window where blocks-config.json isn't readable yet. loadConfigFromS3()
+    // deliberately does NOT cache that empty result, so throw a typed transient
+    // error here — BEFORE importing the backend — so the createLambdaHandler()
+    // catch resets initPromise and the next request re-runs initialize(), which
+    // re-fetches from S3 and picks up the now-present config. Without this throw,
+    // initialize() would succeed with empty config, `handler` would be assigned,
+    // and the `if (!handler)` guard below would never fire again, poisoning the
+    // container for its whole life (it would import the backend against empty
+    // process.env and serve "not configured" 500s forever).
+    //
+    // A genuinely config-less app does NOT throw: the no-bucket local-dev path
+    // and a real empty `{}` config both cache their result, so isConfigResolved()
+    // is true and the retry never spins. Once the blob is readable the successful
+    // load caches, so there is no unbounded per-request S3 re-fetch either.
+    if (process.env.BLOCKS_CONFIG_BUCKET && process.env.BLOCKS_CONFIG_KEY && !isConfigResolved()) {
+      throw new TransientConfigError();
+    }
+
     // Merge hosting-provided CORS origins into the main env var so the lazy
     // getCorsPatterns() sees a combined value on first access.
     // loadConfigToProcessEnv() won't override CORS_ALLOWED_ORIGINS if it's
@@ -318,7 +338,18 @@ export function createLambdaHandler(backendFactory: () => Promise<any>) {
 
   return async (event: any, context?: LambdaContext) => {
     if (!handler) {
-      if (!initPromise) initPromise = initialize();
+      // Retry init on failure instead of caching the rejection. If initialize() throws (most often
+      // because loadConfigToProcessEnv() couldn't read blocks-config.json during the brief
+      // post-deploy window before it's readable), a memoized rejected promise would poison this
+      // container for its whole lifetime — every later request re-awaits the same rejection and 500s.
+      // Resetting initPromise lets the next invocation re-run initialize() (config.ts re-fetches,
+      // since it doesn't cache failures), so the handler self-heals once config is available.
+      if (!initPromise) {
+        initPromise = initialize().catch((err) => {
+          initPromise = null;
+          throw err;
+        });
+      }
       await initPromise;
     }
 
@@ -390,6 +421,27 @@ class HandlerTimeoutError extends Error {
   }
 }
 
+/**
+ * Thrown by `initialize()` when the app has config coordinates
+ * (BLOCKS_CONFIG_BUCKET/KEY) but the S3 config load resolved empty because
+ * blocks-config.json wasn't readable yet — the transient window right after a
+ * deploy, before the BucketDeployment settles.
+ *
+ * It flows through the `createLambdaHandler()` init catch, which resets
+ * `initPromise` so the NEXT request re-runs `initialize()` and picks up the
+ * now-present config (config.ts does not cache a not-found result, so the retry
+ * re-fetches). A distinct type keeps the recovery path greppable and testable
+ * and separates it from real init failures, which surface with their own error.
+ *
+ * @internal Exported for testing only.
+ */
+export class TransientConfigError extends Error {
+  constructor() {
+    super('[Blocks] Config not readable yet (transient post-deploy S3 window); will retry on next request');
+    this.name = 'TransientConfigError';
+  }
+}
+
 /**
  * Extract the request path from a Lambda event, normalizing between
  * API Gateway v1 (REST) and v2 (HTTP API) event shapes.
@@ -477,8 +529,17 @@ function createHandler(backend: any) {
       if (matched) {
         return handleRawRoute(event, matched.route, matched.params, corsHeaders, signal);
       }
-      // No RawRoute matched and path is not the RPC endpoint — return 404
+      // No RawRoute matched and path is not the RPC endpoint — return 404.
+      // Log it: an unmatched route used to be entirely silent, which is what
+      // made a split route registry (duplicate @aws-blocks/core copies)
+      // undiagnosable from CloudWatch alone. The path is already in the API
+      // Gateway access logs, so this adds no new category of data.
       if (!requestPath.startsWith(BLOCKS_RPC_PREFIX)) {
+        const copies = getLoadedCoreCopies();
+        const copiesNote = copies > 1 ? ` — ${copies} copies of @aws-blocks/core are loaded` : '';
+        console.error(
+          `No RawRoute matched ${httpMethod} ${requestPath} (${getRegisteredRoutes().length} routes registered)${copiesNote}`,
+        );
         return {
           statusCode: 404,
           headers: {