@geekmidas/cloud 10.0.0-alpha.37 → 10.0.0-alpha.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/cloud",
-  "version": "10.0.0-alpha.37",
+  "version": "10.0.0-alpha.39",
   "type": "module",
   "files": [
     "dist",
@@ -41,8 +41,8 @@
   },
   "dependencies": {
     "lodash.snakecase": "~4.1.1",
-    "@geekmidas/envkit": "10.0.0-alpha.37",
-    "@geekmidas/manifest": "10.0.0-alpha.37"
+    "@geekmidas/envkit": "10.0.0-alpha.39",
+    "@geekmidas/manifest": "10.0.0-alpha.39"
   },
   "devDependencies": {
     "@types/lodash.get": "~4.4.9",
@@ -58,10 +58,10 @@
     "@pulumi/aws": ">=7.47.0",
     "@pulumi/random": ">=4.21.2",
     "@pulumi/pulumi": ">=3.263.0",
-    "@geekmidas/manifest": "^10.0.0-alpha.37",
-    "@geekmidas/storage": "^10.0.0-alpha.37",
-    "@geekmidas/events": "^10.0.0-alpha.37",
-    "@geekmidas/db": "^10.0.0-alpha.37"
+    "@geekmidas/manifest": "^10.0.0-alpha.39",
+    "@geekmidas/storage": "^10.0.0-alpha.39",
+    "@geekmidas/events": "^10.0.0-alpha.39",
+    "@geekmidas/db": "^10.0.0-alpha.39"
   },
   "peerDependenciesMeta": {
     "@geekmidas/manifest": {

package/src/sst/__tests__/fromManifest.integration.spec.ts

@@ -44,6 +44,12 @@ function manifest(): ConstructManifest {
 			id: 'Emails',
 			fifo: true,
 			provides: keys('Emails', 'queue', ['publisherConnectionString']),
+			// The queue's one consumer, as the build folds it in.
+			worker: {
+				id: 'EmailsWorker',
+				handler: '.gkm/aws-lambda/queues/emails.handler',
+				dependencies: [{ target: 'Uploads', kind: 'objects' }],
+			},
 		},
 		Users: {
 			kind: 'topic',
@@ -172,6 +178,27 @@ describe('fromManifest', () => {
 		expect(argsOf(provisioned.Orders)).toMatchObject({ vpc, version: '18' });
 	});
 
+	it('subscribes each queue’s one consumer, linked to the queue and what it reaches', () => {
+		vi.spyOn(console, 'log').mockImplementation(() => {});
+
+		const provisioned = fromManifest(stack, manifest(), overrides, {
+			cache: 'db',
+			email: 'smtp',
+		});
+		const { subscribed } = provisioned.Emails as unknown as {
+			subscribed: { subscriber: { handler: string; link: unknown[] } }[];
+		};
+
+		expect(subscribed).toHaveLength(1);
+		expect(subscribed[0]?.subscriber.handler).toBe(
+			'.gkm/aws-lambda/queues/emails.handler',
+		);
+		expect(subscribed[0]?.subscriber.link).toEqual([
+			provisioned.Emails,
+			provisioned.Uploads,
+		]);
+	});
+
 	it('builds the site against the addresses its edges resolve to', () => {
 		vi.spyOn(console, 'log').mockImplementation(() => {});
 

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

@@ -1,13 +1,15 @@
 import { resolveEnvKeys } from '@geekmidas/envkit/sst';
-import { providedKeyFor, provideKey } from '@geekmidas/manifest';
+import { NoUrlForStage, providedKeyFor, provideKey } from '@geekmidas/manifest';
 import { describe, expect, it } from 'vitest';
 import { ObjectStorage } from '../aws/ObjectStorage';
 import { type ProvidesMismatch, UnknownDeclarationKind } from '../errors';
 import {
 	assertProvides,
+	PROVISIONED_ELSEWHERE,
 	type ProvisionedManifest,
 	provisionerFor,
 	resolveEdges,
+	subscribeConsumers,
 } from '../fromManifest';
 
 /**
@@ -249,18 +251,152 @@ describe('the key a provided role becomes', () => {
 describe('Credential', () => {
 	it('provides under the role the declaration named', async () => {
 		// The role *is* the contract: providing `value` against a declared
-		// `STRIPE_CREDENTIAL` supplies `STRIPE_VALUE`, and assertProvides
+		// `STRIPE_CREDENTIALS` supplies `STRIPE_VALUE`, and assertProvides
 		// rejects the stack at synth. Which is the check working.
 		const { Credential } = await import('../aws/Credential');
 
 		expect(
 			Object.keys(new Credential({} as never, 'Stripe').provides()),
-		).toEqual(['credential']);
+		).toEqual(['credentials']);
 	});
 
 	it('agrees with what the construct declares', () => {
-		expect(providedKeyFor('Stripe', 'credential', 'credential')).toBe(
-			'STRIPE_CREDENTIAL',
+		expect(providedKeyFor('Stripe', 'credential', 'credentials')).toBe(
+			'STRIPE_CREDENTIALS',
 		);
 	});
+
+	it('links under the key the construct reads, not the secret’s bare name', async () => {
+		const { Credential } = await import('../aws/Credential');
+		const stripe = new Credential({} as never, 'Stripe');
+
+		expect(resolveEnvKeys({ Stripe: { type: stripe._type } })).toEqual([
+			'STRIPE_CREDENTIALS',
+		]);
+		expect(stripe.getSSTLink().properties).toEqual(stripe.provides());
+	});
+
+	it('is what a function depending on it is linked to', async () => {
+		const { Credential } = await import('../aws/Credential');
+		const stripe = new Credential({} as never, 'Stripe');
+
+		const { link, envKeys } = resolveEdges(
+			[{ target: 'Stripe', kind: 'credential' }],
+			{ Stripe: stripe },
+		);
+
+		expect(link).toEqual([stripe]);
+		expect(envKeys).toEqual(['STRIPE_CREDENTIALS']);
+	});
+});
+
+describe('ExternalApi', () => {
+	const stack = (stage: string) => ({ stage }) as never;
+
+	it('provides the URL for its stage and its credentials, under the declared keys', async () => {
+		const { ExternalApi } = await import('../aws/ExternalApi');
+		const payfast = new ExternalApi(stack('production'), 'PayFast', {
+			url: {
+				production: 'https://www.payfast.co.za',
+				default: 'https://sandbox.payfast.co.za',
+			},
+		});
+
+		expect(payfast.provides().url).toBe('https://www.payfast.co.za');
+		expect(
+			Object.keys(payfast.provides()).map((role) =>
+				providedKeyFor('PayFast', 'external-api', role),
+			),
+		).toEqual(['PAY_FAST_URL', 'PAY_FAST_CREDENTIALS']);
+	});
+
+	it('falls back to the default URL for a stage it does not name', async () => {
+		const { ExternalApi } = await import('../aws/ExternalApi');
+		const payfast = new ExternalApi(stack('staging'), 'PayFast', {
+			url: {
+				production: 'https://www.payfast.co.za',
+				default: 'https://sandbox.payfast.co.za',
+			},
+		});
+
+		expect(payfast.provides().url).toBe('https://sandbox.payfast.co.za');
+	});
+
+	it('fails synth for a stage it has no URL for', async () => {
+		const { ExternalApi } = await import('../aws/ExternalApi');
+
+		expect(
+			() =>
+				new ExternalApi(stack('staging'), 'PayFast', {
+					url: { production: 'https://www.payfast.co.za' },
+				}),
+		).toThrow(NoUrlForStage);
+	});
+
+	it('flattens into the same keys at runtime', () => {
+		expect(
+			resolveEnvKeys({ PayFast: { type: 'gkm:aws:ExternalApi' } }).sort(),
+		).toEqual(['PAY_FAST_CREDENTIALS', 'PAY_FAST_URL']);
+	});
+});
+
+describe('a queue’s one consumer', () => {
+	it('is subscribed from the handler the build wrote, linked to what it depends on', () => {
+		const consumed: { handler: string; link?: unknown[] }[] = [];
+		const uploads = { _id: 'Uploads', _type: 'sst.aws.Bucket' };
+		const provisioned = {
+			Uploads: uploads,
+			Emails: {
+				_id: 'Emails',
+				_type: 'sst.aws.Queue',
+				consume: (consumer: { handler: string; link?: unknown[] }) =>
+					consumed.push(consumer),
+			},
+		} as unknown as ProvisionedManifest;
+
+		subscribeConsumers(
+			{
+				Uploads: { kind: 'objects', id: 'Uploads', provides: ['UPLOADS_URL'] },
+				Emails: {
+					kind: 'queue',
+					id: 'Emails',
+					provides: ['EMAILS_PUBLISHER_CONNECTION_STRING'],
+					worker: {
+						id: 'EmailsWorker',
+						handler: '.gkm/aws-lambda/queues/emails.handler',
+						dependencies: [{ target: 'Uploads', kind: 'objects' }],
+					},
+				},
+			} as never,
+			provisioned,
+		);
+
+		expect(consumed).toEqual([
+			{ handler: '.gkm/aws-lambda/queues/emails.handler', link: [uploads] },
+		]);
+	});
+
+	it('subscribes through SST, with the queue itself linked', async () => {
+		const { Queue } = await import('../aws/Queue');
+		const queue = new Queue({} as never, 'Emails');
+
+		queue.consume({ handler: 'emails.handler', link: [], batchSize: 5 });
+
+		const [{ subscriber, args }] = (
+			queue as unknown as { subscribed: { subscriber: any; args: unknown }[] }
+		).subscribed;
+		expect(subscriber.handler).toBe('emails.handler');
+		expect(subscriber.link).toEqual([queue]);
+		expect(args).toEqual({ batch: { size: 5 } });
+	});
+});
+
+describe('kinds provisioned elsewhere', () => {
+	it('skips a worker, which is a process rather than a resource', () => {
+		// A worker in the manifest used to throw UnknownDeclarationKind at synth,
+		// so any app with background work could not be deployed to AWS at all.
+		expect(PROVISIONED_ELSEWHERE.has('worker')).toBe(true);
+		expect(PROVISIONED_ELSEWHERE.has('mobile-app')).toBe(true);
+		expect(PROVISIONED_ELSEWHERE.has('queue')).toBe(false);
+	});
 });

package/src/sst/aws/Credential.ts

@@ -1,4 +1,5 @@
-import { Secret, type SecretProps } from './Secret';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import type { StackType } from '../Stack';
 
 /**
  * `Credential` — a third-party credential SST holds, and the infra half of the
@@ -8,21 +9,53 @@ import { Secret, type SecretProps } from './Secret';
  * the lifecycle rather than the mechanism: a secret is generated and rotated by
  * the platform, while a credential is issued by someone else and has a shape
  * the construct validates on the way in. Both are values you set out of band
- * with `sst secret set`.
+ * with `sst secret set`, under the construct's id.
  *
- * The role is `credential` rather than `value`, and that is not cosmetic. The
+ * The role is `credentials` rather than `value`, and that is not cosmetic. The
  * role *is* the contract — `providedKeyFor` turns it into the key the app
  * declared — so a credential providing `value` would supply `STRIPE_VALUE`
- * against a declared `STRIPE_CREDENTIAL`, and `assertProvides` would reject the
- * stack at synth. Which is the check working; renaming here is the fix.
+ * against a declared `STRIPE_CREDENTIALS`, and `assertProvides` would reject
+ * the stack at synth.
+ *
+ * It holds an `sst.Secret` rather than being one, and reports its own type,
+ * for the same reason one level down: the type decides the keys a link
+ * resolves to. As an SST secret it resolved to `STRIPE`, so a function that
+ * declared `STRIPE_CREDENTIALS` was linked to nothing.
  */
 export class Credential<
 	TStage extends string = string,
 	TDomain extends string = string,
-> extends Secret<TStage, TDomain> {
-	override provides(): Record<string, $util.Input<string>> {
-		return { credential: this.value };
+> implements GkmLinkable
+{
+	readonly _id: string;
+
+	private readonly secret: sst.Secret;
+
+	get _type() {
+		return ResourceType.Credential;
+	}
+
+	constructor(
+		_stack: StackType<TStage, TDomain>,
+		name: string,
+		props: CredentialProps = {},
+	) {
+		this._id = name;
+		// The id itself, as it always was: a value already set with
+		// `sst secret set Stripe …` is still the one read.
+		this.secret = new sst.Secret(name, props.placeholder);
+	}
+
+	provides(): Record<string, $util.Input<string>> {
+		return { credentials: this.secret.value };
+	}
+
+	getSSTLink() {
+		return { properties: { ...this.provides() } };
 	}
 }
 
-export interface CredentialProps extends SecretProps {}
+export interface CredentialProps {
+	/** A value until one is set, for a preview stage. */
+	placeholder?: string;
+}

package/src/sst/aws/ExternalApi.ts

@@ -0,0 +1,58 @@
+import { externalApiUrl } from '@geekmidas/manifest';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import type { StackType } from '../Stack';
+
+/**
+ * `ExternalApi` — the infra half of the `external-api` kind.
+ *
+ * Nothing is provisioned: the API is somebody else's. What this holds is the
+ * two facts a function needs to call it on this stage — the URL the
+ * declaration names for it, and the credentials the provider issued, kept as
+ * an SST secret and set out of band:
+ *
+ * ```
+ * sst secret set PolarCredentials '{"clientId":"…","clientSecret":"…"}' --stage prod
+ * ```
+ */
+export class ExternalApi<
+	TStage extends string = string,
+	TDomain extends string = string,
+> implements GkmLinkable
+{
+	readonly _id: string;
+
+	private readonly url: string;
+
+	private readonly credentials: sst.Secret;
+
+	get _type() {
+		return ResourceType.ExternalApi;
+	}
+
+	constructor(
+		stack: StackType<TStage, TDomain>,
+		name: string,
+		props: ExternalApiProps,
+	) {
+		this._id = name;
+		// Read at synth, so a stage the declaration has no URL for fails the
+		// deploy — with the stage named — rather than the first request.
+		this.url = externalApiUrl({ id: name, url: props.url }, stack.stage);
+		this.credentials = new sst.Secret(`${name}Credentials`, props.placeholder);
+	}
+
+	provides(): Record<string, $util.Input<string>> {
+		return { url: this.url, credentials: this.credentials.value };
+	}
+
+	getSSTLink() {
+		return { properties: { ...this.provides() } };
+	}
+}
+
+export interface ExternalApiProps {
+	/** The declaration's `url` — one for every stage, or one per stage name. */
+	url: string | Readonly<Record<string, string>>;
+	/** A value for the credentials secret until one is set, for a preview stage. */
+	placeholder?: string;
+}

package/src/sst/aws/Queue.ts

@@ -11,7 +11,8 @@ import type { StackType } from '../Stack';
  * 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`.
+ * one consumer — the handler the queue was declared with — is subscribed by
+ * {@link Queue.consume}.
  *
  * SST's native `Queue` link exposes only `url`, so `getSSTLink` is overridden to
  * also expose `arn` (what the resolver needs). `QueueProps` extends
@@ -73,6 +74,25 @@ export class Queue<
 		};
 	}
 
+	/**
+	 * Subscribe the queue's one consumer: a Lambda running `handler`, linked to
+	 * what the consumer depends on and to this queue itself.
+	 *
+	 * A queue has exactly one consumer, so this is called once per queue — by
+	 * `fromManifest`, from the handler the build wrote for it.
+	 */
+	consume(consumer: QueueConsumer) {
+		return this.subscribe(
+			{
+				handler: consumer.handler,
+				link: [this, ...(consumer.link ?? [])],
+				runtime: 'nodejs24.x',
+				...(consumer.timeout ? { timeout: consumer.timeout } : {}),
+			},
+			consumer.batchSize ? { batch: { size: consumer.batchSize } } : {},
+		);
+	}
+
 	override getSSTLink() {
 		const link = super.getSSTLink();
 		return {
@@ -82,6 +102,16 @@ export class Queue<
 	}
 }
 
+/** The queue's one consumer, as {@link Queue.consume} subscribes it. */
+export interface QueueConsumer {
+	/** The built handler — `.gkm/aws-lambda/queues/emails.handler`. */
+	handler: string;
+	/** What the consumer depends on; the queue itself is always linked. */
+	link?: unknown[];
+	timeout?: `${number} seconds` | `${number} minutes`;
+	batchSize?: number;
+}
+
 export interface QueueProps extends sst.aws.QueueArgs {
 	/**
 	 * The physical queue name, where the auto-generated one will not do.

package/src/sst/fromManifest.ts

@@ -45,6 +45,7 @@ import { Database, DatabaseNeedsVpc, type DatabaseProps } from './aws/Database';
 import { DatabaseBootstrap } from './aws/DatabaseBootstrap';
 import { DatabaseReader, DatabaseSchema } from './aws/DerivedDatabase';
 import { Email, EmailNeedsSender } from './aws/Email';
+import { ExternalApi, type ExternalApiProps } from './aws/ExternalApi';
 import { FileServer } from './aws/FileServer';
 import { ObjectStorage } from './aws/ObjectStorage';
 import { Queue } from './aws/Queue';
@@ -399,6 +400,19 @@ const PROVISIONERS: Partial<Record<DeclarationKind, Provisioner>> = {
 
 	// The same storage as a secret, under a different role — see the component.
 	credential: (stack, d, props) => new Credential(stack, d.id, props),
+
+	// Nothing to provision: the URL this stage calls, and the credentials kept
+	// as a secret.
+	'external-api': (stack, d, props) => {
+		if (d.kind !== 'external-api') {
+			throw new UnknownDeclarationKind(d.kind, []);
+		}
+
+		return new ExternalApi(stack, d.id, {
+			...(props as Partial<ExternalApiProps>),
+			url: d.url,
+		});
+	},
 };
 
 /**
@@ -736,6 +750,46 @@ export function isServed(id: string, manifest: ConstructManifest): boolean {
 	);
 }
 
+/**
+ * Kinds this stack provisions nothing for of their own.
+ *
+ * - `mobile-app` ships through EAS and the stores. It is in the manifest for
+ *   what it makes the surfaces trust, which `callersOf` reads off the graph.
+ * - `worker` is a process, not a resource: what it runs is provisioned as
+ *   what it is — a queue's consumer by {@link subscribeConsumers}.
+ * - `cron` and `function` are Lambdas built from `manifest.crons` and
+ *   `manifest.functions` (`Cron.fromManifest`, `Function.fromManifest`).
+ */
+export const PROVISIONED_ELSEWHERE: ReadonlySet<DeclarationKind> =
+	new Set<DeclarationKind>(['mobile-app', 'worker', 'cron', 'function']);
+
+/** A provisioned queue: what {@link subscribeConsumers} subscribes through. */
+interface Consumable {
+	consume(consumer: { handler: string; link?: unknown[] }): unknown;
+}
+
+/**
+ * Subscribe every queue's one consumer — the handler the build wrote for it,
+ * linked to what that consumer depends on.
+ *
+ * After every construct is provisioned, because a consumer links to things
+ * that `provisionOrder` does not order before the queue.
+ */
+export function subscribeConsumers(
+	manifest: ConstructManifest,
+	provisioned: ProvisionedManifest,
+): void {
+	for (const [id, declaration] of Object.entries(manifest)) {
+		if (declaration?.kind !== 'queue') continue;
+
+		const queue = provisioned[id] as unknown as Consumable | undefined;
+		if (!queue) continue;
+
+		const { link } = resolveEdges(declaration.worker.dependencies, provisioned);
+		queue.consume({ handler: declaration.worker.handler, link });
+	}
+}
+
 /** The provisioner for a kind. Pure — the lookup is testable without Pulumi. */
 export function provisionerFor(kind: DeclarationKind): Provisioner {
 	const provisioner = PROVISIONERS[kind];
@@ -824,10 +878,7 @@ export function fromManifest(
 	for (const id of [...rest, ...sites]) {
 		const declaration = manifest[id];
 		if (!declaration) continue;
-		// A mobile app ships through EAS and the stores, not this stack. It is
-		// in the manifest for what it makes the surfaces trust, which
-		// `callersOf` reads off the graph.
-		if (declaration.kind === 'mobile-app') continue;
+		if (PROVISIONED_ELSEWHERE.has(declaration.kind)) continue;
 
 		const component = provisionerFor(declaration.kind)(
 			stack,
@@ -851,6 +902,9 @@ export function fromManifest(
 		provisioned[id] = component;
 	}
 
+	// Each queue's one consumer, once everything it links to exists.
+	subscribeConsumers(manifest, provisioned);
+
 	for (const line of describeRoutes(manifest)) console.log(line);
 
 	// Now everything exists, so every surface's callers can be resolved — the