@geekmidas/constructs 9.0.2 → 9.1.0

package/src/endpoints/EndpointFactory.ts

@@ -8,6 +8,8 @@ import type { Logger } from '@geekmidas/logger';
 import { ConsoleLogger } from '@geekmidas/logger/console';
 import type { Service } from '@geekmidas/services';
 import uniqBy from 'lodash.uniqby';
+import { cloneWith } from '../clone';
+import { addMonitor, type MonitorService } from '../monitor';
 import type { HttpMethod } from '../types';
 import {
 	type Authorizer,
@@ -79,6 +81,7 @@ export class EndpointFactory<
 	private defaultActorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
 	private customSecuritySchemes: TSecuritySchemes = {} as TSecuritySchemes;
 	private defaultRlsConfig?: TRlsConfig;
+	private defaultMonitors: MonitorService[] = [];
 
 	constructor({
 		basePath,
@@ -95,6 +98,7 @@ export class EndpointFactory<
 		defaultActorExtractor,
 		customSecuritySchemes = {} as TSecuritySchemes,
 		defaultRlsConfig,
+		defaultMonitors = [],
 	}: EndpointFactoryOptions<
 		TServices,
 		TBasePath,
@@ -128,6 +132,17 @@ export class EndpointFactory<
 		this.defaultActorExtractor = defaultActorExtractor;
 		this.customSecuritySchemes = customSecuritySchemes;
 		this.defaultRlsConfig = defaultRlsConfig;
+		this.defaultMonitors = defaultMonitors;
+	}
+
+	/**
+	 * Report every endpoint's requests to a monitor. Endpoints built from this
+	 * factory inherit it, and can add their own with `.monitor()`.
+	 */
+	monitor(monitor: MonitorService): this {
+		return cloneWith(this, {
+			defaultMonitors: addMonitor(this.defaultMonitors, monitor),
+		});
 	}
 
 	static joinPaths<TBasePath extends string, P extends string>(
@@ -212,6 +227,7 @@ export class EndpointFactory<
 			defaultLogger: this.defaultLogger,
 			defaultSessionExtractor: this.defaultSessionExtractor,
 			defaultEventPublisher: this.defaultEventPublisher,
+			defaultMonitors: this.defaultMonitors,
 			availableAuthorizers: authorizerConfigs,
 			defaultAuthorizerName: this.defaultAuthorizerName,
 			defaultAuditorStorage: this.defaultAuditorStorage,
@@ -278,6 +294,7 @@ export class EndpointFactory<
 			defaultLogger: this.defaultLogger,
 			defaultSessionExtractor: this.defaultSessionExtractor,
 			defaultEventPublisher: this.defaultEventPublisher,
+			defaultMonitors: this.defaultMonitors,
 			availableAuthorizers: this.availableAuthorizers,
 			defaultAuthorizerName: this.defaultAuthorizerName,
 			defaultAuditorStorage: this.defaultAuditorStorage,
@@ -360,6 +377,7 @@ export class EndpointFactory<
 			defaultLogger: this.defaultLogger,
 			defaultSessionExtractor: this.defaultSessionExtractor,
 			defaultEventPublisher: this.defaultEventPublisher,
+			defaultMonitors: this.defaultMonitors,
 			availableAuthorizers: this.availableAuthorizers,
 			defaultAuthorizerName:
 				name === 'none' ? undefined : (name as TAuthorizers[number]),
@@ -413,6 +431,7 @@ export class EndpointFactory<
 			defaultLogger: this.defaultLogger,
 			defaultSessionExtractor: this.defaultSessionExtractor,
 			defaultEventPublisher: this.defaultEventPublisher,
+			defaultMonitors: this.defaultMonitors,
 			availableAuthorizers: this.availableAuthorizers,
 			defaultAuthorizerName: this.defaultAuthorizerName,
 			defaultAuditorStorage: this.defaultAuditorStorage,
@@ -464,6 +483,7 @@ export class EndpointFactory<
 			defaultLogger: this.defaultLogger,
 			defaultSessionExtractor: this.defaultSessionExtractor,
 			defaultEventPublisher: this.defaultEventPublisher,
+			defaultMonitors: this.defaultMonitors,
 			availableAuthorizers: this.availableAuthorizers,
 			defaultAuthorizerName: this.defaultAuthorizerName,
 			defaultAuditorStorage: this.defaultAuditorStorage,
@@ -521,6 +541,7 @@ export class EndpointFactory<
 				| SessionFn<[...S, ...TServices], TLogger, TSession, TDatabase>
 				| undefined,
 			defaultEventPublisher: this.defaultEventPublisher,
+			defaultMonitors: this.defaultMonitors,
 			availableAuthorizers: this.availableAuthorizers,
 			defaultAuthorizerName: this.defaultAuthorizerName,
 			defaultAuditorStorage: this.defaultAuditorStorage,
@@ -584,6 +605,7 @@ export class EndpointFactory<
 				TSession
 			>,
 			defaultEventPublisher: this.defaultEventPublisher,
+			defaultMonitors: this.defaultMonitors,
 			availableAuthorizers: this.availableAuthorizers,
 			defaultAuthorizerName: this.defaultAuthorizerName,
 			defaultAuditorStorage: this.defaultAuditorStorage,
@@ -644,6 +666,7 @@ export class EndpointFactory<
 			defaultLogger: this.defaultLogger,
 			defaultSessionExtractor: this.defaultSessionExtractor,
 			defaultEventPublisher: publisher,
+			defaultMonitors: this.defaultMonitors,
 			availableAuthorizers: this.availableAuthorizers,
 			defaultAuthorizerName: this.defaultAuthorizerName,
 			defaultAuditorStorage: this.defaultAuditorStorage,
@@ -698,6 +721,7 @@ export class EndpointFactory<
 			defaultLogger: this.defaultLogger,
 			defaultSessionExtractor: session,
 			defaultEventPublisher: this.defaultEventPublisher,
+			defaultMonitors: this.defaultMonitors,
 			availableAuthorizers: this.availableAuthorizers,
 			defaultAuthorizerName: this.defaultAuthorizerName,
 			defaultAuditorStorage: this.defaultAuditorStorage,
@@ -765,6 +789,7 @@ export class EndpointFactory<
 				| SessionFn<TServices, TLogger, TSession, T>
 				| undefined,
 			defaultEventPublisher: this.defaultEventPublisher,
+			defaultMonitors: this.defaultMonitors,
 			availableAuthorizers: this.availableAuthorizers,
 			defaultAuthorizerName: this.defaultAuthorizerName,
 			defaultAuditorStorage: this.defaultAuditorStorage,
@@ -819,6 +844,7 @@ export class EndpointFactory<
 			defaultLogger: this.defaultLogger,
 			defaultSessionExtractor: this.defaultSessionExtractor,
 			defaultEventPublisher: this.defaultEventPublisher,
+			defaultMonitors: this.defaultMonitors,
 			availableAuthorizers: this.availableAuthorizers,
 			defaultAuthorizerName: this.defaultAuthorizerName,
 			defaultAuditorStorage: storage,
@@ -878,6 +904,7 @@ export class EndpointFactory<
 			defaultLogger: this.defaultLogger,
 			defaultSessionExtractor: this.defaultSessionExtractor,
 			defaultEventPublisher: this.defaultEventPublisher,
+			defaultMonitors: this.defaultMonitors,
 			availableAuthorizers: this.availableAuthorizers,
 			defaultAuthorizerName: this.defaultAuthorizerName,
 			defaultAuditorStorage: this.defaultAuditorStorage,
@@ -946,6 +973,7 @@ export class EndpointFactory<
 			defaultLogger: this.defaultLogger,
 			defaultSessionExtractor: this.defaultSessionExtractor,
 			defaultEventPublisher: this.defaultEventPublisher,
+			defaultMonitors: this.defaultMonitors,
 			availableAuthorizers: this.availableAuthorizers,
 			defaultAuthorizerName: this.defaultAuthorizerName,
 			defaultAuditorStorage: this.defaultAuditorStorage,
@@ -1019,6 +1047,8 @@ export class EndpointFactory<
 			builder._setPublisher(this.defaultEventPublisher);
 		}
 
+		builder._monitors = [...this.defaultMonitors];
+
 		// Set available authorizers and default
 		builder._availableAuthorizers = this.availableAuthorizers;
 		if (this.defaultAuthorizerName) {
@@ -1143,6 +1173,7 @@ export interface EndpointFactoryOptions<
 	defaultActorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
 	customSecuritySchemes?: TSecuritySchemes;
 	defaultRlsConfig?: TRlsConfig;
+	defaultMonitors?: MonitorService[];
 }
 
 export const e = new EndpointFactory();

package/src/endpoints/HonoEndpointAdaptor.ts

@@ -18,6 +18,7 @@ import { logger as honoLogger } from 'hono/logger';
 import { timing } from 'hono/timing';
 import type { ContentfulStatusCode } from 'hono/utils/http-status';
 import { validator } from 'hono/validator';
+import { startMonitors } from '../monitor';
 import { publishConstructEvents } from '../publisher';
 import type { HttpMethod, LowerHttpMethod } from '../types';
 import type { MappedAudit } from './audit';
@@ -66,6 +67,7 @@ interface EndpointFeatures {
 	hasEvents: boolean;
 	hasRateLimit: boolean;
 	hasRls: boolean;
+	hasMonitors: boolean;
 }
 
 /**
@@ -111,6 +113,7 @@ function analyzeEndpointFeatures(
 		hasEvents: (endpoint.events?.length ?? 0) > 0,
 		hasRateLimit: !!endpoint.rateLimit,
 		hasRls: !!endpoint.rlsConfig && !endpoint.rlsBypass,
+		hasMonitors: endpoint.monitors.length > 0,
 	};
 }
 
@@ -361,8 +364,13 @@ export class HonoEndpoint<
 			// Set response header
 			c.header('X-Request-ID', requestId);
 
+			const monitor = features.hasMonitors
+				? await startMonitors(endpoint, serviceDiscovery, logger)
+				: undefined;
+			let failure: unknown;
+
 			// Wrap entire handler in request context for services to access
-			return runWithRequestContext(
+			const response = await runWithRequestContext(
 				{ logger, requestId, startTime },
 				async () => {
 					try {
@@ -631,6 +639,7 @@ export class HonoEndpoint<
 							return c.json(error, error.statusCode as ContentfulStatusCode);
 						}
 					} catch (e: any) {
+						failure = e;
 						logger.error(e, 'Error processing endpoint request');
 						const error = wrapError(e, 500, 'Internal Server Error');
 						if (HonoEndpoint.isDev) {
@@ -643,6 +652,12 @@ export class HonoEndpoint<
 					}
 				},
 			);
+
+			// Not awaited: a server stays up after responding, so the request
+			// does not wait on the monitoring service. `settle` never throws.
+			void monitor?.settle(response.status, failure);
+
+			return response;
 		};
 
 		// Register route with conditional validators

package/src/endpoints/TestEndpointAdaptor.ts

@@ -5,7 +5,7 @@ import type {
 } from '@geekmidas/audit';
 import { DefaultAuditor } from '@geekmidas/audit';
 import { EnvironmentParser } from '@geekmidas/envkit';
-import { ForbiddenError } from '@geekmidas/errors';
+import { ForbiddenError, wrapError } from '@geekmidas/errors';
 import type { EventPublisher } from '@geekmidas/events';
 import type { Logger } from '@geekmidas/logger';
 import type {
@@ -19,6 +19,7 @@ import {
 	type ServiceRecord,
 } from '@geekmidas/services';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { startMonitors } from '../monitor';
 import { publishConstructEvents } from '../publisher';
 import type { HttpMethod } from '../types';
 import type { MappedAudit } from './audit';
@@ -199,170 +200,213 @@ export class TestEndpointAdaptor<
 		// Get database from context for session extraction
 		const rawDb = (ctx as any).database as TDatabase;
 
+		const monitor = await startMonitors(
+			this.endpoint,
+			this.serviceDiscovery,
+			logger,
+		);
+
 		// Wrap handler execution in request context
-		return runWithRequestContext({ logger, requestId, startTime }, async () => {
-			const session = await this.endpoint.getSession({
-				logger,
-				services: ctx.services,
-				header,
-				cookie,
-				...(rawDb !== undefined && { db: rawDb }),
-			} as any);
-
-			// Check authorization
-			const isAuthorized = await this.endpoint.authorize({
-				header,
-				cookie,
-				services: ctx.services,
-				logger,
-				session,
-				...(rawDb !== undefined && { db: rawDb }),
-				body,
-				query,
-				params,
-			} as any);
-
-			if (!isAuthorized) {
-				logger.warn('Forbidden access attempt');
-				throw new ForbiddenError(
-					'Forbidden access to the endpoint',
-					'You do not have permission to access this resource.',
-				);
-			}
+		try {
+			const response = await runWithRequestContext(
+				{ logger, requestId, startTime },
+				async () =>
+					this.run(ctx, { body, query, params, header, cookie, logger, rawDb }),
+			);
+			await monitor.settle(response.status);
+			return response;
+		} catch (error) {
+			await monitor.settle(wrapError(error).statusCode, error);
+			throw error;
+		}
+	}
 
-			// Create audit context if audit storage is provided
-			// The auditorStorage instance is required when endpoint uses .auditor()
-			const auditorStorage = (ctx as any).auditorStorage as TAuditStorage;
-			let auditContext: AuditExecutionContext<TAuditAction> | undefined;
-
-			if (auditorStorage) {
-				// Extract actor if configured
-				let actor: AuditActor = { id: 'system', type: 'system' };
-				if (this.endpoint.actorExtractor) {
-					try {
-						actor = await this.endpoint.actorExtractor({
-							services: ctx.services as any,
-							session,
-							header,
-							cookie,
-							logger,
-						});
-					} catch (error) {
-						logger.error(error as Error, 'Failed to extract actor for audits');
-					}
+	private async run(
+		ctx: TestRequestAdaptor<
+			TInput,
+			TServices,
+			TEventPublisher,
+			TEventPublisherServiceName,
+			TAuditStorage,
+			TAuditStorageServiceName,
+			TDatabase,
+			TDatabaseServiceName
+		>,
+		{
+			body,
+			query,
+			params,
+			header,
+			cookie,
+			logger,
+			rawDb,
+		}: {
+			body: unknown;
+			query: unknown;
+			params: unknown;
+			header: ReturnType<typeof createObjectHeaders>;
+			cookie: ReturnType<typeof createCookieHeaderAccessor>;
+			logger: TLogger;
+			rawDb: TDatabase;
+		},
+	): Promise<TestHttpResponse<InferStandardSchema<TOutSchema>>> {
+		const session = await this.endpoint.getSession({
+			logger,
+			services: ctx.services,
+			header,
+			cookie,
+			...(rawDb !== undefined && { db: rawDb }),
+		} as any);
+
+		// Check authorization
+		const isAuthorized = await this.endpoint.authorize({
+			header,
+			cookie,
+			services: ctx.services,
+			logger,
+			session,
+			...(rawDb !== undefined && { db: rawDb }),
+			body,
+			query,
+			params,
+		} as any);
+
+		if (!isAuthorized) {
+			logger.warn('Forbidden access attempt');
+			throw new ForbiddenError(
+				'Forbidden access to the endpoint',
+				'You do not have permission to access this resource.',
+			);
+		}
+
+		// Create audit context if audit storage is provided
+		// The auditorStorage instance is required when endpoint uses .auditor()
+		const auditorStorage = (ctx as any).auditorStorage as TAuditStorage;
+		let auditContext: AuditExecutionContext<TAuditAction> | undefined;
+
+		if (auditorStorage) {
+			// Extract actor if configured
+			let actor: AuditActor = { id: 'system', type: 'system' };
+			if (this.endpoint.actorExtractor) {
+				try {
+					actor = await this.endpoint.actorExtractor({
+						services: ctx.services as any,
+						session,
+						header,
+						cookie,
+						logger,
+					});
+				} catch (error) {
+					logger.error(error as Error, 'Failed to extract actor for audits');
 				}
+			}
 
-				const auditor = new DefaultAuditor<TAuditAction>({
-					actor,
-					storage: auditorStorage as AuditStorage,
-					metadata: {
-						endpoint: this.endpoint.route,
-						method: this.endpoint.method,
-					},
-				});
+			const auditor = new DefaultAuditor<TAuditAction>({
+				actor,
+				storage: auditorStorage as AuditStorage,
+				metadata: {
+					endpoint: this.endpoint.route,
+					method: this.endpoint.method,
+				},
+			});
 
-				auditContext = { auditor, storage: auditorStorage as AuditStorage };
-			}
+			auditContext = { auditor, storage: auditorStorage as AuditStorage };
+		}
 
-			// Warn if declarative audits are configured but no audit storage
-			const audits = this.endpoint.audits as MappedAudit<
-				TAuditAction,
-				TOutSchema
-			>[];
-			if (!auditContext && audits?.length) {
-				logger.warn('No auditor storage service available');
-			}
+		// Warn if declarative audits are configured but no audit storage
+		const audits = this.endpoint.audits as MappedAudit<
+			TAuditAction,
+			TOutSchema
+		>[];
+		if (!auditContext && audits?.length) {
+			logger.warn('No auditor storage service available');
+		}
 
-			// Execute handler with automatic audit transaction support
-			const result = await executeWithAuditTransaction(
-				auditContext,
-				async (auditor) => {
-					// Use audit transaction as db if available (when storage has same database)
-					// For testing, the tester controls whether to use transactional auditing
-					const trx = auditor?.getTransaction?.();
-					const db = trx ?? rawDb;
-
-					const responseBuilder = new ResponseBuilder();
-					const response = await this.endpoint.handler(
-						{
-							body,
-							query,
-							params,
-							session,
-							services: ctx.services,
-							logger,
-							header,
-							cookie,
-							auditor,
-							db,
-						} as any,
-						responseBuilder,
-					);
-
-					// Check if response has metadata
-					let data = response;
-					let metadata = responseBuilder.getMetadata();
-
-					if (Endpoint.hasMetadata(response)) {
-						data = response.data;
-						metadata = response.metadata;
-					}
+		// Execute handler with automatic audit transaction support
+		const result = await executeWithAuditTransaction(
+			auditContext,
+			async (auditor) => {
+				// Use audit transaction as db if available (when storage has same database)
+				// For testing, the tester controls whether to use transactional auditing
+				const trx = auditor?.getTransaction?.();
+				const db = trx ?? rawDb;
+
+				const responseBuilder = new ResponseBuilder();
+				const response = await this.endpoint.handler(
+					{
+						body,
+						query,
+						params,
+						session,
+						services: ctx.services,
+						logger,
+						header,
+						cookie,
+						auditor,
+						db,
+					} as any,
+					responseBuilder,
+				);
 
-					const output = await this.endpoint.parseOutput(data);
+				// Check if response has metadata
+				let data = response;
+				let metadata = responseBuilder.getMetadata();
 
-					return { output, metadata, responseBuilder };
-				},
-				// Process declarative audits after handler (inside transaction)
-				async (result, auditor) => {
-					if (!audits?.length) return;
-
-					for (const audit of audits) {
-						if (audit.when && !audit.when(result.output as any)) {
-							continue;
-						}
-						const payload = audit.payload(result.output as any);
-						const entityId = audit.entityId?.(result.output as any);
-						auditor.audit(audit.type as any, payload as any, {
-							table: audit.table,
-							entityId,
-						});
-					}
-				},
-				// Pass rawDb so storage can reuse existing transactions
-				{ db: rawDb },
-			);
+				if (Endpoint.hasMetadata(response)) {
+					data = response.data;
+					metadata = response.metadata;
+				}
 
-			const { output, metadata } = result;
+				const output = await this.endpoint.parseOutput(data);
 
-			ctx.publisher && (await this.serviceDiscovery.register([ctx.publisher]));
-			await publishConstructEvents(
-				this.endpoint,
-				output,
-				this.serviceDiscovery,
-			);
+				return { output, metadata, responseBuilder };
+			},
+			// Process declarative audits after handler (inside transaction)
+			async (result, auditor) => {
+				if (!audits?.length) return;
 
-			// Convert cookies to Set-Cookie headers
-			const headers: Record<string, string | string[]> = {
-				...(metadata.headers || {}),
-			};
-
-			if (metadata.cookies && metadata.cookies.size > 0) {
-				const setCookieValues: string[] = [];
-				for (const [name, cookie] of metadata.cookies.entries()) {
-					setCookieValues.push(
-						serializeCookie(name, cookie.value, cookie.options),
-					);
+				for (const audit of audits) {
+					if (audit.when && !audit.when(result.output as any)) {
+						continue;
+					}
+					const payload = audit.payload(result.output as any);
+					const entityId = audit.entityId?.(result.output as any);
+					auditor.audit(audit.type as any, payload as any, {
+						table: audit.table,
+						entityId,
+					});
 				}
-				headers['set-cookie'] = setCookieValues;
+			},
+			// Pass rawDb so storage can reuse existing transactions
+			{ db: rawDb },
+		);
+
+		const { output, metadata } = result;
+
+		ctx.publisher && (await this.serviceDiscovery.register([ctx.publisher]));
+		await publishConstructEvents(this.endpoint, output, this.serviceDiscovery);
+
+		// Convert cookies to Set-Cookie headers
+		const headers: Record<string, string | string[]> = {
+			...(metadata.headers || {}),
+		};
+
+		if (metadata.cookies && metadata.cookies.size > 0) {
+			const setCookieValues: string[] = [];
+			for (const [name, cookie] of metadata.cookies.entries()) {
+				setCookieValues.push(
+					serializeCookie(name, cookie.value, cookie.options),
+				);
 			}
+			headers['set-cookie'] = setCookieValues;
+		}
 
-			// Return HTTP response format
-			return {
-				body: output,
-				status: metadata.status || 200,
-				headers,
-			};
-		});
+		// Return HTTP response format
+		return {
+			body: output,
+			status: metadata.status || 200,
+			headers,
+		};
 	}
 
 	async request(

package/src/endpoints/__tests__/EndpointBuilder.audit.spec.ts

@@ -49,7 +49,8 @@ describe('EndpointBuilder audit methods', () => {
 			const builder = new EndpointBuilder('/users', 'POST');
 			const result = builder.auditor(auditStorageService);
 
-			expect(result).toBe(builder);
+			expect(result).toBeInstanceOf(EndpointBuilder);
+			expect(result).not.toBe(builder);
 		});
 
 		it('should pass auditor storage service to endpoint', () => {
@@ -96,7 +97,8 @@ describe('EndpointBuilder audit methods', () => {
 			const builder = new EndpointBuilder('/users', 'POST');
 			const result = builder.actor(() => ({ id: '123', type: 'user' }));
 
-			expect(result).toBe(builder);
+			expect(result).toBeInstanceOf(EndpointBuilder);
+			expect(result).not.toBe(builder);
 		});
 
 		it('should pass actor extractor to endpoint', () => {
@@ -183,7 +185,8 @@ describe('EndpointBuilder audit methods', () => {
 			const builder = new EndpointBuilder('/users', 'POST');
 			const result = builder.audit([]);
 
-			expect(result).toBe(builder);
+			expect(result).toBeInstanceOf(EndpointBuilder);
+			expect(result).not.toBe(builder);
 		});
 
 		it('should pass audit definitions to endpoint', () => {

package/src/endpoints/__tests__/EndpointBuilder.responseType.spec.ts

@@ -24,7 +24,10 @@ describe('EndpointBuilder.responseType', () => {
 		const builder = new EndpointBuilder('/users', 'GET');
 		const result = builder.responseType('text/plain');
 
-		expect(result).toBe(builder);
+		// A new builder rather than the same one: a configured base has to stay
+		// reusable, so a chain step cannot write back into what it came from.
+		expect(result).toBeInstanceOf(EndpointBuilder);
+		expect(result).not.toBe(builder);
 	});
 
 	it('supports any arbitrary MIME type', () => {