@aws-blocks/core 0.3.0 → 0.5.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/dashboard-registry.ts

@@ -0,0 +1,68 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import * as cdk from 'aws-cdk-lib';
+import type { Construct } from 'constructs';
+
+const REGISTRY_KEY = Symbol.for('BLOCKS_DASHBOARD_REGISTRY');
+
+/** A Dashboard's deferred widget-body build, run once after the app is constructed. */
+type DashboardFinalizer = () => void;
+
+/**
+ * Get or create the deferred-dashboard list for a given stack. Stored on the
+ * stack object (keyed by a Symbol), so each stack in a multi-stack synth gets
+ * its own — mirrors the config + compute registries.
+ */
+function getRegistry(stack: cdk.Stack): DashboardFinalizer[] {
+	let list = (stack as unknown as Record<symbol, DashboardFinalizer[] | undefined>)[REGISTRY_KEY];
+	if (!list) {
+		list = [];
+		(stack as unknown as Record<symbol, DashboardFinalizer[]>)[REGISTRY_KEY] = list;
+	}
+	return list;
+}
+
+/**
+ * Register a Dashboard's deferred body-build, to run after every Building Block
+ * in the app has been constructed (the end of `BlocksStack`/`BlocksBackend`
+ * `create()`, once the backend module has fully imported).
+ *
+ * The Dashboard builds its widget body here rather than in its constructor
+ * because the body depends on which computes are traced, and a `Tracer` may be
+ * constructed *after* the Dashboard. Deferring makes the Dashboard observe the
+ * complete app, so it never depends on construction order. (The Dashboard's
+ * CloudWatch resource itself is created eagerly in the constructor, so its URL /
+ * redirect route never dangle — only the body is deferred.)
+ *
+ * This is intentionally scoped to the Dashboard (the only deferred-build case
+ * today) rather than a generic finalizer mechanism; generalize it only if a
+ * second use case appears.
+ *
+ * @param scope - Any construct in the stack (used to locate the stack).
+ * @param finalize - The deferred body-build; run once (in registration order)
+ *   by {@link finalizeDashboards}.
+ */
+export function registerDashboardFinalizer(scope: Construct, finalize: DashboardFinalizer): void {
+	getRegistry(cdk.Stack.of(scope)).push(finalize);
+}
+
+/**
+ * Run — and clear — every registered Dashboard finalizer on `scope`'s stack, in
+ * registration order. Called once from `create()` after the backend module has
+ * imported. Clearing the list makes a repeated call a no-op, so a dashboard's
+ * body is never built twice.
+ *
+ * A Dashboard constructed outside `create()` (e.g. directly in a unit test) must
+ * call this explicitly before synth — the same way `config-registry.test.ts`
+ * drives `finalizeConfigRegistry`. (A Dashboard's CloudWatch resource is created
+ * eagerly in its constructor, so even if its finalizer never runs its URL /
+ * redirect never dangle — only the widget body is missing.)
+ *
+ * @param scope - Any construct in the stack (used to locate the stack).
+ */
+export function finalizeDashboards(scope: Construct): void {
+	const list = getRegistry(cdk.Stack.of(scope));
+	// Drain the list so a repeated call can't rebuild an already-built dashboard.
+	const pending = list.splice(0, list.length);
+	for (const finalize of pending) finalize();
+}