@geekmidas/cloud 10.0.0-alpha.10 → 10.0.0-alpha.101

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

@@ -1,13 +1,24 @@
 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 { App } from '../App';
+import { Cron } from '../aws/Cron';
+import { Database } from '../aws/Database';
+import { DatabaseSchema } from '../aws/DerivedDatabase';
+import { Function } from '../aws/Function';
 import { ObjectStorage } from '../aws/ObjectStorage';
+import { RestApiSurface } from '../aws/RestApiSurface';
 import { type ProvidesMismatch, UnknownDeclarationKind } from '../errors';
 import {
 	assertProvides,
+	mountRoutes,
+	PROVISIONED_ELSEWHERE,
 	type ProvisionedManifest,
+	provisionCompute,
 	provisionerFor,
 	resolveEdges,
+	subscribeConsumers,
+	vpcFor,
 } from '../fromManifest';
 
 /**
@@ -249,18 +260,308 @@ 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: 'apps/api/.gkm/aws/queues/emails.handler',
+						dependencies: [{ target: 'Uploads', kind: 'objects' }],
+					},
+				},
+			} as never,
+			provisioned,
+		);
+
+		expect(consumed).toEqual([
+			{ handler: 'apps/api/.gkm/aws/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('a surface’s endpoints', () => {
+	const routesOf = (surface: RestApiSurface) =>
+		(
+			surface as unknown as {
+				routes: { key: string; handler: any; args: unknown }[];
+			}
+		).routes;
+
+	it('are mounted from the handlers the build wrote, each linked to what it depends on', () => {
+		// An API Gateway with no routes 404s everything — which is what a deploy
+		// produced while the routes sat in the manifest with nothing reading them.
+		const api = new RestApiSurface({} as never, 'Api');
+		const uploads = { _id: 'Uploads', _type: 'sst.aws.Bucket' };
+
+		mountRoutes(
+			{
+				Uploads: { kind: 'objects', id: 'Uploads', provides: ['UPLOADS_URL'] },
+				Api: {
+					kind: 'rest-api',
+					id: 'Api',
+					provides: ['API_URL'],
+					endpoints: [
+						{
+							id: 'ApiGET/users/{id}',
+							method: 'GET',
+							path: '/users/{id}',
+							handler: 'apps/api/.gkm/aws/routes/getUser.handler',
+							dependencies: [{ target: 'Uploads', kind: 'objects' }],
+							authorizer: 'none',
+						},
+						{
+							id: 'ApiGET/health',
+							method: 'GET',
+							path: '/health',
+							handler: 'apps/api/.gkm/aws/routes/health.handler',
+							dependencies: [],
+						},
+					],
+				},
+			} as never,
+			{ Uploads: uploads, Api: api } as unknown as ProvisionedManifest,
+		);
+
+		const [getUser, health] = routesOf(api);
+		expect(getUser?.key).toBe('GET /users/{id}');
+		expect(getUser?.handler.handler).toBe(
+			'apps/api/.gkm/aws/routes/getUser.handler',
+		);
+		expect(getUser?.handler.link).toEqual([uploads]);
+		expect(getUser?.args).toEqual({});
+		// Least privilege: an endpoint is linked to its own edges, not the app's.
+		expect(health?.key).toBe('GET /health');
+		expect(health?.handler.link).toEqual([]);
+	});
+
+	it('leaves IAM to the gateway, and every other authorizer to the handler', () => {
+		const api = new RestApiSurface({} as never, 'Api');
+
+		api.mount({
+			method: 'POST',
+			path: '/x',
+			handler: 'x.handler',
+			authorizer: 'iam',
+		});
+		api.mount({
+			method: 'POST',
+			path: '/y',
+			handler: 'y.handler',
+			authorizer: 'session',
+		});
+
+		const [x, y] = routesOf(api);
+		expect(x?.args).toEqual({ auth: { iam: true } });
+		expect(y?.args).toEqual({});
+	});
+
+	it('runs a handler that reaches a database inside the database’s network', () => {
+		const vpc = { id: 'stub-vpc' } as never;
+		const cluster = new Database({} as never, 'Orders', { vpc });
+		const tenant = new DatabaseSchema('Billing', cluster, 'billing');
+
+		expect(vpcFor([cluster as never])).toBe(vpc);
+		// A schema tenant lives in its parent's cluster, so in its network too.
+		expect(vpcFor([{ _id: 'Uploads' } as never, tenant as never])).toBe(vpc);
+		expect(vpcFor([{ _id: 'Uploads' } as never])).toBeUndefined();
+	});
+});
+
+describe('functions and crons', () => {
+	const stack = new App({
+		name: 'shop',
+		stage: 'prod',
+		domain: 'example.com',
+		hostedZoneId: 'Z',
+		region: 'eu-west-1',
+	}).stack('jobs');
+	const argsOf = (component: unknown) =>
+		(component as { args: Record<string, any> }).args;
+
+	it('are deployed from the declarations, each linked to its own edges', () => {
+		// The `manifest.crons` / `manifest.functions` tables they were built from
+		// are gone: the declarations carry the handler, schedule and edges.
+		const vpc = { id: 'stub-vpc' } as never;
+		const orders = new Database({} as never, 'Orders', { vpc });
+		const uploads = { _id: 'Uploads', _type: 'sst.aws.Bucket' };
+		const provisioned = {
+			Orders: orders,
+			Uploads: uploads,
+		} as unknown as ProvisionedManifest;
+
+		const [digest] = provisionCompute(
+			stack,
+			{
+				Orders: { kind: 'database', id: 'Orders' },
+				Uploads: { kind: 'objects', id: 'Uploads', provides: ['UPLOADS_URL'] },
+				Invoice: {
+					kind: 'function',
+					id: 'Invoice',
+					handler: 'apps/api/.gkm/aws/functions/invoice.handler',
+					dependencies: [{ target: 'Uploads', kind: 'objects' }],
+					provides: ['INVOICE_URL'],
+				},
+				Digest: {
+					kind: 'cron',
+					id: 'Digest',
+					handler: 'apps/api/.gkm/aws/crons/digest.handler',
+					schedule: 'rate(1 day)',
+					dependencies: [{ target: 'Orders', kind: 'database' }],
+				},
+			} as never,
+			provisioned,
+		);
+
+		const invoice = provisioned.Invoice as unknown as Function;
+		expect(invoice).toBeInstanceOf(Function);
+		expect(argsOf(invoice)).toMatchObject({
+			name: stack.logicalPrefixedName('Invoice'),
+			handler: 'apps/api/.gkm/aws/functions/invoice.handler',
+			link: [uploads],
+			url: { authorization: 'iam' },
+		});
+		expect(argsOf(invoice).vpc).toBeUndefined();
+
+		// A cron is a schedule, not something to link to; its Lambda reaches
+		// the database, so it runs in the database's network.
+		expect(provisioned.Digest).toBeUndefined();
+		expect(digest).toBeInstanceOf(Cron);
+		expect(argsOf(digest).schedule).toBe('rate(1 day)');
+		expect(argsOf(digest!.processor)).toMatchObject({
+			handler: 'apps/api/.gkm/aws/crons/digest.handler',
+			link: [orders],
+			vpc,
+		});
+	});
+});
+
+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/__tests__/function.spec.ts

@@ -0,0 +1,121 @@
+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'],
+		});
+	});
+});
+
+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,
+		});
+	});
+});
+
+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);
+	});
+});