@geekmidas/cli 10.0.0-alpha.12 → 10.0.0-alpha.120

package/dist/SubscriberGenerator-C8CPxrCK.cjs

@@ -0,0 +1,592 @@
+const require_errors = require("./errors-DMC4Umsb.cjs");
+const require_EndpointGenerator = require("./EndpointGenerator-BDa6pPgE.cjs");
+const require_discover = require("./discover-DozUKs8f.cjs");
+let node_path = require("node:path");
+let node_fs_promises = require("node:fs/promises");
+let _geekmidas_manifest = require("@geekmidas/manifest");
+let node_url = require("node:url");
+let _geekmidas_constructs_subscribers = require("@geekmidas/constructs/subscribers");
+//#region src/types.ts
+/** Whether `value` names a cache backend. */
+function isCacheBackend(value) {
+	return value === "upstash" || value === "elasticache" || value === "db" || value === "redis";
+}
+/**
+* Whether a backend holds every declared cache, a cache declared from a
+* database (`database.cache('Sessions')`) included.
+*
+* Every other backend leaves such a cache where its declaration put it: the
+* declaration is the stronger statement. The stack's own Redis is the
+* exception, because a stack that runs one runs it *for* the cache — a table
+* beside it would be a second cache nobody asked for.
+*/
+function holdsEveryCache(backend) {
+	return backend === "redis";
+}
+/**
+* The backend a project gets when it says nothing, by where it deploys.
+*
+* Flat defaults could not be right for both: `upstash` on a single box means a
+* SaaS round-trip for a cache the database could have held, and `minio` on AWS
+* means running a bucket beside S3. So the default is a function of the target,
+* and an app that says nothing gets the obvious answer in both places — which
+* is the whole of what "zero config" can mean once there is more than one
+* target.
+*
+* `server` covers Dokploy and a bare host alike: the question these answer is
+* whether the app is next to a managed cloud or next to its own containers, and
+* on that question the two are the same.
+*
+* A per-construct, per-stage override is the layer above this — see
+* `constructs-outstanding.md` — so two buckets in one app can differ. This is
+* only what happens when nobody has said anything at all.
+*/
+const DEFAULT_CACHE = {
+	aws: "upstash",
+	server: "db"
+};
+/**
+* Which broker carries a declared queue or topic, by target.
+*
+* Whether there are events at all is the manifest's answer — a declared
+* `Topic` or `Queue` — so this only ever answers the second question. AWS
+* deploys them to SNS and SQS, and locally the AWS emulator stands in, so the
+* broker a developer runs is the one production has. A server has a Postgres
+* already, and pg-boss keeps its queues there.
+*/
+const DEFAULT_EVENTS = {
+	aws: "sns",
+	server: "pgboss"
+};
+/** Where a bucket lives when nobody said — see {@link DEFAULT_CACHE}. */
+const DEFAULT_STORAGE = {
+	aws: "s3",
+	server: "minio"
+};
+//#endregion
+//#region src/reconcile/fakes.ts
+/**
+* Fakes, read from where the convention puts them.
+*
+* `test/fakes/<id>.ts` default-exports `fake.app(…)` or `fake.image(…)` for an
+* external API, and `fake.credential(…)` for a credential. The construct never
+* names it — that is what keeps a fake out of a deployed bundle — so this is
+* the one place it is found, by the same rule that finds a database's factory
+* in `test/factories/<id>.ts`.
+*/
+/** Where a project keeps its external APIs' fakes, relative to its root. */
+const DEFAULT_FAKES_DIR = "test/fakes";
+/** The marker `fake.app` and `fake.image` set — the same registered symbol. */
+const FAKE = Symbol.for("@geekmidas/constructs/fake");
+/**
+* The fake for every external API the manifest declares, keyed by id.
+*
+* @throws {NoFake} when an external API has no file, since a local stage would
+* otherwise have nothing to call.
+* @throws {NotAFake} when the file's default export is not one.
+*/
+async function readFakes(root, manifest) {
+	const fakes = {};
+	for (const [id, declaration] of Object.entries(manifest)) {
+		if (declaration?.kind !== "external-api") continue;
+		const file = await fakeFile((0, node_path.join)(root, DEFAULT_FAKES_DIR), id);
+		if (!file) throw new NoFake(id, `${fakeBase(root, id)}.ts`);
+		const value = await importFake(file);
+		if (value.kind === "credential") throw new NotAFake(file);
+		fakes[id] = {
+			file,
+			...value.kind === "image" ? {
+				image: value.image,
+				port: value.port
+			} : {},
+			credentials: JSON.stringify(value.credentials)
+		};
+	}
+	return fakes;
+}
+/**
+* Each credential's fake value, as the JSON `<ID>_CREDENTIALS` holds, keyed by
+* id — for the credentials that have a fake. Unlike an external API's, a
+* credential's fake is optional here: a stage that stores the real value
+* needs none. The test stage's own check (`assertTestCredentials`) is what
+* refuses one with neither.
+*
+* @throws {NotAFake} when the file's default export is not a credential's fake.
+*/
+async function readCredentialFakes(root, manifest) {
+	const values = {};
+	for (const [id, declaration] of Object.entries(manifest)) {
+		if (declaration?.kind !== "credential") continue;
+		const file = await fakeFile((0, node_path.join)(root, DEFAULT_FAKES_DIR), id);
+		if (!file) continue;
+		const value = await importFake(file);
+		if (value.kind !== "credential") throw new NotAFake(file);
+		values[id] = JSON.stringify(value.credentials);
+	}
+	return values;
+}
+/**
+* A credential the test stage has no value for: no fake, and nothing stored.
+* Raised when the stage is set up, before a test reaches it — not as a schema
+* error inside the handler that first asked.
+*/
+var CredentialHasNoTestValue = class extends require_errors.GkmError {
+	id;
+	key;
+	file;
+	constructor(id, key, file) {
+		super(`'${id}' is a credential, and the test stage has no value for ${key}: no fake, and none stored — a stage set up fresh, as CI's auto-setup does, holds no third party's credentials. Give it a fake: create ${file}, default-exporting fake.credential(…) from @geekmidas/constructs/credential. It is read only by gkm test and gkm dev --fake; a deployed stage still needs the real value (gkm secrets:add --stage <stage>).`);
+		this.id = id;
+		this.key = key;
+		this.file = file;
+		this.name = "CredentialHasNoTestValue";
+	}
+};
+/**
+* Every credential the test stage must hand its suite, with the value it
+* resolved — a fake's, or one the stage stores.
+*
+* @throws {CredentialHasNoTestValue} for the first one with neither.
+*/
+function assertTestCredentials(root, plan, env) {
+	const values = {};
+	for (const { id, kind, envKey } of plan.resources) {
+		if (kind !== "credential") continue;
+		const value = env[envKey];
+		if (value === void 0) throw new CredentialHasNoTestValue(id, envKey, `${fakeBase(root, id)}.ts`);
+		values[envKey] = value;
+	}
+	return values;
+}
+/** `<root>/test/fakes/<id>`, without an extension. */
+function fakeBase(root, id) {
+	return (0, node_path.join)(root, DEFAULT_FAKES_DIR, (0, _geekmidas_manifest.kebabCase)(id));
+}
+/** The first of `<id>.ts`, `.mts`, `.js`, `.mjs` that exists. */
+async function fakeFile(folder, id) {
+	const base = (0, node_path.join)(folder, (0, _geekmidas_manifest.kebabCase)(id));
+	for (const extension of [
+		".ts",
+		".mts",
+		".js",
+		".mjs"
+	]) {
+		const file = `${base}${extension}`;
+		if (await (0, node_fs_promises.access)(file).then(() => true, () => false)) return file;
+	}
+}
+/**
+* A fake file's default export.
+*
+* @throws {NotAFake} when it is not a fake.
+*/
+async function importFake(file) {
+	const value = (await import((0, node_url.pathToFileURL)(file).href)).default;
+	if (!isFakeExport(value)) throw new NotAFake(file);
+	return value;
+}
+function isFakeExport(value) {
+	return typeof value === "object" && value !== null && value[FAKE] === true;
+}
+/** An external API with no fake for a local stage to call. */
+var NoFake = class extends require_errors.GkmError {
+	id;
+	file;
+	constructor(id, file) {
+		super(`'${id}' is an external API, and a local stage calls its fake rather than the provider — but there is none. Create ${file}, default-exporting fake.app(…) or fake.image(…) from @geekmidas/constructs/external-api.`);
+		this.id = id;
+		this.file = file;
+		this.name = "NoFake";
+	}
+};
+/** A file in the fakes folder whose default export is not a fake. */
+var NotAFake = class extends require_errors.GkmError {
+	file;
+	constructor(file) {
+		super(`${file} is where a fake lives, and its default export is not one for its construct. For an external API, export default fake.app(handler, { credentials }) or fake.image(image, { port, credentials }); for a credential, fake.credential(value).`);
+		this.file = file;
+		this.name = "NotAFake";
+	}
+};
+//#endregion
+//#region src/generators/subscriberRoute.ts
+/**
+* Where SNS pushes a topic subscriber's messages, on the server that runs it:
+* named after the subscriber's export.
+*
+* One definition for both sides — the generated server mounts the route, and
+* the stack exposes exactly these paths on a worker's host — so the path the
+* edge lets through and the path the worker answers cannot drift.
+*/
+const SUBSCRIBER_ROUTE_PREFIX = "/__gkm/subscribers/";
+/** The route a subscriber's pushes arrive on. */
+function subscriberRoute(exportName) {
+	return `${SUBSCRIBER_ROUTE_PREFIX}${exportName}`;
+}
+//#endregion
+//#region src/generators/SubscriberGenerator.ts
+var SubscriberGenerator = class extends require_discover.ConstructGenerator {
+	isConstruct(value) {
+		return _geekmidas_constructs_subscribers.Subscriber.isSubscriber(value);
+	}
+	async build(context, constructs, outputDir, options) {
+		const target = options?.target ?? "aws";
+		const logger = console;
+		const subscriberInfos = [];
+		if (target === "server") {
+			await this.generateServerSubscribersFile(outputDir, constructs, context.eventsBackends?.includes("sns") ?? false);
+			logger.log(`Generated server subscribers file with ${constructs.length} subscribers (polling mode)`);
+			return subscriberInfos;
+		}
+		if (constructs.length === 0) return subscriberInfos;
+		const subscribersDir = (0, node_path.join)(outputDir, "subscribers");
+		await (0, node_fs_promises.mkdir)(subscribersDir, { recursive: true });
+		for (const { key, construct, path } of constructs) {
+			const handlerFile = await this.generateSubscriberHandler(subscribersDir, path.relative, key, construct, context, construct.owner);
+			subscriberInfos.push({
+				name: key,
+				handler: (0, node_path.relative)(options?.root ?? process.cwd(), handlerFile).replace(/\.ts$/, ".handler"),
+				subscribedEvents: construct.subscribedEvents || [],
+				...construct.topicName ? {
+					transport: "topic",
+					topic: construct.topicName
+				} : {},
+				timeout: construct.timeout,
+				memorySize: construct.memorySize,
+				environment: await construct.getEnvironment({ markOptional: context.markOptional }),
+				dependencies: construct.constructs
+			});
+			logger.log(`Generated subscriber handler: ${key}`);
+		}
+		return subscriberInfos;
+	}
+	async generateSubscriberHandler(outputDir, sourceFile, exportName, _subscriber, context, owner) {
+		const handlerFileName = `${exportName}.ts`;
+		const handlerPath = (0, node_path.join)(outputDir, handlerFileName);
+		const importPath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), sourceFile).replace(/\.ts$/, ".js");
+		const runtime = require_EndpointGenerator.runtimeFor(context, (0, node_path.dirname)(handlerPath), owner);
+		const content = `import { AWSLambdaSubscriber } from '@geekmidas/constructs/aws';
+import { ${exportName} } from '${importPath}';
+${runtime.imports}
+${context.storageDrivers?.imports ?? ""}
+${runtime.bindings}
+${context.storageDrivers?.setup ? `\n// The handler registers the drivers its target needs.\n${context.storageDrivers.setup}\n` : ""}
+const adapter = new AWSLambdaSubscriber(envParser, ${exportName});
+
+export const handler = adapter.handler;
+`;
+		await (0, node_fs_promises.writeFile)(handlerPath, content);
+		return handlerPath;
+	}
+	async generateServerSubscribersFile(outputDir, subscribers, push) {
+		await (0, node_fs_promises.mkdir)(outputDir, { recursive: true });
+		const subscribersPath = (0, node_path.join)(outputDir, "subscribers.ts");
+		if (subscribers.length === 0) {
+			await (0, node_fs_promises.writeFile)(subscribersPath, `/**
+ * Generated subscribers setup — this app declares none.
+ */
+import type { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+
+export async function setupSubscribers(
+  _app: unknown,
+  _envParser: EnvironmentParser<any>,
+  _logger: Logger,
+): Promise<(port: number) => Promise<void>> {
+  return async () => {};
+}
+
+export function subscribersStatus(): { failed: string[]; connections: unknown[] } {
+  return { failed: [], connections: [] };
+}
+
+export async function stopSubscribers(): Promise<void> {}
+`);
+			return subscribersPath;
+		}
+		const importsByFile = /* @__PURE__ */ new Map();
+		for (const { path, key } of subscribers) {
+			const importPath = (0, node_path.relative)((0, node_path.dirname)(subscribersPath), path.relative).replace(/\.ts$/, ".js");
+			importsByFile.set(importPath, [...importsByFile.get(importPath) ?? [], key]);
+		}
+		const content = `/**
+ * Generated subscribers setup.
+ *
+ * Each subscriber is run against the topic it is bound to, through that
+ * topic's own connection string:
+ *
+ * - **sns://** — pushed, not polled. The subscriber gets an HTTP route on this
+ *   server, and the route is subscribed to the topic with a filter policy of
+ *   the events it named, so SNS fans out to each subscriber. The route runs the
+ *   subscriber through the same adaptor a Lambda subscription does.
+ * - **anything else** (pgboss://, rabbitmq://, sqs://) — polled. On pg-boss
+ *   each subscriber drains a queue of its own, \`<topic>/<subscriber>\`, so
+ *   every subscriber sees every event; replicas of one subscriber share it.
+ *
+ * GKM_SUBSCRIBERS=off (\`gkm dev --no-subscribers\`) runs none of them.
+ * GKM_SUBSCRIBER_PUSH_URL is the address SNS pushes to; against the local
+ * emulator it defaults to this server through host.docker.internal.
+ */
+import { connect } from 'node:net';
+import type { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+import { EventConnectionFactory, Subscriber } from '@geekmidas/events';
+import type { EventConnection } from '@geekmidas/events';
+import { ServiceDiscovery } from '@geekmidas/services';
+${Array.from(importsByFile.entries()).map(([importPath, exports]) => `import { ${exports.join(", ")} } from '${importPath}';`).join("\n")}
+
+const subscribers = [
+${subscribers.map(({ key, construct }) => {
+			const connectionKey = construct.topicName ? (0, _geekmidas_manifest.provideKey)((0, _geekmidas_manifest.canonicalId)(construct.topicName), "publisherConnectionString") : void 0;
+			return `  { id: '${key}', subscriber: ${key}, topic: ${construct.topicName ? `'${construct.topicName}'` : "undefined"}, connectionKey: ${connectionKey ? `'${connectionKey}'` : "undefined"} },`;
+		}).join("\n")}
+];
+
+// What was opened, and what could not be: a worker's health check reads both,
+// and its shutdown closes what was opened.
+const connections = new Map<string, EventConnection>();
+const failed: string[] = [];
+
+/** The route a subscriber's pushes arrive on. */
+export const SUBSCRIBER_ROUTE = (id: string) => \`${SUBSCRIBER_ROUTE_PREFIX}\${id}\`;
+
+/** Resolves once something is accepting connections on the port. */
+async function listening(port: number): Promise<void> {
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const open = await new Promise<boolean>((resolve) => {
+      const socket = connect(port, '127.0.0.1');
+      socket.once('connect', () => { socket.end(); resolve(true); });
+      socket.once('error', () => resolve(false));
+    });
+    if (open) return;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
+/**
+ * Mount each pushed subscriber's route and start each polled one. Returns what
+ * to run once the server is listening: subscribing a route makes SNS send its
+ * confirmation at once, so the route has to be reachable first.
+ */
+export async function setupSubscribers(
+  app: { post: (path: string, handler: (c: any) => unknown) => unknown },
+  envParser: EnvironmentParser<any>,
+  logger: Logger,
+): Promise<(port: number) => Promise<void>> {
+  if (process.env.GKM_SUBSCRIBERS === 'off') {
+    logger.info('Subscribers are off (--no-subscribers)');
+    return async () => {};
+  }
+
+  const serviceDiscovery = ServiceDiscovery.getInstance(envParser);
+  const afterListening: ((port: number) => Promise<void>)[] = [];
+
+  for (const { id, subscriber, topic, connectionKey } of subscribers) {
+    const events = subscriber.subscribedEvents || [];
+    if (events.length === 0) {
+      logger.warn({ subscriber: id }, 'Subscriber has no subscribed events, skipping');
+      continue;
+    }
+    const connectionString = connectionKey ? process.env[connectionKey] : undefined;
+    if (!connectionString) {
+      logger.error(
+        { subscriber: id, connectionKey },
+        'No connection string for the topic this subscriber is bound to',
+      );
+      failed.push(id);
+      continue;
+    }
+
+    try {
+${push ? `      if (connectionString.startsWith('sns:')) {
+        const { SNSConnection, snsUrl, subscribeHttpEndpoint } = await import('@geekmidas/events/sns');
+        const { SnsPushSubscriberAdaptor } = await import('@geekmidas/constructs/subscribers');
+        const address = snsUrl.parse(connectionString);
+        const route = SUBSCRIBER_ROUTE(id);
+        const adaptor = new SnsPushSubscriberAdaptor(envParser, subscriber, {
+          topicArn: address.topicArn,
+          // An emulator signs nothing. Decided by the address this server was
+          // configured with, never by anything a request says about itself.
+          verify: !address.endpoint,
+          ...(address.endpoint ? { emulatorEndpoint: address.endpoint } : {}),
+        });
+
+        app.post(route, async (c: any) => {
+          const body = JSON.parse(await c.req.text());
+          const response = await adaptor.handle(body);
+          return c.json(response.body, response.status);
+        });
+
+        afterListening.push(async (port) => {
+          const base =
+            process.env.GKM_SUBSCRIBER_PUSH_URL ??
+            (address.endpoint ? \`http://host.docker.internal:\${port}\` : undefined);
+          if (!base) {
+            logger.error(
+              { subscriber: id },
+              'Set GKM_SUBSCRIBER_PUSH_URL to the public URL of this worker, which SNS pushes to',
+            );
+            return;
+          }
+          const connection = await SNSConnection.fromConnectionString(connectionString);
+          await subscribeHttpEndpoint(connection, {
+            endpoint: new URL(route, base).toString(),
+            events,
+          });
+          logger.info({ subscriber: id, events }, 'Subscriber subscribed for push');
+        });
+        continue;
+      }
+` : `      if (connectionString.startsWith('sns:')) {
+        // Built for a broker other than SNS, so this entry registered no SNS
+        // driver and has no push route to offer.
+        logger.error(
+          { subscriber: id, connectionKey },
+          'This build has no SNS driver: it was built for a target whose broker is not SNS',
+        );
+        failed.push(id);
+        continue;
+      }
+`}
+
+      let connection = connections.get(connectionString);
+      if (!connection) {
+        connection = await EventConnectionFactory.fromConnectionString(connectionString);
+        connections.set(connectionString, connection);
+      }
+      // Named, so a broker with one address for everything (pg-boss) gives
+      // this subscriber a queue of its own: fan-out, not competition.
+      const eventSubscriber = await Subscriber.fromConnection(connection, {
+        topic,
+        subscription: id,
+      });
+      const services = subscriber.services.length > 0
+        ? await serviceDiscovery.register(subscriber.services)
+        : {};
+      // The subscriber's database — the worker's, or its own — as \`db\`. A
+      // pushed subscriber gets it from the adaptor above instead.
+      const db = subscriber.databaseService
+        ? (await serviceDiscovery.register([subscriber.databaseService]))[
+            subscriber.databaseService.serviceName
+          ]
+        : undefined;
+
+      await eventSubscriber.subscribe(events, async (event) => {
+        try {
+          await subscriber.handler({
+            events: [event],
+            services: services as any,
+            logger: subscriber.logger,
+            db,
+          } as any);
+        } catch (error) {
+          logger.error({ err: error, event, subscriber: id }, 'Failed to process event');
+          // Rethrown so the transport keeps the event for a retry — as a queue
+          // consumer's failure does, and as a pushed subscriber's 500 does.
+          throw error;
+        }
+      });
+      logger.info({ subscriber: id, events }, 'Subscriber started polling');
+    } catch (error) {
+      // The message too: a missing module's code alone does not say which.
+      logger.error(
+        { err: error, subscriber: id },
+        'Failed to set up subscriber',
+      );
+      failed.push(id);
+    }
+  }
+
+  return async (port) => {
+    if (afterListening.length === 0) return;
+    await listening(port);
+    for (const subscribe of afterListening) {
+      await subscribe(port).catch((error) => {
+        logger.error({ err: error }, 'Failed to subscribe for push');
+      });
+    }
+  };
+}
+
+/** The subscribers that could not start, and the connections that did. */
+export function subscribersStatus(): { failed: string[]; connections: EventConnection[] } {
+  return { failed: [...failed], connections: [...connections.values()] };
+}
+
+/**
+ * Stop polling, let the events in flight finish, and close each broker
+ * connection — pg-boss's graceful stop does all three. The caller bounds it.
+ */
+export async function stopSubscribers(): Promise<void> {
+  const open = [...connections.values()];
+  connections.clear();
+  await Promise.all(open.map((connection) => connection.close()));
+}
+`;
+		await (0, node_fs_promises.writeFile)(subscribersPath, content);
+		return subscribersPath;
+	}
+};
+//#endregion
+Object.defineProperty(exports, "DEFAULT_CACHE", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_CACHE;
+	}
+});
+Object.defineProperty(exports, "DEFAULT_EVENTS", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_EVENTS;
+	}
+});
+Object.defineProperty(exports, "DEFAULT_STORAGE", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_STORAGE;
+	}
+});
+Object.defineProperty(exports, "SubscriberGenerator", {
+	enumerable: true,
+	get: function() {
+		return SubscriberGenerator;
+	}
+});
+Object.defineProperty(exports, "assertTestCredentials", {
+	enumerable: true,
+	get: function() {
+		return assertTestCredentials;
+	}
+});
+Object.defineProperty(exports, "holdsEveryCache", {
+	enumerable: true,
+	get: function() {
+		return holdsEveryCache;
+	}
+});
+Object.defineProperty(exports, "isCacheBackend", {
+	enumerable: true,
+	get: function() {
+		return isCacheBackend;
+	}
+});
+Object.defineProperty(exports, "readCredentialFakes", {
+	enumerable: true,
+	get: function() {
+		return readCredentialFakes;
+	}
+});
+Object.defineProperty(exports, "readFakes", {
+	enumerable: true,
+	get: function() {
+		return readFakes;
+	}
+});
+Object.defineProperty(exports, "subscriberRoute", {
+	enumerable: true,
+	get: function() {
+		return subscriberRoute;
+	}
+});
+
+//# sourceMappingURL=SubscriberGenerator-C8CPxrCK.cjs.map