@geekmidas/cloud 1.1.1 → 10.0.0-alpha.0

package/src/sst/aws/ObjectStorage.ts

@@ -0,0 +1,76 @@
+import { s3Url } from '@geekmidas/storage/aws';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import type { StackType } from '../Stack';
+
+/**
+ * `ObjectStorage` — a linkable S3 bucket (wraps `sst.aws.Bucket`), and the
+ * infra half of the `objects` construct.
+ *
+ * Its whole contribution is the link. SST injects the linked resource's
+ * properties at runtime and `@geekmidas/envkit`'s resolvers turn them into the
+ * env a construct reads — so composing a URL here would produce a value nothing
+ * ever reads.
+ *
+ * Usable on its own. `Stack.fromManifest` translates a manifest into these, but
+ * the component takes ordinary props so it works in a hand-written
+ * `sst.config.ts` with no manifest anywhere.
+ */
+export class ObjectStorage<
+		TStage extends string = string,
+		TDomain extends string = string,
+	>
+	extends sst.aws.Bucket
+	implements GkmLinkable
+{
+	readonly _id!: string;
+
+	get _type() {
+		return ResourceType.ObjectStorage;
+	}
+
+	constructor(
+		_stack: StackType<TStage, TDomain>,
+		name: string,
+		props: ObjectStorageProps = {},
+	) {
+		super(name, props);
+		this._id = name;
+	}
+
+	/**
+	 * The values this bucket resolves onto anything that depends on it, keyed by
+	 * role. `provideKey` turns a role into the env key the app declared, so
+	 * `url` here is `UPLOADS_URL` there.
+	 *
+	 * Composed *here* because only the resource knows its own shape: the name may
+	 * be supplied through props or generated, and the region is the bucket's, not
+	 * the reader's. It stays a method rather than being inlined below so the
+	 * contract can be asserted — declared keys against supplied ones — without a
+	 * deploy.
+	 */
+	provides(): Record<string, $util.Input<string>> {
+		return {
+			url: $util
+				.all([this.name, this.nodes.bucket.region])
+				.apply(([bucket, region]) => s3Url.build({ bucket, region })),
+		};
+	}
+
+	/**
+	 * The link carries those values, because the link is what reaches the running
+	 * code: SST injects these properties and envkit's resolvers flatten them into
+	 * env. Composing anywhere else produces a value nothing reads.
+	 *
+	 * The permissions `super` includes are untouched: what a link grants stays
+	 * SST's business.
+	 */
+	override getSSTLink() {
+		const link = super.getSSTLink();
+		return {
+			...link,
+			properties: { ...link.properties, ...this.provides() },
+		};
+	}
+}
+
+export interface ObjectStorageProps extends sst.aws.BucketArgs {}

package/src/sst/aws/Queue.ts

