@geekmidas/cloud 1.1.1 → 10.0.0-alpha.0

package/src/sst/aws/Cache.ts

@@ -0,0 +1,259 @@
+import { elasticache } from '@pulumi/aws';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import type { StackType } from '../Stack';
+
+/**
+ * `Cache` — a key/value cache, and the infra half of the `cache` kind.
+ *
+ * The kind where the *backend* is the whole design, because unlike mail the
+ * three do not speak the same protocol. What this composes is a URL whose
+ * scheme names one of them, and the generated entry registers the matching
+ * driver — so the two agree by construction rather than by being kept in step.
+ *
+ * Only one of the three provisions anything:
+ *
+ * - **`db`** provisions nothing at all. The cache is a table in the database
+ *   already declared, so this resolves that database's URL and the table is
+ *   created by the same thing that creates the schema. No second resource, no
+ *   second credential, and nothing to pay for while idle.
+ * - **`upstash`** provisions a Redis database through Upstash's own Pulumi
+ *   provider, which SST installs on demand: `sst add upstash`. It is not one of
+ *   the two providers SST preloads, so the component checks for its global and
+ *   says which command is missing rather than failing on an undefined name. A
+ *   URL can still be supplied instead, for a database that already exists.
+ * - **`elasticache`** is the one that creates something, and it comes with the
+ *   constraints of a thing in a VPC: it is reachable from functions in that VPC
+ *   and from nothing else.
+ */
+export class Cache<
+	TStage extends string = string,
+	TDomain extends string = string,
+> implements GkmLinkable
+{
+	readonly _id: string;
+
+	private readonly url: $util.Input<string>;
+
+	get _type() {
+		return ResourceType.Cache;
+	}
+
+	constructor(
+		_stack: StackType<TStage, TDomain>,
+		name: string,
+		props: CacheProps,
+	) {
+		this._id = name;
+		this.url = props.url ?? this.provision(name, props);
+	}
+
+	/**
+	 * Create the cache, for the two backends that can be created.
+	 *
+	 * `db` never reaches here — it resolves the declared database's URL, which
+	 * the caller passes in as `url`.
+	 */
+	private provision(name: string, props: CacheProps): $util.Input<string> {
+		return props.backend === 'upstash'
+			? this.provisionUpstash(name, props)
+			: this.provisionElastiCache(name, props);
+	}
+
+	/**
+	 * An Upstash Redis database, over HTTP.
+	 *
+	 * The default backend, because HTTP with a token is reachable from a Lambda
+	 * with no VPC and no connection pool — the same argument that makes it worth
+	 * running a proxy in front of Redis locally so both speak one protocol.
+	 *
+	 * The token goes in the URL's userinfo rather than a second key, because an
+	 * address and the credential that opens it are one fact.
+	 */
+	private provisionUpstash(
+		name: string,
+		props: CacheProps,
+	): $util.Input<string> {
+		// Upstash is installed on demand rather than preloaded, so its global is
+		// absent until `sst add upstash` has run. Checking for it turns an
+		// undefined-name crash into a sentence naming the command.
+		if (typeof upstash === 'undefined') throw new CacheNeedsProvider(name);
+
+		const database = new upstash.RedisDatabase(`${name}Cache`, {
+			databaseName: name,
+			// `global` needs a primary region named alongside it, so a plain
+			// region is the default that needs no second decision.
+			region: props.region ?? 'eu-west-1',
+			// In transit, always. The client speaks HTTPS either way, and a cache
+			// reachable unencrypted over the public internet is not one.
+			tls: true,
+		});
+
+		return $util
+			.all([database.endpoint, database.restToken])
+			.apply(
+				([endpoint, token]) =>
+					`https://:${encodeURIComponent(token)}@${endpoint}`,
+			);
+	}
+
+	/**
+	 * A serverless Valkey cache, in the VPC the caller named.
+	 *
+	 * Serverless rather than a node group because this design provisions per
+	 * stage, and a node running around the clock under every preview stage is a
+	 * bill nobody chose. The database went the other way — a plain RDS instance —
+	 * because a cluster buys complexity there rather than savings; the two are
+	 * separate calls, not one principle applied twice.
+	 *
+	 * TLS is not optional — ElastiCache Serverless only accepts encrypted
+	 * connections — which is why the URL is `rediss://` and why the driver
+	 * registers both schemes.
+	 */
+	private provisionElastiCache(
+		name: string,
+		props: CacheProps,
+	): $util.Input<string> {
+		if (!props.vpc) throw new CacheNeedsVpc(name);
+
+		const cache = new elasticache.ServerlessCache(`${name}Cache`, {
+			engine: 'valkey',
+			name,
+			subnetIds: props.vpc.subnets,
+			securityGroupIds: props.vpc.securityGroups,
+		});
+
+		return $util.output(cache.endpoints).apply((endpoints) => {
+			const endpoint = endpoints[0];
+			if (!endpoint) throw new CacheNeedsVpc(name);
+
+			return $util
+				.all([endpoint.address, endpoint.port])
+				.apply(([address, port]) => `rediss://${address}:${port}`);
+		});
+	}
+
+	/** One key, the URL — and its scheme is the contract with the driver. */
+	provides(): Record<string, $util.Input<string>> {
+		return { url: this.url };
+	}
+
+	getSSTLink() {
+		return { properties: { ...this.provides() } };
+	}
+}
+
+export interface CacheProps {
+	/** Which backend to create. `db` never creates anything and never gets here. */
+	backend?: 'upstash' | 'elasticache' | 'db';
+	/** The region to create an Upstash database in. */
+	region?: string;
+	/**
+	 * The cache's URL, whose scheme picks the driver.
+	 *
+	 * Supplied for the two backends that are not provisioned here — the declared
+	 * database's URL for `db`, a secret for `upstash`. Absent for `elasticache`,
+	 * which creates a cluster and composes its own.
+	 */
+	url?: $util.Input<string>;
+	/**
+	 * The VPC to put an ElastiCache cluster in.
+	 *
+	 * Required for that backend and meaningless for the others. A cache in a VPC
+	 * is reachable from functions in that VPC and from nothing else, which is
+	 * the trade that comes with choosing it.
+	 */
+	vpc?: {
+		subnets: $util.Input<$util.Input<string>[]>;
+		securityGroups: $util.Input<$util.Input<string>[]>;
+	};
+}
+
+/** An ElastiCache-backed cache was declared and no VPC was supplied for it. */
+export class CacheNeedsVpc extends Error {
+	constructor(readonly id: string) {
+		super(
+			`'${id}' is an ElastiCache cache and needs a VPC to live in. Supply ` +
+				`one through the deploy layer — ` +
+				`fromManifest(stack, manifest, { ${id}: { vpc } }) — the same one ` +
+				`the functions that read it run in, since a cache in a VPC is ` +
+				`reachable from nowhere else.`,
+		);
+		this.name = 'CacheNeedsVpc';
+	}
+}
+
+/**
+ * A cache backed by the database was declared, and no database was.
+ *
+ * The same rule pg-boss has, and the same reason: provisioning a database to
+ * hold only a cache is the resource this design refuses to invent on your
+ * behalf.
+ */
+/**
+ * A cache's address: its database's URL, carrying the table it reads.
+ *
+ * The table travels in the URL rather than beside it because a database-backed
+ * cache has no address of its own — two caches in one database resolve the same
+ * connection string, so the parameter is the only thing that identifies which
+ * one a client is holding. Mirrors what the local target composes, so the same
+ * application code reads the same shape in both places.
+ */
+export function withCacheTable(url: string, table: string): string {
+	const parsed = new URL(url);
+	parsed.searchParams.set('table', table);
+
+	return parsed.toString();
+}
+
+/**
+ * `services.cache: 'db'` 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
+ * success. The fix is a stronger statement in application code:
+ * `orders.cache('Sessions')` names the database.
+ */
+export class CacheIsAmbiguous extends Error {
+	constructor(
+		readonly id: string,
+		readonly databases: readonly string[],
+	) {
+		super(
+			`'${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.`,
+		);
+		this.name = 'CacheIsAmbiguous';
+	}
+}
+
+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'.`,
+		);
+		this.name = 'CacheNeedsDatabase';
+	}
+}
+
+/**
+ * An Upstash cache was declared and Upstash's provider is not installed.
+ *
+ * SST preloads two providers and installs the rest on demand, so the global this
+ * component reaches for does not exist until somebody runs the command. Naming
+ * the command beats an undefined-name crash halfway through a synth.
+ */
+export class CacheNeedsProvider extends Error {
+	constructor(readonly id: string) {
+		super(
+			`'${id}' is an Upstash cache and the Upstash provider is not ` +
+				`installed. Run \`sst add upstash\` in the app, or supply a URL for ` +
+				`a database that already exists — ` +
+				`fromManifest(stack, manifest, { ${id}: { url } }).`,
+		);
+		this.name = 'CacheNeedsProvider';
+	}
+}

