@geekmidas/cloud 10.0.0-alpha.4 → 10.0.0-alpha.41

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

@@ -0,0 +1,192 @@
+import { describe, expect, it } from 'vitest';
+import { App } from '../App';
+import { Cron } from '../aws/Cron';
+import { Function } from '../aws/Function';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+
+/**
+ * A Lambda and a schedule as data: the args each hands SST (a recording stub
+ * in `test/sst-globals.ts`), and the env validation that fails before deploy.
+ */
+
+const app = new App({
+	name: 'shop',
+	stage: 'prod',
+	domain: 'shop.test',
+	hostedZoneId: 'Z1',
+	region: 'eu-west-1',
+});
+const stack = app.stack('jobs');
+const db: GkmLinkable = { _id: 'db', _type: ResourceType.Postgres };
+
+const argsOf = (component: unknown) =>
+	(component as { args: Record<string, unknown> }).args;
+
+describe('Function', () => {
+	it('defaults the runtime and logging, and links only what its variables need', () => {
+		const fn = new Function(stack, 'Reports', {
+			handler: 'reports.handler',
+			links: [db],
+			envVars: ['DB_URL'],
+			environment: { FEATURE: 'on' },
+		});
+
+		expect(fn._type).toBe(ResourceType.Function);
+		expect(argsOf(fn)).toMatchObject({
+			handler: 'reports.handler',
+			runtime: 'nodejs24.x',
+			logging: { format: 'json' },
+			link: [db],
+			environment: expect.objectContaining({
+				SERVICE_NAME: 'Reports',
+				STAGE: 'prod',
+				FEATURE: 'on',
+			}),
+		});
+		expect(fn.validate().valid).toBe(true);
+	});
+
+	it('keeps a runtime and logging it was given', () => {
+		const fn = new Function(stack, 'Legacy', {
+			handler: 'legacy.handler',
+			runtime: 'nodejs20.x',
+			logging: { format: 'text' },
+		});
+
+		expect(argsOf(fn)).toMatchObject({
+			runtime: 'nodejs20.x',
+			logging: { format: 'text' },
+			link: [],
+		});
+	});
+
+	it('fails the synth on a variable no link provides, unless told not to check', () => {
+		expect(
+			() =>
+				new Function(stack, 'Mailer', {
+					handler: 'mailer.handler',
+					envVars: ['SMTP_URL'],
+				}),
+		).toThrow(/SMTP_URL/);
+
+		const unchecked = new Function(stack, 'Mailer', {
+			handler: 'mailer.handler',
+			envVars: ['SMTP_URL'],
+			autoValidate: false,
+		});
+		expect(unchecked.validate()).toMatchObject({
+			valid: false,
+			invalidVars: ['SMTP_URL'],
+		});
+	});
+
+	it('builds one function per manifest entry, named for the stack', () => {
+		const functions = Function.fromManifest(
+			stack,
+			{
+				billing: [
+					{
+						name: 'Invoice',
+						handler: '.gkm/aws-lambda/functions/invoice.handler',
+						environment: ['DB_URL'],
+						timeout: 60,
+						memorySize: 512,
+					},
+				],
+				ops: [
+					{
+						name: 'Ping',
+						handler: '.gkm/aws-lambda/functions/ping.handler',
+						environment: [],
+					},
+				],
+			} as never,
+			{ links: [db] },
+		);
+
+		expect(functions.map((f) => argsOf(f))).toEqual([
+			expect.objectContaining({
+				name: stack.logicalPrefixedName('Invoice'),
+				timeout: '60 seconds',
+				memory: '512 MB',
+				link: [db],
+			}),
+			expect.objectContaining({
+				name: stack.logicalPrefixedName('Ping'),
+				timeout: undefined,
+				memory: undefined,
+				link: [],
+			}),
+		]);
+	});
+});
+
+describe('Cron', () => {
+	it('schedules the function it is given, by ARN', () => {
+		const processor = { arn: 'arn:aws:lambda:eu-west-1:1:function:nightly' };
+		const cron = new Cron(stack, 'Nightly', {
+			processor: processor as never,
+			schedule: 'rate(1 day)',
+			enabled: false,
+		});
+
+		expect(argsOf(cron)).toEqual({
+			enabled: false,
+			schedule: 'rate(1 day)',
+			function: processor.arn,
+		});
+	});
+
+	it('builds a validated function and a schedule per manifest cron', () => {
+		const crons = Cron.fromManifest(
+			stack,
+			[
+				{
+					name: 'Digest',
+					handler: '.gkm/aws-lambda/crons/digest.handler',
+					schedule: 'cron(0 8 * * ? *)',
+					environment: ['DB_URL'],
+					timeout: 120,
+					memorySize: 1024,
+				},
+				{
+					name: 'Sweep',
+					handler: '.gkm/aws-lambda/crons/sweep.handler',
+					schedule: 'rate(1 hour)',
+					environment: [],
+				},
+			] as never,
+			{ links: [db], enabled: true },
+		);
+
+		const [digest, sweep] = crons.map((c) => argsOf(c));
+		expect(digest).toMatchObject({
+			schedule: 'cron(0 8 * * ? *)',
+			enabled: true,
+			function: expect.stringContaining('DigestFunction'),
+		});
+		expect(sweep).toMatchObject({ schedule: 'rate(1 hour)' });
+	});
+});
+
+describe('App and Stack', () => {
+	it('pick a value for the stage, falling back to the default', () => {
+		expect(app.select({ prod: 'live', default: 'test' })).toBe('live');
+		expect(stack.select({ staging: 'test', default: 'dev' } as never)).toBe(
+			'dev',
+		);
+	});
+
+	it('name subdomains and URLs under the root domain', () => {
+		expect(stack.domain).toBe('shop.test');
+		expect(stack.getSubdomain('api')).toBe('api.shop.test');
+		expect(stack.getURL('api')).toBe('https://api.shop.test');
+		expect(stack.getURL()).toBe('https://shop.test');
+		expect(app.getURL()).toBe('https://shop.test');
+	});
+
+	it('prefix physical names with the stage, app and stack', () => {
+		expect(app.logicalPrefixedName('Uploads')).toBe('prod-shop-uploads');
+		expect(stack.logicalPrefixedName('Uploads')).toBe('prod-shop-jobs-uploads');
+	});
+});

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

