@dunx/create-app 2.4.0 → 3.0.0

package/templates/features/database/ledger.service.ts

@@ -16,12 +16,9 @@ import { ledger, type Entry } from './schema.js';
 
 export class Ledger implements OnInit, OnShutdown {
   /**
-   * `SyncDatabase` is drizzle's `BunSQLiteDatabase` under a name that says the
-   * connection was opened in synchronous mode - which is what makes
-   * `transactionSync` below reachable. `@dunx/transform` records the bare type name
-   * (a real runtime class, so a usable token) and ignores the type argument, so the
-   * schema types survive injection. `DbConnection` is the lifecycle and the driver
-   * underneath; drizzle has neither.
+   * `SyncDatabase` is `BunSQLiteDatabase` under a name saying the connection was
+   * opened in synchronous mode, which is what reaches `transactionSync` below.
+   * `DbConnection` carries the lifecycle and the driver; drizzle has neither.
    */
   constructor(
     private readonly db: SyncDatabase<typeof schema>,
@@ -29,13 +26,7 @@ export class Ledger implements OnInit, OnShutdown {
     private readonly logger: Logger,
   ) {}
 
-  /**
-   * Standing in for a migration rather than replacing one: schema changes are
-   * `drizzle-kit generate` plus drizzle-orm/bun-sqlite/migrator, which own the
-   * SQL, the journal and the snapshot folder. A `:memory:` database has nowhere
-   * to keep any of that, so the table is created here - and at `onInit`, so the
-   * routes below have somewhere to write before the first request arrives.
-   */
+  /** Standing in for a migration, which a `:memory:` database cannot keep. */
   async onInit(): Promise<void> {
     this.db.run(sql`CREATE TABLE IF NOT EXISTS ledger (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -55,17 +46,9 @@ export class Ledger implements OnInit, OnShutdown {
   }
 
   /**
-   * The same rows, paginated by cursor instead of by `limit`.
-   *
-   * Keyset rather than `OFFSET`, which is what makes it correct while rows are being
-   * written: a cursor names the last row seen, so an insert between two requests
-   * cannot shift a page and serve the same entry twice. This table has no timestamp,
-   * so `paginate` falls back to the primary key - `id` is unique on its own, so no
-   * tie-break column is needed.
-   *
-   * Synchronous, because `paginate`'s return type follows its `db`: a
-   * `drizzle-orm/bun-sqlite` handle answers `all()` rather than a promise, so this
-   * method needs no `async` and neither does its caller.
+   * Keyset rather than `OFFSET`: a cursor names the last row seen, so an insert
+   * between two requests cannot shift a page and serve an entry twice. No
+   * timestamp column here, so `paginate` falls back to the unique primary key.
    */
   page(options: PageOptions): Page<Entry> {
     return paginate<typeof ledger, Entry>({
@@ -107,11 +90,9 @@ export class Ledger implements OnInit, OnShutdown {
   }
 
   /**
-   * Both legs or neither. `transaction()` from `@dunx/infra/db`, not
-   * `db.transaction()`: drizzle's own on bun-sqlite delegates to `bun:sqlite`'s
-   * synchronous `transaction()`, which commits as soon as the callback returns its
-   * promise - so everything after the first `await` would run in autocommit. That
-   * is what makes the rollback below possible at all.
+   * `transaction()` from `@dunx/infra/db`, not `db.transaction()`: drizzle's own
+   * commits as soon as the callback returns its promise, so everything after the
+   * first `await` would run in autocommit.
    */
   transfer(
     from: string,
@@ -134,11 +115,8 @@ export class Ledger implements OnInit, OnShutdown {
   }
 
   /**
-   * The same two legs, with nothing to await. `transactionSync` is drizzle's own
-   * `db.transaction()` - correct here precisely because the callback cannot return
-   * a promise, which is the case its early commit breaks. The return type is
-   * `number`, not `Promise<number>`, so a controller calling this needs no `async`
-   * and the request never yields.
+   * The same two legs with nothing to await. `transactionSync` is drizzle's own
+   * `db.transaction()`, safe because the callback cannot return a promise.
    */
   transferSync(from: string, to: string, amount: number, fail = false): number {
     return transactionSync(this.db, (tx) => {
@@ -161,8 +139,7 @@ export class Ledger implements OnInit, OnShutdown {
         'table "ledger" created at onInit',
     );
 
-    // The escape hatch. `raw` is `unknown` on the base - the abstract class cannot
-    // promise either driver - and `instanceof` is what restores the concrete type.
+    // `raw` is `unknown` on the base, so `instanceof` restores the driver type.
     if (this.connection instanceof SqliteConnection) {
       logger.info(`raw driver -> bun:sqlite ${this.connection.raw.filename}`);
     }
@@ -195,10 +172,7 @@ export class Ledger implements OnInit, OnShutdown {
     await this.seeds();
   }
 
-  /**
-   * The same rollback with no promise anywhere - `transactionSync` throws where
-   * `transaction` rejects, so the recovery is `try`/`catch` rather than `.catch()`.
-   */
+  /** `transactionSync` throws where `transaction` rejects. */
   private rollsBackSynchronously(): void {
     const before = this.rows();
     try {
@@ -214,7 +188,6 @@ export class Ledger implements OnInit, OnShutdown {
     );
   }
 
-  /** The `await` inside is what proves the transaction is not autocommitting. */
   private async commits(): Promise<void> {
     const balance = await transaction(this.db, async (tx) => {
       tx.insert(ledger).values({ memo: 'refund', amount: 12 }).run();
@@ -246,9 +219,8 @@ export class Ledger implements OnInit, OnShutdown {
   }
 
   /**
-   * Seed *data*, which is the half `drizzle-kit` has no concept of. Numbered files
-   * in `seeds/`, each applied once and recorded in `dunx_seeds` - so this reports
-   * them journaled rather than applied, `onInit` having already run them.
+   * Seed data, the half `drizzle-kit` has no concept of. Numbered files in
+   * `seeds/`, applied once and recorded in `dunx_seeds`.
    */
   private async seeds(): Promise<void> {
     const dir = `${import.meta.dir}/seeds`;

package/templates/features/docs/docs.demo.ts

@@ -17,11 +17,8 @@ const documentAt = async (
 export class DocsDemo {
   constructor(private readonly logger: Logger) {}
 
-  /**
-   * The document is served by a controller in the same graph, so it goes through the
-   * same middleware and the same CORS as everything else - and describes the paths
-   * the app really mounted, `setGlobalPrefix('api')` included.
-   */
+  /** Served by a controller in the same graph, so it goes through the same
+   * middleware and describes the paths the app really mounted. */
   async demonstrate(app: HttpApp, url: string): Promise<void> {
     const { logger } = this;
     const [response, document] = await documentAt(url);
@@ -35,8 +32,6 @@ export class DocsDemo {
       `components/schemas: ${JSON.stringify(Object.keys(document.components.schemas))}`,
     );
 
-    // `.meta({ id: 'CreateUser' })` on the zod schema is what named this ref, and
-    // the $defs entry it referenced (`Tag`) came along with it.
     const create = document.paths['/api/users']?.post;
     logger.info(
       `POST /api/users requestBody -> ` +
@@ -48,9 +43,8 @@ export class DocsDemo {
       `POST /api/users 400 -> ` +
         JSON.stringify(create?.responses['400']?.content?.['application/json']),
     );
-    // `options.response` is the same contract as the request side, so a named
-    // response schema becomes a component and the operation $refs it. It is
-    // documentation only - nothing validates a response.
+    // A named response schema becomes a component the operation $refs. It is
+    // documentation only: nothing validates a response.
     const one = document.paths['/api/users/{id}']?.get;
     logger.info(
       `GET /api/users/{id} responses -> ` +
@@ -66,8 +60,7 @@ export class DocsDemo {
     const list = document.paths['/api/users']?.get;
     logger.info(`GET /api/users query -> ${JSON.stringify(list?.parameters)}`);
 
-    // The check that matters: a $ref that resolves to nothing renders as an empty
-    // box in every viewer and reports no error at all.
+    // A $ref resolving to nothing renders as an empty box and reports no error.
     logger.info(
       `unresolved $refs: ${danglingRefs(document).length}, warnings: ` +
         JSON.stringify(app.get(OpenApiExplorer).warnings),
@@ -81,14 +74,9 @@ export class DocsDemo {
     );
 
     /**
-     * **The page fetches, and this is the check that it only fetches from here.**
-     * The explorer used to be dunx's own bundle inlined into the page, so the
-     * assertion was that nothing was requested at all. It is now `swagger-ui-dist`,
-     * 3.7x the size gzipped, served as two assets - so the guarantee is narrower and
-     * has to be stated as what it is: same-origin only, no CDN.
-     *
-     * Script bodies are stripped first. Inside a `<script>` everything is text, so a
-     * `src=` in the boot script is not a resource.
+     * The page fetches two `swagger-ui-dist` assets, and the guarantee is that
+     * they are same-origin: no CDN. Script bodies are stripped first, since a
+     * `src=` inside a `<script>` is text rather than a resource.
      */
     const shell = html.replace(/(<script[^>]*>)[\s\S]*?(<\/script>)/g, '$1$2');
     const requested = [
@@ -102,9 +90,7 @@ export class DocsDemo {
         JSON.stringify(requested),
     );
 
-    // Every one of them has to actually answer, which is the half a unit test
-    // cannot show: these resolve out of the consumer's own swagger-ui-dist
-    // install, through this app's global prefix.
+    // Each has to answer, resolving out of the consumer's own install.
     for (const href of requested) {
       const asset = await fetch(new URL(href.replace(/^\//, ''), url));
       logger.info(
@@ -116,11 +102,8 @@ export class DocsDemo {
     }
   }
 
-  /**
-   * The guarded app, whose `AuthGuard` is global. Security in the document comes from
-   * the same `@Public()` and `@Roles()` metadata the guards read at runtime - there
-   * is no second annotation for the documentation to disagree with.
-   */
+  /** Security in the document comes from the same `@Public()` and `@Roles()`
+   * metadata the guards read at runtime. */
   async guarded(url: string): Promise<void> {
     const { logger } = this;
     const [, document] = await documentAt(url);
@@ -137,10 +120,8 @@ export class DocsDemo {
       `@Public() GET /api/reports/health -> security ${JSON.stringify(health?.security)}`,
     );
 
-    // The class-level @Roles('admin') is merged into every one of its routes, so it
-    // is documented on this one too - even though no RolesGuard reads it here. The
-    // document describes what the metadata declares; which guard enforces it is a
-    // separate decision, and one no generator can see.
+    // A class-level @Roles merges into every route, so it is documented here
+    // too. The document describes the metadata; enforcement is a separate call.
     const list = document.paths['/api/reports']?.get;
     logger.info(
       `class-level @Roles("admin") GET /api/reports -> security ` +

package/templates/features/health/health.module.ts

@@ -11,20 +11,16 @@ import { HealthDemo } from './health.demo.js';
 import { AppIndicators } from './indicators.js';
 
 /**
- * The indicators, in a module of their own for the reason `WorkspaceModule` is:
- * `HealthModule.forRootAsync` registers its provider in its own scope, so a factory
- * injecting `AppIndicators` has to name the module it comes from - and pointing that
- * back at `ProbesModule` would be a cycle.
- *
- * A health check is still the feature that imports the most, so this list is an
- * accurate statement of what it touches.
+ * Its own module because `HealthModule.forRootAsync` registers in its own scope,
+ * so a factory injecting `AppIndicators` must name where it comes from - and
+ * pointing that back at `ProbesModule` would be a cycle.
  */
 @Module({
   imports: [DatabaseModule, CacheModule, WorkspaceModule],
   providers: [
     provide(AppIndicators, {
-      // Async because the upload root is: `Workspace.create()` is idempotent, so
-      // this is the directory `FilesModule` already made rather than a second one.
+      // `Workspace.create()` is idempotent, so this is the directory
+      // `FilesModule` already made.
       useFactory: async (
         db: DbConnection,
         redis: RedisConnection,
@@ -45,13 +41,9 @@ import { AppIndicators } from './indicators.js';
 export class IndicatorsModule {}
 
 /**
- * `HealthModule` from `@dunx/http`, which mounts `/api/health/live` and
- * `/api/health/ready`. Both are `@Public()` and hidden from the OpenAPI document:
- * a probe carries no credentials and is not an API a consumer calls.
- *
- * There is no indicator for `@dunx/infra/files` or `@dunx/infra/images`. Both are
- * in-process, so "it booted" is already answered by the port answering at all, and
- * a check that cannot fail tells an operator nothing.
+ * Mounts `/api/health/live` and `/api/health/ready`, both `@Public()` and hidden
+ * from the document. No indicator for the in-process packages: a check that
+ * cannot fail tells an operator nothing.
  */
 @Module({
   imports: [
@@ -61,9 +53,8 @@ export class IndicatorsModule {}
       useFactory: (indicators: AppIndicators) => ({
         readiness: indicators.readiness,
         liveness: indicators.liveness,
-        // A real deployment sets a few probe intervals here, so a load balancer
-        // sees readiness fail before the socket closes. Short enough that
-        // `bun run tour` and the suites are not waiting on it.
+        // A real deployment tunes these so a load balancer sees readiness fail
+        // before the socket closes.
         drainDelayMs: 250,
       }),
       inject: [AppIndicators] as const,

package/templates/features/health/indicators.ts

@@ -12,12 +12,8 @@ import type { DbConnection } from '@dunx/infra/db';
 import type { RedisConnection } from '@dunx/infra/redis';
 import { Ledger } from '../database/ledger.service.js';
 
-/**
- * The custom-indicator path: an app-specific query rather than a round trip.
- *
- * `DatabaseIndicator` answers "does the connection answer". This answers "is the
- * data there", which is the part only the app knows how to ask.
- */
+/** A custom indicator: `DatabaseIndicator` asks whether the connection answers,
+ * this asks whether the data is there. */
 export class LedgerIndicator extends HealthIndicator {
   readonly name = 'ledger';
 
@@ -37,12 +33,8 @@ export class LedgerIndicator extends HealthIndicator {
 }
 
 /**
- * `RedisIndicator` with the criticality flipped, because this app treats a missing
- * cache as degraded rather than fatal - the same promise `CacheModule` makes with
- * lazy connections and `maxRetries: 0`.
- *
- * Shedding traffic here would be wrong: the routes that need Redis report
- * themselves degraded and every other route still works.
+ * `RedisIndicator` with the criticality flipped: a missing cache is degraded
+ * rather than fatal, matching `CacheModule`'s lazy connect and `maxRetries: 0`.
  */
 export class CacheIndicator extends RedisIndicator {
   override readonly critical = false;
@@ -57,21 +49,14 @@ export interface AppIndicatorsInit {
 }
 
 /**
- * The one declaration of what this service probes.
- *
- * It is a provider rather than two lists inlined into two factories because two
- * things read it: `HealthModule` answers `/api/health/ready`, and
- * `DashboardModule` lights the same checks on the ops page. A `HealthIndicator`
- * satisfies `DashboardProbe` as written, so neither side needs an adapter.
+ * One declaration of what this service probes, read by both `HealthModule` and
+ * `DashboardModule`. A `HealthIndicator` satisfies `DashboardProbe` as written.
  */
 export class AppIndicators {
   readonly readiness: readonly HealthIndicator[];
   readonly liveness: readonly HealthIndicator[];
-  /**
-   * The readiness list minus what the dashboard already sources itself:
-   * `DashboardOptions.redis` drives the Redis panel *and* a `redis` probe, so
-   * handing it `CacheIndicator` as well would light the same name twice.
-   */
+  /** Minus what the dashboard sources itself: `DashboardOptions.redis` already
+   * drives a `redis` probe, so `CacheIndicator` here would light it twice. */
   readonly dashboardProbes: readonly HealthIndicator[];
 
   constructor(init: AppIndicatorsInit) {
@@ -79,13 +64,12 @@ export class AppIndicators {
       new DatabaseIndicator(init.db),
       new LedgerIndicator(init.ledger),
       new CacheIndicator(init.redis),
-      // Non-critical, because no other pod's disk is any emptier.
       new DiskIndicator(
         new DiskOptions({ path: init.uploadRoot, maxUsedFraction: 0.95 }),
       ),
     ];
-    // A ceiling belongs on liveness, where the orchestrator restarts the process
-    // rather than routing around it.
+    // A ceiling belongs on liveness, where the orchestrator restarts rather
+    // than routes around.
     this.liveness = [
       new MemoryIndicator(
         new MemoryOptions({ maxRssBytes: 1024 * 1024 * 1024 }),

package/templates/features/http/compression.demo.ts

@@ -0,0 +1,80 @@
+import { Logger } from '@dunx/core';
+
+const DOCUMENT = 'api/openapi.json';
+/** Under the 1024-byte threshold, so it is sent as it is. */
+const SMALL = 'api/notes/whoami';
+
+interface Measured {
+  readonly encoding: string;
+  readonly wire: number;
+  readonly decoded: number;
+  readonly vary: string;
+}
+
+/** `fetch` decodes the body but leaves `content-encoding` and the encoded
+ * `content-length`, so one request measures both sides. */
+const measure = async (
+  url: string,
+  path: string,
+  accept: string,
+): Promise<Measured> => {
+  const response = await fetch(new URL(path, url), {
+    headers: { 'accept-encoding': accept },
+  });
+  const decoded = await response.text();
+  const wire = response.headers.get('content-length');
+  return {
+    encoding: response.headers.get('content-encoding') ?? 'identity',
+    wire: wire === null ? decoded.length : Number(wire),
+    decoded: decoded.length,
+    vary: response.headers.get('vary') ?? '-',
+  };
+};
+
+const ratio = (m: Measured): string =>
+  `${((m.wire / m.decoded) * 100).toFixed(1)}%`;
+
+export class CompressionDemo {
+  constructor(private readonly logger: Logger) {}
+
+  async demonstrate(url: string): Promise<void> {
+    const { logger } = this;
+
+    // Vendored by `@dunx/create-app`: a scaffold taking `http` without `openapi`
+    // has no document to encode.
+    const available = await fetch(new URL(DOCUMENT, url));
+    await available.body?.cancel();
+    if (!available.ok) {
+      logger.info(`skipping: no ${DOCUMENT} in this app to encode`);
+      return;
+    }
+
+    // `identity` is a coding the app does not offer, so nothing is picked.
+    for (const accept of ['identity', 'gzip', 'zstd', 'gzip, zstd']) {
+      const m = await measure(url, DOCUMENT, accept);
+      logger.info(
+        `accept-encoding: ${accept.padEnd(11)} -> ${m.encoding.padEnd(8)} ` +
+          `${String(m.wire).padStart(6)} of ${m.decoded} bytes (${ratio(m)})`,
+      );
+    }
+
+    // Same q, so the server's order decides: `['zstd', 'gzip']`.
+    const preferred = await measure(url, DOCUMENT, 'gzip, zstd');
+    logger.info(
+      `a tie in the client's q-values is broken by the server order -> ${preferred.encoding}`,
+    );
+
+    const forced = await measure(url, DOCUMENT, 'zstd;q=0.1, gzip;q=0.9');
+    logger.info(`zstd;q=0.1, gzip;q=0.9 -> ${forced.encoding}`);
+
+    const small = await measure(url, SMALL, 'gzip, zstd');
+    logger.info(
+      `under the 1024-byte threshold: ${SMALL} -> ${small.encoding} ` +
+        `(${small.decoded} bytes, encoding it would add bytes)`,
+    );
+    logger.info(
+      `vary: ${small.vary} - set even when nothing was encoded, so a shared ` +
+        `cache does not serve one client's encoding to another`,
+    );
+  }
+}

package/templates/features/http/http.demo.ts

@@ -34,11 +34,8 @@ const postNote = (url: string, text: unknown): Promise<Response> =>
     body: JSON.stringify({ text }),
   });
 