@@ -0,0 +1,116 @@
+// The codec alone, not the barrel: `@geekmidas/events/sqs` re-exports the
+// publisher and its AWS SDK client, and a deploy config that only needs to
+// *compose a URL* should not have to resolve a runtime it never calls.
+import * as sqsUrl from '@geekmidas/events/sqs/url';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import { regionOfArn } from '../naming';
+import type { StackType } from '../Stack';
+
+/**
+ * `Queue` — a linkable SQS queue (wraps `sst.aws.Queue`), the point-to-point
+ * 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`.
+ *
+ * SST's native `Queue` link exposes only `url`, so `getSSTLink` is overridden to
+ * also expose `arn` (what the resolver needs). `QueueProps` extends
+ * `sst.aws.QueueArgs`. Source-only (extends ambient `sst.aws.*`); see docs §2.
+ */
+export class Queue<
+		TStage extends string = string,
+		TDomain extends string = string,
+	>
+	extends sst.aws.Queue
+	implements GkmLinkable
+{
+	readonly _id!: string;
+
+	get _type() {
+		return ResourceType.Queue;
+	}
+
+	constructor(
+		_stack: StackType<TStage, TDomain>,
+		name: string,
+		props: QueueProps = {},
+	) {
+		const { queueName, ...args } = props;
+
+		super(name, {
+			...args,
+			// A supplied name has to satisfy SQS's rule; an auto-generated one is
+			// Pulumi's problem and it already handles it.
+			...(queueName
+				? {
+						transform: {
+							...args.transform,
+							queue: { name: fifoName(queueName, args.fifo) },
+						},
+					}
+				: {}),
+		});
+		this._id = name;
+	}
+
+	/**
+	 * The values this queue resolves onto anything that publishes to it, keyed
+	 * by role. 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.
+	 *
+	 * The region is read out of the queue's own ARN rather than left for the SDK
+	 * to infer. `AWS_REGION` inside a Lambda is the *function's* region, so a
+	 * connection string that omits it works until the day the queue lives
+	 * somewhere else and then fails at runtime with nothing to point at.
+	 */
+	provides(): Record<string, $util.Input<string>> {
+		return {
+			publisherConnectionString: $util
+				.all([this.url, this.arn])
+				.apply(([queueUrl, arn]) =>
+					sqsUrl.build({ queueUrl, region: regionOfArn(arn) }),
+				),
+		};
+	}
+
+	override getSSTLink() {
+		const link = super.getSSTLink();
+		return {
+			...link,
+			properties: { ...link.properties, arn: this.arn, ...this.provides() },
+		};
+	}
+}
+
+export interface QueueProps extends sst.aws.QueueArgs {
+	/**
+	 * The physical queue name, where the auto-generated one will not do.
+	 *
+	 * Normalised for SQS's FIFO rule — see {@link fifoName}. This is a separate
+	 * prop rather than a `transform` because the rule is easy to not know and
+	 * expensive to discover: the deploy fails at the API call, long after the
+	 * plan looked fine.
+	 */
+	queueName?: string;
+}
+
+/**
+ * A FIFO queue's name must end in `.fifo`, and a standard queue's must not.
+ *
+ * AWS rejects either mistake at the API call rather than at plan time, so the
+ * component fixes it where the fact lives instead of leaving it as something
+ * every caller has to remember. Appending is safe: `.fifo` counts toward the
+ * 80-character limit, so a name already carrying it must not get a second one.
+ */
+export function fifoName(
+	name: string,
+	fifo: sst.aws.QueueArgs['fifo'],
+): string {
+	// `fifo` is an Input and may be an object (`{ contentBasedDeduplication }`),
+	// which is still FIFO — only `false` and `undefined` are not.
+	const isFifo = fifo !== undefined && fifo !== false;
+
+	if (!isFifo) return name.replace(/\.fifo$/, '');
+
+	return name.endsWith('.fifo') ? name : `${name}.fifo`;
+}

package/src/sst/aws/RestApiSurface.ts

@@ -0,0 +1,92 @@
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import type { StackType } from '../Stack';
+
+/**
+ * `RestApiSurface` — an HTTP API, and the infra half of the `rest-api` kind.
+ *
+ * Deliberately *not* `Api`, which takes a route table and validates each
+ * route's environment at synth. That component is the endpoint pipeline's, and
+ * it needs routes; this one is the manifest's, and the manifest's `rest-api`
+ * node currently carries `endpoints: []` for an application's own API.
+ *
+ * So what this provisions is the surface and nothing on it. An API Gateway with
+ * no routes 404s everything, which is the honest state of things — and it is
+ * still worth provisioning, because the *address* is what everything downstream
+ * needs: a site inlines it as `VITE_API_URL`, an auth server puts it on its
+ * trusted-origin list, and the cookie domain derives from it. Those are blocked
+ * on the API existing, not on it answering.
+ *
+ * The two collapse into one component when the endpoint merge lands and the
+ * surface node carries its routes.
+ */
+
+export interface RestApiSurfaceProps extends sst.aws.ApiGatewayV2Args {
+	/**
+	 * Who may call this surface, resolved after everything is provisioned.
+	 *
+	 * A promise rather than a value, because the answer depends on constructs
+	 * that do not exist yet when this one is built — see `provides()`.
+	 */
+	callers?: Promise<{ trustedOrigins: string; cookieDomain?: string }>;
+}
+export class RestApiSurface<
+		TStage extends string = string,
+		TDomain extends string = string,
+	>
+	extends sst.aws.ApiGatewayV2
+	implements GkmLinkable
+{
+	readonly _id!: string;
+
+	get _type() {
+		return ResourceType.ApiGatewayV2;
+	}
+
+	private readonly callers: Promise<{
+		trustedOrigins: string;
+		cookieDomain?: string;
+	}>;
+
+	constructor(
+		_stack: StackType<TStage, TDomain>,
+		name: string,
+		props: RestApiSurfaceProps = {},
+	) {
+		const { callers, ...args } = props;
+
+		super(name, args);
+		this._id = name;
+		this.callers = callers ?? Promise.resolve({ trustedOrigins: '' });
+	}
+
+	/**
+	 * Where the surface answers, and who may call it.
+	 *
+	 * `trustedOrigins` and `cookieDomain` are declared by the construct and are
+	 * *caller*-derived — read off the graph, not off this resource — so they are
+	 * supplied through props rather than composed here. A surface knows its own
+	 * address and nothing about who points at it.
+	 */
+	provides(): Record<string, $util.Input<string>> {
+		return {
+			url: this.url,
+			// Lazy, and it has to be. A surface's callers include the site, and
+			// the site's own build needs *this* surface's address — so the two
+			// values are circular even though the two resources are not. A
+			// promise resolved after everything is provisioned breaks it at the
+			// value level, which is the level the cycle is actually on.
+			trustedOrigins: $util.output(this.callers.then((c) => c.trustedOrigins)),
+			cookieDomain: $util.output(
+				this.callers.then((c) => c.cookieDomain ?? ''),
+			),
+		};
+	}
+
+	override getSSTLink() {
+		const link = super.getSSTLink();
+		return {
+			...link,
+			properties: { ...link.properties, ...this.provides() },
+		};
+	}
+}

