@aws-blocks/core 0.3.0 → 0.4.0

package/src/cdk/config-registry.ts

@@ -4,14 +4,19 @@
 import * as cdk from 'aws-cdk-lib';
 import * as s3 from 'aws-cdk-lib/aws-s3';
 import * as s3deploy from 'aws-cdk-lib/aws-s3-deployment';
-import * as iam from 'aws-cdk-lib/aws-iam';
 import type { Construct } from 'constructs';
+import type { Compute } from './compute/compute.js';
 
 const REGISTRY_KEY = Symbol.for('BLOCKS_CONFIG_REGISTRY');
 
+/** The object key of the config JSON under {@link getConfigLocation}'s bucket. */
+const CONFIG_KEY = 'blocks-config.json';
+
 interface ConfigRegistryState {
 	entries: Map<string, unknown>;
 	finalized: boolean;
+	/** The shared config bucket, created once per stack by {@link getConfigLocation}. */
+	bucket?: s3.Bucket;
 }
 
 /**
@@ -45,62 +50,115 @@ export function registerConfig(scope: Construct, key: string, value: unknown): v
 	registry.entries.set(key, value);
 }
 
+/**
+ * Ensure the shared config bucket exists and return where the config JSON lives
+ * (`{ bucketName, key }`). The bucket is created **once per stack** (memoized on
+ * the registry) and this is idempotent — the first caller creates it, later
+ * callers get the same bucket regardless of order.
+ *
+ * Any compute that loads config at runtime (`loadConfigToProcessEnv()`) injects
+ * these two values as `BLOCKS_CONFIG_BUCKET` / `BLOCKS_CONFIG_KEY`. The Lambda
+ * handler gets them from {@link finalizeConfigRegistry}; other compute that runs
+ * as the shared execution role (e.g. the Agent BB's AgentCore Runtime) calls this
+ * at construction to inject them too, so it loads the same app config the handler
+ * does. IAM is not granted here — `finalizeConfigRegistry` grants read on the config
+ * object to the shared execution role, which such compute inherits.
+ *
+ * @param scope - Any construct in the stack; the bucket is created under the stack.
+ */
+export function getConfigLocation(scope: Construct): { bucketName: string; key: string } {
+	return { bucketName: ensureConfigBucket(scope).bucketName, key: CONFIG_KEY };
+}
+
+/**
+ * Create-or-return the shared config bucket (memoized on the per-stack registry). Created under the
+ * owning `BlocksStack`/`BlocksBackend` (`globalThis.CURRENT_BLOCKS_STACK` — the construct finalize
+ * historically used), so its logical ID is stable regardless of which caller creates it first: a
+ * co-located BB (e.g. the AgentCore Runtime, a deep construct) may be the first to call it, and a
+ * `BlocksBackend` embedded in a customer stack must keep `Blocks/BlocksConfigBucket` (no replacement).
+ * Falls back to the stack when no owner is registered (isolated unit tests). Returns a concrete
+ * `s3.Bucket` so callers don't need a non-null assertion.
+ */
+function ensureConfigBucket(scope: Construct): s3.Bucket {
+	const stack = cdk.Stack.of(scope);
+	const registry = getRegistry(stack);
+	if (!registry.bucket) {
+		const owner = ((globalThis as any).CURRENT_BLOCKS_STACK as Construct | undefined) ?? stack;
+		registry.bucket = new s3.Bucket(owner, 'BlocksConfigBucket', {
+			removalPolicy: cdk.RemovalPolicy.DESTROY,
+			autoDeleteObjects: true,
+			encryption: s3.BucketEncryption.S3_MANAGED,
+			blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+			lifecycleRules: [
+				{ noncurrentVersionExpiration: cdk.Duration.days(1) },
+			],
+		});
+	}
+	return registry.bucket;
+}
+
 /**
  * Finalize the config registry: create an S3 bucket, upload the config JSON,
- * set env vars on the handler, and grant read access.
+ * grant read to the shared execution role, and stamp the config coordinates
+ * (`BLOCKS_CONFIG_BUCKET` / `BLOCKS_CONFIG_KEY`) onto every compute.
+ *
+ * Read access is granted once to the shared role (`root.executionRole`) rather
+ * than to a single function, so every compute that assumes the role can read
+ * the object. The bucket/key coordinates can't live on a role (env vars are
+ * per-compute), so they are set on each compute via `setEnv`.
  *
  * Must be called after all BBs are constructed (i.e., after the backendCDKPath
  * import completes in BlocksStack.create() / BlocksBackend.create()).
  *
- * @param scope - The CDK construct to create resources under
- * @param handler - The Lambda function that needs to read the config
+ * @param root - The construct to create the config resources under (also used
+ *   to locate the owning stack).
+ * @param executionRole - The shared role every compute assumes; config read is
+ *   granted to it once.
+ * @param computes - The computes to stamp `BLOCKS_CONFIG_BUCKET` / `BLOCKS_CONFIG_KEY` on.
  */
 export function finalizeConfigRegistry(
-	scope: Construct,
-	handler: cdk.aws_lambda.IFunction,
+	root: Construct,
+	executionRole: cdk.aws_iam.IRole,
+	computes: readonly Compute[],
 ): void {
-	const stack = cdk.Stack.of(scope);
+	const stack = cdk.Stack.of(root);
 	const registry = getRegistry(stack);
 
 	if (registry.finalized) return;
 	registry.finalized = true;
 
-	if (registry.entries.size === 0) return;
-
-	const configBucket = new s3.Bucket(scope, 'BlocksConfigBucket', {
-		removalPolicy: cdk.RemovalPolicy.DESTROY,
-		autoDeleteObjects: true,
-		encryption: s3.BucketEncryption.S3_MANAGED,
-		blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
-		lifecycleRules: [
-			{ noncurrentVersionExpiration: cdk.Duration.days(1) },
-		],
-	});
+	// Nothing to do only if no config was registered AND no bucket was created (via
+	// getConfigLocation). If a co-located BB created the bucket, still upload (even an empty {}) and
+	// wire the handler so that compute's loadConfigToProcessEnv() resolves instead of 404-ing forever.
+	if (registry.entries.size === 0 && !registry.bucket) return;
 
-	const configKey = 'blocks-config.json';
+	// Ensure the bucket exists (a co-located BB may already have created it via getConfigLocation).
+	const configBucket = ensureConfigBucket(root);
+	const configKey = CONFIG_KEY;
 
 	const configObject = cdk.Lazy.any({
 		produce: () => Object.fromEntries(registry.entries),
 	});
 
-	const deployment = new s3deploy.BucketDeployment(scope, 'BlocksConfigDeployment', {
+	new s3deploy.BucketDeployment(root, 'BlocksConfigDeployment', {
 		sources: [s3deploy.Source.jsonData(configKey, configObject)],
 		destinationBucket: configBucket,
 		prune: false,
 	});
 
-	(handler as cdk.aws_lambda.Function).addEnvironment(
-		'BLOCKS_CONFIG_BUCKET',
-		configBucket.bucketName,
-	);
-	(handler as cdk.aws_lambda.Function).addEnvironment(
-		'BLOCKS_CONFIG_KEY',
-		configKey,
-	);
-
-	// Scope IAM grant to the specific config key
-	(handler as cdk.aws_lambda.Function).addToRolePolicy(new iam.PolicyStatement({
-		actions: ['s3:GetObject'],
-		resources: [`${configBucket.bucketArn}/${configKey}`],
-	}));
+	// Grant read once to the shared role (scoped to the config key), so every
+	// compute assuming the role can read it. We intentionally use `grantRead`
+	// (which also adds s3:GetBucket*/s3:List* alongside s3:GetObject*) rather
+	// than a hand-rolled GetObject-only statement: this is a dedicated,
+	// block-all-public, config-only bucket, so the broader action set carries
+	// negligible exposure, and grantRead stays correct automatically if the
+	// bucket ever moves to KMS encryption (it would add kms:Decrypt).
+	configBucket.grantRead(executionRole, configKey);
+
+	// Stamp the config coordinates on every compute — env vars can't live on a
+	// role, so each compute needs them to locate the object at runtime.
+	for (const compute of computes) {
+		compute.setEnv('BLOCKS_CONFIG_BUCKET', configBucket.bucketName);
+		compute.setEnv('BLOCKS_CONFIG_KEY', configKey);
+	}
 }

package/src/cdk/index.ts

@@ -17,6 +17,7 @@ import { addBlocksStackMetadata } from './stack-metadata.js';
 import { finalizeConfigRegistry } from './config-registry.js';
 import { type BlocksDefaults, BlocksPresets } from './blocks-defaults.js';
 import type { Compute } from './compute/compute.js';
+import { getComputes } from './compute/compute-registry.js';
 import type { DefaultComputeFactory, LambdaShapedCompute } from './compute/default-compute-factory.js';
 
 export {
@@ -28,9 +29,11 @@ export {
 export { DEFAULT_NODE_RUNTIME } from './node-version.js';
 export { blocksNodejsBundling } from './bundling.js';
 export { SandboxDisableDeletionProtection } from './mixins.js';
-export { registerConfig, finalizeConfigRegistry } from './config-registry.js';
+export { registerConfig, finalizeConfigRegistry, getConfigLocation } from './config-registry.js';
+export { ensureApiGatewayAccount } from './apigateway-account.js';
 export {
   type BlocksDefaults,
+  type BlocksThrottling,
   BlocksPresets,
 } from './blocks-defaults.js';
 export { synthGuard } from './synth-guard.js';
@@ -56,6 +59,12 @@ export interface CoreBlocksStackProps extends BlocksStackProps {
 export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
   public readonly id: string;
   public readonly backendHandlerPath: string;
+  /**
+   * Path to the app's backend module (`props.backendCDKPath`). Exposed so Building Blocks that
+   * co-bundle the backend at synth (e.g. the Agent BB's AgentCore Runtime) can discover it via
+   * `globalThis.CURRENT_BLOCKS_STACK.backendModulePath`.
+   */
+  public readonly backendModulePath: string;
   /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
   public readonly executionRole: cdk.aws_iam.IRole;
   /** Infrastructure defaults for Building Blocks created under this stack. */
@@ -75,6 +84,10 @@ export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
   get apiUrl(): string {
     return this.requireDefaultCompute().apiUrl;
   }
+  /** The default compute's handler CloudWatch log group. `bb-logger` reconfigures its retention. */
+  get handlerLogGroup(): cdk.aws_logs.ILogGroup {
+    return this.requireDefaultCompute().logGroup;
+  }
 
   private requireDefaultCompute(): LambdaShapedCompute {
     if (!this._defaultCompute) {
@@ -88,6 +101,7 @@ export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
     this.id = id;
     this.backendHandlerPath = props.backendHandlerPath;
     this.defaults = props.defaults;
+    this.backendModulePath = props.backendCDKPath;
 
     // Set globalThis so Building Blocks attach directly to this stack
     (globalThis as any).CURRENT_BLOCKS_STACK = this;
@@ -124,7 +138,7 @@ export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
       }
     }
     // Finalize BB config → S3 (after all BBs have registered their config)
-    finalizeConfigRegistry(stack, stack.handler);
+    finalizeConfigRegistry(stack, stack.executionRole, getComputes(stack));
 
     new cdk.CfnOutput(stack, 'ApiUrl', { value: stack.apiUrl });
 
@@ -220,6 +234,24 @@ export class Scope extends Construct {
     return defaultCompute;
   }
 
+  /**
+   * The stack's default compute, **ignoring** any per-scope `_compute`
+   * assignment (unlike {@link compute}, which resolves the nearest assigned
+   * one). Use when a resource is a stack-level singleton that must bind to one
+   * deterministic compute regardless of the block's resolved compute — e.g.
+   * Realtime's shared WebSocket route integration, where one WebSocket API
+   * integrates to a single target and connection bookkeeping is compute-agnostic.
+   *
+   * @internal Not a customer surface; for framework/BB singleton infra only.
+   */
+  get defaultCompute(): Compute {
+    const defaultCompute = this.root._defaultCompute;
+    if (!defaultCompute) {
+      throw new Error('Default compute not initialized — BlocksStack/BlocksBackend.create() must run before resolving `defaultCompute`.');
+    }
+    return defaultCompute;
+  }
+
   /**
    * The backend entry file the owning BlocksStack/BlocksBackend runs — the
    * single handler entry shared across the whole app.
@@ -244,6 +276,17 @@ export class Scope extends Construct {
     return name;
   }
 
+  /**
+   * The shared handler Lambda's CloudWatch log group (the default compute's).
+   * Resolves the same way as {@link handler} — via the owning
+   * BlocksStack/BlocksBackend. `bb-logger` uses this to reconfigure retention on
+   * the single, framework-owned group rather than creating a second one that
+   * would collide on the log-group name.
+   */
+  get handlerLogGroup(): cdk.aws_logs.ILogGroup {
+    return this.root.handlerLogGroup;
+  }
+
   get fullId(): string {
     return computeScopeFullId(this);
   }

package/src/client/index.ts

@@ -316,5 +316,5 @@ export function ApiNamespaceClient<T extends Record<string, (...args: any[]) =>
   });
 }
 
-export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
+export { ApiError, blocksError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
 export { Scope, type ScopeOptions } from '../common/index.js';

package/src/common/config.test.ts

@@ -131,6 +131,27 @@ describe('config — S3 errors', () => {
 		assert.strictEqual(result, '', 'Should return empty string (empty config) on 404');
 	});
 
+	it('does not cache a not-found result — a later call re-fetches once the config exists', async () => {
+		process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+		process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+
+		// Simulate the transient post-deploy window: the object isn't written yet on the first
+		// fetch, then becomes available. A not-found result must NOT be cached, or the container
+		// would be poisoned with empty config for its lifetime.
+		let call = 0;
+		const notFound = new Error('The specified key does not exist.');
+		(notFound as any).name = 'NoSuchKey';
+		_setS3Fetcher(async () => {
+			call++;
+			if (call === 1) throw notFound;
+			return JSON.stringify({ READY_KEY: 'ready-value' });
+		});
+
+		assert.strictEqual(await getConfig('READY_KEY'), '', 'first call sees the not-yet-written config as empty');
+		assert.strictEqual(await getConfig('READY_KEY'), 'ready-value', 'later call re-fetches once the config exists');
+		assert.strictEqual(call, 2, 'a not-found result must not be cached — S3 is retried');
+	});
+
 	it('throws with clear message on S3 network error', async () => {
 		process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
 		process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';

package/src/common/config.ts

@@ -60,9 +60,13 @@ async function loadConfigFromS3(): Promise<Record<string, string>> {
 			|| error?.Code === 'NoSuchKey'
 			|| error?.$metadata?.httpStatusCode === 404;
 		if (isNotFound) {
-			console.warn(`[Blocks] Config file not found in S3 (${bucket}/${key}), proceeding with empty config`);
-			configCache = {};
-			return configCache;
+			// Do NOT cache the empty result: a 404 right after deploy is usually the config file
+			// not being readable yet (the transient window before the BucketDeployment settles), not
+			// a genuinely config-less app. Caching {} here would poison the container for its whole
+			// lifetime. Returning without caching lets the next invocation re-fetch and pick up the
+			// real config once it's present. (Apps that truly have no config just re-check cheaply.)
+			console.warn(`[Blocks] Config file not found in S3 (${bucket}/${key}), proceeding with empty config (will retry on next request)`);
+			return {};
 		}
 		const msg = error instanceof Error ? error.message : String(error);
 		throw new Error(`[Blocks] Failed to load config from S3 (${bucket}/${key}): ${msg}`);
@@ -152,6 +156,46 @@ export async function loadConfigToProcessEnv(): Promise<void> {
 	}
 }
 
+/**
+ * Whether a config load has resolved and cached a result.
+ *
+ * Returns `true` once `loadConfigFromS3()` has cached a config object — either a
+ * successful S3 load, a genuinely-empty `{}` config, or the no-bucket local-dev
+ * path (both of which cache `{}`). Returns `false` in the initial state AND
+ * after a transient not-found miss: the 404 path deliberately does NOT cache its
+ * empty result (see `loadConfigFromS3`), so a `false` return immediately after
+ * awaiting a load uniquely identifies the post-deploy S3 window where
+ * blocks-config.json isn't readable yet.
+ *
+ * Callers use this to tell a transient-empty load (retry on the next request)
+ * apart from a legitimately-config-less app (do nothing) without reaching into
+ * the module's private cache.
+ */
+export function isConfigResolved(): boolean {
+	return configCache !== null;
+}
+
+/**
+ * Sanitize a Blocks identifier into a valid config/env-var key segment:
+ * uppercase, with every non-alphanumeric character replaced by `_`.
+ *
+ * Config entries are loaded into `process.env` at runtime (see
+ * {@link loadConfigToProcessEnv}), so a key must be a valid env-var name. This
+ * is the single rule both sides of a key share: whoever *writes* a config key
+ * (`registerConfig(\`PREFIX_${sanitizeConfigKey(id)}\`, …)`) and whoever *reads*
+ * it (`getConfigSync(\`PREFIX_${sanitizeConfigKey(id)}\`)`) MUST go through this
+ * function so they reconstruct a byte-identical key — a hand-inlined variant
+ * that drifts silently misses the lookup at runtime.
+ *
+ * @example
+ * ```typescript
+ * registerConfig(this, `BLOCKS_QUEUE_URL_${sanitizeConfigKey(this.fullId)}`, url);
+ * ```
+ */
+export function sanitizeConfigKey(id: string): string {
+	return id.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+}
+
 /**
  * Reset the config cache. **For testing only.**
  */

package/src/common/index.ts

@@ -338,6 +338,14 @@ export interface BlocksStackProps extends StackProps {
 
 export class BlocksStack {
 	public readonly id: string;
+	/**
+	 * Path to the app's backend module (`props.backendCDKPath`). A typed contract for Building
+	 * Blocks that co-bundle the backend at synth time and read it off
+	 * `globalThis.CURRENT_BLOCKS_STACK` (the CDK `BlocksStack` / `BlocksBackend` set it). Declared
+	 * here so those consumers can type against this shared `BlocksStack` contract — which the CDK
+	 * `BlocksStack` / `BlocksBackend` implements — instead of `any`.
+	 */
+	declare readonly backendModulePath: string;
 	constructor(scope: Construct, id: string, props: BlocksStackProps) {
 		this.id = id;
 	}

package/src/errors.ts

@@ -78,6 +78,27 @@ export function isBlocksError<N extends string>(e: unknown, name: N): e is Error
 	return e instanceof Error && e.name === name;
 }
 
+/**
+ * Build a named `Error` whose `name` is a BB error constant, so it is matchable
+ * with {@link isBlocksError} on both server and client. The name is also
+ * prefixed into the message for readable logs.
+ *
+ * This is the producer half of the {@link isBlocksError} contract: throw via
+ * this helper so the `name` a consumer matches on is set consistently. It has
+ * no runtime dependencies, so it is safe to use in every bundle — mock,
+ * aws-runtime, and CDK synth.
+ *
+ * @example
+ * ```typescript
+ * throw blocksError(KVStoreErrors.ConditionalCheckFailed, 'Key already exists');
+ * ```
+ */
+export function blocksError(name: string, message: string): Error {
+	const err = new Error(`${name}: ${message}`);
+	err.name = name;
+	return err;
+}
+
 /**
  * Type guard for branching on a failed `AuthState` (the recommended
  * `setAuthState` client path) by its structured `errorName`.

package/src/hosting.test.ts

@@ -484,6 +484,34 @@ describe('Hosting', () => {
       }
       assert.ok(foundRetain, 'At least one bucket should have Retain deletion policy');
     });
+
+    it('forwards buildRetentionDays to the hosting bucket lifecycle rule (#480)', () => {
+      createSpaBuildOutput(tmpDir);
+
+      const app = new App();
+      const stack = new Stack(app, 'RetentionStack');
+
+      new Hosting(stack, 'Hosting', {
+        root: tmpDir,
+        api: MOCK_API,
+        buildRetentionDays: 90,
+      });
+
+      const template = Template.fromStack(stack);
+      // Before the fix, core dropped buildRetentionDays (only retainOnDelete was
+      // forwarded), so this asserted 30. It must now reach the DeleteOldBuilds
+      // rule as 90.
+      template.hasResourceProperties('AWS::S3::Bucket', {
+        LifecycleConfiguration: Match.objectLike({
+          Rules: Match.arrayWith([
+            Match.objectLike({
+              Id: 'DeleteOldBuilds',
+              ExpirationInDays: 90,
+            }),
+          ]),
+        }),
+      });
+    });
   });
 
   // ── API integration tests ────────────────────────────────────

package/src/hosting.ts

@@ -264,6 +264,16 @@ export interface HostingProps {
   /** Retain the S3 bucket when the stack is deleted. Default: false. */
   retainOnDelete?: boolean;
 
+  /**
+   * Days to retain SUPERSEDED build artifacts in S3 before they are expired.
+   * Default: 30. The build currently referenced by CloudFront KVS (`meta.b`)
+   * is NEVER expired regardless of this value — only builds that have been
+   * replaced by a newer deploy are cleaned up (issue #480). Raise this to keep
+   * a longer rollback window. Must be at least `skewProtection.maxAge`
+   * (converted to days), or synth throws `InvalidSkewProtectionMaxAgeError`.
+   */
+  buildRetentionDays?: number;
+
   /** Custom Content-Security-Policy header value. */
   contentSecurityPolicy?: string;
 
@@ -671,7 +681,17 @@ export class Hosting extends Construct {
       environment: Object.keys(plainEnv).length ? plainEnv : undefined,
       domain: resolvedDomain,
       waf: props.waf,
-      storage: props.retainOnDelete != null ? { retainOnDelete: props.retainOnDelete } : undefined,
+      storage:
+        props.retainOnDelete != null || props.buildRetentionDays != null
+          ? {
+              ...(props.retainOnDelete != null
+                ? { retainOnDelete: props.retainOnDelete }
+                : {}),
+              ...(props.buildRetentionDays != null
+                ? { buildRetentionDays: props.buildRetentionDays }
+                : {}),
+            }
+          : undefined,
       cdn:
         props.contentSecurityPolicy || props.priceClass || props.geoRestriction || props.quotas
           ? {

package/src/index.cdk.ts

@@ -24,11 +24,14 @@ export {
 	type BlocksDefaults,
 	BlocksPresets,
 	BlocksStack,
+	type BlocksThrottling,
 	blocksNodejsBundling,
 	type CoreBlocksBackendProps,
 	type CoreBlocksStackProps,
 	DEFAULT_NODE_RUNTIME,
+	ensureApiGatewayAccount,
 	finalizeConfigRegistry,
+	getConfigLocation,
 	registerConfig,
 	SandboxDisableDeletionProtection,
 	Scope,
@@ -44,7 +47,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,