@geekmidas/manifest 10.0.0-alpha.13 → 10.0.0-alpha.130

package/dist/index.cjs

@@ -34,6 +34,19 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 */
 const DEFAULT_POSTGRES_VERSION = 18;
 /**
+* What a `Telemetry` node provides to each process with an edge to it.
+*
+* `OTEL_SERVICE_NAME` is resolved per process — the app's name — so it is
+* listed here but composed by whichever target hands it over.
+*/
+const TELEMETRY_KEYS = [
+	"OTEL_EXPORTER_OTLP_ENDPOINT",
+	"OTEL_EXPORTER_OTLP_HEADERS",
+	"OTEL_SERVICE_NAME",
+	"OTEL_TRACES_SAMPLER",
+	"OTEL_TRACES_SAMPLER_ARG"
+];
+/**
 * What each kind may derive from.
 *
 * Small enough to state exhaustively, and stating it makes cycles impossible
@@ -57,21 +70,26 @@ const DERIVES_FROM = {
 const PUBLIC = {
 	objects: [],
 	"file-server": ["url"],
-	email: [],
+	email: ["inboxUrl"],
 	database: [],
 	"database-reader": [],
 	"database-schema": [],
 	cache: [],
 	secret: [],
 	credential: [],
+	encryption: [],
 	"rest-api": ["url"],
+	"websocket-api": ["url"],
 	queue: [],
 	topic: [],
 	oidc: ["issuer", "audience"],
+	"external-api": [],
 	function: [],
 	cron: [],
+	"mobile-app": [],
 	site: ["url"],
-	worker: []
+	worker: [],
+	telemetry: []
 };
 //#endregion
 //#region src/errors.ts
@@ -846,7 +864,9 @@ function cookieDomain(urls) {
 * cannot catch anything.
 */
 function providedKeyFor(id, kind, role) {
-	return kind === "secret" ? environmentCase(id) : provideKey(id, role);
+	if (kind === "secret") return environmentCase(id);
+	if (kind === "telemetry") return "OTEL_EXPORTER_OTLP_ENDPOINT";
+	return provideKey(id, role);
 }
 //#endregion
 //#region src/derive.ts
