@geekmidas/cloud 1.0.1 → 1.1.0

package/src/sst/Function.ts

@@ -0,0 +1,128 @@
+import type { EnvValidator, ValidationResult } from '@geekmidas/envkit/sst';
+import {
+	type FunctionInfo,
+	flattenManifestField,
+	type ManifestField,
+} from '@geekmidas/manifest';
+import { type GkmLinkable, ResourceType } from './Linkable';
+import { LinkedEnvironment } from './LinkedEnvironment';
+import type { StackType } from './Stack';
+
+/**
+ * `Function` — wraps SST's `sst.aws.Function` with standard env defaults and
+ * before-deploy env-var validation.
+ *
+ * `FunctionProps` extends the native `sst.aws.FunctionArgs`, so every native
+ * option (`handler`, `name`, `nodejs`, `vpc`, `url`, `permissions`, …) passes
+ * through; the construct only merges env defaults, defaults the runtime to
+ * `nodejs24.x` and JSON logging (both overridable), and resolves/validates
+ * `link` from the `links` pool against the required `envVars`.
+ *
+ * Source-only (extends ambient `sst.aws.*`); see docs §2.
+ */
+export class Function<
+		TStage extends string = string,
+		TDomain extends string = string,
+	>
+	extends sst.aws.Function
+	implements GkmLinkable
+{
+	readonly _id!: string;
+	private readonly validator: EnvValidator;
+	private readonly envVars: readonly string[];
+
+	get _type() {
+		return ResourceType.Function;
+	}
+
+	constructor(
+		stack: StackType<TStage, TDomain>,
+		id: string,
+		props: FunctionProps,
+	) {
+		const {
+			links = [],
+			envVars = [],
+			autoValidate = true,
+			environment,
+			runtime,
+			logging,
+			...fnArgs
+		} = props;
+
+		const mergedEnvironment = {
+			...LinkedEnvironment.createBaseEnvironment(stack, id),
+			...environment,
+		};
+
+		const linked = new LinkedEnvironment(links, {
+			whitelist: Object.keys(mergedEnvironment),
+			context: id,
+		});
+		if (autoValidate) {
+			linked.validator.assert(envVars);
+		}
+
+		super(id, {
+			...fnArgs,
+			environment: mergedEnvironment,
+			// Linking is managed via the `links`/`envVars` flow, so this overrides
+			// any native `link` passed through `fnArgs`.
+			link: linked.resolveLink(envVars),
+			runtime: runtime ?? 'nodejs24.x',
+			logging: logging ?? { format: 'json' },
+		});
+
+		this._id = id;
+		this.validator = linked.validator;
+		this.envVars = envVars;
+	}
+
+	/** Re-runs validation and returns the result (does not throw). */
+	validate(): ValidationResult {
+		return this.validator.validate(this.envVars);
+	}
+
+	/**
+	 * Build one `Function` per entry in a `gkm build` manifest's `functions`
+	 * field (flat or partitioned). Shared `props` (e.g. `links`) apply to every
+	 * function.
+	 *
+	 * ```ts
+	 * Function.fromManifest(stack, manifest.functions, { links: [db] });
+	 * ```
+	 */
+	static fromManifest<
+		TStage extends string = string,
+		TDomain extends string = string,
+	>(
+		stack: StackType<TStage, TDomain>,
+		functions: ManifestField<FunctionInfo>,
+		props: Omit<FunctionProps, 'handler'> = {},
+	): Function<TStage, TDomain>[] {
+		return flattenManifestField(functions).map(
+			(fn) =>
+				new Function(stack, fn.name, {
+					...props,
+					name: stack.logicalPrefixedName(fn.name),
+					handler: fn.handler,
+					envVars: fn.environment,
+					timeout: fn.timeout ? `${fn.timeout} seconds` : undefined,
+					memory: fn.memorySize ? `${fn.memorySize} MB` : undefined,
+				}),
+		);
+	}
+}
+
+export interface FunctionProps extends sst.aws.FunctionArgs {
+	/** Required env vars for this function; validated against `links`. */
+	envVars?: readonly string[];
+	/** Pool of linkable resources `envVars` are resolved and validated against. */
+	links?: GkmLinkable[];
+	/**
+	 * Validate `envVars` against the links in the constructor (fails synth before
+	 * deploy on a missing variable).
+	 * @default true
+	 */
+	autoValidate?: boolean;
+}

