ddd-ts-kit 0.0.0-stage → 0.1.1

package/templates/init/platform/events/aggregate-key-of.ts.tpl

@@ -0,0 +1,24 @@
+import type { IntegrationEvent } from '@ddd-ts-kit/kernel';
+
+/**
+ * The record key, which decides the order: the events of one aggregate share a key, so they stay
+ * on one partition and a consumer receives them in the order they were published. An event is
+ * named `<context>.<aggregate>.<fact>` and its payload names its aggregate as `<aggregate>Id`,
+ * which is what the generated publishers write. An event that carries no such field is produced
+ * without a key and ordered with nothing. The relay of the outbox is given the same function with
+ * `ordering: 'per-key'` (start-outbox-relay.ts), or the order would be lost before Kafka sees the
+ * events. To give up the order for an even spread of the load, remove `keyOf` from the event
+ * provider and the two lines of the relay: the key is then the event id.
+ */
+export function aggregateKeyOf(event: IntegrationEvent): string | undefined {
+  const aggregate = (event.type.split('.')[1] ?? '').replace(/-([a-z0-9])/g, (_match, letter: string) =>
+    letter.toUpperCase(),
+  );
+
+  const payload: unknown = event.payload;
+
+  const id: unknown =
+    typeof payload === 'object' && payload !== null ? Reflect.get(payload, aggregate + 'Id') : undefined;
+
+  return typeof id === 'string' ? id : undefined;
+}

package/templates/init/platform/events/create-event-provider.custom.ts.tpl

@@ -0,0 +1,9 @@
+import { CustomEventBus } from '{{alias.platform}}/events/custom-event-bus.js';
+import type { EventProvider } from '{{alias.platform}}/events/event-provider.js';
+
+// TODO(platform): give the adapter its connection settings from the validated config, name one subscriber per consuming context, and open and close the connection in start and close.
+export function createEventProvider(): EventProvider {
+  const bus = new CustomEventBus();
+
+  return { bus, forConsumer: () => bus, start: () => Promise.resolve(), close: () => Promise.resolve() };
+}

package/templates/init/platform/events/create-event-provider.kafka.ts.tpl

