ddd-ts-kit 0.0.0-stage → 0.1.1

package/templates/init/platform/http/with-documentation.ts.tpl

@@ -0,0 +1,20 @@
+import type { Route } from '@ddd-ts-kit/http';
+import { openApiDocsRoutes } from '@ddd-ts-kit/http/docs';
+import { generateOpenApi } from '@ddd-ts-kit/http/openapi';
+import { securitySchemes } from '{{alias.platform}}/auth/security-schemes.js';
+import type { AppConfig } from '{{alias.platform}}/config/app-config.js';
+
+/** Adds the contract and its interactive page next to the routes, unless documentation is switched off (API_DOCS, off in production by default). */
+export function withDocumentation(routes: readonly Route[], config: AppConfig): readonly Route[] {
+  if (!config.docsEnabled) {
+    return routes;
+  }
+
+  const document = generateOpenApi({
+    info: { title: config.serviceName, version: config.serviceVersion },
+    routes,
+    securitySchemes,
+  });
+
+  return [...routes, ...openApiDocsRoutes(document, { ui: '{{docs.ui}}' })];
+}

package/templates/init/platform/job-settings.ts.tpl

@@ -0,0 +1,23 @@
+import type { JobSettings } from '@ddd-ts-kit/kernel';
+
+type Environment = Readonly<Record<string, string | undefined>>;
+
+/**
+ * What configuration changes of each scheduled job, by job name: a job is switched off in one
+ * environment with `JOB_<CONTEXT>_<JOB>_ENABLED=false`, never by a code change.
+ * `ddd-ts-kit generate job` adds a line; a schedule or a timeout read from the environment goes
+ * on the same line. Given a context, only its jobs are kept: an application that hosts one
+ * context is refused the settings of a job it does not declare.
+ */
+export function jobSettings(environment: Environment, context?: string): Readonly<Record<string, JobSettings>> {
+  const settings: Readonly<Record<string, JobSettings>> = {
+    // ddd-ts-kit:jobs
+    // /ddd-ts-kit:jobs
+  };
+
+  if (context === undefined) {
+    return settings;
+  }
+
+  return Object.fromEntries(Object.entries(settings).filter(([name]) => name.startsWith(context + '.')));
+}

package/templates/init/platform/jobs/configured-job-scheduler.ts.tpl

@@ -0,0 +1,43 @@
+import type { JobDefinition, JobDescription, JobRun, JobScheduler, JobSettings } from '@ddd-ts-kit/kernel';
+
+type Run = JobDefinition['run'];
+
+/** What is put around each run from outside (its span): told the job and the context its name starts with. */
+type Observe = (run: Run, job: { readonly name: string; readonly context: string }) => Run;
+
+/**
+ * The scheduler of the platform with the settings of the configuration applied: what
+ * `job-settings.ts` says of a job wins over what its context registered, and a key left
+ * undefined changes nothing. Each run goes through what observes the jobs from outside.
+ */
+export class ConfiguredJobScheduler implements JobScheduler {
+  constructor(
+    private readonly scheduler: JobScheduler,
+    private readonly settings: Readonly<Record<string, JobSettings>>,
+    private readonly observe: Observe,
+  ) {}
+
+  register(job: JobDefinition): void {
+    const written = Object.entries(this.settings[job.name] ?? {}).filter(([, value]) => value !== undefined);
+
+    const run = this.observe(job.run, { name: job.name, context: job.name.split('.')[0] ?? job.name });
+
+    this.scheduler.register({ ...job, ...Object.fromEntries(written), run });
+  }
+
+  start(): Promise<void> {
+    return this.scheduler.start();
+  }
+
+  stop(): Promise<void> {
+    return this.scheduler.stop();
+  }
+
+  runNow(name: string): Promise<JobRun> {
+    return this.scheduler.runNow(name);
+  }
+
+  describe(): readonly JobDescription[] {
+    return this.scheduler.describe();
+  }
+}

package/templates/init/platform/lay-foundations.tsyringe.ts.tpl