package/src/sst/Linkable.ts

@@ -0,0 +1,19 @@
+import { ResourceType } from '@geekmidas/envkit/sst';
+
+export { ResourceType };
+
+/**
+ * A linkable resource: an SST component carrying a stable `_id` (its name, used
+ * as the environment-variable prefix) and a `_type` drawn from the shared
+ * `ResourceType` vocabulary in `@geekmidas/envkit/sst`. The same `_type` values
+ * drive the runtime resolvers, so a linked resource resolves to predictable
+ * environment variables — and can be validated before deploy (see the validation
+ * model in `packages/cloud/docs/sst-constructs.md`).
+ *
+ * `_type` is the infra-time analogue of the runtime resource's `type`; the Api
+ * construct bridges the two when validating (`{ [_id]: { type: _type } }`).
+ */
+export interface GkmLinkable {
+	readonly _id: string;
+	readonly _type: ResourceType;
+}

package/src/sst/LinkedEnvironment.ts

@@ -0,0 +1,61 @@
+import { EnvValidator, type LinkRecord } from '@geekmidas/envkit/sst';
+import type { GkmLinkable } from './Linkable';
+import type { StackType } from './Stack';
+
+/**
+ * Shared environment defaults + env-var validation + least-privilege linking for
+ * the Lambda-backed constructs — `Function` (once) and `Api` (per route).
+ * Bridges infra-time links (`_id`/`_type`) to the runtime resolver shape, builds
+ * one `EnvValidator`, and resolves the minimal set of links a required-vars set
+ * needs.
+ *
+ * Used by **composition**, not inheritance: the constructs already extend their
+ * SST base component (`sst.aws.Function` / `sst.aws.ApiGatewayV2`), so they hold
+ * a `LinkedEnvironment` rather than subclassing a common base.
+ */
+export class LinkedEnvironment {
+	readonly validator: EnvValidator;
+	private readonly linkByName: Map<string, GkmLinkable>;
+
+	constructor(
+		links: GkmLinkable[],
+		options: { whitelist: readonly string[]; context?: string },
+	) {
+		this.linkByName = new Map(links.map((link) => [link._id, link]));
+		const linkRecord: LinkRecord = Object.fromEntries(
+			links.map((link) => [link._id, { type: link._type }]),
+		);
+		this.validator = new EnvValidator(linkRecord, {
+			platform: 'aws',
+			whitelist: options.whitelist,
+			context: options.context,
+		});
+	}
+
+	/**
+	 * The standard environment defaults every Lambda-backed construct injects from
+	 * its stack. `serviceName` adds `SERVICE_NAME` (functions set it to their id;
+	 * the API leaves it off). Callers spread their own `environment` over the
+	 * result, so the user's values always win.
+	 */
+	static createBaseEnvironment<TStage extends string, TDomain extends string>(
+		stack: StackType<TStage, TDomain>,
+		serviceName?: string,
+	): Record<string, string> {
+		return {
+			NODE_ENV: 'production',
+			...(serviceName ? { SERVICE_NAME: serviceName } : {}),
+			STAGE: stack.stage,
+			REGION: stack.region,
+			APP_NAME: stack.app.name,
+		};
+	}
+
+	/** The link objects that provide at least one of `envVars` (least privilege). */
+	resolveLink(envVars: readonly string[]): GkmLinkable[] {
+		return this.validator
+			.getProvidersForEnvVars(envVars)
+			.map((name) => this.linkByName.get(name))
+			.filter((link): link is GkmLinkable => link !== undefined);
+	}
+}

package/src/sst/Queue.ts