package/src/sst/aws/Secret.ts

@@ -0,0 +1,76 @@
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import type { StackType } from '../Stack';
+
+/**
+ * `Secret` — a linkable SST secret, and the infra half of the `secret` kind.
+ *
+ * The odd one among the kinds: it provisions no cloud resource of its own. An
+ * SST secret is a value held in the app's own encrypted state and set out of
+ * band (`sst secret set AuthSecret …`), which is why the component is thin and
+ * why the *deploy* fails rather than the *runtime* when nobody set one — SST
+ * raises `SecretMissingError` at synth, which is the earliest anything can.
+ *
+ * It provides a value rather than an address, which is the whole reason it is a
+ * node instead of a field on whatever needs it: the thing that generates a
+ * signing key, the thing that stores it, and the thing that reads it are three
+ * different systems deployed, and one derived string locally.
+ *
+ * Usable on its own. `Stack.fromManifest` translates a manifest into these, but
+ * the component takes an ordinary placeholder so it works in a hand-written
+ * `sst.config.ts` with no manifest anywhere.
+ */
+export class Secret<
+		TStage extends string = string,
+		TDomain extends string = string,
+	>
+	extends sst.Secret
+	implements GkmLinkable
+{
+	readonly _id!: string;
+
+	get _type() {
+		return ResourceType.SSTSecret;
+	}
+
+	constructor(
+		_stack: StackType<TStage, TDomain>,
+		name: string,
+		props: SecretProps = {},
+	) {
+		super(name, props.placeholder);
+		this._id = name;
+	}
+
+	/**
+	 * The one value this secret resolves onto anything that depends on it.
+	 *
+	 * `value` is the role, so `provideKey` turns it into the key the app
+	 * declared. Note that a secret's key is its *name* rather than
+	 * `<NAME>_VALUE` — `Auth` signs with `AUTH_SECRET`, which is also what
+	 * better-auth's own tooling looks for — so the manifest declares that key
+	 * directly and this contributes the value behind it.
+	 */
+	provides(): Record<string, $util.Input<string>> {
+		return { value: this.value };
+	}
+
+	override getSSTLink() {
+		const link = super.getSSTLink();
+		return {
+			...link,
+			properties: { ...link.properties, ...this.provides() },
+		};
+	}
+}
+
+export interface SecretProps {
+	/**
+	 * A value to fall back to when none is set.
+	 *
+	 * Deliberately not a default for anything that signs: a placeholder signing
+	 * key is one every deploy of every app shares, so leaving this unset — and
+	 * letting the deploy fail — is the correct handling for a real secret. It
+	 * exists for the values that are secrets by habit rather than by need.
+	 */
+	placeholder?: string;
+}

package/src/sst/aws/StaticSite.ts

