@aws-blocks/core 0.4.0 → 0.5.0

package/src/cdk/blocks-stack.test.ts

@@ -7,6 +7,7 @@ import { before, describe, test } from 'node:test';
 import { fileURLToPath } from 'node:url';
 import * as cdk from 'aws-cdk-lib';
 import * as apigateway from 'aws-cdk-lib/aws-apigateway';
+import type { IWidget } from 'aws-cdk-lib/aws-cloudwatch';
 import * as lambda from 'aws-cdk-lib/aws-lambda-nodejs';
 import type { Construct } from 'constructs';
 import type { ScopeParent } from '../common/index.js';
@@ -15,7 +16,7 @@ import { BlocksBackend } from './blocks-backend.js';
 import { Compute } from './compute/compute.js';
 import { getComputes } from './compute/compute-registry.js';
 import type { DefaultComputeFactory } from './compute/default-compute-factory.js';
-import { BlocksStack, BlocksPresets, Scope } from './index.js';
+import { BlocksPresets, BlocksStack, Scope } from './index.js';
 
 // A real app gets its default compute from @aws-blocks/bb-lambda-compute (via
 // @aws-blocks/blocks), which core's own tests can't depend on. Use an
@@ -55,6 +56,17 @@ class StubLambdaCompute extends Compute {
 	setEnv(key: string, value: string): void {
 		this.fn.addEnvironment(key, value);
 	}
+
+	protected applyTracing(): void {}
+	protected healthWidgets(_region: string): IWidget[][] {
+		return [];
+	}
+	protected loggingWidgets(_region: string): IWidget[][] {
+		return [];
+	}
+	protected tracingWidgets(_region: string): IWidget[][] {
+		return [];
+	}
 }
 
 const stubComputeFactory: DefaultComputeFactory = (root) => new StubLambdaCompute(root as never, 'DefaultCompute');
@@ -72,9 +84,19 @@ const factoryBackendPath = join(__dirname, '__fixtures__', 'factory-backend.js')
 // Wrap create(), injecting the stub default-compute factory the way
 // @aws-blocks/blocks injects LambdaCompute — so tests don't repeat it.
 const makeStack = (scope: Construct, id: string, backendCDKPath: string) =>
-	BlocksStack.create(scope, id, { backendHandlerPath: handlerPath, backendCDKPath, defaults: BlocksPresets.production, defaultComputeFactory: stubComputeFactory });
+	BlocksStack.create(scope, id, {
+		backendHandlerPath: handlerPath,
+		backendCDKPath,
+		defaults: BlocksPresets.production,
+		defaultComputeFactory: stubComputeFactory,
+	});
 const makeBackend = (scope: Construct, id: string, backendCDKPath: string) =>