@@ -0,0 +1,46 @@
+import { type GkmLinkable, ResourceType } from './Linkable';
+import type { StackType } from './Stack';
+
+/**
+ * `Queue` — a linkable SQS queue (wraps `sst.aws.Queue`), the point-to-point
+ * work queue. Link it to a producer and the runtime resolves `<NAME>_URL`,
+ * `<NAME>_ARN`, and a `<NAME>_PUBLISHER_CONNECTION_STRING` (`sqs://?queueUrl=…`)
+ * that `@geekmidas/events`'s `Publisher.fromConnectionString` consumes. Its
+ * single consumer is wired by `QueueSubscriber`.
+ *
+ * SST's native `Queue` link exposes only `url`, so `getSSTLink` is overridden to
+ * also expose `arn` (what the resolver needs). `QueueProps` extends
+ * `sst.aws.QueueArgs`. Source-only (extends ambient `sst.aws.*`); see docs §2.
+ */
+export class Queue<
+		TStage extends string = string,
+		TDomain extends string = string,
+	>
+	extends sst.aws.Queue
+	implements GkmLinkable
+{
+	readonly _id!: string;
+
+	get _type() {
+		return ResourceType.Queue;
+	}
+
+	constructor(
+		_stack: StackType<TStage, TDomain>,
+		name: string,
+		props: QueueProps = {},
+	) {
+		super(name, props);
+		this._id = name;
+	}
+
+	override getSSTLink() {
+		const link = super.getSSTLink();
+		return {
+			...link,
+			properties: { ...link.properties, arn: this.arn },
+		};
+	}
+}
+
+export interface QueueProps extends sst.aws.QueueArgs {}

package/src/sst/Stack.ts

@@ -0,0 +1,55 @@
+import type { App, StageValues } from './App';
+
+/**
+ * Stack context: an `App` scoped to a logical stack name. Created via
+ * `app.stack(name)` (see docs §5). Delegates `stage`/`region`/`domain` to the
+ * app and prefixes resource names with the stack name.
+ */
+export class Stack<
+	TStage extends string = string,
+	TDomain extends string = string,
+> {
+	constructor(
+		readonly app: App<TStage, TDomain>,
+		/** This stack's logical name (e.g. `api`), used in resource prefixes. */
+		readonly name: string,
+	) {}
+
+	get stage(): TStage {
+		return this.app.stage;
+	}
+
+	get region(): string {
+		return this.app.region;
+	}
+
+	get domain(): TDomain {
+		return this.app.domain;
+	}
+
+	/**
+	 * Kebab-cased `{stage}-{appName}-{stackName}-{resource}` physical name.
+	 * Delegates to the app's scheme (so the two can't drift) and includes the app
+	 * name so resources stay unique across apps sharing an account/stage.
+	 */
+	logicalPrefixedName(resource: string): string {
+		return this.app.logicalPrefixedName(`${this.name}-${resource}`);
+	}
+
+	select<T>(values: StageValues<TStage, T>): T {
+		return this.app.select(values);
+	}
+
+	getSubdomain<TSub extends string>(subdomain: TSub) {
+		return this.app.getSubdomain(subdomain);
+	}
+
+	getURL<TSub extends string>(subdomain?: TSub) {
+		return this.app.getURL(subdomain);
+	}
+}
+
+export type StackType<
+	TStage extends string = string,
+	TDomain extends string = string,
+> = Stack<TStage, TDomain>;

package/src/sst/Storage.ts

@@ -0,0 +1,55 @@
+import { type GkmLinkable, ResourceType } from './Linkable';
+import type { StackType } from './Stack';
+
+/**
+ * `Storage` — a linkable S3 bucket (wraps `sst.aws.Bucket`). Link it to a
+ * `Function`/`Api` route and the runtime resolves a `<NAME>_NAME` environment
+ * variable (via the `Bucket` resolver in `@geekmidas/envkit/sst`) holding the
+ * bucket's name — exactly what `@geekmidas/storage`'s `AmazonStorageClient`
+ * consumes:
+ *
+ * ```ts
+ * // app: a service backed by @geekmidas/storage
+ * const storage = {
+ *   serviceName: 'storage' as const,
+ *   async register(env) {
+ *     const { bucket } = env.create((get) => ({
+ *       bucket: get('UPLOADS_NAME').string(),
+ *     })).parse();
+ *     return AmazonStorageClient.create({ bucket });
+ *   },
+ * };
+ *
+ * // infra: provision + link
+ * const uploads = new Storage(stack, 'uploads');
+ * new Function(stack, 'Upload', { handler, links: [uploads], envVars: ['UPLOADS_NAME'] });
+ * ```
+ *
+ * The construct id (`uploads`) is the link's `_id`, which becomes the env-var
+ * prefix; `StorageProps` extends `sst.aws.BucketArgs` so native options pass
+ * through. Source-only (extends ambient `sst.aws.*`); see docs §2.
+ */
+export class Storage<
+		TStage extends string = string,
+		TDomain extends string = string,
+	>
+	extends sst.aws.Bucket
+	implements GkmLinkable
+{
+	readonly _id!: string;
+
+	get _type() {
+		return ResourceType.Bucket;
+	}
+
+	constructor(
+		_stack: StackType<TStage, TDomain>,
+		name: string,
+		props: StorageProps = {},
+	) {
+		super(name, props);
+		this._id = name;
+	}
+}
+
+export interface StorageProps extends sst.aws.BucketArgs {}