@@ -0,0 +1,92 @@
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import type { StackType } from '../Stack';
+
+/**
+ * `StaticSite` — a built frontend on a distribution, and the infra half of the
+ * `site` kind.
+ *
+ * The same infrastructure a file server is, which is why they are neighbours
+ * here: a bucket, a distribution, a certificate and a domain. What differs is
+ * only what sits in the bucket — a build output rather than live contents.
+ *
+ * Its `environment` is the interesting part and is not composed here. The values
+ * a site inlines are derived from its *edges* by `publicEnvFor`, filtered by
+ * which provided values may be shipped to a browser, and renamed by the
+ * variant's prefix. That derivation is shared with the local target, so a site
+ * built by `gkm dev` and the same site built by a deploy inline the same names.
+ */
+export class StaticSite<
+		TStage extends string = string,
+		TDomain extends string = string,
+	>
+	extends sst.aws.StaticSite
+	implements GkmLinkable
+{
+	readonly _id!: string;
+
+	get _type() {
+		return ResourceType.StaticSite;
+	}
+
+	constructor(
+		_stack: StackType<TStage, TDomain>,
+		name: string,
+		props: StaticSiteProps = {},
+	) {
+		const { variant = 'static', ...args } = props;
+
+		super(name, {
+			// The variant's build, unless the caller supplied one. A site is
+			// source until something builds it — uploading `path` directly is what
+			// puts `src/` and `node_modules/` in a bucket — and *how* to build is
+			// exactly what the variant knows and the declaration deliberately does
+			// not.
+			build: BUILDS[variant],
+			...args,
+		});
+		this._id = name;
+	}
+
+	/**
+	 * Where the site is served.
+	 *
+	 * Worth providing even though a browser gets there by typing it: an email
+	 * templating a link back to the console needs this URL, and that is otherwise
+	 * one more hand-maintained variable — the exact class of thing declaring a
+	 * site was meant to remove.
+	 */
+	provides(): Record<string, $util.Input<string>> {
+		return { url: this.url };
+	}
+
+	override getSSTLink() {
+		const link = super.getSSTLink();
+		return {
+			...link,
+			properties: { ...link.properties, ...this.provides() },
+		};
+	}
+}
+
+export interface StaticSiteProps extends sst.aws.StaticSiteArgs {
+	/** Which framework builds it, for the default build command. */
+	variant?: 'static' | 'next' | 'tanstack';
+}
+
+/**
+ * How each variant builds, and where it leaves the result.
+ *
+ * One neutral name from the construct, one build per framework — the same
+ * arrangement the `VITE_`/`NEXT_PUBLIC_` prefixes have, and for the same
+ * reason: the framework changes the code you write, so it changes this and
+ * nothing else.
+ */
+const BUILDS: Record<
+	NonNullable<StaticSiteProps['variant']>,
+	{ command: string; output: string }
+> = {
+	static: { command: 'npm run build', output: 'dist' },
+	tanstack: { command: 'npm run build', output: 'dist' },
+	// Next's static export lands in `out`, not `dist`.
+	next: { command: 'npm run build', output: 'out' },
+};

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

@@ -1,5 +1,5 @@
-import { type GkmLinkable, ResourceType } from './Linkable';
-import type { StackType } from './Stack';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import type { StackType } from '../Stack';
 
 /**
  * `Storage` — a linkable S3 bucket (wraps `sst.aws.Bucket`). Link it to a
@@ -39,7 +39,7 @@ export class Storage<
 	readonly _id!: string;
 
 	get _type() {
-		return ResourceType.Bucket;
+		return ResourceType.ObjectStorage;
 	}
 
 	constructor(

package/src/sst/aws/Topic.ts

@@ -0,0 +1,68 @@
+// The codec alone — see the note in `Queue.ts`.
+import * as snsUrl from '@geekmidas/events/sns/url';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import { regionOfArn } from '../naming';
+import type { StackType } from '../Stack';
+
+/**
+ * `Topic` — a linkable SNS topic (wraps `sst.aws.SnsTopic`), the pub/sub fan-out
+ * bus. Link it to a publisher and the runtime resolves `<NAME>_ARN` and a
+ * `<NAME>_PUBLISHER_CONNECTION_STRING` (`sns://?topicArn=…`) that
+ * `@geekmidas/events`'s `Publisher.fromConnectionString` consumes. Subscribers
+ * attach via `TopicSubscriber`/`Subscriber`.
+ *
+ * `StorageProps`-style: `TopicProps` extends `sst.aws.SnsTopicArgs`.
+ * Source-only (extends ambient `sst.aws.*`); see docs §2.
+ */
+export class Topic<
+		TStage extends string = string,
+		TDomain extends string = string,
+	>
+	extends sst.aws.SnsTopic
+	implements GkmLinkable
+{
+	readonly _id!: string;
+
+	get _type() {
+		return ResourceType.SnsTopic;
+	}
+
+	constructor(
+		_stack: StackType<TStage, TDomain>,
+		name: string,
+		props: TopicProps = {},
+	) {
+		super(name, props);
+		this._id = name;
+	}
+
+	/**
+	 * The publisher's connection string, and nothing else.
+	 *
+	 * A subscriber is *bound* to a topic rather than depending on it, so the
+	 * binding is an edge the deploy target reads and not a key anyone can hold —
+	 * which is what keeps a subscriber from being able to publish.
+	 *
+	 * The region comes out of the topic's own ARN, for the same reason it does
+	 * on a queue: the reader's region is not the resource's.
+	 */
+	provides(): Record<string, $util.Input<string>> {
+		return {
+			publisherConnectionString: $util
+				.output(this.arn)
+				.apply((topicArn) =>
+					snsUrl.build({ topicArn, region: regionOfArn(topicArn) }),
+				),
+		};
+	}
+
+	override getSSTLink() {
+		const link = super.getSSTLink();
+		return {
+			...link,
+			properties: { ...link.properties, ...this.provides() },
+		};
+	}
+}
+
+export interface TopicProps extends sst.aws.SnsTopicArgs {}

