@geekmidas/cloud 9.0.2 → 10.0.0-alpha.1

package/src/dokploy/__tests__/Application.spec.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { appNameFor, diffApplication } from '../Application';
+
+/**
+ * The decisions, without a Dokploy server. Instantiating the resource needs
+ * Pulumi and a real endpoint; deciding what a change *costs* does not, which is
+ * the half worth asserting — a wrong answer here is a destroy nobody previewed.
+ */
+
+const base = {
+	name: 'Api',
+	projectId: 'proj-1',
+	environmentId: 'env-1',
+};
+
+describe('appNameFor', () => {
+	it('is what Dokploy will actually call it', () => {
+		expect(appNameFor('My API')).toBe('my-api');
+	});
+
+	it('collapses anything that is not a name character', () => {
+		expect(appNameFor('Orders_v2!')).toBe('orders-v2-');
+	});
+});
+
+describe('diffApplication', () => {
+	it('sees no change when nothing changed', () => {
+		expect(diffApplication(base, base)).toMatchObject({
+			changes: false,
+			replaces: [],
+		});
+	});
+
+	it('replaces on a renamed application, because appName derives from it', () => {
+		// Dokploy computes `appName` from the name, so changing it is a different
+		// application rather than an edit to this one.
+		expect(diffApplication(base, { ...base, name: 'Gateway' })).toMatchObject({
+			changes: true,
+			replaces: ['name'],
+		});
+	});
+
+	it('does not replace when only the casing changed', () => {
+		// `Api` and `API` are the same `appName`, so there is nothing to destroy —
+		// and destroying an application to restyle its name in the UI would be a
+		// spectacular way to lose one.
+		expect(diffApplication(base, { ...base, name: 'API' })).toMatchObject({
+			replaces: [],
+			changes: true,
+		});
+	});
+
+	it('replaces on a move between projects or environments', () => {
+		expect(
+			diffApplication(base, { ...base, projectId: 'proj-2' }).replaces,
+		).toEqual(['projectId']);
+		expect(
+			diffApplication(base, { ...base, environmentId: 'env-2' }).replaces,
+		).toEqual(['environmentId']);
+	});
+
+	it('creates the replacement before removing the old one', () => {
+		// A Dokploy project can hold both for a moment; it cannot hold a gap
+		// where the application used to be.
+		expect(
+			diffApplication(base, { ...base, name: 'Gateway' }).deleteBeforeReplace,
+		).toBe(false);
+	});
+});

package/src/dokploy/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Dokploy as Pulumi resources — a prototype.
+ *
+ * The question it exists to answer: is wrapping Dokploy's REST API in a dynamic
+ * provider worth doing for the rest of the resources? If it is, `deploy/state.ts`
+ * and `SSMStateProvider` stop being necessary — remembering what you created is
+ * the whole job of a state file — and `--target=server` becomes another
+ * provisioner table rather than a deployment engine written by hand.
+ *
+ * One resource so far, and nothing has run against a real server.
+ */
+
+export {
+	Application,
+	type ApplicationArgs,
+	appNameFor,
+	diffApplication,
+} from './Application';

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

@@ -14,7 +14,10 @@ const stack = new App({
 }).stack('api');
 
 const db: GkmLinkable = { _id: 'db', _type: ResourceType.Postgres };