package/src/sst/Topic.ts

@@ -0,0 +1,37 @@
+import { type GkmLinkable, ResourceType } from './Linkable';
+import type { StackType } from './Stack';
+
+/**
+ * `Topic` — a linkable SNS topic (wraps `sst.aws.SnsTopic`), the pub/sub fan-out
+ * bus. Link it to a publisher and the runtime resolves `<NAME>_ARN` and a
+ * `<NAME>_PUBLISHER_CONNECTION_STRING` (`sns://?topicArn=…`) that
+ * `@geekmidas/events`'s `Publisher.fromConnectionString` consumes. Subscribers
+ * attach via `TopicSubscriber`/`Subscriber`.
+ *
+ * `StorageProps`-style: `TopicProps` extends `sst.aws.SnsTopicArgs`.
+ * Source-only (extends ambient `sst.aws.*`); see docs §2.
+ */
+export class Topic<
+		TStage extends string = string,
+		TDomain extends string = string,
+	>
+	extends sst.aws.SnsTopic
+	implements GkmLinkable
+{
+	readonly _id!: string;
+
+	get _type() {
+		return ResourceType.SnsTopic;
+	}
+
+	constructor(
+		_stack: StackType<TStage, TDomain>,
+		name: string,
+		props: TopicProps = {},
+	) {
+		super(name, props);
+		this._id = name;
+	}
+}
+
+export interface TopicProps extends sst.aws.SnsTopicArgs {}

package/src/sst/__tests__/LinkedEnvironment.spec.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { App } from '../App';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import { LinkedEnvironment } from '../LinkedEnvironment';
+
+// App/Stack are runtime-pure (they reference SST only via erased type
+// annotations), so they can be constructed directly in tests.
+const stack = new App({
+	name: 'my-app',
+	stage: 'prod',
+	domain: 'example.com',
+	hostedZoneId: 'Z123',
+	region: 'us-east-1',
+}).stack('api');
+
+const db: GkmLinkable = { _id: 'db', _type: ResourceType.Postgres };
+const uploads: GkmLinkable = { _id: 'uploads', _type: ResourceType.Bucket };
+
+describe('LinkedEnvironment', () => {
+	describe('createBaseEnvironment', () => {
+		it('builds the stack env defaults (no SERVICE_NAME without a name)', () => {
+			expect(LinkedEnvironment.createBaseEnvironment(stack)).toEqual({
+				NODE_ENV: 'production',
+				STAGE: 'prod',
+				REGION: 'us-east-1',
+				APP_NAME: 'my-app',
+			});
+		});
+
+		it('adds SERVICE_NAME when a service name is given', () => {
+			const env = LinkedEnvironment.createBaseEnvironment(stack, 'processor');
+			expect(env.SERVICE_NAME).toBe('processor');
+			expect(env.APP_NAME).toBe('my-app');
+		});
+	});
+
+	describe('validation', () => {
+		const linked = new LinkedEnvironment([db, uploads], {
+			whitelist: ['APP_NAME'],
+			context: 'orders-fn',
+		});
+
+		it('exposes link-derived vars, the platform whitelist, and extras', () => {
+			expect(linked.validator.has('DB_HOST')).toBe(true);
+			expect(linked.validator.has('UPLOADS_NAME')).toBe(true);
+			expect(linked.validator.has('AWS_REGION')).toBe(true); // platform: aws
+			expect(linked.validator.has('APP_NAME')).toBe(true); // extra whitelist
+			expect(linked.validator.has('NOPE')).toBe(false);
+		});
+
+		it('validates required vars against the links', () => {
+			expect(linked.validator.validate(['DB_HOST', 'APP_NAME']).valid).toBe(
+				true,
+			);
+			expect(linked.validator.validate(['MISSING_ONE']).valid).toBe(false);
+		});
+	});
+
+	describe('resolveLink (least privilege)', () => {
+		const linked = new LinkedEnvironment([db, uploads], {
+			whitelist: [],
+		});
+
+		it('attaches only the links that provide a requested var', () => {
+			expect(linked.resolveLink(['DB_HOST'])).toEqual([db]);
+		});
+
+		it('attaches multiple links when several are needed', () => {
+			expect(linked.resolveLink(['DB_URL', 'UPLOADS_NAME'])).toEqual([
+				db,
+				uploads,
+			]);
+		});
+
+		it('attaches nothing for a non-link (e.g. platform) var', () => {
+			expect(linked.resolveLink(['AWS_REGION'])).toEqual([]);
+		});
+	});
+});

