@aws-blocks/core 0.2.0 → 0.4.0

package/src/cdk/blocks-backend.ts

@@ -2,19 +2,18 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import * as cdk from 'aws-cdk-lib';
-import * as lambda from 'aws-cdk-lib/aws-lambda-nodejs';
-import * as apigateway from 'aws-cdk-lib/aws-apigateway';
+import type * as apigateway from 'aws-cdk-lib/aws-apigateway';
 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 { DEFAULT_NODE_RUNTIME } from './node-version.js';
-import { blocksNodejsBundling } from './bundling.js';
 import { addBlocksStackMetadata } from './stack-metadata.js';
 import { finalizeConfigRegistry, registerConfig } from './config-registry.js';
 import type { BlocksDefaults } from './blocks-defaults.js';
-import { BLOCKS_NAMESPACE, BLOCKS_RPC_PREFIX } from '../constants.js';
 import { registerBuiltinRoutes } from '../builtin-routes.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';
 
 /**
  * Validate that the Node.js process was started with `--conditions=cdk`.
@@ -44,6 +43,13 @@ export function assertCdkConditionActive(): void {
   }
 }
 
+/**
+ * Timeout of the shared Blocks handler Lambda, and therefore the ceiling on a
+ * single invocation. Exported because resources that feed the handler have to
+ * size their own timeouts against it (e.g. an SQS queue's visibility timeout).
+ */
+export const SHARED_HANDLER_TIMEOUT_SECONDS = 60 * 15;
+
 export interface BlocksBackendProps {
   backendHandlerPath: string;
   backendCDKPath: string;
@@ -57,7 +63,23 @@ export interface BlocksBackendProps {
   defaults: BlocksDefaults;
 }
 
-/** Shared infra setup — creates Lambda + API Gateway on the given scope. */
+/**
+ * Core's `create()` props: the public {@link BlocksBackendProps} plus the
+ * required `defaultComputeFactory`, spread on by the umbrella (`@aws-blocks/blocks`).
+ * Customers use {@link BlocksBackendProps} and never set the factory.
+ *
+ * @internal
+ */
+export interface CoreBlocksBackendProps extends BlocksBackendProps {
+  /** Builds the backend's default compute. Injected by `@aws-blocks/blocks`. */
+  defaultComputeFactory: DefaultComputeFactory;
+}
+
+/**
+ * Shared infra setup — provisions the stack-level resources that are NOT owned
+ * by a compute: the shared execution role, resource groups, and console-redirect
+ * routes.
+ */
 export function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id?: string) {
   // Fail fast with an actionable message at the create() call site if `defaults`
   // is missing (e.g. a plain-JS caller, `as any`, or a dynamically-built props
@@ -70,79 +92,31 @@ export function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id
     );
   }
 
-  // ── Shared execution role ──────────────────────────────────────────────
+  // ── Shared execution role ───────────────────────────────────────────────
   // A single IAM role that every Building Block grants to. Provisioned here so
   // it exists before the backend module is imported (Building Blocks reach it
   // via `scope.executionRole`). Block grants sit on the role's default (inline)
-  // policy. AWSLambdaBasicExecutionRole is attached so the handler retains
+  // policy. AWSLambdaBasicExecutionRole is attached so compute functions retain
   // CloudWatch Logs permissions.
+  //
+  // INVARIANT: this must be a mutable, framework-owned `iam.Role` — never an
+  // imported role (`Role.fromRoleArn`/`fromRoleName`), which is immutable by
+  // default. On an immutable role, every Building Block's `grant*()` /
+  // `addToPrincipalPolicy()` silently becomes a no-op (returns false, no error),
+  // so permissions would quietly vanish. If a bring-your-own-role option is ever
+  // added, it must resolve to a mutable role (`{ mutable: true }`).
   const executionRole = new iam.Role(scope, 'BlocksRole', {
-    // CompositePrincipal (rather than a bare ServicePrincipal) so additional
-    // compute types can assume this same shared role as they are introduced
-    // (e.g. ECS tasks via ecs-tasks.amazonaws.com), by adding principals here.
+    // CompositePrincipal (rather than a bare ServicePrincipal) so a Building Block
+    // whose compute runs AS this shared role can add its own trust principal here
+    // (e.g. the Agent BB adds bedrock-agentcore in its CDK construct) — core stays
+    // agnostic and only Lambda is trusted by default.
     assumedBy: new iam.CompositePrincipal(new iam.ServicePrincipal('lambda.amazonaws.com')),
     managedPolicies: [
       iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaBasicExecutionRole'),
     ],
   });
 