package/src/sst/aws/Credential.ts

@@ -0,0 +1,28 @@
+import { Secret, type SecretProps } from './Secret';
+
+/**
+ * `Credential` — a third-party credential SST holds, and the infra half of the
+ * `credential` kind.
+ *
+ * The *same storage* as a secret and a different kind, because what differs is
+ * 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`.
+ *
+ * The role is `credential` 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.
+ */
+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 };
+	}
+}
+
+export interface CredentialProps extends SecretProps {}

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

@@ -3,9 +3,9 @@ import {
 	flattenManifestField,
 	type ManifestField,
 } from '@geekmidas/manifest';
+import type { GkmLinkable } from '../Linkable';
+import type { StackType } from '../Stack';
 import { Function } from './Function';
-import type { GkmLinkable } from './Linkable';
-import type { StackType } from './Stack';
 
 export type CronExpressionValue = number | '*' | '?' | `${number}/${number}`;
 export type CronExpressionDay =

package/src/sst/aws/Database.ts

@@ -0,0 +1,190 @@
+import * as postgresUrl from '@geekmidas/db/pg/url';
+import { type GkmLinkable, ResourceType } from '../Linkable';
+import type { StackType } from '../Stack';
+
+/**
+ * `Database` — an RDS Postgres instance, and the infra half of the `database`
+ * kind.
+ *
+ * **A provisioned instance rather than Aurora Serverless v2.** Aurora is the
+ * more interesting answer on paper — it scales to zero, so an idle preview
+ * stage costs storage and nothing else, which suits a design that provisions
+ * per stage. It is also a cluster: more moving parts, a different resource
+ * type, and pricing that is harder to predict for the steady-state workload
+ * most stages actually are. A plain instance is the ordinary thing, and the
+ * ordinary thing is the better default.
+ *
+ * Aurora is not reachable from here: this class *is* the RDS component and its
+ * props are that component's args, so a stage wanting a cluster needs a second
+ * class rather than an override. Worth adding when something wants it; not
+ * worth pretending it already exists.
+ *
+ * :::caution
+ * Moving between the two replaces the database. They are different resources,
+ * not different settings — the data does not come with you.
+ * :::
+ *
+ * **Who provisions the read replica** — nobody does, and a reader resolves to
+ * the writer's address. An Aurora cluster has a reader endpoint; an RDS
+ * instance has no second address to hand out, so `DatabaseReader` returns this
+ * one. That is the fallback the design already specified for `--target=server`
+ * and it is safe for the same reason: read-only is enforced by the role's
+ * grants, never by which endpoint you happened to reach. Adding `replicas`
+ * creates instances but no endpoint that balances across them, so it changes
+ * nothing here.
+ */
+export class Database<
+		TStage extends string = string,
+		TDomain extends string = string,
+	>
+	extends sst.aws.Postgres
+	implements GkmLinkable
+{
+	readonly _id!: string;
+
+	get _type() {
+		return ResourceType.SSTPostgres;
+	}
+
+	/** The schema pinned on the connection's `search_path`, where one applies. */
+	private readonly schema: string | undefined;
+
+	/**
+	 * The VPC this cluster lives in.
+	 *
+	 * Kept so the bootstrap function can be put in the same one — a database
+	 * reachable from outside its VPC is the problem the requirement avoids, and
+	 * the DDL has to reach it from inside.
+	 */
+	readonly vpc: sst.aws.Vpc;
+
+	constructor(
+		_stack: StackType<TStage, TDomain>,
+		name: string,
+		props: DatabaseProps,
+	) {
+		const { schema, ...args } = props;
+
+		super(name, args);
+		this._id = name;
+		this.schema = schema;
+		this.vpc = args.vpc;
+	}
+
+	/**
+	 * One key, the URL a running handler connects with.
+	 *
+	 * The owner URL is deliberately not here. It exists — a migrator needs DDL
+	 * rights — but it is wired straight into the migrator by the adapter, so no
+	 * edge in any manifest can name it and nothing can be granted it by mistake.
+	 *
+	 * Composed through `@geekmidas/db`'s codec rather than by hand, which is what
+	 * puts `search_path` in as a libpq `options` parameter. A plain
+	 * `?search_path=` is accepted by every URL parser, ignored by the server, and
+	 * produces a database that looks empty.
+	 */
+	provides(): Record<string, $util.Input<string>> {
+		return { url: this.urlFor({}) };
+	}
+
+	/**
+	 * This cluster's connection URL, optionally through the reader endpoint or
+	 * pinned to a different schema.
+	 *
+	 * One composition serving three callers — the cluster itself, a reader, and
+	 * a schema tenant — so the three cannot come to disagree about how a URL is
+	 * put together. That matters more than it sounds: `search_path` is the part
+	 * that goes quietly missing when the join is done by hand.
+	 */
+	urlFor(options: {
+		/**
+		 * Ask for the read path.
+		 *
+		 * Kept in the signature and currently resolved to the same address: an
+		 * RDS instance has one endpoint. It states the caller's intent — a reader
+		 * wants the read path — so moving a stage to a cluster that *has* a second
+		 * endpoint changes one line here rather than every call site. What makes
+		 * the connection read-only is the role it authenticates as, not this.
+		 */
+		reader?: boolean;
+		schema?: string;
+		/**
+		 * Connect as a role other than the master.
+		 *
+		 * What every tenant does. The master credential exists before any role
+		 * does, which is why the bootstrap uses it and why nothing else should: a
+		 * handler holding it could drop the database it was reading.
+		 */
+		as?: { user: $util.Input<string>; password: $util.Input<string> };
+	}): $util.Input<string> {
+		// One address: an RDS instance has no reader endpoint. Reading through the
+		// writer is safe because the reader *role* is what forbids writing.
+		const host = this.host;
+		// A role carries its own `search_path`, pinned by `ALTER ROLE`. It goes in
+		// the URL only for the master, which has no role of its own to pin it on.
+		const searchPath = options.as ? undefined : (options.schema ?? this.schema);
+
+		return $util
+			.all([
+				host,
+				this.port,
+				this.database,
+				options.as?.user ?? this.username,
+				options.as?.password ?? this.password,
+			])
+			.apply(([resolvedHost, port, database, username, password]) =>
+				postgresUrl.build({
+					host: resolvedHost,
+					port,
+					database,
+					username,
+					password,
+					...(searchPath ? { searchPath } : {}),
+				}),
+			);
+	}
+
+	override getSSTLink() {
+		const link = super.getSSTLink();
+		return {
+			...link,
+			properties: { ...link.properties, ...this.provides() },
+		};
+	}
+}
+
+export interface DatabaseProps extends Omit<sst.aws.PostgresArgs, 'vpc'> {
+	/** The schema to pin on the connection's `search_path`. */
+	schema?: string;
+	/**
+	 * The VPC the database lives in.
+	 *
+	 * Narrowed to the component from the wider argument the RDS component
+	 * accepts, because the bootstrap function has to run in this same VPC and a
+	 * function needs security groups as well as subnets — which the loose form
+	 * cannot carry. Requiring the component means one thing is passed and both
+	 * halves can use it.
+	 */
+	vpc: sst.aws.Vpc;
+}
+
+/**
+ * A database was declared and the deploy layer supplied no VPC.
+ *
+ * Not something the adapter can default. RDS lives in a VPC, and creating one
+ * means creating a NAT gateway — a real monthly cost, in an account whose
+ * networking may already be someone else's decision. So it is required, named,
+ * and supplied where other provider-specific props are.
+ */
+export class DatabaseNeedsVpc extends Error {
+	constructor(readonly id: string) {
+		super(
+			`'${id}' is a database, and a database needs a VPC to live in. ` +
+				`Supply one through the deploy layer — ` +
+				`fromManifest(stack, manifest, { ${id}: { vpc } }) — because ` +
+				`creating one means creating a NAT gateway, which costs money in an ` +
+				`account whose networking may already be someone else's decision.`,
+		);
+		this.name = 'DatabaseNeedsVpc';
+	}
+}