@aws-blocks/core 0.4.0 → 0.5.0

package/README.md

@@ -76,6 +76,18 @@ The body is JSON-RPC 2.0:
 - `params` is a POSITIONAL array of the method's arguments. A named object also works (its values are used in order).
 - Errors come back as HTTP `200` with an `error` object in the body (per JSON-RPC), not as a non-2xx status.
 
+Error responses use these JSON-RPC codes:
+
+| Code | Meaning | When Blocks uses it |
+|------|---------|---------------------|
+| `-32700` | Parse error | Request body is not valid JSON. |
+| `-32600` | Invalid Request | Body is not a valid Blocks JSON-RPC request, such as missing `jsonrpc: "2.0"` or a `method` that is not `namespace.method`. |
+| `-32601` | Method not found | The requested namespace or method is not exported by the backend. |
+| `-32602` | Invalid params | Reserved for JSON-RPC parameter validation failures. Application-level validation should throw an `ApiError` with the appropriate HTTP status instead. |
+| `-32603` | Internal error | Reserved for generic JSON-RPC internal errors. Unhandled application errors currently use code `500`. |
+
+Errors thrown with `ApiError` use the positive HTTP status as the JSON-RPC `error.code` (for example, `401`, `404`, or `409`) and include `error.data.name` when an error name is available. The typed client converts JSON-RPC errors back into `ApiError`.
+
 Working example:
 
 ```bash

package/dist/cdk/blocks-backend.d.ts

@@ -88,7 +88,9 @@ export declare class BlocksBackend extends Construct {
     get gateway(): apigateway.RestApi;
     /** The default compute's RPC endpoint URL. To be removed once consumers move to the multi-compute model. */
     get apiUrl(): string;
-    /** The default compute's handler CloudWatch log group. `bb-logger` reconfigures its retention. */
+    /** The default compute's handler CloudWatch log group. Its retention comes from
+     * the compute's `logRetention` (falling back to `defaults.logRetention`); the
+     * `bb-logger` CDK construct is a no-op and no longer touches it. */
     get handlerLogGroup(): cdk.aws_logs.ILogGroup;
     private requireDefaultCompute;
     /**
@@ -111,6 +113,7 @@ export declare class BlocksBackend extends Construct {
      * fallback to the (token-free) construct id should no resolvable name exist.
      */
     get fullId(): string;
+    private _vpcOptions?;
     private constructor();
     static create(scope: Construct, id: string, props: CoreBlocksBackendProps): Promise<BlocksBackend>;
 }

package/dist/cdk/blocks-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blocks-backend.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-backend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,KAAK,KAAK,UAAU,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAIvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,qBAAqB,EAAuB,MAAM,sCAAsC,CAAC;AAEvG;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAkB/C;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,QAAU,CAAC;AAEtD,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,8EAA8E;IAC9E,qBAAqB,EAAE,qBAAqB,CAAC;CAC9C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,CAAC,EAAE,MAAM;;EAyFxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAC3C;;;;OAIG;IACH,SAAgB,iBAAiB,EAAE,MAAM,CAAC;IAC1C,yFAAyF;IACzF,SAAgB,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC;IACzC,8EAA8E;IAC9E,SAAgB,QAAQ,EAAE,cAAc,CAAC;IACzC,iGAAiG;IACjG,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,2GAA2G;IAC3G,IAAI,OAAO,IAAI,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAElD;IACD,gHAAgH;IAChH,IAAI,OAAO,IAAI,UAAU,CAAC,OAAO,CAEhC;IACD,4GAA4G;IAC5G,IAAI,MAAM,IAAI,MAAM,CAEnB;IACD,kGAAkG;IAClG,IAAI,eAAe,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAE5C;IAED,OAAO,CAAC,qBAAqB;IAO7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,MAAM,IAAI,MAAM,CAUnB;IAED,OAAO;WAoBM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB;CA6BhF"}
+{"version":3,"file":"blocks-backend.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-backend.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,KAAK,KAAK,UAAU,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,qBAAqB,EAAuB,MAAM,sCAAsC,CAAC;AAQvG;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAkB/C;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,QAAU,CAAC;AAEtD,MAAM,WAAW,kBAAkB;IAClC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IACjE,8EAA8E;IAC9E,qBAAqB,EAAE,qBAAqB,CAAC;CAC7C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,CAAC,EAAE,MAAM;;EAqGxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC3C,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAC3C;;;;OAIG;IACH,SAAgB,iBAAiB,EAAE,MAAM,CAAC;IAC1C,yFAAyF;IACzF,SAAgB,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC;IACzC,8EAA8E;IAC9E,SAAgB,QAAQ,EAAE,cAAc,CAAC;IACzC,iGAAiG;IACjG,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,2GAA2G;IAC3G,IAAI,OAAO,IAAI,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAElD;IACD,gHAAgH;IAChH,IAAI,OAAO,IAAI,UAAU,CAAC,OAAO,CAEhC;IACD,4GAA4G;IAC5G,IAAI,MAAM,IAAI,MAAM,CAEnB;IACD;;wEAEoE;IACpE,IAAI,eAAe,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAE5C;IAED,OAAO,CAAC,qBAAqB;IAS7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,MAAM,IAAI,MAAM,CAUnB;IAED,OAAO,CAAC,WAAW,CAAC,CAAmB;IAEvC,OAAO;WA6BM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB;CAyD/E"}

package/dist/cdk/blocks-backend.js

@@ -1,14 +1,17 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
+import { pathToFileURL } from 'node:url';
 import * as cdk from 'aws-cdk-lib';
 import * as iam from 'aws-cdk-lib/aws-iam';
 import { CfnGroup } from 'aws-cdk-lib/aws-resourcegroups';
 import { Construct } from 'constructs';
-import { pathToFileURL } from 'node:url';
-import { addBlocksStackMetadata } from './stack-metadata.js';
-import { finalizeConfigRegistry, registerConfig } from './config-registry.js';
 import { registerBuiltinRoutes } from '../builtin-routes.js';
 import { getComputes } from './compute/compute-registry.js';
+import { finalizeConfigRegistry, registerConfig } from './config-registry.js';
+import { finalizeDashboards } from './dashboard-registry.js';
+import { finalizeTracing } from './tracer-registry.js';
+import { addBlocksStackMetadata } from './stack-metadata.js';
+import { anyRequirementNeedsVpc, finalizeVpc, getOrCreateVpc, initializeVpc } from './vpc.js';
 /**
  * Validate that the Node.js process was started with `--conditions=cdk`.
  *
@@ -20,7 +23,7 @@ import { getComputes } from './compute/compute-registry.js';
 export function assertCdkConditionActive() {
     const nodeOptions = process.env.NODE_OPTIONS ?? '';
     const execArgv = process.execArgv ?? [];
-    const hasCdkCondition = execArgv.some(arg => arg === '--conditions=cdk') ||
+    const hasCdkCondition = execArgv.some((arg) => arg === '--conditions=cdk') ||
         execArgv.some((arg, i) => (arg === '--conditions' || arg === '-C') && execArgv[i + 1] === 'cdk') ||
         nodeOptions.includes('--conditions=cdk') ||
         /(?:--conditions|-C)\s+cdk/.test(nodeOptions);
@@ -72,13 +75,17 @@ export function setupBlocksInfra(scope, props, id) {
         assumedBy: new iam.CompositePrincipal(new iam.ServicePrincipal('lambda.amazonaws.com')),
         managedPolicies: [
             iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaBasicExecutionRole'),
+            // When Lambda is placed in a VPC it needs ENI management permissions
+            ...(props.defaults.vpc
+                ? [iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaVPCAccessExecutionRole')]
+                : []),
         ],
     });
     // ── Resource Groups ───────────────────────────────────────────────────
     let rootStack = cdk.Stack.of(scope);
     while (rootStack.nestedStackParent)
         rootStack = rootStack.nestedStackParent;
-    const groupPrefix = (id && id !== rootStack.stackName) ? `${rootStack.stackName}-${id}` : rootStack.stackName;
+    const groupPrefix = id && id !== rootStack.stackName ? `${rootStack.stackName}-${id}` : rootStack.stackName;
     new CfnGroup(scope, 'StackResources', {
         name: `${groupPrefix}-resources`,
         resourceQuery: {
@@ -111,12 +118,20 @@ export function setupBlocksInfra(scope, props, id) {
     // ── Console redirect routes ───────────────────────────────────────────
     const region = cdk.Fn.ref('AWS::Region');
     const resourcesUrl = cdk.Fn.join('', [
-        'https://', region, '.console.aws.amazon.com/resource-groups/group/',
-        `${groupPrefix}-resources`, '?region=', region,
+        'https://',
+        region,
+        '.console.aws.amazon.com/resource-groups/group/',
+        `${groupPrefix}-resources`,
+        '?region=',
+        region,
     ]);
     const settingsUrl = cdk.Fn.join('', [
-        'https://', region, '.console.aws.amazon.com/resource-groups/group/',
-        `${groupPrefix}-settings`, '?region=', region,
+        'https://',
+        region,
+        '.console.aws.amazon.com/resource-groups/group/',
+        `${groupPrefix}-settings`,
+        '?region=',
+        region,
     ]);
     registerConfig(scope, 'BB_RESOURCES_GROUP_URL', resourcesUrl);
     registerConfig(scope, 'BB_SETTINGS_GROUP_URL', settingsUrl);
@@ -166,7 +181,9 @@ export class BlocksBackend extends Construct {
     get apiUrl() {
         return this.requireDefaultCompute().apiUrl;
     }
-    /** The default compute's handler CloudWatch log group. `bb-logger` reconfigures its retention. */
+    /** The default compute's handler CloudWatch log group. Its retention comes from
+     * the compute's `logRetention` (falling back to `defaults.logRetention`); the
+     * `bb-logger` CDK construct is a no-op and no longer touches it. */
     get handlerLogGroup() {
         return this.requireDefaultCompute().logGroup;
     }
@@ -206,16 +223,25 @@ export class BlocksBackend extends Construct {
         }
         return `${stackName}-${this.node.id}`;
     }
+    _vpcOptions;
     constructor(scope, id, props) {
         super(scope, id);
         this.backendHandlerPath = props.backendHandlerPath;
         this.backendModulePath = props.backendCDKPath;
+        this._vpcOptions = props.defaults.vpc;
         // Expose self to Building Blocks at CDK time
         globalThis.CURRENT_BLOCKS_STACK = this;
         // Store defaults on the backend (not the stack) so several BlocksBackends
         // in one stack each keep their own posture; Building Blocks resolve them by
         // walking up to their owning backend (see Scope.defaults).
         this.defaults = props.defaults;
+        // Initialize VPC context before the default compute is created and before
+        // BBs are constructed, so both can discover it: the default compute
+        // (LambdaCompute) reads it via getVpcContext(this) to place its function in
+        // the VPC, and BBs (e.g. bb-data) read it to co-locate their resources.
+        if (this._vpcOptions) {
+            initializeVpc(this, this._vpcOptions);
+        }
         const infra = setupBlocksInfra(this, props, id);
         this.executionRole = infra.executionRole;
         // The default compute (and thus handler/gateway) is created in create(),
@@ -247,6 +273,26 @@ export class BlocksBackend extends Construct {
         addBlocksStackMetadata(cdk.Stack.of(backend));
         // Finalize BB config → S3 (after all BBs have registered their config)
         finalizeConfigRegistry(backend, backend.executionRole, getComputes(backend));
+        // Tracing is presence-gated: if the app contains a Tracer, enable X-Ray on
+        // every compute. Runs before the dashboard finalize.
+        finalizeTracing(backend, backend.executionRole);
+        // Build any deferred Dashboards now that every compute's observability
+        // state is settled — so the dashboard is order-independent.
+        finalizeDashboards(backend);
+        // Finalize VPC. Derived resource: use the customer's if provided, else
+        // lazily create one only if a Building Block requires it.
+        if (backend._vpcOptions) {
+            finalizeVpc(backend, backend._vpcOptions);
+        }
+        else if (anyRequirementNeedsVpc(backend)) {
+            const derived = getOrCreateVpc(backend);
+            const options = { network: derived };
+            initializeVpc(backend, options);
+            finalizeVpc(backend, options);
+            cdk.Annotations.of(backend).addInfoV2('blocks:vpc:derived', 'A Building Block required a VPC and none was provided, so Blocks created one ' +
+                '(with a NAT gateway, which has an ongoing cost). Pass `defaults.vpc: { network }` to ' +
+                'bring your own. See packages/blocks/VPC.md.');
+        }
         return backend;
     }
 }

package/dist/cdk/blocks-backend.test.js

@@ -14,6 +14,7 @@ import { BlocksBackend } from './blocks-backend.js';
 import { BlocksPresets } from './blocks-defaults.js';
 import { Compute } from './compute/compute.js';
 import { Scope } from './index.js';
+import { getVpcContext } from './vpc.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
 // equivalent inline stub: a Compute that owns a NodejsFunction + API Gateway,
@@ -31,6 +32,11 @@ class StubLambdaCompute extends Compute {
         this.logGroup = new cdk.aws_logs.LogGroup(this, 'HandlerLogGroup', {
             removalPolicy: cdk.RemovalPolicy.DESTROY,
         });
+        // Discover the shared VPC context from the owning stack/backend, mirroring
+        // LambdaCompute — so the core-side VPC placement plumbing (initializeVpc →
+        // getVpcContext) is exercised by these tests without depending on
+        // @aws-blocks/bb-lambda-compute.
+        const vpcContext = getVpcContext(this);
         this.fn = new lambda.NodejsFunction(this, 'Handler', {
             entry: this.backendHandlerPath,
             runtime: cdk.aws_lambda.Runtime.NODEJS_22_X,
@@ -39,6 +45,13 @@ class StubLambdaCompute extends Compute {
             logGroup: this.logGroup,
             environment: { BLOCKS_STACK_NAME: this.backendStackName },
             bundling: { minify: true, esbuildArgs: { '--conditions': 'aws-runtime' } },
+            ...(vpcContext
+                ? {
+                    vpc: vpcContext.vpc,
+                    vpcSubnets: vpcContext.computeSubnets,
+                    securityGroups: [vpcContext.computeSecurityGroup],
+                }
+                : {}),
         });
         this.apiGateway = new apigateway.RestApi(this, 'API', { restApiName: 'Blocks API' });
         this.apiGateway.root.addProxy({
@@ -50,6 +63,16 @@ class StubLambdaCompute extends Compute {
     setEnv(key, value) {
         this.fn.addEnvironment(key, value);
     }
+    applyTracing() { }
+    healthWidgets(_region) {
+        return [];
+    }
+    loggingWidgets(_region) {
+        return [];
+    }
+    tracingWidgets(_region) {
+        return [];
+    }
 }
 const stubComputeFactory = (root) => new StubLambdaCompute(root, 'DefaultCompute');
 // Simulate the CDK condition being active (tests import CDK files directly)
@@ -65,7 +88,12 @@ const EXECUTION_ROLE_MARKER_ACTION = 'blocks-test:MarkerAction';
 const importMetaHandlerPath = join(__dirname, '__fixtures__', 'import-meta-handler.js');
 // Wraps BlocksBackend.create, injecting the stub default-compute factory the way
 // @aws-blocks/blocks injects LambdaCompute — so tests don't repeat it 15 times.
-const makeBackend = (scope, id, backendCDKPath) => BlocksBackend.create(scope, id, { backendHandlerPath: handlerPath, backendCDKPath, defaults: BlocksPresets.production, defaultComputeFactory: stubComputeFactory });
+const makeBackend = (scope, id, backendCDKPath) => BlocksBackend.create(scope, id, {
+    backendHandlerPath: handlerPath,
+    backendCDKPath,
+    defaults: BlocksPresets.production,
+    defaultComputeFactory: stubComputeFactory,
+});
 describe('ESM cache-busting (multi-stage)', () => {
     test('BlocksBackend.create() with same backendCDKPath but different IDs produces constructs in each', async () => {
         const app = new cdk.App();
@@ -294,3 +322,45 @@ describe('infrastructure defaults (backend-anchored)', () => {
         assert.strictEqual(inner.defaults, BlocksPresets.sandbox);
     });
 });
+describe('VPC placement', () => {
+    test('places the handler Lambda in the VPC with a security group when vpc is provided', async () => {
+        const app = new cdk.App();
+        const parent = new cdk.Stack(app, 'VpcParent', {
+            env: { account: '123456789012', region: 'us-east-1' },
+        });
+        const vpc = new cdk.aws_ec2.Vpc(parent, 'AppVpc', { maxAzs: 2, natGateways: 1 });
+        await BlocksBackend.create(parent, 'Blocks', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+            defaults: { ...BlocksPresets.production, vpc: { network: vpc } },
+            defaultComputeFactory: stubComputeFactory,
+        });
+        const template = Template.fromStack(parent);
+        // The handler Lambda is VPC-attached: it has a VpcConfig with subnets + SGs.
+        template.hasResourceProperties('AWS::Lambda::Function', {
+            VpcConfig: Match.objectLike({
+                SubnetIds: Match.anyValue(),
+                SecurityGroupIds: Match.anyValue(),
+            }),
+        });
+        // The VPC-access managed policy is attached to the execution role.
+        const policies = template.findResources('AWS::IAM::Role');
+        const hasVpcManagedPolicy = Object.values(policies).some((role) => JSON.stringify(role.Properties?.ManagedPolicyArns ?? []).includes('AWSLambdaVPCAccessExecutionRole'));
+        assert.ok(hasVpcManagedPolicy, 'execution role should have the VPC access managed policy');
+    });
+    test('no VpcConfig on the handler when vpc is omitted', async () => {
+        const app = new cdk.App();
+        const parent = new cdk.Stack(app, 'NoVpcParent');
+        await BlocksBackend.create(parent, 'Blocks', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
+            defaultComputeFactory: stubComputeFactory,
+        });
+        const template = Template.fromStack(parent);
+        const fns = template.findResources('AWS::Lambda::Function');
+        for (const fn of Object.values(fns)) {
+            assert.strictEqual(fn.Properties?.VpcConfig, undefined, 'handler must not have VpcConfig when no VPC is configured');
+        }
+    });
+});

package/dist/cdk/blocks-defaults.d.ts

@@ -1,5 +1,6 @@
 import { RemovalPolicy } from 'aws-cdk-lib';
 import { RetentionDays } from 'aws-cdk-lib/aws-logs';
+import type { BlocksVpcOptions } from './vpc-types.js';
 /**
  * Request-rate limits applied to an API Gateway stage. On a REST API these are
  * requests/second; on a WebSocket API the unit is messages/second across the
@@ -89,6 +90,16 @@ export interface BlocksDefaults {
      * `ensureApiGatewayAccount` for the full multi-stack teardown caveat.
      */
     accessLogging: boolean;
+    /**
+     * Place the app's compute and VPC-resident resources in a VPC. Pass a
+     * standard CDK VPC — Blocks handles Lambda placement, endpoint provisioning
+     * (based on which Building Blocks are in scope), and security-group wiring.
+     *
+     * Omit for no VPC (the preset default — Lambda runs in the AWS-managed
+     * network). A Building Block that can't function without a VPC causes Blocks
+     * to derive one on demand even when this is unset.
+     */
+    vpc?: BlocksVpcOptions;
 }
 /**
  * Prepared starting points for {@link BlocksDefaults}. Pick one and override

package/dist/cdk/blocks-defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blocks-defaults.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-defaults.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;OAKG;IACH,aAAa,EAAE,aAAa,CAAC;IAE7B;;;;OAIG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAE5B;;;;;OAKG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB;;;;;;;;;;;OAWG;IACH,mBAAmB,EAAE,OAAO,GAAG;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IAEzD;;;;;;;OAOG;IACH,YAAY,EAAE,aAAa,CAAC;IAE5B;;;;;;;OAOG;IACH,UAAU,EAAE,gBAAgB,CAAC;IAE7B;;;;;;;;;;;;;;OAcG;IACH,aAAa,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;IACzB,qFAAqF;;;;;;;;;;;;;IAUrF;;;;;OAKG;;;;;;;;;;;;;CAcsC,CAAC"}
+{"version":3,"file":"blocks-defaults.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-defaults.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;OAKG;IACH,aAAa,EAAE,aAAa,CAAC;IAE7B;;;;OAIG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAE5B;;;;;OAKG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB;;;;;;;;;;;OAWG;IACH,mBAAmB,EAAE,OAAO,GAAG;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IAEzD;;;;;;;OAOG;IACH,YAAY,EAAE,aAAa,CAAC;IAE5B;;;;;;;OAOG;IACH,UAAU,EAAE,gBAAgB,CAAC;IAE7B;;;;;;;;;;;;;;OAcG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,gBAAgB,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;IACzB,qFAAqF;;;;;;;;;;;;;IAUrF;;;;;OAKG;;;;;;;;;;;;;CAcsC,CAAC"}

package/dist/cdk/blocks-stack.test.js

@@ -11,7 +11,7 @@ import { BLOCKS_RPC_PREFIX } from '../constants.js';
 import { BlocksBackend } from './blocks-backend.js';
 import { Compute } from './compute/compute.js';
 import { getComputes } from './compute/compute-registry.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
 // equivalent inline stub: a Compute that owns a NodejsFunction + API Gateway,
@@ -48,6 +48,16 @@ class StubLambdaCompute extends Compute {
     setEnv(key, value) {
         this.fn.addEnvironment(key, value);
     }
+    applyTracing() { }
+    healthWidgets(_region) {
+        return [];
+    }
+    loggingWidgets(_region) {
+        return [];
+    }
+    tracingWidgets(_region) {
+        return [];
+    }
 }
 const stubComputeFactory = (root) => new StubLambdaCompute(root, 'DefaultCompute');
 // Simulate the CDK condition being active (tests import CDK files directly)
@@ -60,8 +70,18 @@ const sideEffectBackendPath = join(__dirname, '__fixtures__', 'side-effect-backe
 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, id, backendCDKPath) => BlocksStack.create(scope, id, { backendHandlerPath: handlerPath, backendCDKPath, defaults: BlocksPresets.production, defaultComputeFactory: stubComputeFactory });
-const makeBackend = (scope, id, backendCDKPath) => BlocksBackend.create(scope, id, { backendHandlerPath: handlerPath, backendCDKPath, defaults: BlocksPresets.production, defaultComputeFactory: stubComputeFactory });
+const makeStack = (scope, id, backendCDKPath) => BlocksStack.create(scope, id, {
+    backendHandlerPath: handlerPath,
+    backendCDKPath,
+    defaults: BlocksPresets.production,
+    defaultComputeFactory: stubComputeFactory,
+});
+const makeBackend = (scope, id, backendCDKPath) => 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 () => {
         const app = new cdk.App();

package/dist/cdk/compute/compute.d.ts

@@ -1,3 +1,4 @@
+import type { IWidget } from 'aws-cdk-lib/aws-cloudwatch';
 import type { ScopeOptions } from '../../common/index.js';
 import { Scope } from '../index.js';
 /**
@@ -11,11 +12,17 @@ import { Scope } from '../index.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 declare abstract class Compute extends Scope {
     /**
@@ -24,6 +31,16 @@ export declare abstract class Compute extends Scope {
      * unpopulated (no compute assignment surface yet).
      */
     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;
+    /** 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;
     constructor(id: string, options?: ScopeOptions);
     /**
      * Inject a runtime configuration value (an environment variable) into this
@@ -31,5 +48,66 @@ export declare 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;
+    /**
+     * 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;
+    /**
+     * 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[][];
 }
 //# sourceMappingURL=compute.d.ts.map

package/dist/cdk/compute/compute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compute.d.ts","sourceRoot":"","sources":["../../../src/cdk/compute/compute.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGpC;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,OAAQ,SAAQ,KAAK;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAM;gBAEvB,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAQ9C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CACjD"}
+{"version":3,"file":"compute.d.ts","sourceRoot":"","sources":["../../../src/cdk/compute/compute.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGpC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,OAAQ,SAAQ,KAAK;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAM;IAEnC;;;;;OAKG;IACH,OAAO,CAAC,aAAa,CAAS;IAE9B;8EAC0E;IAC1E,SAAS,KAAK,eAAe,IAAI,OAAO,CAEvC;gBAEW,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAQ9C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAEjD;;;;;;OAMG;IACH,aAAa,IAAI,IAAI;IAMrB;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,IAAI,IAAI;IAEvC;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,uBAAuB;IAWzD;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,EAAE;IAE7D;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,EAAE;IAE9D;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,EAAE;CAC9D;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC;IACpB,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC;IACtB,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC;CACtB"}

package/dist/cdk/compute/compute.js

@@ -13,11 +13,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 class Compute extends Scope {
     /**
@@ -26,11 +32,59 @@ export class Compute extends Scope {
      * unpopulated (no compute assignment surface yet).
      */
     namespaces = [];
+    /**
+     * 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.
+     */
+    tracerEnabled = false;
+    /** Read-only view of {@link tracerEnabled} for subclasses (e.g. to guard
+     * their `tracingWidgets` builder). Subclasses can read but not set it. */
+    get isTracerEnabled() {
+        return this.tracerEnabled;
+    }
     constructor(id, options) {
         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);
     }
+    /**
+     * 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() {
+        if (this.tracerEnabled)
+            return;
+        this.tracerEnabled = true;
+        this.applyTracing();
+    }
+    /**
+     * 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) {
+        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,
+        };
+    }
 }

package/dist/cdk/config-registry.test.js

@@ -37,6 +37,18 @@ class TestCompute extends Compute {
     setEnv(key, value) {
         this.fn.addEnvironment(key, value);
     }
+    // Observability hooks are irrelevant to config-registry tests — stub them so
+    // this test double satisfies Compute's abstract contract.
+    applyTracing() { }
+    healthWidgets() {
+        return [];
+    }
+    loggingWidgets() {
+        return [];
+    }
+    tracingWidgets() {
+        return [];
+    }
 }
 function stackWithCompute(id) {
     const app = new cdk.App();

package/dist/cdk/dashboard-registry.d.ts

@@ -0,0 +1,41 @@
+import type { Construct } from 'constructs';
+/** A Dashboard's deferred widget-body build, run once after the app is constructed. */
+type DashboardFinalizer = () => void;
+/**
+ * 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 declare function registerDashboardFinalizer(scope: Construct, finalize: DashboardFinalizer): void;
+/**
+ * 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 declare function finalizeDashboards(scope: Construct): void;
+export {};
+//# sourceMappingURL=dashboard-registry.d.ts.map

package/dist/cdk/dashboard-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-registry.d.ts","sourceRoot":"","sources":["../../src/cdk/dashboard-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C,uFAAuF;AACvF,KAAK,kBAAkB,GAAG,MAAM,IAAI,CAAC;AAgBrC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAE/F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAKzD"}