@aws-blocks/core 0.2.0 → 0.3.0

package/src/cdk/index.ts

@@ -16,8 +16,15 @@ import { setupBlocksInfra, BlocksBackend, assertCdkConditionActive } from './blo
 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 type { DefaultComputeFactory, LambdaShapedCompute } from './compute/default-compute-factory.js';
 
-export { BlocksBackend, type BlocksBackendProps } from './blocks-backend.js';
+export {
+	BlocksBackend,
+	type BlocksBackendProps,
+	type CoreBlocksBackendProps,
+	SHARED_HANDLER_TIMEOUT_SECONDS,
+} from './blocks-backend.js';
 export { DEFAULT_NODE_RUNTIME } from './node-version.js';
 export { blocksNodejsBundling } from './bundling.js';
 export { SandboxDisableDeletionProtection } from './mixins.js';
@@ -30,16 +37,51 @@ export { synthGuard } from './synth-guard.js';
 export type { ScopeOptions } from '../index.js';
 export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
 
+/**
+ * Core's `create()` props: the public {@link BlocksStackProps} plus the required
+ * `defaultComputeFactory`. The umbrella (`@aws-blocks/blocks`) supplies the
+ * factory (which builds a `LambdaCompute`) by spreading it onto the customer's
+ * props; customers use {@link BlocksStackProps} and never set the factory.
+ *
+ * Kept separate (rather than a `create()` argument) so the factory travels with
+ * the props object and core stays free of any concrete compute class.
+ *
+ * @internal
+ */
+export interface CoreBlocksStackProps extends BlocksStackProps {
+  /** Builds the stack's default compute. Injected by `@aws-blocks/blocks`. */
+  defaultComputeFactory: DefaultComputeFactory;
+}
+
 export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
   public readonly id: string;
-  public readonly apiUrl: string;
-  public readonly gateway: cdk.aws_apigateway.RestApi;
-  public readonly handler: cdk.aws_lambda_nodejs.NodejsFunction;
   public readonly backendHandlerPath: 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. */
   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(): cdk.aws_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;
+  }
+
+  private requireDefaultCompute(): LambdaShapedCompute {
+    if (!this._defaultCompute) {
+      throw new Error('Blocks stack not fully initialized — access .handler/.gateway/.apiUrl after BlocksStack.create() resolves.');
+    }
+    return this._defaultCompute as LambdaShapedCompute;
+  }
 
   private constructor(scope: Construct, id: string, props: BlocksStackProps) {
     super(scope, id, props);
@@ -51,13 +93,10 @@ export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
     (globalThis as any).CURRENT_BLOCKS_STACK = this;
 
     const infra = setupBlocksInfra(this, props, id);
-    this.handler = infra.handler;
-    this.gateway = infra.gateway;
-    this.apiUrl = infra.apiUrl;
     this.executionRole = infra.executionRole;
   }
 
