@geekmidas/cloud 1.1.1 → 10.0.0-alpha.0

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

@@ -0,0 +1,266 @@
+import { resolveEnvKeys } from '@geekmidas/envkit/sst';
+import { providedKeyFor, provideKey } from '@geekmidas/manifest';
+import { describe, expect, it } from 'vitest';
+import { ObjectStorage } from '../aws/ObjectStorage';
+import { type ProvidesMismatch, UnknownDeclarationKind } from '../errors';
+import {
+	assertProvides,
+	type ProvisionedManifest,
+	provisionerFor,
+	resolveEdges,
+} from '../fromManifest';
+
+/**
+ * The decisions, tested as data. Instantiating a component needs Pulumi, so the
+ * adapter keeps its decisions in pure functions and its Pulumi in three lines —
+ * otherwise nothing here would be reachable without a deploy.
+ */
+
+describe('provisionerFor', () => {
+	it('resolves a kind this adapter can provision', () => {
+		expect(provisionerFor('objects')).toBeTypeOf('function');
+	});
+
+	it.each([
+		'objects',
+		'queue',
+		'topic',
+		'secret',
+	] as const)('provisions %s', (kind) => {
+		expect(provisionerFor(kind)).toBeTypeOf('function');
+	});
+
+	it('reports what is supported when a kind has no provisioner', () => {
+		expect.assertions(3);
+		try {
+			// A kind no adapter will ever have, so this test does not go stale
+			// every time one more kind becomes provisionable.
+			provisionerFor('carrier-pigeon' as never);
+		} catch (error) {
+			const e = error as UnknownDeclarationKind;
+			expect(e).toBeInstanceOf(UnknownDeclarationKind);
+			expect(e.kind).toBe('carrier-pigeon');
+			expect(e.supported).toContain('objects');
+		}
+	});
+});
+
+describe('assertProvides', () => {
+	it('passes when declared and supplied agree', () => {
+		expect(() =>
+			assertProvides('Uploads', ['UPLOADS_URL'], ['UPLOADS_URL']),
+		).not.toThrow();
+	});
+
+	it('catches infra supplying nothing for a declared key', () => {
+		expect.assertions(2);
+		try {
+			assertProvides('Uploads', ['UPLOADS_URL'], []);
+		} catch (error) {
+			const e = error as ProvidesMismatch;
+			expect(e.missing).toEqual(['UPLOADS_URL']);
+			expect(e.extra).toEqual([]);
+		}
+	});
+
+	it('catches infra supplying a key the app never declared', () => {
+		expect.assertions(2);
+		try {
+			assertProvides(
+				'Uploads',
+				['UPLOADS_URL'],
+				['UPLOADS_URL', 'UPLOADS_CDN_URL'],
+			);
+		} catch (error) {
+			const e = error as ProvidesMismatch;
+			expect(e.missing).toEqual([]);
+			// adding cdn to the component without declaring it is caught here
+			expect(e.extra).toEqual(['UPLOADS_CDN_URL']);
+		}
+	});
+
+	it('treats both sides as empty by default, so a resource may provide nothing', () => {
+		expect(() => assertProvides('Nothing')).not.toThrow();
+	});
+
+	it('names the construct, since a manifest has many', () => {
+		expect.assertions(1);
+		try {
+			assertProvides('Avatars', ['AVATARS_URL'], []);
+		} catch (error) {
+			expect((error as ProvidesMismatch).id).toBe('Avatars');
+		}
+	});
+});
+
+describe('ObjectStorage', () => {
+	const bucket = new ObjectStorage({} as never, 'Uploads');
+
+	it('composes the url from the resource, not the stack', () => {
+		expect(bucket.provides().url).toBe('s3://Uploads?region=stub-region');
+	});
+
+	it('carries those values on the link, which is what reaches runtime', () => {
+		const link = bucket.getSSTLink();
+		expect(link.properties).toMatchObject({
+			name: 'Uploads',
+			url: 's3://Uploads?region=stub-region',
+		});
+	});
+
+	it('leaves the permissions super grants alone', () => {
+		expect(bucket.getSSTLink()).toHaveProperty('include');
+	});
+
+	it('supplies exactly the key the construct declares', () => {
+		// The construct emits provides: ['UPLOADS_URL']; a role becomes that key.
+		expect(() =>
+			assertProvides(
+				'Uploads',
+				['UPLOADS_URL'],
+				Object.keys(bucket.provides()).map((role) =>
+					provideKey('Uploads', role),
+				),
+			),
+		).not.toThrow();
+	});
+
+	it('is what envkit flattens into env', () => {
+		expect(resolveEnvKeys({ Uploads: { type: bucket._type } })).toContain(
+			'UPLOADS_URL',
+		);
+	});
+});
+
+describe('component settings', () => {
+	const provision = (
+		declaration: never,
+		props = {},
+		manifest: ConstructManifest = {},
+	) =>
+		provisionerFor('objects')({} as never, declaration, props, {
+			manifest,
+			provisioned: {},
+		}) as unknown as {
+			name: string;
+			props?: Record<string, unknown>;
+		};
+
+	it('maps a declared neutral option to this provider’s word for it', () => {
+		// `versioned` is the app's vocabulary; `versioning` is S3's.
+		const bucket = provision({
+			kind: 'objects',
+			id: 'Uploads',
+			versioned: true,
+		} as never);
+		expect(bucket.name).toBe('Uploads');
+	});
+
+	it('accepts provider-specific props the declaration cannot express', () => {
+		expect(() =>
+			provision({ kind: 'objects', id: 'Uploads' } as never, {
+				cors: [{ allowOrigins: ['*'] }],
+			}),
+		).not.toThrow();
+	});
+});
+
+describe('resolveEdges', () => {
+	const stub = (id: string) => ({ _id: id, _type: 'sst.aws.Bucket' }) as never;
+
+	const provisioned = {
+		Uploads: stub('Uploads'),
+		Avatars: stub('Avatars'),
+	} as unknown as ProvisionedManifest;
+
+	it('links what the function declared, and yields its keys', () => {
+		const { link, envKeys } = resolveEdges(
+			[{ target: 'Uploads', kind: 'objects' }],
+			provisioned,
+		);
+		expect(link.map((l) => l._id)).toEqual(['Uploads']);
+		expect(envKeys).toContain('UPLOADS_URL');
+	});
+
+	it('links nothing more — the property least privilege depends on', () => {
+		const { link, envKeys } = resolveEdges(
+			[{ target: 'Uploads', kind: 'objects' }],
+			provisioned,
+		);
+		expect(link.map((l) => l._id)).not.toContain('Avatars');
+		expect(envKeys.some((k) => k.startsWith('AVATARS'))).toBe(false);
+	});
+
+	it('is unchanged when an unrelated construct joins the manifest', () => {
+		const before = resolveEdges(
+			[{ target: 'Uploads', kind: 'objects' }],
+			provisioned,
+		);
+		const after = resolveEdges([{ target: 'Uploads', kind: 'objects' }], {
+			...provisioned,
+			Reports: stub('Reports'),
+		} as unknown as ProvisionedManifest);
+
+		expect(after.envKeys).toEqual(before.envKeys);
+		expect(after.link.map((l) => l._id)).toEqual(before.link.map((l) => l._id));
+	});
+
+	it('gives a function with no edges nothing at all', () => {
+		expect(resolveEdges([], provisioned)).toEqual({ link: [], envKeys: [] });
+	});
+
+	it('names what is available when an edge does not resolve', () => {
+		expect.assertions(2);
+		try {
+			resolveEdges([{ target: 'Missing', kind: 'objects' }], provisioned);
+		} catch (error) {
+			const e = error as UnresolvedDependency;
+			expect(e.target).toBe('Missing');
+			expect(e.available).toContain('Uploads');
+		}
+	});
+});
+
+describe('the key a provided role becomes', () => {
+	it('qualifies an ordinary role by its id', () => {
+		expect(providedKeyFor('Uploads', 'objects', 'url')).toBe('UPLOADS_URL');
+	});
+
+	it('leaves a secret’s name as its key', () => {
+		// `Auth` signs with `AUTH_SECRET`, which is also what better-auth's own
+		// tooling looks for — and qualifying it would produce
+		// `AUTH_SECRET_VALUE`, which nothing reads.
+		expect(providedKeyFor('AuthSecret', 'secret', 'value')).toBe('AUTH_SECRET');
+	});
+
+	it('is the same derivation the contract check uses', () => {
+		// The point of sharing it: a check deriving the key differently from the
+		// thing it checks passes on drift instead of catching it.
+		expect(() =>
+			assertProvides(
+				'AuthSecret',
+				['AUTH_SECRET'],
+				['value'].map((role) => providedKeyFor('AuthSecret', 'secret', role)),
+			),
+		).not.toThrow();
+	});
+});
+
+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
+		// 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']);
+	});
+
+	it('agrees with what the construct declares', () => {
+		expect(providedKeyFor('Stripe', 'credential', 'credential')).toBe(
+			'STRIPE_CREDENTIAL',
+		);
+	});
+});

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