@@ -0,0 +1,209 @@
+import { describe, expect, it } from 'vitest';
+import { Cache, CacheNeedsProvider, CacheNeedsVpc } from '../aws/Cache';
+import { Database } from '../aws/Database';
+import { DatabaseReader, DatabaseSchema } from '../aws/DerivedDatabase';
+import { Email } from '../aws/Email';
+import { FileServer } from '../aws/FileServer';
+import { Queue } from '../aws/Queue';
+import { RestApiSurface } from '../aws/RestApiSurface';
+import { Secret } from '../aws/Secret';
+import { StaticSite } from '../aws/StaticSite';
+import { Storage } from '../aws/Storage';
+import { Topic } from '../aws/Topic';
+import { ResourceType } from '../Linkable';
+
+/**
+ * What a linked function receives from each component, and the type that
+ * decides which variables a link provides. `getSSTLink()` is the payload SST
+ * injects into every handler linked to the resource; `_type` is what
+ * `LinkedEnvironment` keys the variable names off.
+ */
+
+const stack = {} as never;
+const vpc = { subnets: ['subnet-1'], securityGroups: ['sg-1'] } as never;
+
+/** Resolves `$util.output(promise)`, which the stub leaves as the promise. */
+const settle = async (value: unknown) =>
+	(value as { apply: (fn: (v: unknown) => unknown) => unknown }).apply(
+		(v) => v,
+	);
+
+describe('link payloads', () => {
+	it('a queue adds its ARN and connection string to SST’s own link', () => {
+		const queue = new Queue(stack, 'Emails');
+
+		expect(queue._type).toBe(ResourceType.Queue);
+		// The connection string itself is parsed back in provides.spec; here, the
+		// link carries exactly what `provides()` resolved.
+		expect(queue.getSSTLink().properties).toEqual({
+			name: 'Emails',
+			arn: queue.arn,
+			...queue.provides(),
+		});
+	});
+
+	it('a topic carries its publisher connection string', () => {
+		const topic = new Topic(stack, 'Users');
+
+		expect(topic._type).toBe(ResourceType.SnsTopic);
+		expect(topic.getSSTLink().properties).toEqual({
+			name: 'Users',
+			...topic.provides(),
+		});
+	});
+
+	it('a secret carries its value', () => {
+		const secret = new Secret(stack, 'AuthSecret');
+
+		expect(secret._type).toBe(ResourceType.SSTSecret);
+		expect(secret.getSSTLink().properties).toMatchObject(secret.provides());
+	});
+
+	it('a mailer carries its URL and sending identity, and nothing else', () => {
+		const email = new Email(stack, 'Mail', {
+			backend: 'smtp',
+			url: 'smtp://relay.test:587',
+			from: 'hello@shop.test',
+		} as never);
+
+		expect(email._type).toBe(ResourceType.Email);
+		expect(email.getSSTLink()).toEqual({
+			properties: { url: 'smtp://relay.test:587', from: 'hello@shop.test' },
+		});
+	});
+
+	it('a file server routes everything to its bucket, and links its URL', () => {
+		const origin = new Storage(stack, 'Uploads');
+		const server = new FileServer(stack, 'Files', { origin } as never);
+
+		expect(origin._type).toBe(ResourceType.ObjectStorage);
+		expect(origin._id).toBe('Uploads');
+		expect(server._type).toBe(ResourceType.FileServer);
+		expect((server as unknown as { routed: unknown[] }).routed).toEqual([
+			{ pattern: '/*', bucket: origin },
+		]);
+		expect(server.getSSTLink().properties).toMatchObject({
+			url: server.url,
+		});
+	});
+
+	it('a site is built the way its variant builds, and links its URL', () => {
+		const vite = new StaticSite(stack, 'Web');
+		const next = new StaticSite(stack, 'Admin', {
+			variant: 'next',
+			build: { command: 'pnpm build:custom', output: 'out' },
+		} as never);
+		const args = (site: unknown) => (site as { args: { build: unknown } }).args;
+
+		expect(vite._type).toBe(ResourceType.StaticSite);
+		expect(args(vite).build).toEqual(expect.objectContaining({}));
+		// A build the caller supplied wins over the variant's.
+		expect(args(next).build).toEqual({
+			command: 'pnpm build:custom',
+			output: 'out',
+		});
+		expect(vite.getSSTLink().properties).toMatchObject({ url: vite.url });
+	});
+
+	it('a surface links its address and, once resolved, who may call it', async () => {
+		const bare = new RestApiSurface(stack, 'Api');
+		const called = new RestApiSurface(stack, 'Api', {
+			callers: Promise.resolve({
+				trustedOrigins: 'https://web.shop.test',
+				cookieDomain: 'shop.test',
+			}),
+		});
+
+		expect(bare._type).toBe(ResourceType.ApiGatewayV2);
+		expect(await settle(bare.provides().trustedOrigins)).toBe('');
+		expect(await settle(bare.provides().cookieDomain)).toBe('');
+
+		const link = called.getSSTLink().properties as Record<string, unknown>;
+		expect(link.url).toBe(called.url);
+		expect(await settle(link.trustedOrigins)).toBe('https://web.shop.test');
+		expect(await settle(link.cookieDomain)).toBe('shop.test');
+	});
+
+	it('a database and the nodes derived from it each link only their own URL', () => {
+		const cluster = new Database(stack, 'Orders', { vpc, schema: 'app' });
+		const reader = new DatabaseReader('OrdersReader', cluster);
+		const tenant = new DatabaseSchema('AuthDb', cluster, 'authdb');
+
+		expect(cluster._type).toBe(ResourceType.SSTPostgres);
+		expect(reader._type).toBe(ResourceType.SSTPostgres);
+		expect(tenant._type).toBe(ResourceType.SSTPostgres);
+		expect(cluster.getSSTLink().properties).toMatchObject({
+			url: cluster.provides().url,
+		});
+		// Least privilege: the reader's link is its URL and not the writer's.
+		expect(reader.getSSTLink()).toEqual({
+			properties: { url: reader.provides().url },
+		});
+		expect(tenant.getSSTLink()).toEqual({
+			properties: { url: tenant.provides().url },
+		});
+	});
+
+	it('a cache given its URL links it as-is', () => {
+		const cache = new Cache(stack, 'Sessions', {
+			backend: 'db',
+			url: 'postgres://db.test/app',
+		});
+
+		expect(cache._type).toBe(ResourceType.Cache);
+		expect(cache.getSSTLink()).toEqual({
+			properties: { url: 'postgres://db.test/app' },
+		});
+	});
+});
+
+describe('Cache on Upstash', () => {
+	/** `sst add upstash` installs this global; here, a recording stand-in. */
+	const created: { name: string; args: Record<string, unknown> }[] = [];
+	class RedisDatabase {
+		readonly endpoint = 'eu1-cache.upstash.io';
+		readonly restToken = 'tok/en+1';
+		constructor(name: string, args: Record<string, unknown>) {
+			created.push({ name, args });
+		}
+	}
+
+	it('creates a TLS database and puts its token in the URL', () => {
+		(globalThis as Record<string, unknown>).upstash = { RedisDatabase };
+		try {
+			const defaulted = new Cache(stack, 'Sessions', { backend: 'upstash' });
+			new Cache(stack, 'Rates', { backend: 'upstash', region: 'us-east-1' });
+
+			expect(created).toEqual([
+				{
+					name: 'SessionsCache',
+					args: { databaseName: 'Sessions', region: 'eu-west-1', tls: true },
+				},
+				{
+					name: 'RatesCache',
+					args: { databaseName: 'Rates', region: 'us-east-1', tls: true },
+				},
+			]);
+			// The address and the credential that opens it are one fact.
+			expect(defaulted.provides().url).toBe(
+				`https://:${encodeURIComponent('tok/en+1')}@eu1-cache.upstash.io`,
+			);
+		} finally {
+			delete (globalThis as Record<string, unknown>).upstash;
+		}
+	});
+});
+
+describe('Cache provisioning refusals', () => {
+	it('asks for the Upstash provider when it is not installed', () => {
+		expect(() => new Cache(stack, 'Sessions', { backend: 'upstash' })).toThrow(
+			CacheNeedsProvider,
+		);
+	});
+
+	it('asks for a VPC before creating an ElastiCache', () => {
+		expect(
+			() => new Cache(stack, 'Sessions', { backend: 'elasticache' }),
+		).toThrow(CacheNeedsVpc);
+	});
+});