package/src/sst/__type-tests__/authorizers.type-test.ts

@@ -0,0 +1,72 @@
+// Type-level tests for the Api authorizer generics. Checked by `ts:check:sst`
+// (it's under src/sst and not a *.spec.ts, so the gate type-checks it; vitest
+// ignores it). Each `@ts-expect-error` self-validates: if the enforcement
+// regresses, the now-unused directive becomes a TS error the gate catches.
+
+import { Api } from '../Api';
+import { App } from '../App';
+import { Function } from '../Function';
+
+const stack = new App({
+	name: 'a',
+	stage: 'dev',
+	domain: 'example.com',
+	hostedZoneId: 'Z',
+	region: 'us-east-1',
+}).stack('api');
+
+// Valid: built-ins (`iam`/`none`) plus the declared `jwt` and custom names.
+export const ok = new Api(stack, 'Ok', {
+	authorizers: {
+		jwt: { issuer: 'https://issuer', audiences: ['aud'] },
+		employee: { handler: 'src/employee-auth.handler' },
+	},
+	routes: [
+		{ method: 'GET', path: '/a', handler: 'a.handler', authorizer: 'iam' },
+		{ method: 'GET', path: '/b', handler: 'b.handler', authorizer: 'none' },
+		{ method: 'GET', path: '/c', handler: 'c.handler', authorizer: 'jwt' },
+		{ method: 'GET', path: '/d', handler: 'd.handler', authorizer: 'employee' },
+		{ method: 'GET', path: '/e', handler: 'e.handler' },
+	],
+});
+
+// An undeclared authorizer name is rejected.
+export const badName = new Api(stack, 'BadName', {
+	authorizers: { jwt: { issuer: 'i', audiences: ['a'] } },
+	routes: [
+		{
+			method: 'GET',
+			path: '/x',
+			handler: 'x.handler',
+			// @ts-expect-error 'nope' is not a declared authorizer
+			authorizer: 'nope',
+		},
+	],
+});
+
+// A `jwt` authorizer must supply JWT settings (`audiences` required here).
+export const badJwt = new Api(stack, 'BadJwt', {
+	authorizers: {
+		// @ts-expect-error jwt requires `audiences`
+		jwt: { issuer: 'i' },
+	},
+	routes: [],
+});
+
+// A custom (Lambda) authorizer must supply a `handler`.
+export const badLambda = new Api(stack, 'BadLambda', {
+	authorizers: {
+		// @ts-expect-error custom authorizer requires `handler`
+		employee: { payload: '2.0' },
+	},
+	routes: [],
+});
+
+// A Lambda authorizer `handler` accepts one of our `Function` constructs.
+const authFn = new Function(stack, 'AuthFn', { handler: 'src/auth.handler' });
+export const okFnHandler = new Api(stack, 'OkFn', {
+	authorizers: { employee: { handler: authFn } },
+	routes: [
+		{ method: 'GET', path: '/x', handler: 'x.handler', authorizer: 'employee' },
+	],
+});

package/src/sst/__type-tests__/manifest.type-test.ts