-  const handler = new lambda.NodejsFunction(scope, 'Handler', {
-    entry: props.backendHandlerPath,
-    runtime: DEFAULT_NODE_RUNTIME,
-    handler: 'handler',
-    role: executionRole,
-    memorySize: 2048,
-    timeout: cdk.Duration.seconds(60 * 15),
-    environment: {
-      NODE_ENV: 'production',
-      /**
-       * BLOCKS_STACK_NAME is used at runtime to derive physical resource names
-       * (DynamoDB table names, env var prefixes). It must match the CDK-time
-       * fullId of the BlocksStack/BlocksBackend so resource lookups work correctly.
-       *
-       * For BlocksStack: this equals the stack name (id).
-       * For BlocksBackend: the caller overrides this after construction to include
-       * the parent stack name for deployment uniqueness.
-       */
-      BLOCKS_STACK_NAME: id ?? cdk.Stack.of(scope).stackName,
-    },
-    // blocksNodejsBundling shims import.meta.* to CommonJS equivalents so a
-    // CJS-bundled `fileURLToPath(import.meta.url)` resolves instead of throwing at
-    // Lambda load. See ./bundling.ts.
-    bundling: blocksNodejsBundling({
-      minify: true,
-      esbuildArgs: { '--conditions': 'aws-runtime' },
-    }),
-  });
-
-  // In sandbox mode, allow localhost origins so the local dev frontend can
-  // reach the deployed Lambda API via CORS.
-  const isSandbox =
-    scope.node.tryGetContext('sandboxMode') === 'true' ||
-    scope.node.tryGetContext('sandboxMode') === true;
-  if (isSandbox) {
-    handler.addEnvironment('CORS_ALLOWED_ORIGINS', '^https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?$');
-  }
-
-  const api = new apigateway.RestApi(scope, 'API', {
-    restApiName: 'Blocks API',
-    deployOptions: { cachingEnabled: false },
-  });
-
-  const integration = new apigateway.LambdaIntegration(handler);
-
-  // Build the nested resource tree for /aws-blocks/api.
-  // Intermediate resource gets a proxy so sub-paths (RawRoutes) still reach Lambda.
-  const awsBlocksResource = api.root.addResource(BLOCKS_NAMESPACE.slice(1));
-  awsBlocksResource.addProxy({ defaultIntegration: integration, anyMethod: true });
-  
-  const apiResource = awsBlocksResource.addResource('api');
-  apiResource.addMethod('POST', integration);
-  apiResource.addMethod('OPTIONS', integration);
-
-  api.root.addProxy({ defaultIntegration: integration, anyMethod: true });
-
-  // ── Resource Groups ────────────────────────────────────────────────────
+  // ── 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;
@@ -178,7 +152,7 @@ export function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id
     },
   });
 