-	BlocksBackend.create(scope, id, { backendHandlerPath: handlerPath, backendCDKPath, defaults: BlocksPresets.production, defaultComputeFactory: stubComputeFactory });
+	BlocksBackend.create(scope, id, {
+		backendHandlerPath: handlerPath,
+		backendCDKPath,
+		defaults: BlocksPresets.production,
+		defaultComputeFactory: stubComputeFactory,
+	});
 
 describe('ESM cache-busting (multi-stage)', () => {
 	test('BlocksStack.create() with same backendCDKPath but different IDs produces constructs in each', async () => {
@@ -203,16 +225,13 @@ describe('assertCdkConditionActive', () => {
 		try {
 			const app = new cdk.App();
 
-			await assert.rejects(
-				makeStack(app, 'MissingConditionStack', sideEffectBackendPath),
-				(err: Error) => {
-					assert.ok(
-						err.message.includes('Missing --conditions=cdk'),
-						`Expected condition error, got: ${err.message}`,
-					);
-					return true;
-				},
-			);
+			await assert.rejects(makeStack(app, 'MissingConditionStack', sideEffectBackendPath), (err: Error) => {
+				assert.ok(
+					err.message.includes('Missing --conditions=cdk'),
+					`Expected condition error, got: ${err.message}`,
+				);
+				return true;
+			});
 		} finally {
 			process.env.NODE_OPTIONS = origNodeOptions;
 			process.execArgv = origExecArgv;

package/src/cdk/compute/compute.ts

@@ -1,6 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import type { IWidget } from 'aws-cdk-lib/aws-cloudwatch';
 import type { ScopeOptions } from '../../common/index.js';
 import { Scope } from '../index.js';
 import { registerCompute } from './compute-registry.js';
@@ -16,11 +17,17 @@ import { registerCompute } from './compute-registry.js';
  * compute in an app runs the same backend and agrees on the resource-name
  * namespace.
  *
+ * **Observability is compute-owned at deploy time.** Logging is always on (a
+ * compute owns its log group and captures stdout; retention is a compute-level
+ * setting), so there is no "enable logging" — logs always exist. Tracing, by
+ * contrast, provisions real infrastructure (X-Ray) and has cost, so it is
+ * enabled explicitly via {@link enableTracing} — which the framework calls on
+ * every compute when the app contains a `Tracer` (presence-gated).
+ *
  * The abstract base lives in core (a framework primitive); concrete computes
  * live in their own packages (e.g. `LambdaCompute` in `@aws-blocks/bb-lambda-compute`).
  *
- * @internal Not exported from the package's public entry points. Customers
- * cannot instantiate a compute until the customer-facing surface exists.
+ * @internal Not exported from the package's public entry points.
  */
 export abstract class Compute extends Scope {
 	/**
@@ -30,9 +37,23 @@ export abstract class Compute extends Scope {
 	 */
 	readonly namespaces: string[] = [];
 
+	/**
+	 * Whether tracing has been enabled on this compute — flipped by
+	 * {@link enableTracing}. Private so it can't be set independently of the
+	 * infra; read internally by {@link dashboardSection} to decide whether to
+	 * render the traces section.
+	 */
+	private tracerEnabled = false;
+
+	/** Read-only view of {@link tracerEnabled} for subclasses (e.g. to guard
+	 * their `tracingWidgets` builder). Subclasses can read but not set it. */
+	protected get isTracerEnabled(): boolean {
+		return this.tracerEnabled;
+	}
+
 	constructor(id: string, options?: ScopeOptions) {
 		super(id, options);
-		// Self-register on the owning stack so finalize steps (config, routing,
+		// Self-register on the owning stack so finalize steps (tracing, routing,
 		// dashboards) can enumerate every compute without a separate discovery
 		// pass. Scoped per stack, so a multi-stack synth keeps lists isolated.
 		registerCompute(this);
@@ -44,4 +65,85 @@ export abstract class Compute extends Scope {
 	 * directly so config targets the right compute.
 	 */
 	abstract setEnv(key: string, value: string): void;
+
+	/**
+	 * Enable distributed tracing on this compute: mark it traced (so the Dashboard
+	 * renders its traces section) and turn on the compute's active tracing via
+	 * {@link applyTracing}. Idempotent — the framework calls this on **every**
+	 * compute when the app contains a `Tracer` (tracing is presence-gated, not
+	 * per-compute), so calling it more than once is a no-op.
+	 */
+	enableTracing(): void {
+		if (this.tracerEnabled) return;
+		this.tracerEnabled = true;
+		this.applyTracing();
+	}
+
+	/**
+	 * Turn on this compute's active tracing (e.g. X-Ray) and grant its role the
+	 * permission to publish trace segments. Called by {@link enableTracing};
+	 * `protected` so tracing can't be turned on without marking the compute
+	 * traced.
+	 */
+	protected abstract applyTracing(): void;
+
+	/**
+	 * Build this compute's CloudWatch Dashboard section: health widgets and log
+	 * widgets **always** (logs are always captured for a compute), plus trace
+	 * widgets **only when** tracing is enabled on this compute (via
+	 * {@link enableTracing}).
+	 *
+	 * This is the single public entry the Dashboard Building Block uses; the
+	 * per-kind builders below are `protected`. Whether the logs / traces sections
+	 * are actually shown is a display choice the Dashboard makes on top (its
+	 * `logs` / `traces` options) — this returns what the compute *has*.
+	 *
+	 * @param region - AWS region the widgets query metrics in.
+	 */
+	dashboardSection(region: string): ComputeDashboardSection {
+		return {
+			// The scope id (e.g. 'DefaultCompute', 'api') — short and readable for a
+			// section header, and distinct per compute within a stack.
+			label: this.id,
+			health: this.healthWidgets(region),
+			logging: this.loggingWidgets(region),
+			tracing: this.tracerEnabled ? this.tracingWidgets(region) : undefined,
+		};
+	}
+
+	/**
+	 * Build this compute's health widget rows. Implemented by a concrete compute;
+	 * obtained only via {@link dashboardSection}.
+	 */
+	protected abstract healthWidgets(region: string): IWidget[][];
+
+	/**
+	 * Build this compute's **log** widget rows for its own log group. Logs always
+	 * exist, so this is always available; the Dashboard's `logs` option decides
+	 * whether to render it.
+	 */
+	protected abstract loggingWidgets(region: string): IWidget[][];
+
+	/**
+	 * Build this compute's **trace** widget rows. Gated behind
+	 * {@link dashboardSection} so it is only used when tracing is enabled.
+	 */
+	protected abstract tracingWidgets(region: string): IWidget[][];
+}
+
+/**
+ * A compute's self-reported CloudWatch Dashboard section. `health` and `logging`
+ * are always present; `tracing` is populated only when tracing is enabled on the
+ * compute. (The Dashboard may still hide `logging` / `tracing` via its display
+ * options.)
+ */
+export interface ComputeDashboardSection {
+	/** Display label used as the compute's group header. */
+	label: string;
+	/** Health widget rows — always present. */
+	health: IWidget[][];
+	/** Log widget rows — always present (logs are always captured). */
+	logging?: IWidget[][];
+	/** Trace widget rows — present only when tracing is enabled. */
+	tracing?: IWidget[][];
 }

package/src/cdk/config-registry.test.ts

@@ -13,6 +13,7 @@ import assert from 'node:assert';
 import { afterEach, test } from 'node:test';
 import * as cdk from 'aws-cdk-lib';
 import { Match, Template } from 'aws-cdk-lib/assertions';
+import type { IWidget } from 'aws-cdk-lib/aws-cloudwatch';
 import { Construct } from 'constructs';
 import { Compute } from './compute/compute.js';
 import { finalizeConfigRegistry, getConfigLocation, registerConfig } from './config-registry.js';
@@ -42,6 +43,19 @@ class TestCompute extends Compute {
 	setEnv(key: string, value: string): void {
 		this.fn.addEnvironment(key, value);
 	}
+
+	// Observability hooks are irrelevant to config-registry tests — stub them so
+	// this test double satisfies Compute's abstract contract.
+	protected applyTracing(): void {}
+	protected healthWidgets(): IWidget[][] {
+		return [];
+	}
+	protected loggingWidgets(): IWidget[][] {
+		return [];
+	}
+	protected tracingWidgets(): IWidget[][] {
+		return [];
+	}
 }
 
 function stackWithCompute(id: string): {

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();
+}