@@ -0,0 +1,77 @@
+// Type-level checks that the `fromManifest` integrators accept the unified
+// `gkm build` manifest shape (`export const manifest = { … } as const`) — both
+// the flat and the partitioned `ManifestField` forms. Checked by `ts:check:sst`.
+
+import type { Manifest, ManifestField, RouteInfo } from '@geekmidas/manifest';
+import { Api } from '../Api';
+import { App } from '../App';
+import { Cron } from '../Cron';
+import { Function } from '../Function';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+
+const stack = new App({
+	name: 'a',
+	stage: 'dev',
+	domain: 'example.com',
+	hostedZoneId: 'Z',
+	region: 'us-east-1',
+}).stack('api');
+
+const db: GkmLinkable = { _id: 'db', _type: ResourceType.Postgres };
+
+// Mirrors a generated `manifest/aws.ts` — one object, `as const`.
+const manifest = {
+	routes: [
+		{
+			path: '/users/{id}',
+			method: 'GET',
+			handler: 'users.handler',
+			authorizer: 'none',
+			environment: ['DB_HOST'],
+			timeout: 30,
+			memorySize: 1024,
+		},
+	],
+	functions: [
+		{ name: 'worker', handler: 'worker.handler', environment: ['DB_URL'] },
+	],
+	crons: [
+		{ name: 'nightly', handler: 'nightly.handler', schedule: 'rate(1 day)' },
+	],
+} as const satisfies Manifest;
+
+// Each integrator takes the manifest *field*.
+export const api = Api.fromManifest(stack, 'Api', manifest.routes, {
+	links: [db],
+	authorizers: { jwt: { issuer: 'https://i', audiences: ['a'] } },
+});
+export const workers = Function.fromManifest(stack, manifest.functions, {
+	links: [db],
+});
+export const crons = Cron.fromManifest(stack, manifest.crons, { links: [db] });
+
+// The partitioned `ManifestField` form is also accepted.
+const partitionedRoutes = {
+	admin: [
+		{
+			path: '/admin',
+			method: 'GET',
+			handler: 'admin.handler',
+			authorizer: 'iam',
+		},
+	],
+	default: [
+		{
+			path: '/health',
+			method: 'GET',
+			handler: 'health.handler',
+			authorizer: 'none',
+		},
+	],
+} satisfies ManifestField<RouteInfo>;
+export const partitionedApi = Api.fromManifest(
+	stack,
+	'PartApi',
+	partitionedRoutes,
+	{ links: [db] },
+);

package/src/sst/__type-tests__/messaging.type-test.ts

@@ -0,0 +1,29 @@
+// Type-level check that Queue/Topic are linkables whose publisher connection
+// strings validate. Checked by `ts:check:sst`; vitest ignores it.
+
+import { App } from '../App';
+import { Function } from '../Function';
+import { Queue } from '../Queue';
+import { Topic } from '../Topic';
+
+const stack = new App({
+	name: 'shop',
+	stage: 'dev',
+	domain: 'example.com',
+	hostedZoneId: 'Z',
+	region: 'us-east-1',
+}).stack('events');
+
+const orders = new Queue(stack, 'orders');
+const events = new Topic(stack, 'events');
+
+// A producer linked to both resolves each resource's publisher connection
+// string (namespaced by name) — env validation passes for both.
+export const producer = new Function(stack, 'Producer', {
+	handler: 'producer.handler',
+	links: [orders, events],
+	envVars: [
+		'ORDERS_PUBLISHER_CONNECTION_STRING',
+		'EVENTS_PUBLISHER_CONNECTION_STRING',
+	],
+});

package/src/sst/__type-tests__/storage.type-test.ts

@@ -0,0 +1,24 @@
+// Type-level check that Storage is a linkable usable in a Function's links.
+// Checked by `ts:check:sst`; vitest ignores it.
+
+import { App } from '../App';
+import { Function } from '../Function';
+import { Storage } from '../Storage';
+
+const stack = new App({
+	name: 'a',
+	stage: 'dev',
+	domain: 'example.com',
+	hostedZoneId: 'Z',
+	region: 'us-east-1',
+}).stack('files');
+
+const uploads = new Storage(stack, 'uploads');
+
+// A Storage is a GkmLinkable, so it can be linked; `UPLOADS_NAME` is the env var
+// its `Bucket` resolver yields and what `@geekmidas/storage` consumes.
+export const upload = new Function(stack, 'Upload', {
+	handler: 'upload.handler',
+	links: [uploads],
+	envVars: ['UPLOADS_NAME'],
+});