@@ -0,0 +1,107 @@
+import { snsUrl } from '@geekmidas/events/sns';
+import { sqsUrl } from '@geekmidas/events/sqs';
+import { describe, expect, it } from 'vitest';
+import { fifoName, Queue } from '../aws/Queue';
+import { Secret } from '../aws/Secret';
+import { Topic } from '../aws/Topic';
+import { regionOfArn } from '../naming';
+
+/**
+ * What each component resolves onto its consumers.
+ *
+ * Asserted by parsing the string back with the client's own codec, not by
+ * matching text: the contract is that the publisher can read what the deploy
+ * target wrote, and a string comparison would pass on a value nothing can
+ * consume.
+ */
+
+const stack = {} as never;
+
+describe('Queue', () => {
+	it('provides a connection string its publisher can parse', () => {
+		const provided = new Queue(stack, 'Emails').provides();
+
+		expect(
+			sqsUrl.parse(provided.publisherConnectionString as string),
+		).toMatchObject({
+			queueUrl: expect.stringContaining('/Emails'),
+			region: 'stub-region',
+		});
+	});
+
+	it('provides one key, the producer’s', () => {
+		// A worker is reached *through* the queue, so there is no second address
+		// and nothing can depend on the handler.
+		expect(Object.keys(new Queue(stack, 'Emails').provides())).toEqual([
+			'publisherConnectionString',
+		]);
+	});
+});
+
+describe('Topic', () => {
+	it('provides a connection string its publisher can parse', () => {
+		const provided = new Topic(stack, 'Users').provides();
+
+		expect(
+			snsUrl.parse(provided.publisherConnectionString as string),
+		).toMatchObject({
+			topicArn: expect.stringContaining(':Users'),
+			region: 'stub-region',
+		});
+	});
+
+	it('names no queue, so a subscriber cannot be reached by holding it', () => {
+		const provided = new Topic(stack, 'Users').provides();
+
+		expect(
+			snsUrl.parse(provided.publisherConnectionString as string).queueName,
+		).toBeUndefined();
+	});
+});
+
+describe('Secret', () => {
+	it('provides a value, because it has no address to hand out instead', () => {
+		expect(new Secret(stack, 'AuthSecret').provides()).toEqual({
+			value: 'stub-secret-AuthSecret',
+		});
+	});
+});
+
+describe('regionOfArn', () => {
+	it('reads the region out of an ARN', () => {
+		// Carried explicitly because AWS_REGION inside a Lambda is the
+		// *function's* region: a queue elsewhere works until it doesn't.
+		expect(regionOfArn('arn:aws:sqs:eu-west-1:123:emails')).toBe('eu-west-1');
+	});
+
+	it('is undefined where an ARN carries no region', () => {
+		expect(regionOfArn('arn:aws:iam::123:role/x')).toBeUndefined();
+		expect(regionOfArn('not-an-arn')).toBeUndefined();
+	});
+});
+
+describe('fifoName', () => {
+	it('appends .fifo to a FIFO queue’s name', () => {
+		// AWS rejects the mistake at the API call rather than at plan time, so
+		// the component fixes it where the fact lives.
+		expect(fifoName('emails', true)).toBe('emails.fifo');
+	});
+
+	it('does not append it twice', () => {
+		// `.fifo` counts toward the 80-character limit.
+		expect(fifoName('emails.fifo', true)).toBe('emails.fifo');
+	});
+
+	it('treats the object form as FIFO', () => {
+		expect(fifoName('emails', { contentBasedDeduplication: true })).toBe(
+			'emails.fifo',
+		);
+	});
+
+	it('strips it from a standard queue’s name', () => {
+		// The rule runs both ways: a standard queue whose name ends in `.fifo`
+		// is rejected just as loudly.
+		expect(fifoName('emails.fifo', false)).toBe('emails');
+		expect(fifoName('emails.fifo', undefined)).toBe('emails');
+	});
+});

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

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+import {
+	NoSmtpEndpoint,
+	SMTP_REGIONS,
+	sesSmtpUrl,
+	smtpEndpoint,
+	smtpPassword,
+} from '../aws/ses';
+
+/**
+ * AWS documents the recipe and publishes no worked example, so there is no
+ * golden value to assert against. These check the properties the recipe implies
+ * instead — which is weaker, and worth being explicit about rather than
+ * inventing an expected string.
+ */
+
+const KEY = 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY';
+
+describe('smtpPassword', () => {
+	it('carries the version byte SES looks for', () => {
+		// Without it the password is the right bytes and still rejected.
+		const decoded = Buffer.from(smtpPassword(KEY, 'us-east-1'), 'base64');
+
+		expect(decoded[0]).toBe(0x04);
+	});
+
+	it('is a version byte and one SHA-256 digest, and nothing else', () => {
+		expect(Buffer.from(smtpPassword(KEY, 'us-east-1'), 'base64')).toHaveLength(
+			33,
+		);
+	});
+
+	it('is deterministic, because it is a signature and not a secret', () => {
+		// A password that changed per call would rotate itself out from under
+		// every deploy.
+		expect(smtpPassword(KEY, 'us-east-1')).toBe(smtpPassword(KEY, 'us-east-1'));
+	});
+
+	it('differs per region, which is why credentials are not portable', () => {
+		expect(smtpPassword(KEY, 'us-east-1')).not.toBe(
+			smtpPassword(KEY, 'eu-west-1'),
+		);
+	});
+
+	it('differs per key', () => {
+		expect(smtpPassword(KEY, 'us-east-1')).not.toBe(
+			smtpPassword(`${KEY}x`, 'us-east-1'),
+		);
+	});
+
+	it('refuses a region with no SMTP endpoint', () => {
+		// The set is smaller than the set of regions SES runs in, so this is a
+		// real mistake to make — and it would surface at the first send.
+		expect(() => smtpPassword(KEY, 'af-south-1')).toThrow(NoSmtpEndpoint);
+		expect(SMTP_REGIONS).not.toContain('af-south-1');
+	});
+});
+
+describe('sesSmtpUrl', () => {
+	it('is an smtp:// URL like every other backend’s', () => {
+		// The whole reason the declaration promises `smtp://` and names no
+		// provider: what changes is a host and a credential, not the client.
+		const url = sesSmtpUrl({
+			accessKeyId: 'AKIAEXAMPLE',
+			secretAccessKey: KEY,
+			region: 'eu-west-1',
+		});
+
+		expect(url.startsWith('smtp://AKIAEXAMPLE:')).toBe(true);
+		expect(url.endsWith('@email-smtp.eu-west-1.amazonaws.com:587')).toBe(true);
+	});
+
+	it('encodes the password, which is base64 and may contain + and /', () => {
+		// Both mean something else in a URL's authority section.
+		const url = sesSmtpUrl({
+			accessKeyId: 'AKIAEXAMPLE',
+			secretAccessKey: KEY,
+			region: 'eu-west-1',
+		});
+
+		// Round-tripped through the URL parser, which is the consumer that has
+		// to get the password back out intact.
+		expect(decodeURIComponent(new URL(url).password)).toBe(
+			smtpPassword(KEY, 'eu-west-1'),
+		);
+	});
+
+	it('derives the endpoint rather than taking one', () => {
+		expect(smtpEndpoint('ap-southeast-2')).toBe(
+			'email-smtp.ap-southeast-2.amazonaws.com',
+		);
+	});
+});

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