-  // ── Console redirect routes ────────────────────────────────────────────
+  // ── Console redirect routes ───────────────────────────────────────────
   const region = cdk.Fn.ref('AWS::Region');
   const resourcesUrl = cdk.Fn.join('', [
     'https://', region, '.console.aws.amazon.com/resource-groups/group/',
@@ -194,7 +168,7 @@ export function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id
 
   registerBuiltinRoutes();
 
-  return { handler, gateway: api, apiUrl: `${api.url}${BLOCKS_RPC_PREFIX.slice(1)}`, executionRole };
+  return { executionRole };
 }
 
 /**
@@ -215,14 +189,43 @@ export function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id
  * ```
  */
 export class BlocksBackend extends Construct {
-  public readonly apiUrl: string;
-  public readonly gateway: apigateway.RestApi;
-  public readonly handler: cdk.aws_lambda_nodejs.NodejsFunction;
   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: iam.IRole;
   /** Infrastructure defaults for Building Blocks created under this backend. */
   public readonly defaults: BlocksDefaults;
+  /** The default compute (owns the Lambda function + API Gateway); set in `create()`. @internal */
+  _defaultCompute?: Compute;
+
+  /** The default compute's Lambda function. To be removed once consumers move to the multi-compute model. */
+  get handler(): cdk.aws_lambda_nodejs.NodejsFunction {
+    return this.requireDefaultCompute().fn;
+  }
+  /** The default compute's API Gateway REST API. To be removed once consumers move to the multi-compute model. */
+  get gateway(): apigateway.RestApi {
+    return this.requireDefaultCompute().apiGateway;
+  }
+  /** The default compute's RPC endpoint URL. To be removed once consumers move to the multi-compute model. */
+  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) {
+      throw new Error('Blocks backend not fully initialized — access .handler/.gateway/.apiUrl after BlocksBackend.create() resolves.');
+    }
+    return this._defaultCompute as LambdaShapedCompute;
+  }
 
   /**
    * The fullId used by child Scopes to compute their env var names,
@@ -259,6 +262,7 @@ export class BlocksBackend extends Construct {
     super(scope, id);
 
     this.backendHandlerPath = props.backendHandlerPath;
+    this.backendModulePath = props.backendCDKPath;
 
     // Expose self to Building Blocks at CDK time
     (globalThis as any).CURRENT_BLOCKS_STACK = this;
@@ -269,20 +273,21 @@ export class BlocksBackend extends Construct {
     this.defaults = props.defaults;
 
     const infra = setupBlocksInfra(this, props, id);
-    this.handler = infra.handler;
-    this.gateway = infra.gateway;
-    this.apiUrl = infra.apiUrl;
     this.executionRole = infra.executionRole;
-
-    // Override BLOCKS_STACK_NAME to include the parent stack name so runtime
-    // resource lookups (DynamoDB table names) match the CDK-time fullId
-    // and are unique per deployment.
-    this.handler.addEnvironment('BLOCKS_STACK_NAME', this.fullId);
+    // The default compute (and thus handler/gateway) is created in create(),
+    // after construction — it derives BLOCKS_STACK_NAME from this.fullId.
   }
 
-  static async create(scope: Construct, id: string, props: BlocksBackendProps) {
+  static async create(scope: Construct, id: string, props: CoreBlocksBackendProps) {
     assertCdkConditionActive();
     const backend = new BlocksBackend(scope, id, props);
+    // Create the default compute before importing the backend: it OWNS the
+    // Lambda function + API Gateway (which back .handler/.gateway/.apiUrl), and
+    // a block reading `this.compute` in its constructor (during that import)
+    // must resolve to it. The factory is supplied by the umbrella
+    // @aws-blocks/blocks (which injects LambdaCompute) via props, so core never
+    // imports the concrete compute class.
+    backend._defaultCompute = props.defaultComputeFactory(backend);
     // file:// URL (not a raw path) so the cache-busting query works on Windows,
     // where an absolute path like `D:\...` is rejected as URL scheme `d:`.
     const backendUrl = pathToFileURL(props.backendCDKPath);
@@ -298,7 +303,7 @@ export class BlocksBackend extends Construct {
     addBlocksStackMetadata(cdk.Stack.of(backend));
 
     // Finalize BB config → S3 (after all BBs have registered their config)
-    finalizeConfigRegistry(backend, backend.handler);
+    finalizeConfigRegistry(backend, backend.executionRole, getComputes(backend));
 
     return backend;
   }

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

@@ -10,16 +10,39 @@
 import { test, describe } from 'node:test';
 import assert from 'node:assert';
 import { RemovalPolicy } from 'aws-cdk-lib';
+import { RetentionDays } from 'aws-cdk-lib/aws-logs';
 import { BlocksPresets } from './blocks-defaults.js';
 
 describe('BlocksPresets', () => {
-	test('sandbox is disposable: DESTROY + deletion protection off', () => {
+	test('sandbox is disposable: DESTROY + deletion protection off + no PITR', () => {
 		assert.strictEqual(BlocksPresets.sandbox.removalPolicy, RemovalPolicy.DESTROY);
 		assert.strictEqual(BlocksPresets.sandbox.deletionProtection, false);
+		assert.strictEqual(BlocksPresets.sandbox.pointInTimeRecovery, false);
 	});
 
-	test('production is durable: RETAIN + deletion protection on', () => {
+	test('production is durable: RETAIN + deletion protection on + PITR on', () => {
 		assert.strictEqual(BlocksPresets.production.removalPolicy, RemovalPolicy.RETAIN);
 		assert.strictEqual(BlocksPresets.production.deletionProtection, true);
+		assert.strictEqual(BlocksPresets.production.pointInTimeRecovery, true);
+	});
+
+	test('sandbox keeps logs briefly', () => {
+		assert.strictEqual(BlocksPresets.sandbox.logRetention, RetentionDays.ONE_WEEK);
+	});
+
+	test('production keeps logs a year', () => {
+		assert.strictEqual(BlocksPresets.production.logRetention, RetentionDays.ONE_YEAR);
+	});
+
+	test('access logging is off by default in BOTH presets (opt-in; mutates an account singleton)', () => {
+		assert.strictEqual(BlocksPresets.sandbox.accessLogging, false);
+		assert.strictEqual(BlocksPresets.production.accessLogging, false);
+	});
+
+	test('sandbox caps tighter (200/400) than production (1000/2000)', () => {
+		assert.strictEqual(BlocksPresets.sandbox.throttling.rateLimit, 200);
+		assert.strictEqual(BlocksPresets.sandbox.throttling.burstLimit, 400);
+		assert.strictEqual(BlocksPresets.production.throttling.rateLimit, 1000);
+		assert.strictEqual(BlocksPresets.production.throttling.burstLimit, 2000);
 	});
 });

package/src/cdk/blocks-defaults.ts

@@ -2,6 +2,20 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { RemovalPolicy } from 'aws-cdk-lib';
+import { RetentionDays } from 'aws-cdk-lib/aws-logs';
+
+/**
+ * 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
+ * connection. `rateLimit` is the steady-state ceiling and `burstLimit` the
+ * token-bucket size for short spikes.
+ */
+export interface BlocksThrottling {
+	/** Steady-state request (or WebSocket message) rate ceiling, per second. */
+	rateLimit: number;
+	/** Token-bucket burst size for short spikes above `rateLimit`. */
+	burstLimit: number;
+}
 
 /**
  * Default values for every Amazon-authored Building Block created within a
@@ -25,6 +39,65 @@ export interface BlocksDefaults {
 	 * well as the CLI, API, and AWS console — until it is turned off.
 	 */
 	deletionProtection: boolean;
