ddd-ts-kit 0.0.0-stage → 0.1.1

package/templates/init/platform/compose-application.tsyringe.ts.tpl

@@ -0,0 +1,267 @@
+import { installAspectRuntime } from '@ddd-ts-kit/aspects';
+{{#if http.any}}
+import { Authenticator } from '@ddd-ts-kit/auth';
+{{/if}}
+import {
+  createApplication,
+  kernelModule,
+  type Application as Container,
+  type ContextModule,
+  type JobsOptions,
+} from '@ddd-ts-kit/di';
+{{#if events.outbox}}
+import { OutboxPublisher } from '@ddd-ts-kit/events';
+{{/if}}
+{{#if http.any}}
+import { ErrorMapper, defineRoutes, type Route } from '@ddd-ts-kit/http';
+{{/if}}
+import {
+  Cache,
+  Clock,
+{{#if http.any}}
+  CommandBus,
+{{/if}}
+{{#if errors.sentry}}
+{{#if http.any}}
+  ErrorReporter,
+{{/if}}
+{{/if}}
+  EventBus,
+{{#if http.any}}
+  ExecutionScope,
+{{/if}}
+{{#unless broker.external}}
+  IntegrationEventSubscriber,
+{{/unless}}
+  Logger,
+  Metrics,
+{{#if http.any}}
+  QueryBus,
+{{/if}}
+{{#if cache.rateLimit}}
+  RateLimiter,
+{{/if}}
+  scopedPublisher,
+  type IntegrationEventPublisher,
+{{#if broker.external}}
+  type IntegrationEventSubscriber,
+{{/if}}
+} from '@ddd-ts-kit/kernel';
+import { tracedPublisher } from '@ddd-ts-kit/tracing';
+{{#if audit.on}}
+import { auditModule } from '{{alias.platform}}/audit/audit.module.js';
+{{/if}}
+{{#if audit.route}}
+import { searchAuditEntriesRoute } from '{{alias.platform}}/audit/search-audit-entries.route.js';
+{{/if}}
+import { authorization } from '{{alias.platform}}/auth/authorization.js';
+{{#if http.any}}
+import { httpBoundary, type HttpBoundary } from '{{alias.platform}}/auth/http-boundary.js';
+{{/if}}
+{{#if authz.rebac}}
+import { relateSystemActors } from '{{alias.platform}}/auth/relate-system-actors.js';
+{{/if}}
+import { createCommandBus } from '{{alias.platform}}/buses/create-command-bus.js';
+import { createQueryBus } from '{{alias.platform}}/buses/create-query-bus.js';
+import type { Persistence } from '{{alias.platform}}/database/persistence.js';
+import { layFoundations, type Foundations } from '{{alias.platform}}/lay-foundations.js';
+import { platformModule, type PlatformOptions } from '{{alias.platform}}/platform.module.js';
+// ddd-ts-kit:imports
+// /ddd-ts-kit:imports
+
+export interface ApplicationOptions extends PlatformOptions {
+  /** Whether this process runs the scheduled jobs, and their settings; left out (the tools, the tests), no job runs by time. */
+  readonly jobs?: JobsOptions;
+}
+
+export interface Application {
+{{#if http.any}}
+  readonly routes: readonly Route[];
+  /** Authenticates every request and runs it inside the execution scope. */
+  readonly boundary: HttpBoundary;
+{{/if}}
+{{#unless http.any}}
+  readonly routes: readonly never[];
+{{/unless}}
+  /** The provider integration events are delivered to. */
+  readonly eventBus: IntegrationEventPublisher;
+  /** Where another context, or a test, listens to what this application publishes. */
+  readonly eventSubscriber: IntegrationEventSubscriber;
+  readonly logger: Logger;
+{{#if cache.rateLimit}}
+  /** What the HTTP server asks before anything else: on the Redis protocol server, or in the memory of the process without one. */
+  readonly rateLimiter: RateLimiter;
+{{/if}}
+{{#if cache.redis}}
+
+  /** Whether what the application depends on answers: the readiness probe of the HTTP server. */
+  ready(): Promise<boolean>;
+
+{{/if}}
+  readonly container: Container;
+
+  start(): Promise<void>;
+
+  stop(): Promise<void>;
+}
+
+/** The contexts an application hosts: all of them here, one alone in `apps/<context>/main.ts`. */
+export interface ContextSelection {
+  readonly modules: readonly ContextModule[];
+{{#if http.any}}
+  /** The routes of each context, given the two buses they call. */
+  readonly routes: readonly ((commands: CommandBus, queries: QueryBus) => readonly Route[])[];
+{{/if}}
+}
+
+const everyContext: ContextSelection = {
+  modules: [
+    // ddd-ts-kit:contexts
+    // /ddd-ts-kit:contexts
+  ],
+{{#if http.any}}
+  routes: [
+    // ddd-ts-kit:routes
+    // /ddd-ts-kit:routes
+  ],
+{{/if}}
+};
+
+/** Wires the bounded contexts on the kernel and the platform. Also used to generate the contracts and by the end-to-end tests. */
+export function composeApplication(
+  persistence: Persistence,
+  options: ApplicationOptions,
+  contexts: ContextSelection = everyContext,
+): Application {
+  const foundations = layFoundations(persistence, options);
+{{#if audit.on}}
+  const guard = authorization(foundations.audit.decisions{{#if http.any}}, options.authenticator{{/if}});
+{{/if}}
+{{#unless audit.on}}
+  const guard = authorization(foundations.decisions{{#if http.any}}, options.authenticator{{/if}});
+{{/unless}}
+
+  const container = createApplication({
+    modules: [
+      kernel(foundations, persistence, options),
+      platformModule(persistence, options),
+      guard,
+{{#if audit.on}}
+      auditModule(foundations.audit),
+{{/if}}
+      ...contexts.modules,
+    ],
+    authorization: 'required',
+    jobs: options.jobs ?? { start: false },
+  });
+
+  installAspectRuntime({
+    logger: container.resolve(Logger),
+    metrics: container.resolve(Metrics),
+    cache: container.resolve(Cache),
+    clock: container.resolve(Clock),
+  });
+
+  return running(container, options, contexts);
+}
+
+/**
+ * The ports of the kernel on what this platform chose: one execution scope, one clock and one
+ * generator for the buses, the logger and every adapter. The instrumentation observes the
+ * application from outside (one span per use case, repository call, domain event, publication,
+ * consumer and job), so what it must see is given here: a port rebound by a later module is
+ * not wrapped.
+ */
+function kernel(foundations: Foundations, persistence: Persistence, options: ApplicationOptions): ContextModule {
+  const { scope, clock, ids, logger, metrics } = foundations;
+  const { bus } = options.events;
+
+  return kernelModule({
+    instrumentation: foundations.traced,
+    clock,
+    ids,
+    executionScope: scope,
+    logger,
+    metrics,
+    eventBus: bus,
+{{#if events.outbox}}
+    // Use cases publish to the outbox, in the transaction of their command; the relay of `main.ts` delivers to the provider.
+    eventPublisher: scopedPublisher(new OutboxPublisher(persistence.outbox), scope),
+{{/if}}
+{{#unless events.outbox}}
+    eventPublisher: scopedPublisher(bus, scope),
+{{/unless}}
+    eventSubscriber: bus,
+{{#if errors.sentry}}
+    // The buses and the jobs report through it, and `container.stop()` flushes it; left out (the tools, the tests), nothing is reported.
+    ...(options.errors === undefined ? {} : { errorReporter: options.errors }),
+{{/if}}
+{{#if cache.relaySignal}}
+    commandBus: (resolve) => createCommandBus(resolve, foundations, options),
+{{/if}}
+{{#unless cache.relaySignal}}
+    commandBus: (resolve) => createCommandBus(resolve, foundations),
+{{/unless}}
+    queryBus: (resolve) => createQueryBus(resolve, foundations),
+  });
+}
+
+function running(container: Container, options: ApplicationOptions, contexts: ContextSelection): Application {
+  const logger = container.resolve(Logger);
+
+  return {
+{{#if http.any}}
+    routes: routesOf(container, contexts),
+    boundary: httpBoundary({
+      authenticator: container.resolve(Authenticator),
+      executionScope: container.resolve(ExecutionScope),
+      errorMapper: container.resolve(ErrorMapper),
+      clock: container.resolve(Clock),
+      logger,
+{{#if errors.sentry}}
+      errors: container.resolve(ErrorReporter),
+{{/if}}
+    }),
+{{/if}}
+{{#unless http.any}}
+    routes: [],
+{{/unless}}
+    // What the outbox relay delivers with: each publication continues the trace stored with its event.
+    eventBus: tracedPublisher(container.resolve(EventBus)),
+{{#if broker.external}}
+    // Behind a broker a listener has queues of its own, under its own name.
+    eventSubscriber: options.events.forConsumer('observer'),
+{{/if}}
+{{#unless broker.external}}
+    eventSubscriber: container.resolve(IntegrationEventSubscriber),
+{{/unless}}
+    logger,
+{{#if cache.rateLimit}}
+    rateLimiter: container.resolve(RateLimiter),
+{{/if}}
+{{#if cache.redis}}
+    ready: () => options.redis?.ready() ?? Promise.resolve(true),
+{{/if}}
+    container,
+{{#if authz.rebac}}
+    start: () =>
+      relateSystemActors()
+        .then(() => container.start())
+        .then(() => options.events.start()),
+{{/if}}
+{{#unless authz.rebac}}
+    start: () => container.start().then(() => options.events.start()),
+{{/unless}}
+    // The jobs, the consumers, the event provider (`onStop` of the platform module), then the error reporter and, last, the logger: whatever logs has closed before its final flush.
+    stop: () => container.stop(),
+  };
+}
+{{#if http.any}}
+
+function routesOf(container: Container, contexts: ContextSelection): readonly Route[] {
+  const commands = container.resolve(CommandBus);
+  const queries = container.resolve(QueryBus);
+
+  return defineRoutes(...contexts.routes.map((routes) => routes(commands, queries)){{#if audit.route}}, [searchAuditEntriesRoute(queries)]{{/if}});
+}
+{{/if}}

package/templates/init/platform/config/app-config.ts.tpl

@@ -0,0 +1,97 @@
+{{#if cache.rateLimit}}
+import type { LogLevel, RateLimit } from '@ddd-ts-kit/kernel';
+{{/if}}
+{{#unless cache.rateLimit}}
+import type { LogLevel } from '@ddd-ts-kit/kernel';
+{{/unless}}
+import type { ResilienceSettings } from '{{alias.platform}}/resilience/resilience-settings.js';
+import type { TracingConfig } from '{{alias.platform}}/config/read-tracing.js';
+
+/** The validated configuration of the process: `loadConfig` is the only reader of the environment. */
+export interface AppConfig {
+  readonly serviceName: string;
+  readonly serviceVersion: string;
+  readonly environment: 'development' | 'test' | 'production';
+  readonly port: number;
+  readonly log: LogConfig;
+  /** What `tracing.ts` starts with, and whether a consumed event continues the trace of its publication. */
+  readonly tracing: TracingConfig;
+  /** The policy around every adapter that leaves the process (kinds `external` and `gateway`). */
+  readonly resilience: ResilienceSettings;
+  /** Whether this process runs the scheduled jobs (`RUN_JOBS`): off for the API of a project that has a worker. */
+  readonly runJobs: boolean;
+  {{#if persistence.needsUrl}}
+  readonly databaseUrl: string;
+  {{/if}}
+  {{#if events.outbox}}
+  readonly outboxRelayIntervalMs: number;
+  {{/if}}
+  {{#if docs.any}}
+  readonly docsEnabled: boolean;
+  {{/if}}
+  {{#if authn.jwt}}
+  readonly auth: AuthConfig;
+  {{/if}}
+  {{#if authn.keycloak}}
+  readonly keycloak: KeycloakConfig;
+  {{/if}}
+  {{#if broker.addressed}}
+  readonly {{broker.key}}: string;
+  {{/if}}
+  {{#if redis.server}}
+  readonly redisUrl: string;
+  {{/if}}
+  {{#if cache.rateLimit}}
+  /** How many requests one caller address may send in a sliding window, before the HTTP layer answers 429. */
+  readonly rateLimit: RateLimit;
+  {{/if}}
+  {{#if errors.sentry}}
+  /** Where unexpected failures are reported: a Sentry or a GlitchTip project. Without a DSN nothing is reported. */
+  readonly errorReporting: ErrorReportingConfig;
+  {{/if}}
+}
+
+/** `LOG_LEVEL`, `LOG_FORMAT` and `LOG_SCRUB_MESSAGES`. */
+interface LogConfig {
+  readonly level: LogLevel;
+  {{#if logger.stdout}}
+  /** One JSON line per entry: this logger has no pretty format (`init --logger pino` or `winston` brings one). */
+  readonly format: 'json';
+  {{/if}}
+  {{#unless logger.stdout}}
+  /** `json` everywhere; `pretty` on a developer's machine only. */
+  readonly format: 'json' | 'pretty';
+  {{/unless}}
+  /** Writes `[message removed]` for the message of every logged error that is not a `DomainError`: for logs that leave your hands. */
+  readonly scrubMessages: boolean;
+}
+{{#if errors.sentry}}
+
+/** What `initSentry` is given: `SENTRY_DSN`, `SENTRY_ENVIRONMENT` (the one of `NODE_ENV` when left out), `SENTRY_RELEASE` and `SENTRY_SCRUB_MESSAGES`. */
+interface ErrorReportingConfig {
+  readonly dsn?: string;
+  readonly environment: string;
+  readonly release?: string;
+  /** Removes the message of every reported error that is not a `DomainError`: for a tracker hosted by a third party. */
+  readonly scrubMessages: boolean;
+}
+{{/if}}
+{{#if authn.keycloak}}
+
+/** The realm tokens come from, and the audience this service answers to; the client id adds its client roles to the realm roles. */
+interface KeycloakConfig {
+  readonly baseUrl: string;
+  readonly realm: string;
+  readonly audience: string;
+  readonly clientId?: string;
+}
+{{/if}}
+{{#if authn.jwt}}
+
+/** Where tokens come from and whom they are for: the issuer, the audience this service answers to, the keys of the issuer. */
+interface AuthConfig {
+  readonly issuer: string;
+  readonly audience: string;
+  readonly jwksUri: string;
+}
+{{/if}}

package/templates/init/platform/config/config-error.ts.tpl

@@ -0,0 +1,7 @@
+/** Every problem of the environment at once, by variable name only: values may be secrets. */
+export class ConfigError extends Error {
+  constructor(readonly problems: readonly string[]) {
+    super('Invalid configuration: ' + problems.join('; '));
+    this.name = 'ConfigError';
+  }
+}

package/templates/init/platform/config/load-config.ts.tpl

@@ -0,0 +1,253 @@
+import { LOG_LEVELS, type LogLevel } from '@ddd-ts-kit/kernel';
+import type { AppConfig } from '{{alias.platform}}/config/app-config.js';
+import { ConfigError } from '{{alias.platform}}/config/config-error.js';
+import { readTracing } from '{{alias.platform}}/config/read-tracing.js';
+
+const environments = ['development', 'test', 'production'] as const;
+
+type Variables = Readonly<Record<string, string | undefined>>;
+
+/** Whether a process runs the scheduled jobs when `RUN_JOBS` does not say. `ddd-ts-kit generate worker` turns it off: the worker then runs them. */
+// ddd-ts-kit:run-jobs
+{{#if worker.off}}
+const runJobsByDefault = true;
+{{/if}}
+{{#if worker.on}}
+const runJobsByDefault = false;
+{{/if}}
+// /ddd-ts-kit:run-jobs
+
+/**
+ * Fails fast: every problem is collected and reported at once, by variable name only
+ * (values may be secrets), before anything starts listening.
+ */
+export function loadConfig(env: Variables): AppConfig {
+  const problems: string[] = [];
+  const environment = readEnvironment(env, problems);
+
+  const config: AppConfig = {
+    serviceName: env['OTEL_SERVICE_NAME'] ?? '{{project.name}}',
+    serviceVersion: env['SERVICE_VERSION'] ?? '0.0.0',
+    environment,
+    port: readInteger(env, { name: 'PORT', fallback: 3000, min: 0, max: 65535 }, problems),
+    log: readLog(env, problems),
+    tracing: readTracing(env, problems),
+    resilience: readResilience(env, problems),
+    runJobs: readFlag(env, { name: 'RUN_JOBS', fallback: runJobsByDefault }, problems),
+    {{#if persistence.needsUrl}}
+    databaseUrl: readUrl(env, 'DATABASE_URL', problems),
+    {{/if}}
+    {{#if events.outbox}}
+    outboxRelayIntervalMs: readInteger(
+      env,
+      { name: 'OUTBOX_RELAY_INTERVAL_MS', fallback: 500, min: 10, max: 60000 },
+      problems,
+    ),
+    {{/if}}
+    {{#if docs.any}}
+    docsEnabled: readFlag(env, { name: 'API_DOCS', fallback: environment !== 'production' }, problems),
+    {{/if}}
+    {{#if broker.addressed}}
+    {{broker.key}}: {{broker.reader}}(env, '{{broker.variable}}', problems),
+    {{/if}}
+    {{#if authn.jwt}}
+    auth: readAuth(env, problems),
+    {{/if}}
+    {{#if authn.keycloak}}
+    keycloak: readKeycloak(env, problems),
+    {{/if}}
+    {{#if redis.server}}
+    redisUrl: readUrl(env, 'REDIS_URL', problems),
+    {{/if}}
+    {{#if cache.rateLimit}}
+    rateLimit: readRateLimit(env, problems),
+    {{/if}}
+    {{#if errors.sentry}}
+    errorReporting: readErrorReporting(env, environment, problems),
+    {{/if}}
+  };
+
+  if (problems.length > 0) {
+    throw new ConfigError(problems);
+  }
+
+  return config;
+}
+
+function readEnvironment(env: Variables, problems: string[]): AppConfig['environment'] {
+  const raw = env['NODE_ENV'] ?? 'development';
+  const environment = environments.find((candidate) => candidate === raw);
+
+  if (environment === undefined) {
+    problems.push('NODE_ENV must be one of ' + environments.join(', '));
+  }
+
+  return environment ?? 'development';
+}
+
+function readLog(env: Variables, problems: string[]): AppConfig['log'] {
+  return {
+    level: readLogLevel(env, problems),
+    format: readLogFormat(env, problems),
+    scrubMessages: readFlag(env, { name: 'LOG_SCRUB_MESSAGES', fallback: false }, problems),
+  };
+}
+
+function readLogLevel(env: Variables, problems: string[]): LogLevel {
+  const raw = env['LOG_LEVEL'] ?? 'info';
+  const level = LOG_LEVELS.find((candidate) => candidate === raw);
+
+  if (level === undefined) {
+    problems.push('LOG_LEVEL must be one of ' + LOG_LEVELS.join(', '));
+  }
+
+  return level ?? 'info';
+}
+
+function readLogFormat(env: Variables, problems: string[]): AppConfig['log']['format'] {
+  const raw = env['LOG_FORMAT'] ?? 'json';
+
+  {{#if logger.stdout}}
+  if (raw !== 'json') {
+    problems.push('LOG_FORMAT must be json: the stdout logger has no pretty format');
+  }
+
+  return 'json';
+  {{/if}}
+  {{#unless logger.stdout}}
+  if (raw !== 'json' && raw !== 'pretty') {
+    problems.push('LOG_FORMAT must be json or pretty');
+  }
+
+  return raw === 'pretty' ? 'pretty' : 'json';
+  {{/unless}}
+}
+
+function readResilience(env: Variables, problems: string[]): AppConfig['resilience'] {
+  return {
+    retryAttempts: readInteger(env, { name: 'OUTBOUND_RETRY_ATTEMPTS', fallback: 3, min: 1, max: 10 }, problems),
+    retryBaseDelayMs: readInteger(
+      env,
+      { name: 'OUTBOUND_RETRY_BASE_DELAY_MS', fallback: 100, min: 1, max: 60000 },
+      problems,
+    ),
+    timeoutMs: readInteger(env, { name: 'OUTBOUND_TIMEOUT_MS', fallback: 2000, min: 1, max: 600000 }, problems),
+  };
+}
+{{#if cache.rateLimit}}
+
+function readRateLimit(env: Variables, problems: string[]): AppConfig['rateLimit'] {
+  return {
+    limit: readInteger(env, { name: 'RATE_LIMIT_MAX', fallback: 120, min: 1, max: 1000000 }, problems),
+    windowMs: readInteger(env, { name: 'RATE_LIMIT_WINDOW_MS', fallback: 60000, min: 100, max: 3600000 }, problems),
+  };
+}
+{{/if}}
+{{#if errors.sentry}}
+
+/** An empty `SENTRY_DSN` is a choice, not a problem: the application starts and reports nothing. */
+function readErrorReporting(env: Variables, environment: string, problems: string[]): AppConfig['errorReporting'] {
+  const dsn = (env['SENTRY_DSN'] ?? '').trim();
+  const named = (env['SENTRY_ENVIRONMENT'] ?? '').trim();
+  const release = (env['SENTRY_RELEASE'] ?? '').trim();
+
+  if (dsn !== '' && !URL.canParse(dsn)) {
+    problems.push('SENTRY_DSN must be a URL, or empty to report nothing');
+  }
+
+  return {
+    ...(dsn === '' ? {} : { dsn }),
+    environment: named === '' ? environment : named,
+    ...(release === '' ? {} : { release }),
+    scrubMessages: readFlag(env, { name: 'SENTRY_SCRUB_MESSAGES', fallback: false }, problems),
+  };
+}
+{{/if}}
+{{#if authn.jwt}}
+
+function readAuth(env: Variables, problems: string[]): AppConfig['auth'] {
+  return {
+    issuer: readUrl(env, 'AUTH_ISSUER', problems),
+    audience: readText(env, 'AUTH_AUDIENCE', problems),
+    jwksUri: readUrl(env, 'AUTH_JWKS_URI', problems),
+  };
+}
+{{/if}}
+{{#if authn.keycloak}}
+
+function readKeycloak(env: Variables, problems: string[]): AppConfig['keycloak'] {
+  const clientId = env['KEYCLOAK_CLIENT_ID'] ?? '';
+
+  return {
+    baseUrl: readUrl(env, 'KEYCLOAK_URL', problems),
+    realm: readText(env, 'KEYCLOAK_REALM', problems),
+    audience: readText(env, 'KEYCLOAK_AUDIENCE', problems),
+    ...(clientId.trim() === '' ? {} : { clientId }),
+  };
+}
+{{/if}}
+
+interface IntegerVariable {
+  readonly name: string;
+  readonly fallback: number;
+  readonly min: number;
+  readonly max: number;
+}
+
+function readInteger(env: Variables, variable: IntegerVariable, problems: string[]): number {
+  const raw = env[variable.name];
+  const value = raw === undefined || raw === '' ? variable.fallback : Number(raw);
+
+  if (!Number.isInteger(value) || value < variable.min || value > variable.max) {
+    problems.push(variable.name + ' must be an integer between ' + variable.min + ' and ' + variable.max);
+  }
+
+  return value;
+}
+
+interface FlagVariable {
+  readonly name: string;
+  readonly fallback: boolean;
+}
+
+const flags: Readonly<Record<string, boolean>> = { true: true, '1': true, false: false, '0': false };
+
+function readFlag(env: Variables, variable: FlagVariable, problems: string[]): boolean {
+  const raw = env[variable.name];
+
+  if (raw === undefined || raw === '') {
+    return variable.fallback;
+  }
+
+  const value = flags[raw];
+
+  if (value === undefined) {
+    problems.push(variable.name + ' must be true or false');
+  }
+
+  return value ?? variable.fallback;
+}
+{{#if needs.url}}
+
+function readUrl(env: Variables, name: string, problems: string[]): string {
+  const raw = env[name] ?? '';
+
+  if (!URL.canParse(raw)) {
+    problems.push(name + ' must be a URL');
+  }
+
+  return raw;
+}
+{{/if}}
+{{#if needs.text}}
+
+function readText(env: Variables, name: string, problems: string[]): string {
+  const raw = env[name] ?? '';
+
+  if (raw.trim() === '') {
+    problems.push(name + ' must be set');
+  }
+
+  return raw;
+}
+{{/if}}

package/templates/init/platform/config/read-tracing.ts.tpl

@@ -0,0 +1,53 @@
+type Variables = Readonly<Record<string, string | undefined>>;
+
+const consumerModes = ['continue', 'link'] as const;
+
+/** What `tracing.ts` starts with and what the composition root traces by. Nothing is imported here: `tracing.ts` reads it before any other module is loaded. */
+export interface TracingConfig {
+  /** `OTEL_EXPORTER_OTLP_ENDPOINT`, read by the exporter itself: left out, no span leaves the process. */
+  readonly endpoint?: string;
+  /** `TRACE_SAMPLE_RATIO`, the share of traces kept, decided where a trace starts. Left out, the standard `OTEL_TRACES_SAMPLER` variables apply and by default every trace is kept. */
+  readonly sampleRatio?: number;
+  /** `TRACE_CONSUMERS`: `continue`, a consumed event stays in the trace of the request that published it; `link`, each delivery starts a trace linked to it. */
+  readonly consumers: (typeof consumerModes)[number];
+}
+
+/** Collects every problem by variable name, like `loadConfig`. */
+export function readTracing(env: Variables, problems: string[]): TracingConfig {
+  const endpoint = (env['OTEL_EXPORTER_OTLP_ENDPOINT'] ?? '').trim();
+  const sampleRatio = readRatio(env['TRACE_SAMPLE_RATIO'], problems);
+
+  if (endpoint !== '' && !URL.canParse(endpoint)) {
+    problems.push('OTEL_EXPORTER_OTLP_ENDPOINT must be a URL, or empty to export nothing');
+  }
+
+  return {
+    ...(endpoint === '' ? {} : { endpoint }),
+    ...(sampleRatio === undefined ? {} : { sampleRatio }),
+    consumers: readConsumers(env['TRACE_CONSUMERS'], problems),
+  };
+}
+
+function readRatio(raw: string | undefined, problems: string[]): number | undefined {
+  if (raw === undefined || raw.trim() === '') {
+    return undefined;
+  }
+
+  const ratio = Number(raw);
+
+  if (Number.isNaN(ratio) || ratio < 0 || ratio > 1) {
+    problems.push('TRACE_SAMPLE_RATIO must be a number between 0 and 1');
+  }
+
+  return ratio;
+}
+
+function readConsumers(raw: string | undefined, problems: string[]): TracingConfig['consumers'] {
+  const mode = consumerModes.find((candidate) => candidate === (raw ?? 'continue'));
+
+  if (mode === undefined) {
+    problems.push('TRACE_CONSUMERS must be one of ' + consumerModes.join(', '));
+  }
+
+  return mode ?? 'continue';
+}