@@ -0,0 +1,132 @@
+import type { ConstructManifest } from '@geekmidas/manifest';
+import { describe, expect, it } from 'vitest';
+import { ObjectStorage } from '../aws/ObjectStorage';
+import { UnresolvedDependency } from '../errors';
+import {
+	isServed,
+	type ProvisionContext,
+	provisionerFor,
+	siteEnvironment,
+} from '../fromManifest';
+
+const stack = {} as never;
+
+const manifest = {
+	Uploads: { kind: 'objects', id: 'Uploads', provides: ['UPLOADS_URL'] },
+	UploadsServer: {
+		kind: 'file-server',
+		id: 'UploadsServer',
+		of: 'Uploads',
+		open: ['brand/**'],
+		provides: ['UPLOADS_SERVER_URL'],
+	},
+	Assets: { kind: 'objects', id: 'Assets', provides: ['ASSETS_URL'] },
+	Api: {
+		kind: 'rest-api',
+		id: 'Api',
+		endpoints: [],
+		provides: ['API_URL', 'API_TRUSTED_ORIGINS', 'API_COOKIE_DOMAIN'],
+	},
+	Orders: { kind: 'database', id: 'Orders', provides: ['ORDERS_URL'] },
+	Console: {
+		kind: 'site',
+		id: 'Console',
+		variant: 'static',
+		path: 'apps/console',
+		dependencies: [
+			{ target: 'Api', kind: 'rest-api' },
+			{ target: 'Orders', kind: 'database' },
+			{ target: 'UploadsServer', kind: 'file-server' },
+		],
+		provides: ['CONSOLE_URL'],
+	},
+} as const satisfies ConstructManifest;
+
+/** A provisioned stand-in that provides whatever it was handed. */
+const provided = (values: Record<string, string>) =>
+	({ provides: () => values }) as never;
+
+const context = (
+	provisioned: Record<string, unknown> = {},
+): ProvisionContext => ({
+	manifest,
+	provisioned: provisioned as never,
+	bootstraps: new Map(),
+});
+
+describe('isServed', () => {
+	it('finds the surface pointing at a bucket', () => {
+		// The cost this design named: the bucket alone no longer says whether it
+		// is served, so you find whoever points at it.
+		expect(isServed('Uploads', manifest)).toBe(true);
+	});
+
+	it('leaves an unserved bucket alone', () => {
+		expect(isServed('Assets', manifest)).toBe(false);
+	});
+});
+
+describe('file-server provisioning', () => {
+	it('refuses an origin that was not provisioned', () => {
+		expect(() =>
+			provisionerFor('file-server')(
+				stack,
+				manifest.UploadsServer,
+				{},
+				context(),
+			),
+		).toThrow(UnresolvedDependency);
+	});
+
+	it('routes everything at the root, so a served path is a bucket key', () => {
+		const origin = new ObjectStorage(stack, 'Uploads');
+		const server = provisionerFor('file-server')(
+			stack,
+			manifest.UploadsServer,
+			{},
+			context({ Uploads: origin }),
+		) as unknown as { routed: { pattern: string }[] };
+
+		expect(server.routed).toEqual([
+			{ pattern: '/*', bucket: expect.anything() },
+		]);
+	});
+});
+
+describe('siteEnvironment', () => {
+	const built = () =>
+		siteEnvironment(
+			manifest.Console,
+			context({
+				Api: provided({ url: 'https://api.example.com' }),
+				Orders: provided({ url: 'postgres://user:pw@db/orders' }),
+				UploadsServer: provided({ url: 'https://files.example.com' }),
+			}),
+		);
+
+	it('inlines an address under the name the bundler expects', () => {
+		expect(built().VITE_API_URL).toBe('https://api.example.com');
+	});
+
+	it('inlines a served bucket’s address, but never the bucket’s own', () => {
+		// A served URL is what a browser fetches; the bucket's presigns, and a
+		// presigner in a bundle is a credential in a bundle.
+		expect(built().VITE_UPLOADS_SERVER_URL).toBe('https://files.example.com');
+		expect(built()).not.toHaveProperty('VITE_UPLOADS_URL');
+	});
+
+	it('keeps a connection string out of the bundle entirely', () => {
+		// A site may legitimately depend on a database — its server half, where
+		// it has one, reads env like anything else. `PUBLIC` decides only what
+		// may be *prefixed*, and a password may not.
+		expect(built()).not.toHaveProperty('VITE_ORDERS_URL');
+	});
+
+	it('fails loudly on an edge nothing provisioned', () => {
+		// A smaller environment builds and then fails at runtime against
+		// `http:///`, with nothing to point at.
+		expect(() =>
+			siteEnvironment(manifest.Console, context({ Api: provided({}) })),
+		).toThrow(UnresolvedDependency);
+	});
+});

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