@@ -0,0 +1,74 @@
+{{#unless audit.on}}
+import type { OnDecision } from '@ddd-ts-kit/auth';
+{{/unless}}
+import {
+  AsyncLocalStorageExecutionScope,
+  SystemClock,
+  UuidGenerator,
+  type Clock,
+  type ExecutionScope,
+  type IdGenerator,
+  type Logger,
+  type Metrics,
+} from '@ddd-ts-kit/kernel';
+import { traceApplication, type ConsumerTrace, type TracedApplication } from '@ddd-ts-kit/tracing';
+{{#if audit.on}}
+import { createAudit, type Audit } from '{{alias.platform}}/audit/create-audit.js';
+{{/if}}
+{{#unless audit.on}}
+import { logDecisions } from '{{alias.platform}}/auth/log-decisions.js';
+{{/unless}}
+import type { Persistence } from '{{alias.platform}}/database/persistence.js';
+import { createLogger, type LogSettings } from '{{alias.platform}}/observability/create-logger.js';
+import { createMetrics } from '{{alias.platform}}/observability/create-metrics.js';
+
+/**
+ * What exists before any module: built once and handed to the kernel module, so that the buses,
+ * the logger{{#if audit.on}}, the audit sources{{/if}} and every adapter read one execution scope, one clock and one
+ * generator.
+ */
+export interface Foundations {
+  readonly scope: ExecutionScope;
+  readonly clock: Clock;
+  readonly ids: IdGenerator;
+  readonly logger: Logger;
+  readonly metrics: Metrics;
+  /** What observes the application from outside: handed to the kernel module, and to the buses this platform builds itself. */
+  readonly traced: TracedApplication;
+{{#if audit.on}}
+  readonly audit: Audit;
+{{/if}}
+{{#unless audit.on}}
+  /** What every authorization decision is told to: the log, since the audit trail is off. */
+  readonly decisions: OnDecision;
+{{/unless}}
+}
+
+interface Observed {
+  /** Where log entries go; left out, the application writes nothing. */
+  readonly log?: LogSettings;
+  /** Whether a consumed event continues the trace of its publication (the default) or starts one linked to it. */
+  readonly traceConsumers?: ConsumerTrace;
+}
+
+export function layFoundations(persistence: Persistence, options: Observed): Foundations {
+  const scope = new AsyncLocalStorageExecutionScope();
+  const clock = new SystemClock();
+  const ids = new UuidGenerator();
+  const logger = createLogger(scope, options.log);
+
+  return {
+    scope,
+    clock,
+    ids,
+    logger,
+    metrics: createMetrics(),
+    traced: traceApplication({ consumers: options.traceConsumers ?? 'continue' }),
+{{#if audit.on}}
+    audit: createAudit(persistence, { scope, clock, ids }),
+{{/if}}
+{{#unless audit.on}}
+    decisions: logDecisions(logger),
+{{/unless}}
+  };
+}

package/templates/init/platform/observability/create-logger.pino.ts.tpl

@@ -0,0 +1,28 @@
+import { NoopLogger, type ExecutionScope, type LogLevel, type Logger } from '@ddd-ts-kit/kernel';
+import { createPinoLogger } from '@ddd-ts-kit/pino';
+import { traceLogFields } from '@ddd-ts-kit/tracing';
+
+/** Where log entries go. Left out (the tools, the tests), the application writes nothing. */
+export interface LogSettings {
+  readonly level: LogLevel;
+  /** `json` everywhere; `pretty` (through `pino-pretty`, in a worker thread) on a developer's machine only. */
+  readonly format: 'json' | 'pretty';
+  readonly service: string;
+  readonly environment: string;
+  /** Writes `[message removed]` for the message of every logged error that is not a `DomainError`. */
+  readonly scrubMessages: boolean;
+}
+
+/**
+ * pino on the standard output, the credential keys of the kernel redacted. Every line carries
+ * what the execution scope knows of the work in progress (correlation id, origin, actor,
+ * tenant) and the ids of the active trace, so a request is followed from its log lines to its
+ * spans and to its audit entries. `stop()` of the application flushes it, last.
+ */
+export function createLogger(scope: ExecutionScope, settings: LogSettings | undefined): Logger {
+  if (settings === undefined) {
+    return new NoopLogger();
+  }
+
+  return createPinoLogger({ ...settings, fields: () => traceLogFields(scope) });
+}

package/templates/init/platform/observability/create-logger.stdout.ts.tpl

@@ -0,0 +1,36 @@
+import { StdoutLogger } from '@ddd-ts-kit/aspects';
+import { NoopLogger, type ExecutionScope, type LogLevel, type Logger } from '@ddd-ts-kit/kernel';
+import { traceLogFields } from '@ddd-ts-kit/tracing';
+
+/** Where log entries go. Left out (the tools, the tests), the application writes nothing. */
+export interface LogSettings {
+  readonly level: LogLevel;
+  /** `json` only: this logger has no pretty format, and `LOG_FORMAT=pretty` is refused when the configuration is loaded. */
+  readonly format: 'json';
+  readonly service: string;
+  readonly environment: string;
+  /** Writes `[message removed]` for the message of every logged error that is not a `DomainError`. */
+  readonly scrubMessages: boolean;
+}
+
+/**
+ * JSON lines on the standard output, credentials not redacted (`init --logger pino` or
+ * `--logger winston` redacts them and has a pretty format). Every entry carries
+ * what the execution scope knows of the work in progress (correlation id, origin, actor,
+ * tenant) and the ids of the active trace, so a request is followed from its log lines to its
+ * spans and to its audit entries. `stop()` of the application flushes it, last.
+ */
+export function createLogger(scope: ExecutionScope, settings: LogSettings | undefined): Logger {
+  if (settings === undefined) {
+    return new NoopLogger();
+  }
+
+  const { level, service, environment, scrubMessages } = settings;
+
+  return new StdoutLogger({
+    level,
+    base: { service, environment },
+    scrubMessages,
+    fields: () => traceLogFields(scope),
+  });
+}

package/templates/init/platform/observability/create-logger.winston.ts.tpl

@@ -0,0 +1,29 @@
+import { NoopLogger, type ExecutionScope, type LogLevel, type Logger } from '@ddd-ts-kit/kernel';
+import { traceLogFields } from '@ddd-ts-kit/tracing';
+import { createWinstonLogger } from '@ddd-ts-kit/winston';
+
+/** Where log entries go. Left out (the tools, the tests), the application writes nothing. */
+export interface LogSettings {
+  readonly level: LogLevel;
+  /** `json` everywhere; `pretty` on a developer's machine only. */
+  readonly format: 'json' | 'pretty';
+  readonly service: string;
+  readonly environment: string;
+  /** Writes `[message removed]` for the message of every logged error that is not a `DomainError`. */
+  readonly scrubMessages: boolean;
+}
+
+/**
+ * winston on the console, the credential keys of the kernel redacted. Its flush is final:
+ * what is logged after `stop()` of the application is dropped. Every line carries
+ * what the execution scope knows of the work in progress (correlation id, origin, actor,
+ * tenant) and the ids of the active trace, so a request is followed from its log lines to its
+ * spans and to its audit entries. `stop()` of the application flushes it, last.
+ */
+export function createLogger(scope: ExecutionScope, settings: LogSettings | undefined): Logger {
+  if (settings === undefined) {
+    return new NoopLogger();
+  }
+
+  return createWinstonLogger({ ...settings, fields: () => traceLogFields(scope) });
+}

package/templates/init/platform/observability/create-metrics.ts.tpl

@@ -0,0 +1,6 @@
+import { NoopMetrics, type Metrics } from '@ddd-ts-kit/kernel';
+
+// TODO(platform): answer an adapter of the kernel Metrics port (OpenTelemetry, Prometheus) here; until then the series of the bus middlewares and of `timed` are measured by nothing.
+export function createMetrics(): Metrics {
+  return new NoopMetrics();
+}

package/templates/init/platform/platform-test.module.tsyringe.ts.tpl

@@ -0,0 +1,24 @@
+import { defineContextModule } from '@ddd-ts-kit/di';
+{{#if persistence.packagedToken}}
+import { {{persistence.token}} } from '{{persistence.tokenPackage}}';
+{{/if}}
+{{#if persistence.ownDatabase}}
+import { Database } from '{{alias.platform}}/database/database.js';
+{{/if}}
+// ddd-ts-kit:imports
+// /ddd-ts-kit:imports
+
+/** The platform of a handler spec: no storage behind it, so every repository a test touches has to be faked. */
+export const platformTestModule = defineContextModule({
+  name: 'platform',
+  register(builder) {
+    {{#if persistence.hasDatabase}}
+    builder.bind({{persistence.token}}).toFactory(() => {
+      throw new Error('A handler spec has no database: give a fake for the repository it uses.');
+    });
+
+    {{/if}}
+    // ddd-ts-kit:test-bindings
+    // /ddd-ts-kit:test-bindings
+  },
+});

package/templates/init/platform/platform.manual.ts.tpl

@@ -0,0 +1,81 @@
+import type { AspectInfo } from '@ddd-ts-kit/aspects';
+import type { Access } from '@ddd-ts-kit/auth';
+import type {
+  ActorContext,
+  Cache,
+  Clock,
+  DomainEventDispatcher,
+  {{#if errors.sentry}}
+  ErrorReporter,
+  {{/if}}
+  ExecutionScope,
+  IdGenerator,
+  InMemoryCommandBus,
+  InMemoryQueryBus,
+  IntegrationEventPublisher,
+  IntegrationEventSubscriber,
+  JobScheduler,
+  Logger,
+  Metrics,
+  {{#if cache.rateLimit}}
+  RateLimiter,
+  {{/if}}
+} from '@ddd-ts-kit/kernel';
+{{#if audit.on}}
+import type { Audit } from '{{alias.platform}}/audit/create-audit.js';
+{{/if}}
+import type { UseCaseProtection } from '{{alias.platform}}/auth/use-case-protection.js';
+import type { Persistence } from '{{alias.platform}}/database/persistence.js';
+
+/** Wraps an adapter from outside: a span for its kind and, for what leaves the process, the default policy unless it states its own. */
+type Adapt = <T extends object>(instance: T, info: AspectInfo) => T;
+
+/** The technical capabilities every context receives. */
+export interface Platform {
+  /** The in-process buses: contexts register their handlers on them, routes and integration event handlers only see the `CommandBus` and `QueryBus` ports. */
+  readonly commands: InMemoryCommandBus;
+  readonly queries: InMemoryQueryBus;
+  readonly clock: Clock;
+  readonly ids: IdGenerator;
+  readonly domainEvents: DomainEventDispatcher;
+  /** What use cases publish through. */
+  readonly publisher: IntegrationEventPublisher;
+  readonly subscriber: IntegrationEventSubscriber;
+  {{#if broker.external}}
+
+  /** The subscriber of one consuming context: a broker gives each context queues of its own. */
+  subscriberFor(context: string): IntegrationEventSubscriber;
+
+  {{/if}}
+  /** The provider itself: what the outbox relay delivers to. */
+  readonly eventBus: IntegrationEventPublisher;
+  readonly persistence: Persistence;
+  /** Asks the policies about one element, then the authorizer: for the rules that need loaded state. */
+  readonly access: Access;
+  /**
+   * The work in progress (correlation id, actor, tenant), for infrastructure only: audit
+   * columns, tenant scoping, consumed events. Use cases get the actor in their message.
+   */
+  readonly scope: ExecutionScope;
+  /** The actor of the execution scope, for an adapter written against `ActorContext`. */
+  readonly actors: ActorContext;
+  readonly logger: Logger;
+  readonly metrics: Metrics;
+  {{#if errors.sentry}}
+  /** Where what stands around the use cases reports an unexpected failure: the buses, the jobs, the HTTP boundary. A handler throws and never calls it. */
+  readonly errors: ErrorReporter;
+  {{/if}}
+  readonly cache: Cache;
+  {{#if cache.rateLimit}}
+  readonly rateLimiter: RateLimiter;
+  {{/if}}
+  /** Where a context registers its scheduled jobs; the application starts it when this process runs the jobs. */
+  readonly jobs: JobScheduler;
+  readonly adapter: Adapt;
+  /** The same, for an adapter that states its own policy, as aspects or as decorators on its class. */
+  readonly selfGoverned: Adapt;
+  readonly protection: UseCaseProtection;
+  {{#if audit.on}}
+  readonly audit: Audit;
+  {{/if}}
+}

package/templates/init/platform/platform.module.tsyringe.ts.tpl

@@ -0,0 +1,146 @@
+{{#if http.any}}
+import type { Authenticator } from '@ddd-ts-kit/auth';
+{{/if}}
+{{#if cache.redis}}
+import { defineContextModule, type ContextModule, type ModuleBuilder } from '@ddd-ts-kit/di';
+{{/if}}
+{{#unless cache.redis}}
+import { defineContextModule, type ContextModule } from '@ddd-ts-kit/di';
+{{/unless}}
+{{#if events.outbox}}
+import { OutboxStore } from '@ddd-ts-kit/events';
+{{/if}}
+{{#if http.any}}
+import { ErrorMapper, createErrorMapper } from '@ddd-ts-kit/http';
+{{/if}}
+{{#if cache.redis}}
+{{#if broker.external}}
+import {
+  Cache,
+  EventSubscribers,
+  Lock,
+  Metrics,
+  ProcessedEventStore,
+  RateLimiter,
+  UnitOfWork,
+  {{#if errors.sentry}}
+  type ErrorReporter,
+  {{/if}}
+} from '@ddd-ts-kit/kernel';
+{{/if}}
+{{#unless broker.external}}
+{{#if errors.sentry}}
+import {
+  Cache,
+  Lock,
+  Metrics,
+  ProcessedEventStore,
+  RateLimiter,
+  UnitOfWork,
+  type ErrorReporter,
+} from '@ddd-ts-kit/kernel';
+{{/if}}
+{{#unless errors.sentry}}
+import { Cache, Lock, Metrics, ProcessedEventStore, RateLimiter, UnitOfWork } from '@ddd-ts-kit/kernel';
+{{/unless}}
+{{/unless}}
+{{/if}}
+{{#unless cache.redis}}
+import { {{#if broker.external}}EventSubscribers, {{/if}}ProcessedEventStore, UnitOfWork{{#if errors.sentry}}, type ErrorReporter{{/if}} } from '@ddd-ts-kit/kernel';
+{{/unless}}
+{{#if persistence.packagedToken}}
+import { {{persistence.token}} } from '{{persistence.tokenPackage}}';
+{{/if}}
+{{#if persistence.ownDatabase}}
+import { Database } from '{{alias.platform}}/database/database.js';
+{{/if}}
+import type { ConsumerTrace } from '@ddd-ts-kit/tracing';
+import type { Persistence } from '{{alias.platform}}/database/persistence.js';
+import type { EventProvider } from '{{alias.platform}}/events/event-provider.js';
+import type { LogSettings } from '{{alias.platform}}/observability/create-logger.js';
+{{#if cache.redis}}
+import type { RedisServices } from '{{alias.platform}}/redis/open-redis.js';
+{{/if}}
+import { adapterAspects } from '{{alias.platform}}/resilience/adapter-aspects.js';
+import { defaultResilience } from '{{alias.platform}}/resilience/default-resilience.js';
+import type { ResilienceSettings } from '{{alias.platform}}/resilience/resilience-settings.js';
+{{#if style.declared}}
+// ddd-ts-kit:imports
+// /ddd-ts-kit:imports
+{{/if}}
+
+/** What the platform is built on, beyond the storage: chosen in `main.ts`, defaulted for the tools and the tests. */
+export interface PlatformOptions {
+  /** The provider integration events are delivered to: the broker in `main.ts`, the process itself for the tools and most tests. */
+  readonly events: EventProvider;
+  {{#if http.any}}
+  /** Who verifies the credential of a request: the real adapter in `main.ts`, a key of their own in the tests. */
+  readonly authenticator: Authenticator;
+  {{/if}}
+  /** Where log entries go; left out, the application writes nothing. */
+  readonly log?: LogSettings;
+  /** The policy around every adapter that leaves the process; left out, the defaults of `resilience/default-resilience.ts`. */
+  readonly resilience?: ResilienceSettings;
+  /** Whether a consumed event continues the trace of its publication (the default) or starts one linked to it. */
+  readonly traceConsumers?: ConsumerTrace;
+  {{#if errors.sentry}}
+  /** Where unexpected failures are reported: the reporter of `errors.ts` in `main.ts`; left out (the tools, the tests), nowhere. */
+  readonly errors?: ErrorReporter;
+  {{/if}}
+  {{#if cache.redis}}
+  /** The Redis protocol server; left out, the cache, the lock and the limiter stay in the memory of the process. */
+  readonly redis?: RedisServices;
+  {{/if}}
+}
+
+/**
+ * What this platform puts in place of the in-process defaults of the kernel module: the storage
+ * and whatever else `main.ts` opened for it. Replacing a provider happens here and nowhere else.
+ */
+export function platformModule(persistence: Persistence, options: PlatformOptions): ContextModule {
+  return defineContextModule({
+    name: 'platform',
+    // Closed inside `stop()` of the application, after the jobs and the consumers and before the logger is flushed.
+    onStop: () => options.events.close(),
+    register(builder) {
+      builder.rebind(UnitOfWork).toValue(persistence.unitOfWork);
+      builder.rebind(ProcessedEventStore).toValue(persistence.processedEvents);
+      {{#if persistence.hasDatabase}}
+      builder.bind({{persistence.token}}).toValue(persistence.database);
+      {{/if}}
+      {{#if events.outbox}}
+      builder.bind(OutboxStore).toValue(persistence.outbox);
+      {{/if}}
+      {{#if broker.external}}
+      builder.rebind(EventSubscribers).toValue({ forContext: (name) => options.events.forConsumer(name) });
+      {{/if}}
+      {{#if http.any}}
+      builder.bind(ErrorMapper).toValue(createErrorMapper());
+      {{/if}}
+      // Cross-cutting behaviour stays out of the contexts. Inside the span and the dispatch the kernel module puts around a binding, outside the aspects a binding states for itself (`ownPolicy`).
+      builder.around(['external', 'gateway'], () => adapterAspects(options.resilience ?? defaultResilience));
+      {{#if cache.redis}}
+
+      if (options.redis !== undefined) {
+        bindRedis(builder, options.redis);
+      }
+      {{/if}}
+      {{#if style.declared}}
+      {{#if cache.redis}}
+
+      {{/if}}
+      // ddd-ts-kit:bindings
+      // /ddd-ts-kit:bindings
+      {{/if}}
+    },
+  });
+}
+{{#if cache.redis}}
+
+/** One server for the cache, the limiter in front of HTTP and the lock that keeps a scheduled job to one instance. */
+function bindRedis(builder: ModuleBuilder, redis: RedisServices): void {
+  builder.rebind(Cache).toFactory((resolve) => redis.cache(resolve(Metrics)));
+  builder.rebind(RateLimiter).toValue(redis.rateLimiter);
+  builder.rebind(Lock).toValue(redis.lock);
+}
+{{/if}}

package/templates/init/platform/redis/open-redis.ts.tpl

@@ -0,0 +1,70 @@
+import type { Cache, Lock, Metrics, RateLimiter } from '@ddd-ts-kit/kernel';
+{{#if cache.relaySignal}}
+import {
+  RedisCache,
+  RedisLock,
+  RedisRateLimiter,
+  RedisRelaySignal,
+  connectRedis,
+  redisHealth,
+} from '@ddd-ts-kit/redis';
+{{/if}}
+{{#unless cache.relaySignal}}
+import { RedisCache, RedisLock, RedisRateLimiter, connectRedis, redisHealth } from '@ddd-ts-kit/redis';
+{{/unless}}
+
+/**
+ * What the platform puts on one connection to a Redis protocol server. The adapters use a common
+ * subset of the protocol: Redis, Dragonfly and Valkey are interchangeable behind `REDIS_URL`.
+ */
+export interface RedisServices {
+  /** The kernel `Cache` port. A server that is away costs a miss, never an exception: watch `cache_errors_total`. */
+  cache(metrics: Metrics): Cache;
+
+  /** Counts across every instance of the service. */
+  readonly rateLimiter: RateLimiter;
+  /** Excludes between processes: what keeps an occurrence of a scheduled job to one instance, best effort. */
+  readonly lock: Lock;
+  {{#if cache.relaySignal}}
+  /** Wakes the outbox relay of every instance as soon as a command committed; the polling interval stays as the safety net. */
+  readonly relaySignal: RedisRelaySignal;
+  {{/if}}
+
+  /** One `PING` answered in time: for the readiness probe. */
+  ready(): Promise<boolean>;
+
+  close(): Promise<void>;
+}
+
+interface RedisSettings {
+  readonly redisUrl: string;
+  /** Prefix of every key, so that several services share one server. */
+  readonly serviceName: string;
+}
+
+export function openRedis({ redisUrl, serviceName }: RedisSettings): RedisServices {
+  const connection = connectRedis(redisUrl);
+  {{#if cache.relaySignal}}
+  const relaySignal = new RedisRelaySignal(connection.client, { channel: serviceName + ':outbox' });
+  {{/if}}
+
+  return {
+    cache: (metrics) => new RedisCache(connection.client, { namespace: serviceName, metrics }),
+    // While the server is away the API keeps serving, without a limit: a limiter must not take the application down.
+    rateLimiter: new RedisRateLimiter(connection.client, { namespace: serviceName + ':rate', onError: 'allow' }),
+    lock: new RedisLock(connection.client, { namespace: serviceName + ':lock' }),
+    {{#if cache.relaySignal}}
+    relaySignal,
+    {{/if}}
+    ready: async () => (await redisHealth(connection.client)).status === 'up',
+    {{#if cache.relaySignal}}
+    close: async () => {
+      await relaySignal.close();
+      await connection.close();
+    },
+    {{/if}}
+    {{#unless cache.relaySignal}}
+    close: () => connection.close(),
+    {{/unless}}
+  };
+}

package/templates/init/platform/resilience/adapter-aspects.ts.tpl

@@ -0,0 +1,17 @@
+import { forKinds, retry, timeout, when, type Aspect } from '@ddd-ts-kit/aspects';
+import type { ResilienceSettings } from '{{alias.platform}}/resilience/resilience-settings.js';
+import { selfGoverned } from '{{alias.platform}}/resilience/self-governed.js';
+
+/**
+ * What goes around every adapter that leaves the process (`external`, `gateway`) and states no
+ * policy of its own: retries with backoff, and a time limit for each attempt.
+ */
+export function adapterAspects(settings: ResilienceSettings): Aspect {
+  const byDefault = when(
+    forKinds('external', 'gateway'),
+    retry({ attempts: settings.retryAttempts, backoff: { baseMs: settings.retryBaseDelayMs } }),
+    timeout(settings.timeoutMs),
+  );
+
+  return (instance, info) => (selfGoverned.has(instance) ? instance : byDefault(instance, info));
+}

package/templates/init/platform/resilience/default-resilience.ts.tpl

@@ -0,0 +1,4 @@
+import type { ResilienceSettings } from '{{alias.platform}}/resilience/resilience-settings.js';
+
+/** What the tools and the tests run with; `main.ts` gives the validated values of the configuration. */
+export const defaultResilience: ResilienceSettings = { retryAttempts: 3, retryBaseDelayMs: 100, timeoutMs: 2000 };

package/templates/init/platform/resilience/own-policy.ts.tpl

@@ -0,0 +1,20 @@
+import { compose, type Aspect } from '@ddd-ts-kit/aspects';
+import { selfGoverned } from '{{alias.platform}}/resilience/self-governed.js';
+
+/**
+ * The policy one adapter states for itself, in place of the default one:
+ * `.with(ownPolicy(retry({ attempts: 5 }), timeout(500)))`. Without argument it says that the
+ * class already carries its policy as decorators of `@ddd-ts-kit/aspects/decorators`; either
+ * way the same aspect never runs twice.
+ */
+export function ownPolicy(...policy: readonly Aspect[]): Aspect {
+  const stated = compose(...policy);
+
+  return (instance, info) => {
+    const governed = stated(instance, info);
+
+    selfGoverned.add(governed);
+
+    return governed;
+  };
+}

package/templates/init/platform/resilience/resilience-settings.ts.tpl

@@ -0,0 +1,6 @@
+/** How often an outbound call is tried again, from which delay, and how long one attempt may last. */
+export interface ResilienceSettings {
+  readonly retryAttempts: number;
+  readonly retryBaseDelayMs: number;
+  readonly timeoutMs: number;
+}

package/templates/init/platform/resilience/self-governed.ts.tpl

@@ -0,0 +1,2 @@
+/** The adapters that state their own policy with `ownPolicy`: the default one leaves them alone. */
+export const selfGoverned = new WeakSet<object>();

package/templates/init/platform/tracing.ts.tpl

@@ -0,0 +1,19 @@
+import { initTracing } from '@ddd-ts-kit/tracing/node';
+import { ConfigError } from '{{alias.platform}}/config/config-error.js';
+import { readTracing } from '{{alias.platform}}/config/read-tracing.js';
+
+// Evaluated before the rest of the application (see main.ts): it validates the variables of its
+// own and reads the two names directly, so that no module an instrumentation patches is loaded
+// before it. The OTLP endpoint is read by the exporter itself, from the standard variable.
+const problems: string[] = [];
+const settings = readTracing(process.env, problems);
+
+if (problems.length > 0) {
+  throw new ConfigError(problems);
+}
+
+export const tracing = initTracing({
+  serviceName: process.env['OTEL_SERVICE_NAME'] ?? '{{project.name}}',
+  environment: process.env['NODE_ENV'] ?? 'development',
+  ...(settings.sampleRatio === undefined ? {} : { sampleRatio: settings.sampleRatio }),
+});