-  static async create(scope: Construct, id: string, props: BlocksStackProps) {
+  static async create(scope: Construct, id: string, props: CoreBlocksStackProps) {
     assertCdkConditionActive();
 
     // Detect ambient pipeline stage scope set by Pipeline appFile imports
@@ -65,6 +104,13 @@ export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
     const actualScope = pipelineScope || scope;
 
     const stack = new BlocksStack(actualScope, 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.
+    stack._defaultCompute = props.defaultComputeFactory(stack);
     // 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);
@@ -104,6 +150,15 @@ export class Scope extends Construct {
    */
   private readonly root: BlocksStack | BlocksBackend;
 
+  /**
+   * Compute assigned at this node. Applies to this block and is inherited by
+   * descendants (a nearer assignment wins). Covers both a handler assigned to a
+   * specific compute and a scope-level default for its subtree. Internal until
+   * the customer-facing surface exists.
+   * @internal
+   */
+  _compute?: Compute;
+
   constructor(id: string, options?: ScopeOptions) {
     const parent = options?.parent || (globalThis as any).CURRENT_BLOCKS_STACK;
     super(parent, id);
@@ -144,6 +199,27 @@ export class Scope extends Construct {
     return this.root.executionRole;
   }
 
+  /**
+   * The compute this block runs on: the nearest `_compute` assigned on this
+   * block or an ancestor scope, else the owning stack/backend's default compute.
+   *
+   * For any app that doesn't assign a compute, this always resolves to the
+   * default — so reads are a no-op refactor. `_compute` is internal
+   * (test/framework) until the customer-facing surface exists; there is no
+   * public option to set it yet.
+   */
+  get compute(): Compute {
+    for (let current: ScopeParent | undefined = this; current; current = (current as Scope).parent) {
+      const assigned = (current as Scope)._compute;
+      if (assigned) return assigned;
+    }
+    const defaultCompute = this.root._defaultCompute;
+    if (!defaultCompute) {
+      throw new Error('Default compute not initialized — BlocksStack/BlocksBackend.create() must run before resolving `compute`.');
+    }
+    return defaultCompute;
+  }
+
   /**
    * The backend entry file the owning BlocksStack/BlocksBackend runs — the
    * single handler entry shared across the whole app.

package/src/cdk/internal.ts

@@ -24,6 +24,7 @@
  */
 
 export { Compute } from './compute/compute.js';
+export type { DefaultComputeFactory } from './compute/default-compute-factory.js';
 // Reserved `/aws-blocks` path segment, needed by concrete computes (e.g.
 // LambdaCompute in @aws-blocks/bb-lambda-compute) to build their API route tree.
 export { BLOCKS_NAMESPACE } from '../constants.js';

package/src/hosting-secrets.test.ts

@@ -0,0 +1,106 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { config, secret } from '@aws-blocks/hosting';
+import {
+	collectSynthMarkers,
+	partitionEnvironment,
+	resolveDomainNames,
+	resolveSecretsAtSynth,
+} from './hosting-secrets.js';
+
+void describe('partitionEnvironment()', () => {
+	void it('splits plain / managed (secret+config)', () => {
+		const { plain, managed } = partitionEnvironment({
+			FLAG: 'on',
+			STRIPE_KEY: secret('STRIPE_KEY'),
+			FEATURE_FLAGS: config('FEATURE_FLAGS'),
+		});
+		assert.deepStrictEqual(plain, { FLAG: 'on' });
+		assert.deepStrictEqual(managed.map((m) => `${m.key}:${m.kind}`).sort(), [
+			'FEATURE_FLAGS:config',
+			'STRIPE_KEY:secret',
+		]);
+	});
+
+	void it('rejects env key / marker key mismatch', () => {
+		assert.throws(
+			() => partitionEnvironment({ STRIPE_KEY: secret('OTHER') }),
+			/must match the environment variable name/,
+		);
+	});
+
+	void it('handles undefined', () => {
+		const { plain, managed, byo } = partitionEnvironment(undefined);
+		assert.deepStrictEqual(plain, {});
+		assert.strictEqual(managed.length, 0);
+		assert.strictEqual(byo.length, 0);
+	});
+});
+
+void describe('collectSynthMarkers()', () => {
+	void it('gathers domain markers, deduped by key', () => {
+		const markers = collectSynthMarkers(['example.com', config('DOMAIN_PROD'), config('DOMAIN_PROD')]);
+		assert.deepStrictEqual(
+			markers.map((m) => m.key),
+			['DOMAIN_PROD'],
+		);
+	});
+	void it('returns nothing when no markers', () => {
+		assert.deepStrictEqual(collectSynthMarkers('example.com'), []);
+		assert.deepStrictEqual(collectSynthMarkers(undefined), []);
+	});
+});
+
+void describe('resolveSecretsAtSynth() — Blocks namespaces', () => {
+	void it('config marker resolves under /blocks/config (SSM leading-slash)', async () => {
+		const seen: string[] = [];
+		const resolved = await resolveSecretsAtSynth([config('DOMAIN_PROD')], async (name) => {
+			seen.push(name);
+			return 'prod.example.com';
+		});
+		assert.deepStrictEqual(seen, ['/blocks/config/DOMAIN_PROD']);
+		assert.strictEqual(resolved.get('DOMAIN_PROD'), 'prod.example.com');
+	});
+
+	void it('secret marker resolves under /blocks/secrets (Secrets Manager slash-free)', async () => {
+		const seen: string[] = [];
+		await resolveSecretsAtSynth([secret('API_KEY')], async (name) => {
+			seen.push(name);
+			return 'k';
+		});
+		assert.deepStrictEqual(seen, ['blocks/secrets/API_KEY']);
+	});
+
+	void it('throws an actionable error when a value is not set', async () => {
+		await assert.rejects(
+			resolveSecretsAtSynth([config('DOMAIN_PROD')], async () => {
+				const e = new Error('not found');
+				e.name = 'ParameterNotFound';
+				throw e;
+			}),
+			/config 'DOMAIN_PROD' is referenced/,
+		);
+	});
+});
+
+void describe('resolveDomainNames()', () => {
+	void it('replaces markers with resolved literals, preserving shape', () => {
+		const resolved = new Map([['DOMAIN_PROD', 'prod.example.com']]);
+		assert.strictEqual(resolveDomainNames(config('DOMAIN_PROD'), resolved), 'prod.example.com');
+		assert.deepStrictEqual(resolveDomainNames(['www.example.com', config('DOMAIN_PROD')], resolved), [
+			'www.example.com',
+			'prod.example.com',
+		]);
+	});
+
+	void it('throws if a marker reached the sync path unresolved', () => {
+		assert.throws(() => resolveDomainNames(config('DOMAIN_PROD'), new Map()), /requires async resolution/);
+	});
+
+	void it('passes literal domains through untouched', () => {
+		assert.strictEqual(resolveDomainNames('example.com', new Map()), 'example.com');
+	});
+});

package/src/hosting-secrets.ts

@@ -0,0 +1,106 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Resolution glue between the dependency-free `secret()` / `config()` markers
+ * (defined in `@aws-blocks/hosting`) and the `Hosting` CDK block.
+ *
+ * Delegates to the shared `@aws-blocks/hosting` engine, pinning only the Blocks
+ * namespaces (`/blocks/secrets`, `/blocks/config`). The store is derived from the
+ * marker's kind (`secret` → Secrets Manager, `config` → SSM), and BYO
+ * `ISecret`/`IParameter` handles are wired identically.
+ *
+ * @module
+ */
+
+import type { ManagedValue } from '@aws-blocks/hosting';
+import {
+	type ByoBinding,
+	type DomainNameInput as LeafDomainNameInput,
+	type EnvValue as LeafEnvValue,
+	assertMarkersExistAtSynth as leafAssertMarkersExistAtSynth,
+	collectSynthMarkers as leafCollectSynthMarkers,
+	partitionEnvironment as leafPartitionEnvironment,
+	resolveDomainNames as leafResolveDomainNames,
+	resolveSecretsAtSynth as leafResolveSecretsAtSynth,
+	type SecretFetcher,
+	type StoreConfig,
+	wireByo as leafWireByo,
+	wireManagedValue as leafWireManagedValue,
+} from '@aws-blocks/hosting/constructs';
+import type * as cdk from 'aws-cdk-lib';
+import { blocksStoreConfig } from './secret-naming.js';
+
+/**
+ * Layer a caller's per-kind store config over the pinned Blocks defaults. Shallow
+ * and per-kind: the Blocks `/blocks/*` prefix stays the default, but any field the
+ * app sets (`prefix`, `stage`, `cacheTtlSeconds`) wins.
+ */
+function mergeBlocksStoreConfig(override?: StoreConfig): StoreConfig {
+	const base = blocksStoreConfig();
+	if (!override) return base;
+	return {
+		secretStore: { ...base.secretStore, ...override.secretStore },
+		configStore: { ...base.configStore, ...override.configStore },
+	};
+}
+
+/** A `compute.environment` value: a literal, a managed marker, or a BYO CDK handle. */
+export type EnvValue = LeafEnvValue;
+
+/** A custom-domain name: a literal, a managed marker, or a mix in an array. */
+export type DomainNameInput = LeafDomainNameInput;
+
+/** Split an environment map into plain literals, managed markers, and BYO handles. */
+export function partitionEnvironment(environment: Record<string, EnvValue> | undefined): {
+	plain: Record<string, string>;
+	managed: ManagedValue[];
+	byo: ByoBinding[];
+} {
+	return leafPartitionEnvironment(environment);
+}
+
+/** Every managed marker requiring a synth-time fetch (domain markers only). */
+export function collectSynthMarkers(domainName: DomainNameInput | undefined): ManagedValue[] {
+	return leafCollectSynthMarkers(domainName);
+}
+
+/**
+ * Resolve managed markers to plaintext at synth time under the Blocks namespaces.
+ * Throws a clear, actionable error if a referenced value was never set. An optional
+ * `storeConfig` overrides the pinned Blocks prefix/stage per kind.
+ */
+export async function resolveSecretsAtSynth(
+	markers: ManagedValue[],
+	fetcher?: SecretFetcher,
+	storeConfig?: StoreConfig,
+): Promise<Map<string, string>> {
+	return leafResolveSecretsAtSynth(markers, { ...mergeBlocksStoreConfig(storeConfig), fetcher });
+}
+
+/** Resolve domain markers to literals using the synth-resolved value map. */
+export function resolveDomainNames(domainName: DomainNameInput, resolved: Map<string, string>): string | string[] {
+	return leafResolveDomainNames(domainName, resolved);
+}
+
+/**
+ * Fail synth (deploy) when a referenced `environment` marker has no value set —
+ * existence only, never fetching the value. Uses the Blocks namespaces (with an
+ * optional per-kind `storeConfig` override), matching how the values are wired.
+ */
+export async function assertMarkersExistAtSynth(markers: ManagedValue[], storeConfig?: StoreConfig): Promise<void> {
+	return leafAssertMarkersExistAtSynth(markers, mergeBlocksStoreConfig(storeConfig));
+}
+
+/**
+ * Wire a runtime managed marker under the Blocks namespace (store from kind). An
+ * optional `storeConfig` overrides the pinned prefix/stage/cacheTtlSeconds per kind.
+ */
+export function wireManagedValue(fn: cdk.aws_lambda.Function, marker: ManagedValue, storeConfig?: StoreConfig): void {
+	leafWireManagedValue(fn, marker, mergeBlocksStoreConfig(storeConfig));
+}
+
+/** Wire a runtime BYO handle (grant + inject locator). Honors an optional `storeConfig`. */
+export function wireByo(fn: cdk.aws_lambda.Function, binding: ByoBinding, storeConfig?: StoreConfig): void {
+	leafWireByo(fn, binding, mergeBlocksStoreConfig(storeConfig));
+}