@@ -3,9 +3,9 @@
 // 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';
+import { Api } from '../aws/Api';
+import { Function } from '../aws/Function';
 
 const stack = new App({
 	name: 'a',

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

@@ -3,10 +3,10 @@
 // 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 { Api } from '../aws/Api';
+import { Cron } from '../aws/Cron';
+import { Function } from '../aws/Function';
 import { type GkmLinkable, ResourceType } from '../Linkable';
 
 const stack = new App({

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

@@ -2,9 +2,9 @@
 // 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';
+import { Function } from '../aws/Function';
+import { Queue } from '../aws/Queue';
+import { Topic } from '../aws/Topic';
 
 const stack = new App({
 	name: 'shop',

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

@@ -2,8 +2,8 @@
 // Checked by `ts:check:sst`; vitest ignores it.
 
 import { App } from '../App';
-import { Function } from '../Function';
-import { Storage } from '../Storage';
+import { Function } from '../aws/Function';
+import { Storage } from '../aws/Storage';
 
 const stack = new App({
 	name: 'a',

package/src/sst/{Api.ts → aws/Api.ts}

@@ -5,10 +5,10 @@ import {
 	type ManifestField,
 	type RouteInfo,
 } from '@geekmidas/manifest';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import { LinkedEnvironment } from '../LinkedEnvironment';
+import type { StackType } from '../Stack';
 import type { Function } from './Function';
-import { type GkmLinkable, ResourceType } from './Linkable';
-import { LinkedEnvironment } from './LinkedEnvironment';
-import type { StackType } from './Stack';
 
 /**
  * `Api` — wraps SST's `sst.aws.ApiGatewayV2` (HTTP API) with a typed route