-const uploads: GkmLinkable = { _id: 'uploads', _type: ResourceType.Bucket };
+const uploads: GkmLinkable = {
+	_id: 'uploads',
+	_type: ResourceType.ObjectStorage,
+};
 
 describe('LinkedEnvironment', () => {
 	describe('createBaseEnvironment', () => {

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

@@ -0,0 +1,249 @@
+import type { ConstructManifest } from '@geekmidas/manifest';
+import { describe, expect, it } from 'vitest';
+import {
+	CacheIsAmbiguous,
+	CacheNeedsDatabase,
+	CacheNeedsProvider,
+	CacheNeedsVpc,
+} from '../aws/Cache';
+import { EmailNeedsSender, EmailNeedsUrl } from '../aws/Email';
+import { type ProvisionContext, provisionerFor } from '../fromManifest';
+
+const stack = {} as never;
+
+const manifest = {
+	Sessions: { kind: 'cache', id: 'Sessions', provides: ['SESSIONS_URL'] },
+	Mail: { kind: 'email', id: 'Mail', provides: ['MAIL_URL'] },
+	Orders: { kind: 'database', id: 'Orders', provides: ['ORDERS_URL'] },
+} as const satisfies ConstructManifest;
+
+const context = (
+	overrides: Partial<ProvisionContext> = {},
+): ProvisionContext => ({
+	manifest,
+	provisioned: {},
+	bootstraps: new Map(),
+	...overrides,
+});
+
+const provided = (values: Record<string, string>) =>
+	({ provides: () => values }) as never;
+
+describe('cache', () => {
+	it('resolves the declared database for the db backend', () => {
+		// No second address and no second credential — which is the whole reason
+		// this backend costs nothing to run.
+		const cache = provisionerFor('cache')(
+			stack,
+			manifest.Sessions,
+			{},
+			context({
+				cache: 'db',
+				provisioned: { Orders: provided({ url: 'postgres://app@db/orders' }) },
+			}),
+		);
+
+		// The table travels in the URL: two caches in one database resolve the
+		// same connection string, so it is the only thing that says which one a
+		// client is holding.
+		expect(cache.provides().url).toBe(
+			'postgres://app@db/orders?table=cache_sessions',
+		);
+	});
+
+	it('gives two caches in one database a table each', () => {
+		// Sharing a table would mean sharing a keyspace: each would read the
+		// other's entries and evict the other's keys.
+		const twoCaches = {
+			...manifest,
+			Rates: {
+				kind: 'cache',
+				id: 'Rates',
+				of: 'Orders',
+				provides: ['RATES_URL'],
+			},
+		} as const satisfies ConstructManifest;
+
+		const urlOf = (id: 'Sessions' | 'Rates') =>
+			provisionerFor('cache')(
+				stack,
+				twoCaches[id],
+				{},
+				context({
+					cache: 'db',
+					manifest: twoCaches,
+					provisioned: {
+						Orders: provided({ url: 'postgres://app@db/orders' }),
+					},
+				}),
+			).provides().url;
+
+		expect(urlOf('Sessions')).not.toBe(urlOf('Rates'));
+		expect(urlOf('Rates')).toContain('table=cache_rates');
+	});
+
+	it('refuses to guess which database, rather than picking the first', () => {
+		const twoDatabases = {
+			...manifest,
+			Reports: { kind: 'database', id: 'Reports', provides: ['REPORTS_URL'] },
+		} as const satisfies ConstructManifest;
+
+		expect(() =>
+			provisionerFor('cache')(
+				stack,
+				twoDatabases.Sessions,
+				{},
+				context({ cache: 'db', manifest: twoDatabases }),
+			),
+		).toThrow(CacheIsAmbiguous);
+	});
+
+	it('refuses a database-backed cache with no database', () => {
+		expect(() =>
+			provisionerFor('cache')(
+				stack,
+				manifest.Sessions,
+				{},
+				context({ cache: 'db' }),
+			),
+		).toThrow(CacheNeedsDatabase);
+	});
+
+	it('names the command when Upstash’s provider is not installed', () => {
+		// SST preloads two providers and installs the rest on demand, so the
+		// global this reaches for is absent until somebody runs the command.
+		// Naming it beats an undefined-name crash halfway through a synth.
+		expect(() =>
+			provisionerFor('cache')(stack, manifest.Sessions, {}, context()),
+		).toThrow(CacheNeedsProvider);
+	});
+
+	it('takes a URL instead, for a database that already exists', () => {
+		const cache = provisionerFor('cache')(
+			stack,
+			manifest.Sessions,
+			{ url: 'https://:token@eu1.upstash.io' },
+			context(),
+		);
+
+		expect(cache.provides().url).toBe('https://:token@eu1.upstash.io');
+	});
+
+	it('refuses an ElastiCache cache with no VPC', () => {
+		// A cache in a VPC is reachable from functions in that VPC and from
+		// nowhere else, so the VPC is the choice rather than a detail.
+		expect(() =>
+			provisionerFor('cache')(
+				stack,
+				manifest.Sessions,
+				{},
+				context({ cache: 'elasticache' }),
+			),
+		).toThrow(CacheNeedsVpc);
+	});
+});
+
+describe('email', () => {
+	it('passes a supplied URL straight through for resend', () => {
+		// Nothing to provision: Resend is an API key you hold, and the URL it
+		// composes into is the same smtp:// shape every other backend produces.
+		const email = provisionerFor('email')(
+			stack,
+			manifest.Mail,
+			{ url: 'smtp://resend:re_xxx@smtp.resend.com:587', from: 'a@b.com' },
+			context({ email: 'resend' }),
+		);
+
+		expect(email.provides().url).toBe(
+			'smtp://resend:re_xxx@smtp.resend.com:587',
+		);
+	});
+
+	it('derives its own credential for ses when given none', () => {
+		// The only backend that is a chain rather than a value: a user, a key,
+		// and a password computed from it.
+		const email = provisionerFor('email')(
+			stack,
+			manifest.Mail,
+			{ from: 'a@b.com' },
+			context({ email: 'ses' }),
+		);
+
+		expect(email.provides().url).toMatch(
+			/^smtp:\/\/.+:.+@email-smtp\.eu-west-1\.amazonaws\.com:587$/,
+		);
+	});
+
+	it('uses credentials that already exist rather than making more', () => {
+		// The common case: a sending identity set up once, by hand. Creating a
+		// second IAM user for it would be a deploy quietly adding another way
+		// into the account.
+		const email = provisionerFor('email')(
+			stack,
+			manifest.Mail,
+			{
+				url: 'smtp://AKIAOLD:pw@email-smtp.eu-west-1.amazonaws.com:587',
+				from: 'a@b.com',
+			},
+			context({ email: 'ses' }),
+		);
+
+		expect(email.provides().url).toBe(
+			'smtp://AKIAOLD:pw@email-smtp.eu-west-1.amazonaws.com:587',
+		);
+	});
+
+	it('refuses a backend that cannot mint its own and was given none', () => {
+		// A sender alone is not enough for Resend: it is an account somebody
+		// created, so there is nothing for a deploy to provision and the URL is
+		// a missing setup step rather than something to default.
+		expect(() =>
+			provisionerFor('email')(
+				stack,
+				manifest.Mail,
+				{ from: 'a@b.com' },
+				context({ email: 'resend' }),
+			),
+		).toThrow(EmailNeedsUrl);
+	});
+
+	it('sends through SES when nothing said otherwise', () => {
+		// The default, because it is what this repo's projects actually use.
+		const email = provisionerFor('email')(
+			stack,
+			manifest.Mail,
+			{ from: 'a@b.com' },
+			context(),
+		);
+
+		expect(email.provides().url).toContain('email-smtp.');
+	});
+
+	it('produces an smtp:// URL whichever backend it is', () => {
+		// The property that lets one client serve all of them, and the reason the
+		// declaration names no provider.
+		const backends = ['resend', 'smtp'] as const;
+
+		for (const backend of backends) {
+			const provisioned = provisionerFor('email')(
+				stack,
+				manifest.Mail,
+				{ url: 'smtp://user:pw@relay.example.com:587', from: 'a@b.com' },
+				context({ email: backend }),
+			);
+
+			expect(String(provisioned.provides().url).startsWith('smtp://')).toBe(
+				true,
+			);
+		}
+	});
+
+	it('refuses to invent a sending identity', () => {
+		// Every provider rejects an unverified sender, so a guess would deploy
+		// cleanly and fail at the first send — which is the worst place to
+		// discover it.
+		expect(() =>
+			provisionerFor('email')(stack, manifest.Mail, {}, context()),
+		).toThrow(EmailNeedsSender);
+	});
+});

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

@@ -0,0 +1,140 @@
+import { roleStatements } from '@geekmidas/db/pg/roles';
+import { describe, expect, it } from 'vitest';
+import { Database } from '../aws/Database';
+import { bootstrapEvent, DatabaseBootstrap } from '../aws/DatabaseBootstrap';
+
+const stack = {} as never;
+const vpc = { subnets: ['subnet-1'], securityGroups: ['sg-1'] } as never;
+
+const cluster = () => new Database(stack, 'Orders', { vpc });
+
+const bootstrapWith = (
+	tenants: { id: string; schema: string; runtime: string; owner: string }[],
+) => {
+	const bootstrap = new DatabaseBootstrap('Orders', cluster());
+	for (const tenant of tenants) bootstrap.add(tenant);
+
+	return bootstrap;
+};
+
+describe('DatabaseBootstrap', () => {
+	it('does nothing when nothing needs bootstrapping', () => {
+		expect(new DatabaseBootstrap('Orders', cluster()).empty).toBe(true);
+	});
+
+	it('creates nothing merely by registering a tenant', () => {
+		// The reason one secret is enough: nothing reads it at runtime. A node
+		// publishes only its own URL through its link, so a handler is *given* its
+		// role and has no IAM to read Secrets Manager at all. The secret is for
+		// out-of-band use and is written once, by `run()`.
+		const bootstrap = bootstrapWith([
+			{
+				id: 'AuthDb',
+				schema: 'authdb',
+				runtime: 'authdb',
+				owner: 'authdb_owner',
+			},
+			{ id: 'Jobs', schema: 'jobs', runtime: 'jobs', owner: 'jobs_owner' },
+		]);
+
+		expect(bootstrap.secret).toBeUndefined();
+		expect(bootstrap.empty).toBe(false);
+	});
+
+	it('has no reader credential unless a reader was asked for', () => {
+		const bootstrap = bootstrapWith([
+			{
+				id: 'AuthDb',
+				schema: 'authdb',
+				runtime: 'authdb',
+				owner: 'authdb_owner',
+			},
+		]);
+
+		expect(bootstrap.readerFor('authdb')).toBeUndefined();
+	});
+
+	it('has one when it was', () => {
+		const bootstrap = new DatabaseBootstrap('Orders', cluster());
+		bootstrap.add({
+			id: 'AuthDb',
+			schema: 'authdb',
+			runtime: 'authdb',
+			owner: 'authdb_owner',
+			reader: 'authdb_reader',
+		});
+
+		expect(bootstrap.readerFor('authdb')?.user).toBe('authdb_reader');
+	});
+});
+
+describe('bootstrapEvent', () => {
+	const master = {
+		host: 'db.stub.rds.amazonaws.com',
+		port: 5432,
+		database: 'orders',
+		username: 'postgres',
+		password: 'master-pw',
+	};
+
+	const tenant = {
+		id: 'AuthDb',
+		schema: 'authdb',
+		runtime: 'authdb',
+		owner: 'authdb_owner',
+		passwords: { runtime: '', owner: '' },
+	};
+
+	const passwords = new Map([
+		['authdb', 'runtime-pw'],
+		['authdb_owner', 'owner-pw'],
+	]);
+
+	it('carries the master credential, which is the only one that exists first', () => {
+		const event = JSON.parse(bootstrapEvent(master, [tenant], passwords));
+
+		expect(event.master.username).toBe('postgres');
+	});
+
+	it('gives every role a password of its own', () => {
+		const event = JSON.parse(bootstrapEvent(master, [tenant], passwords));
+
+		expect(event.tenants[0].passwords).toEqual({
+			runtime: 'runtime-pw',
+			owner: 'owner-pw',
+		});
+	});
+
+	it('produces exactly what the handler’s generator accepts', () => {
+		// The contract between the two halves. A change to one is a type error in
+		// the other, and this asserts the runtime shape agrees too.
+		const event = JSON.parse(bootstrapEvent(master, [tenant], passwords));
+
+		expect(roleStatements(event.tenants[0]).length).toBeGreaterThan(0);
+	});
+
+	it('carries a reader password only where a reader was named', () => {
+		const withReader = { ...tenant, reader: 'authdb_reader' };
+		const event = JSON.parse(
+			bootstrapEvent(
+				master,
+				[withReader],
+				new Map([...passwords, ['authdb_reader', 'reader-pw']]),
+			),
+		);
+
+		expect(event.tenants[0].passwords.reader).toBe('reader-pw');
+		expect(
+			JSON.parse(bootstrapEvent(master, [tenant], passwords)).tenants[0]
+				.passwords,
+		).not.toHaveProperty('reader');
+	});
+
+	it('is stable, so a deploy that changed nothing re-runs nothing', () => {
+		// The invocation keys off this input; an unstable one re-applies the DDL
+		// on every deploy.
+		expect(bootstrapEvent(master, [tenant], passwords)).toBe(
+			bootstrapEvent(master, [tenant], passwords),
+		);
+	});
+});

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

@@ -0,0 +1,119 @@
+import type { ConstructManifest } from '@geekmidas/manifest';
+import { describe, expect, it } from 'vitest';
+import { Database, DatabaseNeedsVpc } from '../aws/Database';
+import { DatabaseReader, DatabaseSchema } from '../aws/DerivedDatabase';
+import { type ProvisionContext, provisionerFor } from '../fromManifest';
+
+const stack = {} as never;
+const vpc = { id: 'stub-vpc' } as never;
+
+const manifest = {
+	Orders: {
+		kind: 'database',
+		id: 'Orders',
+		engine: 'postgres',
+		schema: 'app',
+		provides: ['ORDERS_URL'],
+	},
+	OrdersReader: {
+		kind: 'database-reader',
+		id: 'OrdersReader',
+		of: 'Orders',
+		provides: ['ORDERS_READER_URL'],
+	},
+	AuthDb: {
+		kind: 'database-schema',
+		id: 'AuthDb',
+		of: 'Orders',
+		schema: 'authdb',
+		provides: ['AUTH_DB_URL'],
+	},
+} as const satisfies ConstructManifest;
+
+const cluster = () => new Database(stack, 'Orders', { vpc, schema: 'app' });
+
+const context = (provisioned: Record<string, unknown>): ProvisionContext => ({
+	manifest,
+	provisioned: provisioned as never,
+	bootstraps: new Map(),
+});
+
+describe('Database', () => {
+	it('composes one URL, the runtime role’s', () => {
+		expect(Object.keys(cluster().provides())).toEqual(['url']);
+	});
+
+	it('puts search_path in as a libpq option, not a query parameter', () => {
+		// A plain `?search_path=` is accepted by every URL parser, ignored by the
+		// server, and produces a database that looks empty.
+		const url = cluster().provides().url as string;
+
+		expect(url).toContain('options=-c+search_path%3Dapp');
+		expect(url).not.toMatch(/[?&]search_path=/);
+	});
+
+	it('refuses to invent a VPC', () => {
+		// Creating one means creating a NAT gateway, which costs money in an
+		// account whose networking may already be someone else's decision.
+		expect(() =>
+			provisionerFor('database')(stack, manifest.Orders, {}, context({})),
+		).toThrow(DatabaseNeedsVpc);
+	});
+});
+
+describe('DatabaseReader', () => {
+	it('points at the one endpoint the instance has', () => {
+		// Nobody provisions a replica, and an RDS instance has no second address:
+		// a reader resolves to the writer's endpoint. Safe because read-only is
+		// enforced by the role's grants, never by which host was reached.
+		const url = new DatabaseReader('OrdersReader', cluster()).provides()
+			.url as string;
+
+		expect(url).toContain('@db.stub.rds.amazonaws.com');
+		expect(url).not.toContain('db-ro.');
+	});
+
+	it('is reachable through the provisioner, from its parent', () => {
+		const reader = provisionerFor('database-reader')(
+			stack,
+			manifest.OrdersReader,
+			{},
+			context({ Orders: cluster() }),
+		);
+
+		expect(reader.provides().url).toContain('@db.stub.rds.amazonaws.com');
+	});
+});
+
+describe('DatabaseSchema', () => {
+	it('is the parent’s connection on a different search_path', () => {
+		const url = new DatabaseSchema('AuthDb', cluster(), 'authdb').provides()
+			.url as string;
+
+		expect(url).toContain('options=-c+search_path%3Dauthdb');
+		// The same host: a tenant is a schema inside the parent's database, not a
+		// database of its own.
+		expect(url).toContain('db.stub.rds.amazonaws.com');
+	});
+
+	it('resolves through a chain of derived nodes to the cluster', () => {
+		const tenant = provisionerFor('database-schema')(
+			stack,
+			manifest.AuthDb,
+			{},
+			context({ Orders: cluster() }),
+		);
+
+		// A reader on a tenant walks up two links to reach the cluster.
+		const readerOnTenant = provisionerFor('database-reader')(
+			stack,
+			{ kind: 'database-reader', id: 'AuthDbReader', of: 'AuthDb' },
+			{},
+			context({ Orders: cluster(), AuthDb: tenant }),
+		);
+
+		expect(readerOnTenant.provides().url).toContain(
+			'@db.stub.rds.amazonaws.com',
+		);
+	});
+});