package/src/sst/aws/bootstrap/handler.ts

@@ -0,0 +1,110 @@
+/**
+ * The database bootstrap — role and schema DDL, run inside the VPC.
+ *
+ * SST provisions a cluster; nothing in Pulumi runs SQL. So the statements a
+ * tenant needs — its owner, its runtime role, its schema, and the grants between
+ * them — have to be applied by something that can reach the database, which on
+ * AWS means a Lambda in the same VPC.
+ *
+ * It connects **as the cluster master**, because that is the only credential
+ * that exists before any role does. That is also why this runs once per deploy
+ * and nothing else holds those credentials: the master reaches this function
+ * through its link and reaches nothing else.
+ *
+ * The statements come from `@geekmidas/db/pg/roles`, the same generator the
+ * local target uses. One implementation is what stops "works locally, fails
+ * deployed" — and it means the grants a developer tested against are the grants
+ * production gets.
+ */
+
+import { roleStatements } from '@geekmidas/db/pg/roles';
+import pg from 'pg';
+
+/** One tenant to bootstrap. */
+export interface BootstrapTenant {
+	/** The construct id, so a failure can name it. */
+	id: string;
+	schema: string;
+	runtime: string;
+	owner: string;
+	reader?: string;
+	passwords: { runtime: string; owner: string; reader?: string };
+}
+
+export interface BootstrapEvent {
+	/** The master credential, from the cluster's link. */
+	master: {
+		host: string;
+		port: number;
+		database: string;
+		username: string;
+		password: string;
+	};
+	tenants: BootstrapTenant[];
+}
+
+export interface BootstrapResult {
+	applied: { tenant: string; describe: string; created: boolean }[];
+}
+
+/**
+ * Apply every tenant's DDL, convergently.
+ *
+ * Each statement asks whether it is needed first, exactly as the local applier
+ * does, so a re-deploy is free and a half-applied run recovers by running again.
+ * That matters more here than locally: a Lambda can time out mid-way, and the
+ * recovery has to be "invoke it again" rather than "work out what happened".
+ */
+export async function handler(event: BootstrapEvent): Promise<BootstrapResult> {
+	const client = new pg.Client({
+		host: event.master.host,
+		port: event.master.port,
+		database: event.master.database,
+		user: event.master.username,
+		password: event.master.password,
+		// The cluster is inside the VPC and RDS presents a certificate this
+		// runtime does not carry a root for. Encrypted, unverified — which is the
+		// same posture the AWS SDK's own RDS helpers take, and worth naming rather
+		// than leaving as an unexplained `false`.
+		ssl: { rejectUnauthorized: false },
+	});
+
+	await client.connect();
+
+	const applied: BootstrapResult['applied'] = [];
+
+	try {
+		for (const tenant of event.tenants) {
+			for (const statement of roleStatements(tenant)) {
+				if (statement.exists) {
+					const { rows } = await client.query(
+						statement.exists.sql,
+						statement.exists.values,
+					);
+
+					if (rows.length > 0) {
+						applied.push({
+							tenant: tenant.id,
+							describe: statement.describe,
+							created: false,
+						});
+						continue;
+					}
+				}
+
+				await client.query(statement.sql);
+				applied.push({
+					tenant: tenant.id,
+					describe: statement.describe,
+					// A grant has no existence check and re-granting is a no-op, so it
+					// reports unchanged — a converged deploy still reads as converged.
+					created: Boolean(statement.exists),
+				});
+			}
+		}
+	} finally {
+		await client.end();
+	}
+
+	return { applied };
+}