package/src/sst/aws/Api.ts

@@ -153,7 +153,7 @@ export class Api<
 		// Fail the whole synth if any route is misconfigured, with one actionable
 		// message per offending route.
 		if (failures.length) {
-			throw new Error(failures.map((f) => f.message).join('\n\n'));
+			throw new RoutesMissingEnvironment(id, failures);
 		}
 	}
 
@@ -307,3 +307,18 @@ export interface ApiProps<TAuthorizers extends Record<string, unknown> = {}>
 	 * may override it. */
 	runtime?: sst.aws.FunctionArgs['runtime'];
 }
+
+/**
+ * Routes that read variables nothing links or whitelists. Collected across
+ * every route so one synth reports all of them, each with its own suggestions,
+ * rather than stopping at the first.
+ */
+export class RoutesMissingEnvironment extends Error {
+	constructor(
+		readonly api: string,
+		readonly failures: readonly EnvValidationError[],
+	) {
+		super(failures.map((f) => f.message).join('\n\n'));
+		this.name = 'RoutesMissingEnvironment';
+	}
+}

package/src/sst/aws/Cache.ts

@@ -206,7 +206,7 @@ export function withCacheTable(url: string, table: string): string {
 }
 
 /**
- * `services.cache: 'db'` in an app that declares more than one database.
+ * A `'db'` cache in an app that declares more than one database.
  *
  * Picking one would put the cache somewhere nobody chose, and the symptom —
  * entries that are never found — appears long after the deploy reported
@@ -222,7 +222,7 @@ export class CacheIsAmbiguous extends Error {
 			`'${id}' is a cache backed by the database, and this app declares ` +
 				`${databases.length}: ${databases.join(', ')}. Declare the cache from ` +
 				`its database — e.g. ${databases[0]}.cache('${id}') — rather than ` +
-				`with services.cache.`,
+				`as a bare new Cache().`,
 		);
 		this.name = 'CacheIsAmbiguous';
 	}
@@ -232,8 +232,8 @@ export class CacheNeedsDatabase extends Error {
 	constructor(readonly id: string) {
 		super(
 			`'${id}' is a cache backed by the database, and this app declares no ` +
-				`database for it to live in. Declare one, or set services.cache to ` +
-				`'upstash' or 'elasticache'.`,
+				`database for it to live in. Declare one, or declare the cache from ` +
+				`the database it belongs to.`,
 		);
 		this.name = 'CacheNeedsDatabase';
 	}

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/Database.ts

@@ -84,7 +84,21 @@ export class Database<
 	 * produces a database that looks empty.
 	 */
 	provides(): Record<string, $util.Input<string>> {
-		return { url: this.urlFor({}) };
+		return { url: this.urlFor(this.role ? { as: this.role } : {}) };
+	}
+
+	/**
+	 * The runtime role this database's own handlers connect as.
+	 *
+	 * Set by the adapter once the bootstrap has registered the role — the
+	 * cluster exists before any role does, so it cannot be a constructor
+	 * argument. Until it is set (and under `roles: false`, where it never is),
+	 * the URL is the master's.
+	 */
+	private role: { user: string; password: $util.Input<string> } | undefined;
+
+	connectAs(role: { user: string; password: $util.Input<string> }): void {
+		this.role = role;
 	}
 
 	/**

package/src/sst/aws/DatabaseBootstrap.ts

@@ -65,6 +65,8 @@ export class DatabaseBootstrap {
 		runtime: string;
 		owner: string;
 		reader?: string;
+		/** The database's own roles, whose owner may create in it. */
+		ownsDatabase?: boolean;
 	}): { runtime: $util.Output<string>; reader?: $util.Output<string> } {
 		const runtime = this.password(tenant.runtime);
 		const reader = tenant.reader ? this.password(tenant.reader) : undefined;
@@ -75,6 +77,7 @@ export class DatabaseBootstrap {
 			runtime: tenant.runtime,
 			owner: tenant.owner,
 			...(tenant.reader ? { reader: tenant.reader } : {}),
+			...(tenant.ownsDatabase ? { ownsDatabase: true } : {}),
 			// Filled in by `bootstrapEvent` once the outputs resolve. The function
 			// reads them straight out of its input and never fetches a secret, so
 			// it needs no IAM to read one.

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.