-/**
- * `203.0.113.7` stands in for whatever the caller put in the header itself, and
- * `10.0.0.1` for the entry the one proxy in front of this app appended. With
- * `trust proxy` set to one hop, only the second is worth anything.
- */
+/** `203.0.113.7` is what the caller sent, `10.0.0.1` what the one proxy
+ * appended. With `trust proxy` at one hop, only the second counts. */
 const whoami = async (url: string, forwarded: boolean): Promise<string> => {
   const response = await fetch(new URL('api/notes/whoami', url), {
     headers: forwarded ? { 'x-forwarded-for': '203.0.113.7, 10.0.0.1' } : {},
@@ -83,28 +80,25 @@ export class HttpDemo {
         `${JSON.stringify(await rejected.json())}`,
     );
 
-    // Bun.serve answers a method miss with 404, so a preflight can never be
-    // inferred - enableCors mounts an explicit OPTIONS per path.
+    // Bun.serve answers a method miss with 404, so `enableCors` mounts an
+    // explicit OPTIONS per path.
     const allowed = await preflight(url, origin);
     logger.info(
       `enableCors: OPTIONS from ${origin} -> ${allowed.status} ${describeCors(allowed)}`,
     );
-    // A denied origin gets no CORS headers at all, which is what makes a browser
-    // block the response.
+    // A denied origin gets no CORS headers, which is what blocks the browser.
     const denied = await preflight(url, 'https://evil.test');
     logger.info(
       `OPTIONS from https://evil.test -> ${denied.status} ${describeCors(denied)}`,
     );
 
-    // One trusted hop, so the last entry wins and the caller's own leftmost
-    // entry is ignored. Reaching past the proxy takes set('trust proxy', 2).
+    // One trusted hop, so the last entry wins. Reaching past it takes 2.
     logger.info(
       `set("trust proxy", true): X-Forwarded-For sent -> ${await whoami(url, true)}`,
     );
     logger.info(`no header -> ${await whoami(url, false)}`);
 
-    // The route table and the middleware chain fold into one closure per route at
-    // listen(), so a late call could only ever be a silent no-op.
+    // Routes and middleware fold into one closure per route at listen().
     try {
       app.setGlobalPrefix('too-late');
     } catch (error) {

package/templates/features/http/http.module.ts

@@ -1,11 +1,39 @@
 import { Module } from '@dunx/core';
+import { CompressionModule } from '@dunx/http';
+import { CompressionDemo } from './compression.demo.js';
+import { TraceController } from './trace.controller.js';
+import { TraceDemo } from './trace.demo.js';
 import { HttpDemo } from './http.demo.js';
 import { RequestTrail, RequestTrailMiddleware } from './request-trail.js';
 
 // `use()` resolves middleware from the container, and every class self-binds - so
 // declaring them here is for the reader, not for the resolver.
 @Module({
-  providers: [RequestTrail, RequestTrailMiddleware, HttpDemo],
-  exports: [RequestTrail, RequestTrailMiddleware, HttpDemo],
+  imports: [
+    // Binds `Compression`; the **app** registers it, in `bootstrap.ts`, for the
+    // same reason `StaticFiles` is registered there. Nothing is installed by
+    // importing this, so an app that never calls `app.use(Compression)` has no
+    // branch in the request path to skip.
+    //
+    // Defaults left alone apart from the threshold, which is here to be seen: a
+    // body under it is sent as it is, because gzip's header and trailer alone are
+    // 18 bytes and a short JSON response comes out larger.
+    CompressionModule.forRoot({ threshold: 1024 }),
+  ],
+  controllers: [TraceController],
+  providers: [
+    RequestTrail,
+    RequestTrailMiddleware,
+    HttpDemo,
+    CompressionDemo,
+    TraceDemo,
+  ],
+  exports: [
+    RequestTrail,
+    RequestTrailMiddleware,
+    HttpDemo,
+    CompressionDemo,
+    TraceDemo,
+  ],
 })
 export class HttpModule {}

package/templates/features/http/request-trail.ts

@@ -7,15 +7,12 @@ export class RequestTrail {
 }
 
 /**
- * A class with `handle(req, ctx, next)`, resolved from the container - which is
- * what lets it inject. Chains are folded into one closure per route at boot, and
- * `ctx` is the route it was folded into: names, method, path, and its metadata.
+ * A class with `handle(req, ctx, next)`, resolved from the container so it can
+ * inject. `ctx` is the route the chain was folded into.
  *
- * **This does not log**, which is what the name says now and did not before.
- * `@dunx/http` installs `RequestLoggingMiddleware` itself - one structured entry
- * per request, tuned through `requestLogging` in bootstrap.ts - so an app writing
- * its own would write everything twice. What is left here is the part a framework
- * cannot supply: an app-specific side effect on a response the middleware can see.
+ * It does not log: `@dunx/http` writes the request entry itself, so an app doing
+ * its own would write everything twice. What is left is the app-specific side
+ * effect a framework cannot supply.
  */
 export class RequestTrailMiddleware implements Middleware {
   constructor(private readonly trail: RequestTrail) {}

package/templates/features/http/trace.controller.ts

@@ -0,0 +1,30 @@
+import { RequestContext } from '@dunx/core';
+import { Controller, Get, type Input, type RouteSchemas } from '@dunx/http';
+
+/**
+ * What the request's W3C trace looks like from inside a handler.
+ *
+ * `RequestContext` is bound by `@dunx/core` whatever else the app imports, and
+ * `requestLogging: { trace: true }` is what puts the trace fields into it. Every
+ * log line this request writes carries the same three values.
+ */
+@Controller('trace')
+export class TraceController {
+  constructor(private readonly context: RequestContext) {}
+
+  @Get('/')
+  current(input: Input<RouteSchemas>): {
+    traceId: string | undefined;
+    spanId: string | undefined;
+    parentSpanId: string | undefined;
+    inbound: string | null;
+  } {
+    const { traceId, spanId, parentSpanId } = this.context.getContext();
+    return {
+      traceId: traceId as string | undefined,
+      spanId: spanId as string | undefined,
+      parentSpanId: parentSpanId as string | undefined,
+      inbound: input.req.headers.get('traceparent'),
+    };
+  }
+}

package/templates/features/http/trace.demo.ts

@@ -0,0 +1,58 @@
+import { Logger } from '@dunx/core';
+
+interface Seen {
+  readonly traceId: string | undefined;
+  readonly spanId: string | undefined;
+  readonly parentSpanId: string | undefined;
+}
+
+const UPSTREAM_TRACE = '4bf92f3577b34da6a3ce929d0e0e4736';
+const UPSTREAM_SPAN = '00f067aa0ba902b7';
+
+const ask = async (url: string, traceparent?: string): Promise<Seen> => {
+  const response = await fetch(new URL('api/trace', url), {
+    headers: traceparent === undefined ? {} : { traceparent },
+  });
+  return (await response.json()) as Seen;
+};
+
+export class TraceDemo {
+  constructor(private readonly logger: Logger) {}
+
+  async demonstrate(url: string): Promise<void> {
+    const { logger } = this;
+
+    const fresh = await ask(url);
+    logger.info(
+      `no traceparent in: trace ${fresh.traceId} span ${fresh.spanId} ` +
+        `(no parent - this service started the trace)`,
+    );
+
+    const continued = await ask(
+      url,
+      `00-${UPSTREAM_TRACE}-${UPSTREAM_SPAN}-01`,
+    );
+    logger.info(
+      `traceparent in:    trace ${continued.traceId} span ${continued.spanId} ` +
+        `parent ${continued.parentSpanId}`,
+    );
+    logger.info(
+      `the caller's trace id survived: ${continued.traceId === UPSTREAM_TRACE}, ` +
+        `and its span became this one's parent: ${continued.parentSpanId === UPSTREAM_SPAN}`,
+    );
+
+    // Discarded rather than repaired. An unparseable header means the caller's
+    // trace is unknown, so this request starts one of its own.
+    const broken = await ask(url, '00-not-a-trace-id-01');
+    logger.info(
+      `malformed traceparent in: trace ${broken.traceId} ` +
+        `(a fresh one, not the caller's)`,
+    );
+
+    // Two requests are two traces, and two spans within one.
+    const second = await ask(url);
+    logger.info(
+      `each request gets its own span: ${fresh.spanId !== second.spanId}`,
+    );
+  }
+}