@@ -909,10 +929,15 @@ function dependenciesOf(declaration) {
 	const own = "dependencies" in declaration ? declaration.dependencies ?? [] : [];
 	const calls = "calls" in declaration ? declaration.calls ?? [] : [];
 	const nested = declaration.kind === "rest-api" ? declaration.endpoints.flatMap((endpoint) => endpoint.dependencies) : [];
+	const telemetry = "telemetry" in declaration && typeof declaration.telemetry === "string" ? [{
+		target: declaration.telemetry,
+		kind: "telemetry"
+	}] : [];
 	return [
 		...own,
 		...calls,
-		...nested
+		...nested,
+		...telemetry
 	];
 }
 /**
@@ -946,11 +971,13 @@ function dependentsOf(manifest, id) {
 const PUBLIC_PREFIX = {
 	static: "VITE_",
 	tanstack: "VITE_",
-	next: "NEXT_PUBLIC_"
+	next: "NEXT_PUBLIC_",
+	expo: "EXPO_PUBLIC_"
 };
 /**
 * The keys a site's bundle needs, mapped to the key each value comes from —
-* `{ VITE_API_URL: 'API_URL' }`.
+* `{ VITE_API_URL: 'API_URL' }` — its edges' public values, and a site's own
+* address (`{ VITE_WEB_URL: 'WEB_URL' }`).
 *
 * A rename, not a second derivation: `API_URL` is resolved once, by whatever
 * resolved it for the server, and the site reads the same value under the name
@@ -969,6 +996,10 @@ const PUBLIC_PREFIX = {
 function publicEnvFor(declaration, manifest) {
 	const prefix = PUBLIC_PREFIX[declaration.variant];
 	const keys = {};
+	if (declaration.kind === "site") {
+		const own = provideKey(declaration.id, "url");
+		keys[`${prefix}${own}`] = own;
+	}
 	for (const edge of declaration.dependencies) {
 		const target = manifest[edge.target];
 		if (!target) continue;
@@ -980,36 +1011,288 @@ function publicEnvFor(declaration, manifest) {
 	return keys;
 }
 //#endregion
-//#region src/index.ts
-/** Flatten a manifest field (array or partitioned) into a plain array. */
-function flattenManifestField(field) {
-	if (!field) return [];
-	return Array.isArray(field) ? [...field] : Object.values(field).flat();
+//#region src/derived.ts
+/** Where a processor keeps what it made, in the bucket it reads. */
+const DERIVED_PREFIX = ".gkm-derived/";
+/** How long a derivative is kept when its file server does not say. */
+const DEFAULT_DERIVED_DAYS = 30;
+/**
+* The days a bucket keeps what is under each prefix: what it declared, and —
+* when a file server over it has processors — the derived prefix, for the
+* longest any of those servers asked. `undefined` when it expires nothing.
+*/
+function bucketExpiry(manifest, bucketId) {
+	const expire = { ...manifest[bucketId]?.expire ?? {} };
+	const processed = Object.values(manifest).filter((d) => d.kind === "file-server" && d.of === bucketId && (d.processors?.length ?? 0) > 0);
+	if (processed.length > 0 && expire[".gkm-derived/"] === void 0) expire[DERIVED_PREFIX] = Math.max(...processed.map((s) => s.derivedDays ?? 30));
+	return Object.keys(expire).length > 0 ? expire : void 0;
+}
+//#endregion
+//#region src/encryption.ts
+/**
+* The `kms://` URL an `Encryption` construct reads on AWS.
+*
+* Here because two packages meet on it: `@geekmidas/cloud` composes it from
+* the keys it provisioned, and `@geekmidas/constructs` parses it to reach
+* them. One function, so the two cannot disagree about a parameter's name.
+*/
+const KMS_SCHEME = "kms:";
+/**
+* `kms://<region>?key=<key arn>&index=<hmac key arn>[&endpoint=<url>]`
+*
+* `endpoint` reaches an emulator instead of AWS — floci, locally and in tests —
+* the same parameter an `sns://` connection string carries for the same reason.
+*/
+function kmsUrl(input) {
+	const query = new URLSearchParams({
+		key: input.key,
+		index: input.index,
+		...input.endpoint ? { endpoint: input.endpoint } : {}
+	});
+	return `${KMS_SCHEME}//${input.region}?${query}`;
+}
+//#endregion
+//#region src/external.ts
+/** The key in a by-stage `url` that answers for every stage not listed. */
+const DEFAULT_STAGE_URL = "default";
+/**
+* Where an external API answers on a deployed stage.
+*
+* One URL answers every stage; a record answers by stage name, falling back
+* to `default`. Read at build and deploy, so a stage nobody gave a URL fails
+* there — with the stage named — rather than at the first request.
+*
+* @throws {NoUrlForStage} when a record names neither the stage nor a default.
+*/
+function externalApiUrl(declaration, stage) {
+	const { url } = declaration;
+	if (typeof url === "string") return url;
+	const resolved = url[stage] ?? url["default"];
+	if (!resolved) throw new NoUrlForStage(declaration.id, stage, Object.keys(url));
+	return resolved;
+}
+/** An external API's `url` record has nothing for the stage being deployed. */
+var NoUrlForStage = class extends Error {
+	id;
+	stage;
+	stages;
+	constructor(id, stage, stages) {
+		super(`'${id}' has no URL for the stage '${stage}': its url names ${stages.length ? stages.map((s) => `'${s}'`).join(", ") : "no stages"}. Add '${stage}', or a '${DEFAULT_STAGE_URL}' for every stage not listed.`);
+		this.id = id;
+		this.stage = stage;
+		this.stages = stages;
+		this.name = "NoUrlForStage";
+	}
+};
+//#endregion
+//#region src/headers.ts
+/**
+* Headers gkm reserves for its own services' calls to each other.
+*
+* Shared by `@geekmidas/constructs`, which sends and reads them, and
+* `@geekmidas/cli`, whose edges strip them from every request that arrives
+* from outside — so the two cannot name them differently.
+*/
+/**
+* The address of the client a service-to-service call is made on behalf of.
+*
+* An API asking its auth server for a session sends the client's address in
+* this rather than `X-Forwarded-For`: a forwarding header marks a request as
+* outside traffic, which would start the auth server's span in a new trace,
+* and the address is still needed — Better Auth rate-limits per client.
+*
+* Reserved: the stack's edge (Caddy, Traefik, the `gkm dev` edge) removes it
+* from incoming requests, and the auth server ignores it on any request that
+* is not an internal caller's, so it cannot be spoofed from outside.
+*/
+const CLIENT_IP_HEADER = "x-gkm-client-ip";
+//#endregion
+//#region src/migrations.ts
+/** Where every construct's folder lives, from the project root. */
+const MIGRATIONS_ROOT = "db";
+/** The two folders a construct's folder holds, and nothing else. */
+const DATABASE_FOLDERS = ["migrations", "seeds"];
+/**
+* The constructs that take migrations, parents before the tenants inside them.
+*
+* A database and each schema tenant: every one has an owner role and a schema
+* of its own, and so a history of its own. A reader has neither — it reads its
+* parent's schema — and a cache's table is created by provisioning, not by a
+* migration anyone writes.
+*/
+function migrationTargets(manifest) {
+	return provisionOrder(manifest).flatMap((id) => {
+		const declaration = manifest[id];
+		if (!declaration) return [];
+		if (declaration.kind === "database") return [target(id)];
+		if (declaration.kind === "database-schema") return [{
+			...target(id),
+			of: declaration.of
+		}];
+		return [];
+	});
+}
+/**
+* A construct's folder, relative to the project root.
+*
+* Named by the construct — `AuthDatabase` is `db/auth-database` — in the case
+* every other name outside TypeScript takes. Lowercase, because a folder that
+* differs from another only in case is two folders on Linux and one on a Mac;
+* and `canonicalId` reads it back to the construct exactly, which is how a
+* folder naming nothing is caught rather than skipped.
+*/
+function databaseFolder(id) {
+	return `db/${kebabCase(id)}`;
+}
+/** Where a construct's migrations live: `db/auth-database/migrations`. */
+function migrationFolder(id) {
+	return `${databaseFolder(id)}/migrations`;
+}
+/**
+* Where a construct's seeds live: `db/auth-database/seeds`.
+*
+* Reference data the app needs to run — a permission catalogue, roles, lookup
+* tables. Seeds are upserts run on every pass, after the migrations, so a
+* changed seed is applied by running it again. Sample data is factories'.
+*/
+function seedFolder(id) {
+	return `${databaseFolder(id)}/seeds`;
+}
+function target(id) {
+	return {
+		id,
+		folder: databaseFolder(id),
+		migrations: migrationFolder(id),
+		seeds: seedFolder(id)
+	};
+}
+//#endregion
+//#region src/mobile.ts
+/**
+* How a mobile app is reached: its URL scheme, and the origins a surface trusts
+* for it.
+*
+* Stated once, here, because three targets ask — the local one (`gkm dev`,
+* `gkm test`), Dokploy and AWS — and a scheme one of them derived differently
+* would be an app whose sign-in callback the auth server refuses on exactly one
+* of them.
+*/
+/**
+* An app's scheme: the one given, or the project's name made a valid scheme.
+*
+* One for every stage. A development build and the store build register the
+* same scheme, so the auth server of whichever stage a build talks to trusts
+* it, and nothing about the app differs between stages but its URLs.
+*
+* A scheme is a letter followed by letters, digits, `+`, `-` or `.` — so
+* `Corner Shop` becomes `corner-shop`, and a name that starts with a digit gets a
+* leading `app`.
+*/
+function schemeBase(project, given) {
+	const raw = (given ?? project).toLowerCase().replace(/[^a-z0-9+.-]+/g, "-").replace(/^-+|-+$/g, "");
+	if (!raw) return "app";
+	return /^[a-z]/.test(raw) ? raw : `app${raw}`;
+}
+/**
+* The origins a surface trusts for a mobile caller.
+*
+* Better Auth's Expo plugin sends the app's scheme as its origin
+* (`shop://`), and a link can carry a path after it (`shop://*`).
+* In development, Expo Go sends `exp://<host>:<port>` instead — so a local
+* stage adds the hosts a device actually reaches Metro on, and Metro's port
+* when the target placed it: a whole subnet is not trusted because one phone
+* is on it.
+*/
+function mobileOrigins(scheme, metro) {
+	return [
+		`${scheme}://`,
+		`${scheme}://*`,
+		...(metro?.hosts ?? []).flatMap((host) => [`exp://${host}:${metro?.port ?? "*"}`, `exp://${host}:${metro?.port ?? "*"}/**`])
+	];
+}
+/** Whether an origin is a web one — what a cookie domain is derived from. */
+function isWebOrigin(origin) {
+	return origin.startsWith("http://") || origin.startsWith("https://");
+}
+//#endregion
+//#region src/secret.ts
+/**
+* What a generated secret looks like, and the one way every stage draws it.
+*
+* A server deploy draws from `crypto`, `gkm dev` and `gkm test` from a hash of
+* the project, stage and id, and an AWS deploy asks Pulumi for the same
+* alphabet. Sharing this is what keeps a password that passes a third party's
+* rules on one stage from failing them on the next.
+*/
+/** 43 characters from 64 is 256 bits — as much as anything here needs. */
+const SECRET_LENGTH = 43;
+/**
+* Two symbols nothing has to escape — not a URL, a connection string, a shell
+* or a `.env` file — which with letters and digits is base64url's alphabet.
+*/
+const SECRET_SYMBOLS = "-_";
+const LETTERS_AND_DIGITS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+/**
+* A secret in `format`, each character chosen by `pick(n)` — an integer in
+* `[0, n)` from whatever source the caller trusts.
+*
+* When there are symbols, one is guaranteed: a rule that demands a symbol is
+* the reason anyone names them, and leaving it to chance fails it often —
+* about one draw in seven at 24 characters.
+*/
+function drawSecret(pick, format = {}) {
+	const length = format.length ?? 43;
+	const symbols = [...new Set(format.symbols ?? "-_")].join("");
+	const alphabet = LETTERS_AND_DIGITS + symbols;
+	const chars = Array.from({ length }, () => alphabet[pick(alphabet.length)]);
+	if (symbols && !chars.some((char) => symbols.includes(char))) chars[pick(length)] = symbols[pick(symbols.length)];
+	return chars.join("");
 }
 //#endregion
+exports.CLIENT_IP_HEADER = CLIENT_IP_HEADER;
+exports.DATABASE_FOLDERS = DATABASE_FOLDERS;
+exports.DEFAULT_DERIVED_DAYS = DEFAULT_DERIVED_DAYS;
 exports.DEFAULT_POSTGRES_VERSION = DEFAULT_POSTGRES_VERSION;
+exports.DEFAULT_STAGE_URL = DEFAULT_STAGE_URL;
+exports.DERIVED_PREFIX = DERIVED_PREFIX;
 exports.DERIVES_FROM = DERIVES_FROM;
 exports.IllegalDerivation = IllegalDerivation;
 exports.InvalidConstructId = InvalidConstructId;
+exports.KMS_SCHEME = KMS_SCHEME;
+exports.MIGRATIONS_ROOT = MIGRATIONS_ROOT;
+exports.NoUrlForStage = NoUrlForStage;
 exports.PUBLIC = PUBLIC;
 exports.PUBLIC_PREFIX = PUBLIC_PREFIX;
+exports.SECRET_LENGTH = SECRET_LENGTH;
+exports.SECRET_SYMBOLS = SECRET_SYMBOLS;
+exports.TELEMETRY_KEYS = TELEMETRY_KEYS;
 exports.UnknownParent = UnknownParent;
 exports.assertDerivations = assertDerivations;
+exports.bucketExpiry = bucketExpiry;
 exports.cacheTable = cacheTable;
 exports.canonicalId = canonicalId;
 exports.cloudName = cloudName;
 exports.cookieDomain = cookieDomain;
+exports.databaseFolder = databaseFolder;
 exports.dependenciesOf = dependenciesOf;
 exports.dependentsOf = dependentsOf;
+exports.drawSecret = drawSecret;
 exports.environmentCase = environmentCase;
-exports.flattenManifestField = flattenManifestField;
+exports.externalApiUrl = externalApiUrl;
 exports.isDerived = isDerived;
+exports.isWebOrigin = isWebOrigin;
 exports.kebabCase = kebabCase;
+exports.kmsUrl = kmsUrl;
+exports.migrationFolder = migrationFolder;
+exports.migrationTargets = migrationTargets;
+exports.mobileOrigins = mobileOrigins;
 exports.provideKey = provideKey;
 exports.providedKeyFor = providedKeyFor;
 exports.provisionOrder = provisionOrder;
 exports.publicEnvFor = publicEnvFor;
+exports.schemeBase = schemeBase;
 exports.scopedName = scopedName;
+exports.seedFolder = seedFolder;
 exports.serviceKey = serviceKey;
 
 //# sourceMappingURL=index.cjs.map