@geekmidas/constructs 4.0.1 → 5.0.0

package/src/queue/AWSLambdaQueueAdaptor.ts

@@ -0,0 +1,162 @@
+import type { EnvironmentParser } from '@geekmidas/envkit';
+import { wrapError } from '@geekmidas/errors';
+import type { Logger } from '@geekmidas/logger';
+import type { InferStandardSchema } from '@geekmidas/schema';
+import type { Service, ServiceRecord } from '@geekmidas/services';
+import { runWithRequestContext, ServiceDiscovery } from '@geekmidas/services';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type {
+	Context,
+	Handler,
+	SQSBatchResponse,
+	SQSEvent,
+	SQSRecord,
+} from 'aws-lambda';
+import type { Queue } from './Queue';
+
+export type AWSLambdaHandler<TEvent = any, TResult = any> = Handler<
+	TEvent,
+	TResult
+>;
+
+/**
+ * Runs a {@link Queue} worker as an AWS Lambda backed by an SQS event-source
+ * mapping. Unlike a subscriber, a queue drains *every* record (no type filter):
+ * each record body (`{ type, payload }`, as written by the SQS publisher) is
+ * unwrapped to its `payload`, validated against the queue's `messageSchema`, and
+ * the whole batch is handed to the handler as `messages`.
+ *
+ * Uses SQS partial-batch responses: a record that fails to parse, validate, or
+ * (when the handler throws) process is returned in `batchItemFailures` so SQS
+ * retries only those records.
+ */
+export class AWSLambdaQueue<
+	TName extends string = string,
+	TMessage extends StandardSchemaV1 = StandardSchemaV1,
+	TServices extends Service[] = [],
+	TLogger extends Logger = Logger,
+> {
+	private _services?: ServiceRecord<TServices>;
+
+	constructor(
+		private readonly envParser: EnvironmentParser<{}>,
+		readonly queue: Queue<TName, TMessage, TServices, TLogger>,
+	) {}
+
+	get logger(): TLogger {
+		return this.queue.logger;
+	}
+
+	private async getServices(): Promise<ServiceRecord<TServices>> {
+		if (this._services) {
+			return this._services;
+		}
+
+		const serviceDiscovery = ServiceDiscovery.getInstance(this.envParser);
+
+		this._services =
+			this.queue.services.length > 0
+				? ((await serviceDiscovery.register(
+						this.queue.services,
+					)) as ServiceRecord<TServices>)
+				: ({} as ServiceRecord<TServices>);
+
+		return this._services;
+	}
+
+	private safeJsonParse(value: string): unknown {
+		try {
+			return JSON.parse(value);
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * Unwrap the queue payload from an SQS record. The SQS publisher writes
+	 * `{ type, payload }`; a payload-only body is also accepted as-is.
+	 */
+	private extractPayload(record: SQSRecord): unknown {
+		const body = this.safeJsonParse(record.body);
+		if (body && typeof body === 'object' && 'payload' in body) {
+			return (body as { payload: unknown }).payload;
+		}
+		return body ?? record.body;
+	}
+
+	private async _handler(
+		event: SQSEvent,
+		context: Context,
+	): Promise<SQSBatchResponse> {
+		const logger = this.queue.logger.child({
+			queue: {
+				name: this.queue.name,
+				fn: context.functionName,
+			},
+			req: { id: context.awsRequestId },
+		}) as TLogger;
+
+		const services = await this.getServices();
+		const schema = this.queue.messageSchema;
+
+		const batchItemFailures: { itemIdentifier: string }[] = [];
+		const messages: InferStandardSchema<TMessage>[] = [];
+
+		for (const record of event.Records) {
+			try {
+				const payload = this.extractPayload(record);
+				const validation = await schema['~standard'].validate(payload);
+				if (validation.issues) {
+					logger.error(
+						{ issues: validation.issues, messageId: record.messageId },
+						'Queue message failed validation',
+					);
+					batchItemFailures.push({ itemIdentifier: record.messageId });
+					continue;
+				}
+				messages.push(validation.value as InferStandardSchema<TMessage>);
+			} catch (error) {
+				logger.error(
+					{ error, messageId: record.messageId },
+					'Failed to parse SQS record',
+				);
+				batchItemFailures.push({ itemIdentifier: record.messageId });
+			}
+		}
+
+		if (messages.length === 0) {
+			return { batchItemFailures };
+		}
+
+		try {
+			await this.queue.handler({ messages, services, logger });
+		} catch (error) {
+			logger.error(wrapError(error), 'Queue handler failed; retrying batch');
+			// Handler processes the batch atomically — fail the whole batch so SQS
+			// retries every (valid) record.
+			for (const record of event.Records) {
+				if (
+					!batchItemFailures.some((f) => f.itemIdentifier === record.messageId)
+				) {
+					batchItemFailures.push({ itemIdentifier: record.messageId });
+				}
+			}
+		}
+
+		return { batchItemFailures };
+	}
+
+	get handler(): AWSLambdaHandler<SQSEvent, SQSBatchResponse> {
+		const handler = this._handler.bind(this);
+
+		return (async (event: SQSEvent, context: Context) => {
+			const startTime = Date.now();
+			const requestId = context.awsRequestId;
+			const logger = this.queue.logger.child({ requestId }) as TLogger;
+
+			return runWithRequestContext({ logger, requestId, startTime }, () =>
+				handler(event, context),
+			);
+		}) as unknown as AWSLambdaHandler<SQSEvent, SQSBatchResponse>;
+	}
+}

package/src/queue/Queue.ts

@@ -0,0 +1,128 @@
+import { environmentCase } from '@geekmidas/envkit';
+import {
+	type EventPublisher,
+	type EventPublisherConnectionString,
+	type PublishableMessage,
+	Publisher,
+} from '@geekmidas/events';
+import type { Logger } from '@geekmidas/logger';
+import { ConsoleLogger } from '@geekmidas/logger/console';
+import type { InferStandardSchema } from '@geekmidas/schema';
+import type { Service, ServiceRecord } from '@geekmidas/services';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { Construct, ConstructType } from '../Construct';
+
+const DEFAULT_LOGGER = new ConsoleLogger() as unknown as Logger;
+
+/**
+ * The wire message a queue carries: `{ type: <queue name>, payload: <message> }`.
+ * The producer publishes this shape and the worker receives the `payload`s as
+ * its `messages`. Typing `type` to the queue name keeps the publisher fully
+ * typed and lets pg-boss (local) / SQS (deployed) route by name.
+ */
+export type QueueMessage<
+	TName extends string,
+	TMessage extends StandardSchemaV1,
+> = PublishableMessage<TName, InferStandardSchema<TMessage>>;
+
+/**
+ * A queue worker — a point-to-point SQS-style queue and its single consumer.
+ * Unlike a `Subscriber` (topic fan-out, filtered by `subscribedEvents`), a queue
+ * drains every message of its one `message` type. Build one with `q` (see
+ * `QueueBuilder`); `gkm build` discovers it into the manifest's `queues` field.
+ *
+ * The producer side is {@link Queue.publisher} — a ready-to-inject `Service`
+ * that any endpoint/function drops into `.services([...])` to send messages.
+ */
+export class Queue<
+	TName extends string = string,
+	TMessage extends StandardSchemaV1 = StandardSchemaV1,
+	TServices extends Service[] = [],
+	TLogger extends Logger = Logger,
+> extends Construct<TLogger, string, undefined, undefined, TServices> {
+	__IS_QUEUE__ = true;
+
+	static isQueue(
+		obj: unknown,
+	): obj is Queue<string, StandardSchemaV1, Service[], Logger> {
+		return Boolean(
+			obj &&
+				(obj as { __IS_QUEUE__?: boolean }).__IS_QUEUE__ === true &&
+				(obj as Construct).type === ConstructType.Queue,
+		);
+	}
+
+	constructor(
+		public readonly name: TName,
+		public readonly handler: QueueHandler<TMessage, TServices, TLogger>,
+		public readonly messageSchema: TMessage,
+		public override readonly timeout: number = 30000,
+		public override readonly services: TServices = [] as unknown as TServices,
+		public override readonly logger: TLogger = DEFAULT_LOGGER as TLogger,
+		/** SQS event-source batch size (deployed). */
+		public readonly batchSize?: number,
+		/** Whether the queue is FIFO (deployed). */
+		public readonly fifo?: boolean,
+	) {
+		super(
+			ConstructType.Queue,
+			logger,
+			services,
+			[],
+			undefined,
+			undefined,
+			timeout,
+		);
+	}
+
+	/**
+	 * The producer side — a `Service` exposing an `EventPublisher` typed to this
+	 * queue's message. Inject it via `.services([queue.publisher])`; the handler
+	 * then calls `services.<name>Publisher.publish([{ type, payload }])`.
+	 *
+	 * It reads `<NAME>_PUBLISHER_CONNECTION_STRING` and builds the transport from
+	 * the URL protocol — `pgboss://` locally, `sqs://` deployed — so the same
+	 * code publishes to Postgres in dev and SQS in prod. Because it's a `Service`,
+	 * `Construct.getEnvironment()` sniffs it, so the env requirement flows into
+	 * the manifest and infra links exactly this queue with least privilege.
+	 */
+	get publisher(): Service<
+		`${TName}Publisher`,
+		EventPublisher<QueueMessage<TName, TMessage>>
+	> {
+		const envVar = `${environmentCase(this.name)}_PUBLISHER_CONNECTION_STRING`;
+		return {
+			serviceName: `${this.name}Publisher`,
+			async register({ envParser }) {
+				const { connectionString } = envParser
+					.create((get) => ({
+						connectionString: get(envVar).string(),
+					}))
+					.parse();
+
+				return Publisher.fromConnectionString<QueueMessage<TName, TMessage>>(
+					connectionString as EventPublisherConnectionString,
+				);
+			},
+		};
+	}
+}
+
+/** The context a queue handler receives — a batch of typed messages. */
+export type QueueContext<
+	TMessage extends StandardSchemaV1,
+	TServices extends Service[] = [],
+	TLogger extends Logger = Logger,
+> = {
+	messages: InferStandardSchema<TMessage>[];
+	services: ServiceRecord<TServices>;
+	logger: TLogger;
+};
+
+export type QueueHandler<
+	TMessage extends StandardSchemaV1,
+	TServices extends Service[] = [],
+	TLogger extends Logger = Logger,
+> = (
+	ctx: QueueContext<TMessage, TServices, TLogger>,
+) => unknown | Promise<unknown>;

package/src/queue/QueueBuilder.ts

@@ -0,0 +1,115 @@
+import type { Logger } from '@geekmidas/logger';
+import { DEFAULT_LOGGER } from '@geekmidas/logger/console';
+import type { Service } from '@geekmidas/services';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { Queue, type QueueHandler } from './Queue';
+
+/**
+ * Builds a {@link Queue} worker — `q.queue('orders').services([db]).message(schema).handle(fn)`.
+ * Services are an array (sniffed for required env vars); `message` is the typed
+ * job payload; `handle` is the single consumer. The queue name is captured as a
+ * literal so `queue.publisher` is typed to `{ type: '<name>', payload }`.
+ */
+export class QueueBuilder<
+	TName extends string = string,
+	TMessage extends StandardSchemaV1 | undefined = undefined,
+	TServices extends Service[] = [],
+	TLogger extends Logger = Logger,
+> {
+	private _name?: string;
+	private _messageSchema?: TMessage;
+	private _timeout = 30000;
+	private _batchSize?: number;
+	private _fifo?: boolean;
+	private _services: TServices = [] as Service[] as TServices;
+	private _logger: TLogger = DEFAULT_LOGGER as TLogger;
+
+	/** The queue name — drives the infra queue and its `<NAME>_*` env vars. */
+	queue<T extends string>(
+		name: T,
+	): QueueBuilder<T, TMessage, TServices, TLogger> {
+		this._name = name;
+		return this as unknown as QueueBuilder<T, TMessage, TServices, TLogger>;
+	}
+
+	timeout(timeout: number): this {
+		this._timeout = timeout;
+		return this;
+	}
+
+	/** SQS event-source batch size (deployed). */
+	batchSize(batchSize: number): this {
+		this._batchSize = batchSize;
+		return this;
+	}
+
+	/** Mark the queue as FIFO (deployed). */
+	fifo(fifo = true): this {
+		this._fifo = fifo;
+		return this;
+	}
+
+	services<T extends Service[]>(
+		services: T,
+	): QueueBuilder<TName, TMessage, [...TServices, ...T], TLogger> {
+		this._services = [...this._services, ...services] as unknown as TServices;
+		return this as unknown as QueueBuilder<
+			TName,
+			TMessage,
+			[...TServices, ...T],
+			TLogger
+		>;
+	}
+
+	logger<T extends Logger>(
+		logger: T,
+	): QueueBuilder<TName, TMessage, TServices, T> {
+		this._logger = logger as unknown as TLogger;
+		return this as unknown as QueueBuilder<TName, TMessage, TServices, T>;
+	}
+
+	/** The typed message (job) payload the queue carries. */
+	message<T extends StandardSchemaV1>(
+		schema: T,
+	): QueueBuilder<TName, T, TServices, TLogger> {
+		this._messageSchema = schema as unknown as TMessage;
+		return this as unknown as QueueBuilder<TName, T, TServices, TLogger>;
+	}
+
+	handle(
+		fn: QueueHandler<NonNullable<TMessage>, TServices, TLogger>,
+	): Queue<TName, NonNullable<TMessage>, TServices, TLogger> {
+		if (!this._name) {
+			throw new Error(
+				'Queue requires a name — call .queue(name) before .handle().',
+			);
+		}
+		if (!this._messageSchema) {
+			throw new Error(
+				'Queue requires a message schema — call .message(schema) before .handle().',
+			);
+		}
+
+		const queue = new Queue<TName, NonNullable<TMessage>, TServices, TLogger>(
+			this._name as TName,
+			fn,
+			this._messageSchema as NonNullable<TMessage>,
+			this._timeout,
+			this._services,
+			this._logger,
+			this._batchSize,
+			this._fifo,
+		);
+
+		// Reset builder state to prevent pollution across reuse.
+		this._name = undefined;
+		this._messageSchema = undefined;
+		this._timeout = 30000;
+		this._batchSize = undefined;
+		this._fifo = undefined;
+		this._services = [] as Service[] as TServices;
+		this._logger = DEFAULT_LOGGER as TLogger;
+
+		return queue;
+	}
+}

package/src/queue/TestQueueAdaptor.ts

@@ -0,0 +1,63 @@
+import { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+import type { InferStandardSchema } from '@geekmidas/schema';
+import type { Service, ServiceRecord } from '@geekmidas/services';
+import { runWithRequestContext, ServiceDiscovery } from '@geekmidas/services';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Queue } from './Queue';
+
+/**
+ * In-memory test driver for a {@link Queue} worker. Hand it a batch of messages
+ * and it registers the queue's services, runs the handler in a request context,
+ * and returns the handler result — no SQS/pg-boss required.
+ *
+ * @example
+ * const adapter = new TestQueueAdaptor(ordersQueue);
+ * await adapter.invoke({ messages: [{ orderId: '123' }] });
+ */
+export class TestQueueAdaptor<
+	TName extends string = string,
+	TMessage extends StandardSchemaV1 = StandardSchemaV1,
+	TServices extends Service[] = [],
+	TLogger extends Logger = Logger,
+> {
+	static getDefaultServiceDiscovery() {
+		return ServiceDiscovery.getInstance(new EnvironmentParser({}));
+	}
+
+	constructor(
+		private readonly queue: Queue<TName, TMessage, TServices, TLogger>,
+		private serviceDiscovery: ServiceDiscovery<any> = TestQueueAdaptor.getDefaultServiceDiscovery(),
+	) {}
+
+	async invoke(
+		request: TestQueueRequest<TMessage, TServices>,
+	): Promise<unknown> {
+		const logger = this.queue.logger.child({ test: true }) as TLogger;
+
+		const services =
+			request.services ??
+			((await this.serviceDiscovery.register(
+				this.queue.services,
+			)) as ServiceRecord<TServices>);
+
+		const requestId = `test-${Date.now()}`;
+		const startTime = Date.now();
+
+		return runWithRequestContext({ logger, requestId, startTime }, () =>
+			this.queue.handler({
+				messages: request.messages,
+				services,
+				logger,
+			}),
+		);
+	}
+}
+
+export type TestQueueRequest<
+	TMessage extends StandardSchemaV1 = StandardSchemaV1,
+	TServices extends Service[] = [],
+> = {
+	messages: InferStandardSchema<TMessage>[];
+	services?: ServiceRecord<TServices>;
+};

package/src/queue/__tests__/QueueBuilder.spec.ts

@@ -0,0 +1,137 @@
+import type { Service } from '@geekmidas/services';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { Queue } from '../Queue';
+import { QueueBuilder } from '../QueueBuilder';
+import { TestQueueAdaptor } from '../TestQueueAdaptor';
+
+const schema = z.object({ orderId: z.string() });
+
+const svc = (name: string): Service<string, object> => ({
+	serviceName: name,
+	async register() {
+		return {};
+	},
+});
+
+describe('QueueBuilder', () => {
+	it('builds a Queue from .queue().message().handle()', () => {
+		const handler = async () => {};
+		const queue = new QueueBuilder()
+			.queue('orders')
+			.message(schema)
+			.handle(handler);
+
+		expect(Queue.isQueue(queue)).toBe(true);
+		expect(queue.name).toBe('orders');
+		expect(queue.messageSchema).toBe(schema);
+		expect(queue.handler).toBe(handler);
+		expect(queue.services).toEqual([]);
+	});
+
+	it('collects services as an array', () => {
+		const a = svc('a');
+		const queue = new QueueBuilder()
+			.queue('jobs')
+			.services([a])
+			.message(schema)
+			.handle(async () => {});
+
+		expect(queue.services).toEqual([a]);
+	});
+
+	it('captures batchSize and fifo', () => {
+		const queue = new QueueBuilder()
+			.queue('orders')
+			.batchSize(5)
+			.fifo()
+			.message(schema)
+			.handle(async () => {});
+
+		expect(queue.batchSize).toBe(5);
+		expect(queue.fifo).toBe(true);
+	});
+
+	it('throws when the name is missing', () => {
+		expect(() =>
+			new QueueBuilder().message(schema).handle(async () => {}),
+		).toThrow(/name/);
+	});
+
+	it('throws when the message schema is missing', () => {
+		const builder = new QueueBuilder().queue('x');
+		expect(() =>
+			(builder as QueueBuilder<'x', typeof schema>).handle(async () => {}),
+		).toThrow(/message/);
+	});
+
+	it('resets builder state after handle', () => {
+		const builder = new QueueBuilder();
+		builder
+			.queue('first')
+			.services([svc('x')])
+			.message(schema)
+			.handle(async () => {});
+		// State cleared — a second handle with no name throws.
+		expect(() =>
+			(builder as QueueBuilder<string, typeof schema>).handle(async () => {}),
+		).toThrow(/name/);
+	});
+});
+
+describe('Queue.publisher', () => {
+	it('exposes a `<name>Publisher` producer service', () => {
+		const queue = new QueueBuilder()
+			.queue('orders')
+			.message(schema)
+			.handle(async () => {});
+
+		expect(queue.publisher.serviceName).toBe('ordersPublisher');
+	});
+
+	it('requires the namespaced connection-string env var (sniffed into the manifest)', async () => {
+		const producer = new QueueBuilder()
+			.queue('orderEvents')
+			.message(schema)
+			.handle(async () => {});
+
+		// Inject the publisher into a construct's services so getEnvironment sniffs it.
+		const consumer = new QueueBuilder()
+			.queue('caller')
+			.services([producer.publisher])
+			.message(schema)
+			.handle(async () => {});
+
+		const env = await consumer.getEnvironment();
+		expect(env).toContain('ORDER_EVENTS_PUBLISHER_CONNECTION_STRING');
+	});
+});
+
+describe('TestQueueAdaptor', () => {
+	it('invokes the handler with the batch of messages and services', async () => {
+		const seen: { messages: unknown[]; hadDb: boolean }[] = [];
+		const db = svc('db');
+
+		const queue = new QueueBuilder()
+			.queue('orders')
+			.services([db])
+			.message(schema)
+			.handle(async ({ messages, services }) => {
+				seen.push({
+					messages,
+					hadDb: 'db' in (services as Record<string, unknown>),
+				});
+				return { processed: messages.length };
+			});
+
+		const adapter = new TestQueueAdaptor(queue);
+		const result = await adapter.invoke({
+			messages: [{ orderId: '1' }, { orderId: '2' }],
+		});
+
+		expect(result).toEqual({ processed: 2 });
+		expect(seen).toHaveLength(1);
+		expect(seen[0]?.messages).toEqual([{ orderId: '1' }, { orderId: '2' }]);
+		expect(seen[0]?.hadDb).toBe(true);
+	});
+});

package/src/queue/index.ts

@@ -0,0 +1,12 @@
+export {
+	Queue,
+	type QueueContext,
+	type QueueHandler,
+	type QueueMessage,
+} from './Queue';
+
+import { QueueBuilder } from './QueueBuilder';
+
+export { QueueBuilder } from './QueueBuilder';
+
+export const q = new QueueBuilder();

package/src/subscribers/Subscriber.ts

@@ -63,6 +63,13 @@ export class Subscriber<
 			TEventPublisherServiceName,
 			TEventPublisher
 		>,
+		/**
+		 * The name of the {@link Topic} this subscriber binds to (via
+		 * `s.topic(topic)`), recorded for the manifest so infra wires the SNS
+		 * subscription. Undefined when the subscriber's events are typed from a
+		 * (hand-written) publisher instead.
+		 */
+		public readonly topicName?: string,
 	) {
 		super(
 			ConstructType.Subscriber,

package/src/subscribers/SubscriberBuilder.ts

@@ -6,6 +6,7 @@ import type { Logger } from '@geekmidas/logger';
 import { DEFAULT_LOGGER } from '@geekmidas/logger/console';
 import type { Service } from '@geekmidas/services';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Topic, TopicEvents, TopicMessage } from '../topic/Topic';
 import { Subscriber, type SubscriberHandler } from './Subscriber';
 
 export class SubscriberBuilder<
@@ -22,11 +23,44 @@ export class SubscriberBuilder<
 	private _services: TServices = [] as Service[] as TServices;
 	private _logger: TLogger = DEFAULT_LOGGER;
 	private _publisher?: Service<TEventPublisherServiceName, TEventPublisher>;
+	private _topicName?: string;
 
 	constructor() {
 		this._timeout = 30000; // Default timeout
 	}
 
+	/**
+	 * Bind this subscriber to a {@link Topic} — the preferred way to type and wire
+	 * a fan-out consumer. It supplies the subscribable event types (and their
+	 * payloads) from the topic's contract and records the binding for the manifest,
+	 * so infra wires the SNS subscription.
+	 *
+	 * Prefer this over typing via a hand-written publisher service: a consumer does
+	 * not publish, so binding a topic does *not* require the topic's publisher
+	 * connection string (least privilege). Use `.publisher(...)` only when the
+	 * subscriber actually publishes follow-up events.
+	 */
+	topic<TName extends string, TEvents extends TopicEvents>(
+		topic: Topic<TName, TEvents>,
+	): SubscriberBuilder<
+		TServices,
+		TLogger,
+		OutSchema,
+		EventPublisher<TopicMessage<TEvents>>,
+		TEventPublisherServiceName,
+		TSubscribedEvents
+	> {
+		this._topicName = topic.name;
+		return this as unknown as SubscriberBuilder<
+			TServices,
+			TLogger,
+			OutSchema,
+			EventPublisher<TopicMessage<TEvents>>,
+			TEventPublisherServiceName,
+			TSubscribedEvents
+		>;
+	}
+
 	timeout(timeout: number): this {
 		this._timeout = timeout;
 		return this;
@@ -135,12 +169,14 @@ export class SubscriberBuilder<
 			this._services,
 			this._logger,
 			this._publisher,
+			this._topicName,
 		);
 
 		// Reset builder state after creating the subscriber to prevent pollution
 		this._services = [] as Service[] as TServices;
 		this._logger = DEFAULT_LOGGER;
 		this._publisher = undefined;
+		this._topicName = undefined;
 		this._subscribedEvents = [] as any;
 		this._timeout = 30000; // Reset to default
 		this.outputSchema = undefined;