+
+	/**
+	 * CORS origins the compute's API accepts, as regular-expression patterns
+	 * matched against the request `Origin` header. Empty means no cross-origin
+	 * requests are allowed. The `sandbox` preset allows localhost so a local dev
+	 * frontend can reach a deployed API; `production` allows none by default.
+	 */
+	allowedOrigins: string[];
+
+	/**
+	 * Whether stateful resources that support continuous backups keep them on by
+	 * default — e.g. DynamoDB Point-in-Time Recovery, letting you restore to any
+	 * second in the retention window. On in `production`, off in `sandbox` (where
+	 * throwaway data isn't worth the backup-storage cost). Blocks whose service
+	 * has no equivalent simply ignore it.
+	 *
+	 * `true` enables backups with the service's default window; `false` disables
+	 * them; `{ retentionDays: n }` enables them and pins the window (a block
+	 * clamps/validates `n` to its service's supported range — DynamoDB PITR is
+	 * 1–35 days). Backups only have a window when on, so the two are one field.
+	 */
+	pointInTimeRecovery: boolean | { retentionDays: number };
+
+	/**
+	 * How long CloudWatch Logs keeps log events written by Blocks-managed log
+	 * groups (the core handler Lambda, migration/GSI Lambdas, hosting compute,
+	 * `bb-logger`, and API Gateway access logs) before expiring them. Without a
+	 * retention set, AWS keeps log events forever, which grows cost unbounded —
+	 * every Blocks-managed log group reads this default so retention is applied
+	 * consistently.
+	 */
+	logRetention: RetentionDays;
+
+	/**
+	 * Request-rate limits applied to every Blocks-managed API Gateway stage: the
+	 * core REST API, the SSR/hosting REST API, and the `bb-realtime` WebSocket
+	 * stage. Protects the backend from runaway clients and caps blast radius.
+	 * The sandbox preset caps tighter (200/400) than production (1000/2000) so a
+	 * disposable stack is well-protected without throttling real production
+	 * traffic. See {@link BlocksThrottling}.
+	 */
+	throttling: BlocksThrottling;
+
+	/**
+	 * Whether to emit structured JSON access logs from every Blocks-managed API
+	 * Gateway stage to a dedicated CloudWatch log group (retention follows
+	 * {@link logRetention}).
+	 *
+	 * **Off by default in both presets** — opt in with a per-stack override
+	 * (`defaults: { ...BlocksPresets.production, accessLogging: true }`). It is
+	 * off by default (rather than on for production) because enabling it
+	 * provisions the account-level API Gateway CloudWatch Logs role, which is an
+	 * account/region-level singleton: a second Blocks stack in the same
+	 * account+region that also enables access logging can repoint that role on
+	 * deploy or, on teardown, leave the survivor's access logging broken.
+	 * Enabling it is therefore safe for **one Blocks stack per region** — see
+	 * `ensureApiGatewayAccount` for the full multi-stack teardown caveat.
+	 */
+	accessLogging: boolean;
 }
 
 /**
@@ -36,14 +109,33 @@ export interface BlocksDefaults {
  * ```
  */
 export const BlocksPresets = {
-	/** Disposable development stacks: tear down cleanly, no delete guard. */
+	/** Disposable development stacks: tear down cleanly, no delete guard, no backups. */
 	sandbox: {
 		removalPolicy: RemovalPolicy.DESTROY,
 		deletionProtection: false,
+		allowedOrigins: ['^https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?$'],
+		pointInTimeRecovery: false,
+		logRetention: RetentionDays.ONE_WEEK,
+		throttling: { rateLimit: 200, burstLimit: 400 },
+		accessLogging: false,
 	},
-	/** Durable, protected posture for permanent deployments. */
+	/**
+	 * Durable, protected posture for permanent deployments. A higher throttle
+	 * ceiling (1000/2000) than sandbox so the default doesn't 429 real
+	 * production traffic — raise it via a per-stack `throttling` override for
+	 * higher-volume APIs.
+	 */
 	production: {
 		removalPolicy: RemovalPolicy.RETAIN,
 		deletionProtection: true,
+		allowedOrigins: [],
+		pointInTimeRecovery: true,
+		logRetention: RetentionDays.ONE_YEAR,
+		throttling: { rateLimit: 1000, burstLimit: 2000 },
+		// Off by default even in production: enabling access logging mutates the
+		// account/region-level API Gateway CloudWatch role (a singleton). Opt in
+		// per stack once you've confirmed a single Blocks stack owns it in the
+		// region — see the `accessLogging` field doc.
+		accessLogging: false,
 	},
 } satisfies Record<string, BlocksDefaults>;