@@ -0,0 +1,51 @@
+import { KafkaEventBus } from '@ddd-ts-kit/kafka';
+{{#if errors.broker}}
+import { DeadLetterReports, NoopErrorReporter, type ErrorReporter } from '@ddd-ts-kit/kernel';
+{{/if}}
+import type { AppConfig } from '{{alias.platform}}/config/app-config.js';
+import { aggregateKeyOf } from '{{alias.platform}}/events/aggregate-key-of.js';
+import type { EventProvider } from '{{alias.platform}}/events/event-provider.js';
+
+/**
+ * Kafka: the relay of the outbox produces to one topic per event type and marks a record
+ * published once the in-sync replicas acknowledged it, each consuming context is a consumer
+ * group of its own name and commits an offset after its unit of work committed.
+ */
+{{#unless errors.broker}}
+export function createEventProvider(config: AppConfig): EventProvider {
+{{/unless}}
+{{#if errors.broker}}
+export function createEventProvider(config: AppConfig, errors: ErrorReporter = new NoopErrorReporter()): EventProvider {
+  // An event the broker gives up (retries exhausted, poison message) is reported; a delivery that fails and is retried is not.
+  const deadLetters = new DeadLetterReports(errors);
+
+{{/if}}
+  const bus = new KafkaEventBus({
+    brokers: config.kafkaBrokers,
+    keyOf: aggregateKeyOf,
+    // Codes only reach this hook, never messages: it is safe to log as is.
+{{#unless errors.broker}}
+    onFailure: (failure) => console.error(JSON.stringify({ level: 'error', message: 'event bus failure', ...failure })),
+{{/unless}}
+{{#if errors.broker}}
+    onFailure: (failure) => {
+      console.error(JSON.stringify({ level: 'error', message: 'event bus failure', ...failure }));
+      deadLetters.onFailure(failure);
+    },
+{{/if}}
+  });
+
+  return {
+    bus,
+{{#unless errors.broker}}
+    forConsumer: (name) => bus.forConsumer(name),
+{{/unless}}
+{{#if errors.broker}}
+    // Remembers what a handler threw, so that the report of an event given up carries the real error and its stack.
+    forConsumer: (name) => deadLetters.observing(bus.forConsumer(name)),
+{{/if}}
+    // Fails at startup, not at the first record.
+    start: () => bus.assertTopology(),
+    close: () => bus.close(),
+  };
+}

package/templates/init/platform/events/create-event-provider.nats.ts.tpl

@@ -0,0 +1,50 @@
+{{#if errors.broker}}
+import { DeadLetterReports, NoopErrorReporter, type ErrorReporter } from '@ddd-ts-kit/kernel';
+{{/if}}
+import { NatsEventBus } from '@ddd-ts-kit/nats';
+import type { AppConfig } from '{{alias.platform}}/config/app-config.js';
+import type { EventProvider } from '{{alias.platform}}/events/event-provider.js';
+
+/**
+ * NATS JetStream: the relay of the outbox publishes to one stream and marks a record published
+ * once the stream acknowledged it (a second publication of the same event id is dropped by the
+ * stream), each consuming context reads through durable consumers of its own name and
+ * acknowledges after its unit of work committed.
+ */
+{{#unless errors.broker}}
+export function createEventProvider(config: AppConfig): EventProvider {
+{{/unless}}
+{{#if errors.broker}}
+export function createEventProvider(config: AppConfig, errors: ErrorReporter = new NoopErrorReporter()): EventProvider {
+  // An event the broker gives up (retries exhausted, poison message) is reported; a delivery that fails and is retried is not.
+  const deadLetters = new DeadLetterReports(errors);
+
+{{/if}}
+  const bus = new NatsEventBus({
+    connection: config.natsUrl,
+    // Codes only reach this hook, never messages: it is safe to log as is.
+{{#unless errors.broker}}
+    onFailure: (failure) => console.error(JSON.stringify({ level: 'error', message: 'event bus failure', ...failure })),
+{{/unless}}
+{{#if errors.broker}}
+    onFailure: (failure) => {
+      console.error(JSON.stringify({ level: 'error', message: 'event bus failure', ...failure }));
+      deadLetters.onFailure(failure);
+    },
+{{/if}}
+  });
+
+  return {
+    bus,
+{{#unless errors.broker}}
+    forConsumer: (name) => bus.forConsumer(name),
+{{/unless}}
+{{#if errors.broker}}
+    // Remembers what a handler threw, so that the report of an event given up carries the real error and its stack.
+    forConsumer: (name) => deadLetters.observing(bus.forConsumer(name)),
+{{/if}}
+    // Fails at startup, not at the first message.
+    start: () => bus.assertTopology(),
+    close: () => bus.close(),
+  };
+}

package/templates/init/platform/events/create-event-provider.rabbitmq.ts.tpl

@@ -0,0 +1,48 @@
+{{#if errors.broker}}
+import { DeadLetterReports, NoopErrorReporter, type ErrorReporter } from '@ddd-ts-kit/kernel';
+{{/if}}
+import { RabbitMqEventBus } from '@ddd-ts-kit/rabbitmq';
+import type { AppConfig } from '{{alias.platform}}/config/app-config.js';
+import type { EventProvider } from '{{alias.platform}}/events/event-provider.js';
+
+/**
+ * RabbitMQ: the relay of the outbox publishes with publisher confirms, each consuming context
+ * reads its own durable queues and acknowledges after its unit of work committed.
+ */
+{{#unless errors.broker}}
+export function createEventProvider(config: AppConfig): EventProvider {
+{{/unless}}
+{{#if errors.broker}}
+export function createEventProvider(config: AppConfig, errors: ErrorReporter = new NoopErrorReporter()): EventProvider {
+  // An event the broker gives up (retries exhausted, poison message) is reported; a delivery that fails and is retried is not.
+  const deadLetters = new DeadLetterReports(errors);
+
+{{/if}}
+  const bus = new RabbitMqEventBus({
+    connection: config.amqpUrl,
+    // Codes only reach this hook, never messages: it is safe to log as is.
+{{#unless errors.broker}}
+    onFailure: (failure) => console.error(JSON.stringify({ level: 'error', message: 'event bus failure', ...failure })),
+{{/unless}}
+{{#if errors.broker}}
+    onFailure: (failure) => {
+      console.error(JSON.stringify({ level: 'error', message: 'event bus failure', ...failure }));
+      deadLetters.onFailure(failure);
+    },
+{{/if}}
+  });
+
+  return {
+    bus,
+{{#unless errors.broker}}
+    forConsumer: (name) => bus.forConsumer(name),
+{{/unless}}
+{{#if errors.broker}}
+    // Remembers what a handler threw, so that the report of an event given up carries the real error and its stack.
+    forConsumer: (name) => deadLetters.observing(bus.forConsumer(name)),
+{{/if}}
+    // Fails at startup, not at the first message.
+    start: () => bus.assertTopology(),
+    close: () => bus.close(),
+  };
+}

package/templates/init/platform/events/create-event-provider.redis.ts.tpl

@@ -0,0 +1,50 @@
+{{#if errors.broker}}
+import { DeadLetterReports, NoopErrorReporter, type ErrorReporter } from '@ddd-ts-kit/kernel';
+{{/if}}
+import { RedisStreamsEventBus } from '@ddd-ts-kit/redis/event-bus';
+import type { AppConfig } from '{{alias.platform}}/config/app-config.js';
+import type { EventProvider } from '{{alias.platform}}/events/event-provider.js';
+
+/**
+ * Redis Streams, on Redis, Dragonfly or Valkey: the relay of the outbox appends to one stream per
+ * event type and marks a record published once the server answered its entry, each consuming
+ * context reads through a consumer group of its own name and acknowledges after its unit of work
+ * committed. The server is the one of `REDIS_URL`, shared with whatever else the platform keeps there.
+ */
+{{#unless errors.broker}}
+export function createEventProvider(config: AppConfig): EventProvider {
+{{/unless}}
+{{#if errors.broker}}
+export function createEventProvider(config: AppConfig, errors: ErrorReporter = new NoopErrorReporter()): EventProvider {
+  // An event the broker gives up (retries exhausted, poison message) is reported; a delivery that fails and is retried is not.
+  const deadLetters = new DeadLetterReports(errors);
+
+{{/if}}
+  const bus = new RedisStreamsEventBus({
+    connection: config.redisUrl,
+    // Codes only reach this hook, never messages: it is safe to log as is.
+{{#unless errors.broker}}
+    onFailure: (failure) => console.error(JSON.stringify({ level: 'error', message: 'event bus failure', ...failure })),
+{{/unless}}
+{{#if errors.broker}}
+    onFailure: (failure) => {
+      console.error(JSON.stringify({ level: 'error', message: 'event bus failure', ...failure }));
+      deadLetters.onFailure(failure);
+    },
+{{/if}}
+  });
+
+  return {
+    bus,
+{{#unless errors.broker}}
+    forConsumer: (name) => bus.forConsumer(name),
+{{/unless}}
+{{#if errors.broker}}
+    // Remembers what a handler threw, so that the report of an event given up carries the real error and its stack.
+    forConsumer: (name) => deadLetters.observing(bus.forConsumer(name)),
+{{/if}}
+    // Fails at startup, not at the first message.
+    start: () => bus.assertTopology(),
+    close: () => bus.close(),
+  };
+}

package/templates/init/platform/events/custom-event-bus.contract.spec.ts.tpl

@@ -0,0 +1,8 @@
+import { beforeEach, describe, expect, it } from '{{tests.module}}';
+import { eventBusContract } from '@ddd-ts-kit/testing/contracts';
+import { CustomEventBus } from '{{alias.platform}}/events/custom-event-bus.js';
+
+eventBusContract(
+  { describe, it, expect, beforeEach },
+  { name: 'The custom event bus', createBus: () => ({ bus: new CustomEventBus() }) },
+);

package/templates/init/platform/events/custom-event-bus.ts.tpl

@@ -0,0 +1,25 @@
+import {
+  InMemoryEventBus,
+  type EventBus,
+  type IntegrationEvent,
+  type IntegrationEventCallback,
+  type Subscription,
+} from '@ddd-ts-kit/kernel';
+
+/**
+ * The adapter of the `EventBus` port for your broker or queue service. This stub delivers in
+ * the process so that the application runs; custom-event-bus.contract.spec.ts holds whatever
+ * replaces it to what the outbox relay and the consumers rely on.
+ */
+// TODO(platform): publish with a confirmation of the broker (resolve only once it took every event, reject otherwise) and consume from one durable queue per consumer, acknowledging after the handler succeeded.
+export class CustomEventBus implements EventBus {
+  private readonly delivery = new InMemoryEventBus();
+
+  publish(events: readonly IntegrationEvent[]): Promise<void> {
+    return this.delivery.publish(events);
+  }
+
+  subscribe(eventType: string, handler: IntegrationEventCallback): Subscription {
+    return this.delivery.subscribe(eventType, handler);
+  }
+}

package/templates/init/platform/events/event-provider.ts.tpl

@@ -0,0 +1,13 @@
+import type { EventBus, IntegrationEventSubscriber } from '@ddd-ts-kit/kernel';
+
+/** The provider integration events are delivered to, and how each consuming context listens to it. */
+export interface EventProvider {
+  readonly bus: EventBus;
+
+  /** The subscriber of one consuming context, under its own name. */
+  forConsumer(name: string): IntegrationEventSubscriber;
+
+  start(): Promise<void>;
+
+  close(): Promise<void>;
+}

package/templates/init/platform/events/in-process-events.ts.tpl

@@ -0,0 +1,14 @@
+import { InMemoryEventBus } from '@ddd-ts-kit/kernel';
+import type { EventProvider } from '{{alias.platform}}/events/event-provider.js';
+
+{{#if broker.none}}
+/** Same process, no broker: {{#if events.outbox}}the relay of the outbox publishes to this bus, which runs the consumers{{/if}}{{#unless events.outbox}}use cases publish to this bus, which runs the consumers{{/unless}}. */
+{{/if}}
+{{#unless broker.none}}
+/** For the tools and the tests that run without a broker: the same ports, in the process. */
+{{/unless}}
+export function inProcessEvents(): EventProvider {
+  const bus = new InMemoryEventBus();
+
+  return { bus, forConsumer: () => bus, start: () => Promise.resolve(), close: () => Promise.resolve() };
+}

package/templates/init/platform/events/start-outbox-relay.ts.tpl

@@ -0,0 +1,74 @@
+import { OutboxRelay, type OutboxStore{{#if events.wakeable}}, type RelaySignal{{/if}} } from '@ddd-ts-kit/events';
+{{#if errors.none}}
+import { SystemClock, type IntegrationEventPublisher, type Logger } from '@ddd-ts-kit/kernel';
+{{/if}}
+{{#if errors.sentry}}
+import {
+  DeadLetterReports,
+  NoopErrorReporter,
+  SystemClock,
+  type ErrorReporter,
+  type IntegrationEventPublisher,
+  type Logger,
+} from '@ddd-ts-kit/kernel';
+{{/if}}
+{{#if broker.kafka}}
+import { aggregateKeyOf } from '{{alias.platform}}/events/aggregate-key-of.js';
+{{/if}}
+
+export interface OutboxRelayOptions {
+  readonly store: OutboxStore;
+  /** The provider events are delivered to once their command has committed. */
+  readonly publisher: IntegrationEventPublisher;
+  readonly intervalMs: number;
+  /** How many times a publication is tried before its record is declared dead; left out, the default of the relay. */
+  readonly maxAttempts?: number;
+  readonly logger: Logger;
+{{#if errors.sentry}}
+  /** Where an event whose publication the relay declares dead is reported; left out (the tests), nowhere. */
+  readonly errors?: ErrorReporter;
+{{/if}}
+{{#if events.wakeable}}
+  /** Wakes the relay as soon as an event is stored; the interval stays as the safety net. */
+  readonly wakeOn?: RelaySignal;
+{{/if}}
+}
+
+export interface RunningRelay {
+  stop(): Promise<void>;
+}
+
+export function startOutboxRelay(options: OutboxRelayOptions): RunningRelay {
+{{#if errors.sentry}}
+  const deadLetters = new DeadLetterReports(options.errors ?? new NoopErrorReporter());
+
+{{/if}}
+  const relay = new OutboxRelay({
+    store: options.store,
+    publisher: options.publisher,
+    clock: new SystemClock(),
+    ...(options.maxAttempts === undefined ? {} : { maxAttempts: options.maxAttempts }),
+{{#if broker.kafka}}
+    // The events of one aggregate leave in the order they were stored, under the key Kafka orders them by: it takes a single running relay.
+    ordering: 'per-key',
+    keyOf: aggregateKeyOf,
+{{/if}}
+{{#if events.wakeable}}
+    ...(options.wakeOn === undefined ? {} : { wakeOn: options.wakeOn }),
+{{/if}}
+    // Codes only reach this hook, never messages: it is safe to log as is.
+{{#if errors.none}}
+    onFailure: (failure) => options.logger.error('outbox relay failure', { ...failure }),
+{{/if}}
+{{#if errors.sentry}}
+    onFailure: (failure) => {
+      options.logger.error('outbox relay failure', { ...failure });
+      deadLetters.onFailure(failure);
+    },
+{{/if}}
+  });
+
+  relay.start({ intervalMs: options.intervalMs });
+
+  return { stop: async () => relay.stop() };
+}

package/templates/init/platform/http/create-app-module.ts.tpl

@@ -0,0 +1,12 @@
+import { Module, type DynamicModule } from '@nestjs/common';
+import type { Route } from '@ddd-ts-kit/http';
+import { createRoutesModule } from '@ddd-ts-kit/http/nest';
+import type { HttpBoundary } from '{{alias.platform}}/auth/http-boundary.js';
+
+@Module({})
+class AppModule {}
+
+/** The Nest application: the framework-free routes mounted on its HTTP server by the `RoutesMounter` of their module. */
+export function createAppModule(routes: readonly Route[], boundary: HttpBoundary): DynamicModule {
+  return { module: AppModule, imports: [createRoutesModule(routes, boundary)] };
+}

package/templates/init/platform/http/refusal-for.ts.tpl

@@ -0,0 +1,39 @@
+import type { RateLimit, RateLimiter } from '@ddd-ts-kit/kernel';
+
+const tooManyRequests = 429;
+
+/** What a refused caller receives: RFC 9457 problem details, and how long to wait in `retry-after`. */
+export interface Refusal {
+  readonly headers: Readonly<Record<string, string>>;
+  readonly problem: { readonly type: string; readonly title: string; readonly status: number; readonly code: string };
+}
+
+/**
+ * Asked for every request before authentication costs anything: one sliding window per caller
+ * address. Answers nothing when the request may pass. Behind a proxy, make the HTTP server
+ * trust it, or every caller shares the address of the proxy.
+ */
+export async function refusalFor(
+  limiter: RateLimiter,
+  limit: RateLimit,
+  address: string | undefined,
+): Promise<Refusal | undefined> {
+  const decision = await limiter.consume('ip:' + (address ?? 'unknown'), limit);
+
+  if (decision.allowed) {
+    return undefined;
+  }
+
+  return {
+    headers: {
+      'content-type': 'application/problem+json',
+      'retry-after': String(Math.max(1, Math.ceil(decision.retryAfterMs / 1000))),
+    },
+    problem: {
+      type: 'urn:problem:rate-limited',
+      title: 'Too Many Requests',
+      status: tooManyRequests,
+      code: 'RATE_LIMITED',
+    },
+  };
+}

package/templates/init/platform/http/start-http-server.express.ts.tpl

@@ -0,0 +1,81 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { mountExpress } from '@ddd-ts-kit/http/express';
+import type { Application } from '{{alias.platform}}/compose-application.js';
+import type { AppConfig } from '{{alias.platform}}/config/app-config.js';
+{{#if cache.rateLimit}}
+import { refusalFor } from '{{alias.platform}}/http/refusal-for.js';
+{{/if}}
+{{#if docs.any}}
+import { withDocumentation } from '{{alias.platform}}/http/with-documentation.js';
+{{/if}}
+
+export interface HttpServer {
+  /** The port really bound: differs from the configured one when that was 0. */
+  readonly port: number;
+
+  close(): Promise<void>;
+}
+
+/** What the server needs of the application: its routes and what stands at its edge. */
+type Served = Pick<Application, 'routes' | 'boundary'{{#if cache.rateLimit}} | 'rateLimiter' | 'ready'{{/if}}>;
+
+export async function startHttpServer(served: Served, config: AppConfig): Promise<HttpServer> {
+  const app = express();
+
+  app.disable('x-powered-by');
+{{#if cache.rateLimit}}
+  guardTheDoor(app, served, config);
+{{/if}}
+  app.use(express.json());
+{{#if docs.any}}
+  mountExpress(app, withDocumentation(served.routes, config), served.boundary);
+{{/if}}
+{{#unless docs.any}}
+  mountExpress(app, served.routes, served.boundary);
+{{/unless}}
+
+  const server = await listen(app, config.port);
+
+  return { port: boundPort(server), close: () => close(server) };
+}
+{{#if cache.rateLimit}}
+
+/** The readiness probe, then the limiter, before any route. */
+function guardTheDoor(app: express.Express, served: Served, config: AppConfig): void {
+  app.get(
+    '/health/ready',
+    (_request, response) =>
+      void served.ready().then((ready) => response.status(ready ? 200 : 503).json({ status: ready ? 'up' : 'down' })),
+  );
+
+  app.use((request, response, next) => {
+    void refusalFor(served.rateLimiter, config.rateLimit, request.ip).then((refusal) => {
+      if (refusal === undefined) {
+        next();
+      } else {
+        response.status(refusal.problem.status).set(refusal.headers).send(JSON.stringify(refusal.problem));
+      }
+    }, next);
+  });
+}
+{{/if}}
+
+function listen(app: express.Express, port: number): Promise<Server> {
+  return new Promise<Server>((resolve) => {
+    const server = app.listen(port, () => resolve(server));
+  });
+}
+
+function boundPort(server: Server): number {
+  const address: AddressInfo | string | null = server.address();
+
+  return typeof address === 'object' && address !== null ? address.port : 0;
+}
+
+function close(server: Server): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    server.close((error) => (error === undefined ? resolve() : reject(error)));
+  });
+}

package/templates/init/platform/http/start-http-server.fastify.ts.tpl

@@ -0,0 +1,59 @@
+import Fastify{{#if cache.rateLimit}}, { type FastifyInstance }{{/if}} from 'fastify';
+import { mountFastify } from '@ddd-ts-kit/http/fastify';
+import type { Application } from '{{alias.platform}}/compose-application.js';
+import type { AppConfig } from '{{alias.platform}}/config/app-config.js';
+{{#if cache.rateLimit}}
+import { refusalFor } from '{{alias.platform}}/http/refusal-for.js';
+{{/if}}
+{{#if docs.any}}
+import { withDocumentation } from '{{alias.platform}}/http/with-documentation.js';
+{{/if}}
+
+export interface HttpServer {
+  /** The port really bound: differs from the configured one when that was 0. */
+  readonly port: number;
+
+  close(): Promise<void>;
+}
+
+/** What the server needs of the application: its routes and what stands at its edge. */
+type Served = Pick<Application, 'routes' | 'boundary'{{#if cache.rateLimit}} | 'rateLimiter' | 'ready'{{/if}}>;
+
+export async function startHttpServer(served: Served, config: AppConfig): Promise<HttpServer> {
+  const app = Fastify();
+
+{{#if cache.rateLimit}}
+  guardTheDoor(app, served, config);
+{{/if}}
+{{#if docs.any}}
+  mountFastify(app, withDocumentation(served.routes, config), served.boundary);
+{{/if}}
+{{#unless docs.any}}
+  mountFastify(app, served.routes, served.boundary);
+{{/unless}}
+  await app.listen({ port: config.port, host: '0.0.0.0' });
+
+  const [address] = app.addresses();
+
+  return { port: address?.port ?? 0, close: () => app.close() };
+}
+{{#if cache.rateLimit}}
+
+/** The readiness probe, then the limiter, before any route. */
+function guardTheDoor(app: FastifyInstance, served: Served, config: AppConfig): void {
+  app.get('/health/ready', async (_request, reply) => {
+    const ready = await served.ready();
+
+    return reply.code(ready ? 200 : 503).send({ status: ready ? 'up' : 'down' });
+  });
+
+  app.addHook('onRequest', async (request, reply) => {
+    const refusal =
+      request.url === '/health/ready' ? undefined : await refusalFor(served.rateLimiter, config.rateLimit, request.ip);
+
+    if (refusal !== undefined) {
+      await reply.code(refusal.problem.status).headers(refusal.headers).send(JSON.stringify(refusal.problem));
+    }
+  });
+}
+{{/if}}

package/templates/init/platform/http/start-http-server.nest.ts.tpl

@@ -0,0 +1,99 @@
+import 'reflect-metadata';
+import { Server } from 'node:http';
+import { NestFactory } from '@nestjs/core';
+import type { Application } from '{{alias.platform}}/compose-application.js';
+import type { AppConfig } from '{{alias.platform}}/config/app-config.js';
+import { createAppModule } from '{{alias.platform}}/http/create-app-module.js';
+{{#if cache.rateLimit}}
+import { refusalFor } from '{{alias.platform}}/http/refusal-for.js';
+{{/if}}
+{{#if docs.any}}
+import { withDocumentation } from '{{alias.platform}}/http/with-documentation.js';
+{{/if}}
+
+export interface HttpServer {
+  /** The port really bound: differs from the configured one when that was 0. */
+  readonly port: number;
+
+  close(): Promise<void>;
+}
+
+/** What the server needs of the application: its routes and what stands at its edge. */
+type Served = Pick<Application, 'routes' | 'boundary'{{#if cache.rateLimit}} | 'rateLimiter' | 'ready'{{/if}}>;
+{{#if cache.rateLimit}}
+
+/** The part of the incoming request and of its response the limiter and the probe need, whatever Nest runs on. */
+interface Incoming {
+  readonly url?: string;
+  readonly socket: { readonly remoteAddress?: string };
+}
+
+interface Outgoing {
+  writeHead(status: number, headers: Readonly<Record<string, string>>): Outgoing;
+
+  end(body: string): void;
+}
+{{/if}}
+
+export async function startHttpServer(served: Served, config: AppConfig): Promise<HttpServer> {
+{{#if docs.any}}
+  const app = await NestFactory.create(createAppModule(withDocumentation(served.routes, config), served.boundary), {
+    logger: ['error', 'warn'],
+  });
+{{/if}}
+{{#unless docs.any}}
+  const app = await NestFactory.create(createAppModule(served.routes, served.boundary), { logger: ['error', 'warn'] });
+{{/unless}}
+
+{{#if cache.rateLimit}}
+  app.use(
+    (request: Incoming, response: Outgoing, next: () => void) =>
+      void guardTheDoor({ served, config }, { request, response, next }),
+  );
+
+{{/if}}
+  await app.listen(config.port);
+
+  return { port: boundPort(app.getHttpServer()), close: () => app.close() };
+}
+{{#if cache.rateLimit}}
+
+interface Door {
+  readonly served: Served;
+  readonly config: AppConfig;
+}
+
+interface Exchange {
+  readonly request: Incoming;
+  readonly response: Outgoing;
+  readonly next: () => void;
+}
+
+/** The readiness probe, then the limiter, before any route. */
+async function guardTheDoor({ served, config }: Door, { request, response, next }: Exchange): Promise<void> {
+  if (request.url === '/health/ready') {
+    const ready = await served.ready();
+
+    response
+      .writeHead(ready ? 200 : 503, { 'content-type': 'application/json' })
+      .end(JSON.stringify({ status: ready ? 'up' : 'down' }));
+
+    return;
+  }
+
+  const refusal = await refusalFor(served.rateLimiter, config.rateLimit, request.socket.remoteAddress);
+
+  if (refusal === undefined) {
+    next();
+  } else {
+    response.writeHead(refusal.problem.status, refusal.headers).end(JSON.stringify(refusal.problem));
+  }
+}
+{{/if}}
+
+// Nest types its HTTP server loosely: the port is read only from what proves to be a Node server.
+function boundPort(server: unknown): number {
+  const address = server instanceof Server ? server.address() : null;
+
+  return typeof address === 'object' && address !== null ? address.port : 0;
+}