@starci/hfs 4.7.31 → 4.7.33

package/templates/be/skeleton/src/modules/platform/http/http.port.ts

@@ -0,0 +1,40 @@
+/** The HTTP methods the client sends. */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
+
+/** One outbound request. Callers supply the deadline and correlation id explicitly. */
+export interface HttpRequest {
+    /** The correlation id carried explicitly from the inbound request or delivery; sent as `x-request-id`. */
+    readonly correlationId: string
+    /** The HTTP method. */
+    readonly method: HttpMethod
+    /** The absolute URL. */
+    readonly url: string
+    /** Extra request headers; correlation headers come from `correlationId` instead. */
+    readonly headers?: Readonly<Record<string, string>>
+    /** A JSON-serializable body, sent as `application/json`. */
+    readonly body?: unknown
+    /** Form fields, sent as `application/x-www-form-urlencoded`; use either `body` or `form`, not both. */
+    readonly form?: Readonly<Record<string, string>>
+    /** Raw bytes sent as they are (the caller names their `content-type`); use instead of `body` and `form`. */
+    readonly bytes?: Buffer
+    /** How the answer body is read: parsed as JSON (default) or kept as raw bytes (a Buffer, empty when the answer had none). */
+    readonly read?: "json" | "bytes"
+    /** How long to wait for the answer before the call fails as a timeout. */
+    readonly timeoutMs: number
+    /** Cancels the call when aborted. */
+    readonly signal?: AbortSignal
+}
+
+/** The answer to one request: the status and the body parsed as JSON (undefined when the body is empty), or its raw bytes. */
+export interface HttpResponse {
+    /** The HTTP status code. */
+    readonly status: number
+    /** The parsed JSON body (undefined when the answer had none), or a Buffer when the request asked for `read: "bytes"`. */
+    readonly body: unknown
+}
+
+/** The outbound HTTP port: the only way product code calls another service. */
+export interface HttpClient {
+    /** Sends `request`; rejects with an HttpError on a network failure, a timeout or an unreadable body. */
+    request(request: HttpRequest): Promise<HttpResponse>
+}

package/templates/be/skeleton/src/modules/platform/http/index.ts

@@ -0,0 +1,7 @@
+export { HTTP_ERROR_KINDS, HttpError, HttpErrorCode } from "./errors/http.error"
+export { HTTP_MESSAGES } from "./messages/http.messages"
+export { callGraphql } from "./graphql-call.mapper"
+export type { GraphqlAnswer } from "./graphql-call.mapper"
+export { HTTP_CLIENT, InjectHttpClient } from "./http.decorators"
+export { HttpModule } from "./http.module"
+export type { HttpClient } from "./http.port"

package/templates/be/skeleton/src/modules/platform/http/messages/http.messages.ts

@@ -0,0 +1,15 @@
+import type { MessageBundle } from "@modules/platform/i18n"
+
+/** Display text of the http capability codes, Vietnamese and English. */
+export const HTTP_MESSAGES: MessageBundle = {
+    vi: {
+        "errors.HTTP_TIMEOUT": "Dịch vụ phụ thuộc không phản hồi kịp thời.",
+        "errors.HTTP_NETWORK": "Không thể kết nối tới dịch vụ phụ thuộc.",
+        "errors.HTTP_BODY_UNREADABLE": "Dịch vụ phụ thuộc trả về dữ liệu không đọc được.",
+    },
+    en: {
+        "errors.HTTP_TIMEOUT": "A dependent service did not answer in time.",
+        "errors.HTTP_NETWORK": "A dependent service could not be reached.",
+        "errors.HTTP_BODY_UNREADABLE": "A dependent service answered with an unreadable body.",
+    },
+}

package/templates/be/skeleton/src/modules/platform/ids/ids.decorators.ts

@@ -0,0 +1,9 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { Ids } from "./ids.port"
+
+/** Token of the Ids port. */
+export const IDS: unique symbol = Symbol("platform.ids")
+
+/** Injects the Ids port. Parameter type: Ids. */
+export const InjectIds = (): TypedParameterDecorator<Ids> => injector<Ids>(IDS)

package/templates/be/skeleton/src/modules/platform/ids/ids.module-definition.ts

@@ -0,0 +1,7 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { IdsOptions } from "./ids.options"
+
+/** The configurable-module base of the ids capability; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<IdsOptions>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()

package/templates/be/skeleton/src/modules/platform/ids/ids.module.ts

@@ -0,0 +1,19 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { IDS } from "./ids.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./ids.module-definition"
+import { SystemIds } from "./system-ids.service"
+
+@Module({})
+/** Provides the Ids port backed by the system random source. */
+export class IdsModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [...(base.providers ?? []), { provide: IDS, useClass: SystemIds }],
+            exports: [IDS],
+        }
+    }
+}

package/templates/be/skeleton/src/modules/platform/ids/ids.options.ts

@@ -0,0 +1,2 @@
+/** The ids capability takes no options; the empty record keeps `isGlobal` assignable through the configurable module. */
+export type IdsOptions = Record<never, never>

package/templates/be/skeleton/src/modules/platform/ids/ids.port.ts

@@ -0,0 +1,5 @@
+/** The ids port: business code asks it for a new identifier instead of reading a random source, so a spec can say every id. */
+export interface Ids {
+    /** A new unique identifier (a UUID). */
+    next(): string
+}

package/templates/be/skeleton/src/modules/platform/ids/index.ts

@@ -0,0 +1,4 @@
+export type { Ids } from "./ids.port"
+export { IDS, InjectIds } from "./ids.decorators"
+export { IdsModule } from "./ids.module"
+export { SystemIds } from "./system-ids.service"

package/templates/be/skeleton/src/modules/platform/ids/system-ids.service.spec.ts

@@ -0,0 +1,15 @@
+import { Test } from "@nestjs/testing"
+import { SystemIds } from "./system-ids.service"
+
+describe("SystemIds", () => {
+    it("answers a UUID, and a different one each time", async () => {
+        const moduleRef = await Test.createTestingModule({ providers: [SystemIds] }).compile()
+        const ids = moduleRef.get(SystemIds)
+
+        const first = ids.next()
+        const second = ids.next()
+
+        expect(first).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/)
+        expect(second).not.toBe(first)
+    })
+})

package/templates/be/skeleton/src/modules/platform/ids/system-ids.service.ts

@@ -0,0 +1,10 @@
+import { randomUUID } from "node:crypto"
+import type { Ids } from "./ids.port"
+
+/** The production ids: the one place that reads the ambient random source. It has no dependencies, so the DI container builds it without a decorator. */
+export class SystemIds implements Ids {
+    /** A new random UUID. */
+    next(): string {
+        return randomUUID()
+    }
+}

package/templates/be/skeleton/src/modules/platform/logging/correlation-request.policy.spec.ts

@@ -0,0 +1,59 @@
+import type { INestApplication } from "@nestjs/common"
+import { Test } from "@nestjs/testing"
+import { mock } from "@starci/jest-preset"
+import type { NextFunction, Request, RequestHandler, Response } from "express"
+import type { CorrelationIds, CorrelationRunner } from "./correlation.port"
+import { applyCorrelation, correlationMiddleware } from "./correlation-request.policy"
+import { CORRELATION_IDS, CORRELATION_RUNNER } from "./logging.decorators"
+import { runWithCorrelation, stampLogFields } from "./correlation.policy"
+
+const SUBJECT = Symbol("request-correlation-policy")
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: SUBJECT, useValue: { applyCorrelation, correlationMiddleware } }],
+    }).compile()
+    return moduleRef.get<typeof import("./correlation-request.policy")>(SUBJECT)
+}
+
+describe("request correlation", () => {
+    it("copies the explicit identity to the request and response and scopes downstream work", async () => {
+        const subject = await build()
+        const ids = mock<CorrelationIds>({ fromHeaders: () => "request-id" })
+        const runner = mock<CorrelationRunner>({ run: runWithCorrelation })
+        const request = mock<Request>({ headers: { "x-request-id": "request-id" } })
+        const setHeader = jest.fn()
+        const response = mock<Response>({ setHeader })
+        const next: NextFunction = jest.fn(() => {
+            expect(stampLogFields({}, "root-id")).toEqual({ correlationId: "request-id" })
+        })
+
+        subject.correlationMiddleware(ids, runner)(request, response, next)
+
+        expect(request).toHaveProperty("correlationId", "request-id")
+        expect(setHeader).toHaveBeenCalledWith("x-request-id", "request-id")
+        expect(next).toHaveBeenCalledTimes(1)
+    })
+
+    it("installs the middleware using the registered logging ports", async () => {
+        const subject = await build()
+        const ids = mock<CorrelationIds>({ fromHeaders: () => "installed-id" })
+        const runner = mock<CorrelationRunner>({ run: runWithCorrelation })
+        const installed: Array<RequestHandler> = []
+        const app: INestApplication = mock<INestApplication>({
+            get: jest.fn().mockImplementation((key: unknown) => (key === CORRELATION_IDS ? ids : runner)),
+            use: (handler: RequestHandler): INestApplication => {
+                installed.push(handler)
+                return app
+            },
+        })
+        subject.applyCorrelation(app)
+
+        expect(app.get).toHaveBeenCalledWith(CORRELATION_IDS)
+        expect(app.get).toHaveBeenCalledWith(CORRELATION_RUNNER)
+
+        expect(installed).toHaveLength(1)
+        const setHeader = jest.fn()
+        installed[0]?.(mock<Request>({ headers: {} }), mock<Response>({ setHeader }), jest.fn())
+        expect(setHeader).toHaveBeenCalledWith("x-request-id", "installed-id")
+    })
+})

package/templates/be/skeleton/src/modules/platform/logging/correlation-request.policy.ts

@@ -0,0 +1,21 @@
+import type { INestApplication } from "@nestjs/common"
+import type { RequestHandler } from "express"
+import type { CorrelationIds, CorrelationRunner } from "./correlation.port"
+import { CORRELATION_IDS, CORRELATION_RUNNER } from "./logging.decorators"
+
+/** Copies the identity onto the request and response, then scopes all downstream request logging. */
+export const correlationMiddleware =
+    (ids: CorrelationIds, runner: CorrelationRunner): RequestHandler =>
+    (request, response, next) => {
+        const correlationId = ids.fromHeaders(request.headers)
+        Object.assign(request, { correlationId })
+        response.setHeader("x-request-id", correlationId)
+        runner.run(correlationId, next)
+    }
+
+/** Installs correlation before request handling; transports read the stamped request field explicitly. */
+export const applyCorrelation = (app: INestApplication): void => {
+    app.use(
+        correlationMiddleware(app.get<CorrelationIds>(CORRELATION_IDS), app.get<CorrelationRunner>(CORRELATION_RUNNER)),
+    )
+}

package/templates/be/skeleton/src/modules/platform/logging/correlation.contracts.ts

@@ -0,0 +1,16 @@
+/** Headers accepted at the logging boundary; repeated values are not correlation identities. */
+export interface CorrelationHeaders {
+    /** An inbound HTTP header value. */
+    readonly [name: string]: string | ReadonlyArray<string> | undefined
+}
+
+/** The request identity copied explicitly into transport commands and downstream envelopes. */
+export interface CorrelationRequest {
+    /** The inbound headers read by logging. */
+    readonly headers: CorrelationHeaders
+    /** The validated or minted correlation identity. */
+    readonly correlationId: string
+}
+
+/** Work entered by infrastructure with an explicit identity; its result and failure pass through unchanged. */
+export type CorrelationWork<T> = () => T

package/templates/be/skeleton/src/modules/platform/logging/correlation.policy.spec.ts

@@ -0,0 +1,150 @@
+import { Test } from "@nestjs/testing"
+import { fakeIds } from "@starci/jest-preset"
+import { DomainError } from "@modules/platform/errors"
+import { correlationFromHeaders, isCorrelationId, runWithCorrelation, stampLogFields } from "./correlation.policy"
+
+type LoggingScopeErrorCode = "LOGGING_SCOPE_FAILED"
+class LoggingScopeError extends DomainError<LoggingScopeErrorCode> {}
+
+const SUBJECT = Symbol("correlation-policy")
+const FIRST_ID = "00000000-0000-4000-8000-000000000001"
+const traceId = "4bf92f3577b34da6a3ce929d0e0e4736"
+const spanId = "00f067aa0ba902b7"
+const build = async () => {
+    const ids = fakeIds()
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            {
+                provide: SUBJECT,
+                useValue: { correlationFromHeaders, isCorrelationId, runWithCorrelation, stampLogFields },
+            },
+        ],
+    }).compile()
+    return { subject: moduleRef.get<typeof import("./correlation.policy")>(SUBJECT), ids }
+}
+
+describe("correlationFromHeaders", () => {
+    it("uses the validated trace id before the request id", async () => {
+        const { subject, ids } = await build()
+        expect(
+            subject.correlationFromHeaders(
+                { traceparent: `00-${traceId}-${spanId}-01`, "x-request-id": "request-1" },
+                ids,
+            ),
+        ).toBe(traceId)
+    })
+
+    it.each([`01-${traceId}-${spanId}-01`, `01-${traceId}-${spanId}-01-future-field`])(
+        "reads the known prefix of a higher traceparent version: %s",
+        async (traceparent) => {
+            const { subject, ids } = await build()
+            expect(subject.correlationFromHeaders({ traceparent, "x-request-id": "request-1" }, ids)).toBe(traceId)
+        },
+    )
+
+    it.each([
+        "malformed",
+        `ff-${traceId}-${spanId}-01`,
+        `ff-${traceId}-${spanId}-01-future-field`,
+        `00-${traceId}-${spanId}-01-extra`,
+        `01-${traceId}-${spanId}-01extra`,
+        `01-${traceId}-${spanId}-01_extra`,
+        `01-${traceId}-${spanId}-0`,
+        `00-${traceId}-${spanId}-01\n`,
+        `01-${traceId}-${spanId}-01\n`,
+        `00-${"0".repeat(32)}-${spanId}-01`,
+        `00-${traceId}-${"0".repeat(16)}-01`,
+        `00-${traceId.toUpperCase()}-${spanId}-01`,
+    ])("falls back to a request id when traceparent is invalid: %s", async (traceparent) => {
+        const { subject, ids } = await build()
+        expect(subject.correlationFromHeaders({ traceparent, "x-request-id": "request-1" }, ids)).toBe("request-1")
+    })
+
+    it("does not choose among repeated traceparent values", async () => {
+        const { subject, ids } = await build()
+        expect(
+            subject.correlationFromHeaders(
+                { traceparent: [`00-${traceId}-${spanId}-01`], "x-request-id": "request-1" },
+                ids,
+            ),
+        ).toBe("request-1")
+    })
+
+    it("accepts the bounded safe request id alphabet", async () => {
+        const { subject, ids } = await build()
+        expect(subject.correlationFromHeaders({ "x-request-id": "A-1._:z" }, ids)).toBe("A-1._:z")
+        expect(subject.correlationFromHeaders({ "x-request-id": "a".repeat(128) }, ids)).toHaveLength(128)
+    })
+
+    it.each([
+        { requestId: undefined },
+        { requestId: "" },
+        { requestId: "a".repeat(129) },
+        { requestId: "line\nbreak" },
+        { requestId: "request-id\n" },
+        { requestId: "request-id\r" },
+        { requestId: "unsafe value" },
+        { requestId: ["a", "b"] },
+    ])("mints through Ids for absent or unsafe request ids: %p", async ({ requestId }) => {
+        const { subject, ids } = await build()
+        expect(subject.correlationFromHeaders({ "x-request-id": requestId }, ids)).toBe(FIRST_ID)
+        expect(ids.issued).toEqual([FIRST_ID])
+    })
+})
+
+describe("logging correlation scopes", () => {
+    it("stamps the logger root identity outside a scope", async () => {
+        const { subject } = await build()
+        expect(subject.stampLogFields(undefined, FIRST_ID)).toEqual({ correlationId: FIRST_ID })
+    })
+
+    it("returns the work's result and restores a nested scope", async () => {
+        const { subject } = await build()
+        const result = subject.runWithCorrelation("outer", () => {
+            expect(subject.stampLogFields({ correlationId: "override", owner: "logging" }, FIRST_ID)).toEqual({
+                correlationId: "outer",
+                owner: "logging",
+            })
+            subject.runWithCorrelation("inner", () =>
+                expect(subject.stampLogFields({}, FIRST_ID)).toEqual({ correlationId: "inner" }),
+            )
+            expect(subject.stampLogFields({}, FIRST_ID)).toEqual({ correlationId: "outer" })
+            return "result"
+        })
+        expect(result).toBe("result")
+        expect(subject.stampLogFields({}, FIRST_ID)).toEqual({ correlationId: FIRST_ID })
+    })
+
+    it("restores the surrounding scope after a throw", async () => {
+        const { subject } = await build()
+        const failure = new LoggingScopeError({ code: "LOGGING_SCOPE_FAILED" })
+        expect(() =>
+            subject.runWithCorrelation("failed", () => {
+                throw failure
+            }),
+        ).toThrow(failure)
+        expect(subject.stampLogFields({}, FIRST_ID)).toEqual({ correlationId: FIRST_ID })
+    })
+
+    it("isolates interleaved asynchronous requests", async () => {
+        const { subject } = await build()
+        let releaseFirst: (() => void) | undefined
+        const firstReady = new Promise<void>((resolve) => {
+            releaseFirst = resolve
+        })
+        const first = subject.runWithCorrelation("first", async () => {
+            await firstReady
+            return subject.stampLogFields({}, FIRST_ID)
+        })
+        const second = subject.runWithCorrelation("second", async () => {
+            await Promise.resolve()
+            releaseFirst?.()
+            return subject.stampLogFields({}, FIRST_ID)
+        })
+        await expect(Promise.all([first, second])).resolves.toEqual([
+            { correlationId: "first" },
+            { correlationId: "second" },
+        ])
+        expect(subject.stampLogFields({}, FIRST_ID)).toEqual({ correlationId: FIRST_ID })
+    })
+})

package/templates/be/skeleton/src/modules/platform/logging/correlation.policy.ts

@@ -0,0 +1,42 @@
+import { AsyncLocalStorage } from "node:async_hooks"
+import type { Ids } from "@modules/platform/ids"
+import type { CorrelationHeaders, CorrelationWork } from "./correlation.contracts"
+import type { LogFields } from "./logging.port"
+
+// Logging owns the process's sole ambient correlation store; envelopes carry identities across every other boundary.
+const correlation = new AsyncLocalStorage<string>()
+
+/** Enters a logging scope without making ambient reads part of the public logging port. */
+export const runWithCorrelation = <T>(correlationId: string, work: CorrelationWork<T>): T =>
+    correlation.run(correlationId, work)
+
+/** Stamps the logger's fields last so caller-supplied fields cannot replace the active identity; outside any scope the logger's own root identity stands. */
+export const stampLogFields = (fields: LogFields | undefined, rootId: string): LogFields => ({
+    ...fields,
+    correlationId: correlation.getStore() ?? rootId,
+})
+
+/** Parses the known W3C prefix; newer versions keep opaque additions, while version 00 permits none. */
+const traceIdOf = (traceparent: string): string | undefined => {
+    const match = /^(?!ff)([0-9a-f]{2})-((?!0{32})[0-9a-f]{32})-(?!0{16})[0-9a-f]{16}-[0-9a-f]{2}((?![\s\S])|-)/.exec(
+        traceparent,
+    )
+    if (!match) return undefined
+    if (match[1] === "00" && match[3] === "-") return undefined
+    return match[2]
+}
+
+/** Reads a valid W3C trace identity or a safe request id; malformed headers cannot enter logs. */
+export const correlationFromHeaders = (headers: CorrelationHeaders, ids: Ids): string => {
+    const traceparent = headers["traceparent"]
+    if (typeof traceparent === "string") {
+        const traceId = traceIdOf(traceparent)
+        if (traceId) return traceId
+    }
+    const requestId = headers["x-request-id"]
+    return isCorrelationId(requestId) ? requestId : ids.next()
+}
+
+/** Accepts only bounded, header-safe identities on serialized async envelopes. */
+export const isCorrelationId = (value: unknown): value is string =>
+    typeof value === "string" && value.length > 0 && value.length <= 128 && !/[^A-Za-z0-9._:-]/.test(value)

package/templates/be/skeleton/src/modules/platform/logging/correlation.port.ts

@@ -0,0 +1,15 @@
+import type { CorrelationHeaders, CorrelationWork } from "./correlation.contracts"
+
+/** Runs infrastructure work under a supplied identity so logging stamps its async descendants. */
+export interface CorrelationRunner {
+    /** Restores the surrounding logging scope when the work returns or throws. */
+    run<T>(correlationId: string, work: CorrelationWork<T>): T
+}
+
+/** Resolves explicit request identities without exposing the logger's ambient state. */
+export interface CorrelationIds {
+    /** Uses a valid W3C trace id, then a bounded request id, otherwise asks the Ids port. */
+    fromHeaders(headers: CorrelationHeaders): string
+    /** Mints an identity for work that starts without an inbound request. */
+    create(): string
+}

package/templates/be/skeleton/src/modules/platform/logging/correlation.service.spec.ts

@@ -0,0 +1,23 @@
+import { Test } from "@nestjs/testing"
+import { fakeIds } from "@starci/jest-preset"
+import { IDS } from "@modules/platform/ids"
+import { CorrelationService, createCorrelationRunner } from "./correlation.service"
+import { stampLogFields } from "./correlation.policy"
+
+describe("CorrelationService", () => {
+    it("resolves headers, creates identities, and runs work with an explicit identity", async () => {
+        const ids = fakeIds()
+        const moduleRef = await Test.createTestingModule({
+            providers: [CorrelationService, { provide: IDS, useValue: ids }],
+        }).compile()
+        const service = moduleRef.get<CorrelationService>(CorrelationService)
+
+        expect(service.fromHeaders({ "x-request-id": "request-1" })).toBe("request-1")
+        expect(service.fromHeaders({})).toBe("00000000-0000-4000-8000-000000000001")
+        expect(service.create()).toBe("00000000-0000-4000-8000-000000000002")
+        expect(service.run("explicit-id", () => stampLogFields({}, "root-id"))).toEqual({ correlationId: "explicit-id" })
+        expect(createCorrelationRunner(ids).run("bootstrap-id", () => stampLogFields({}, "root-id"))).toEqual({
+            correlationId: "bootstrap-id",
+        })
+    })
+})

package/templates/be/skeleton/src/modules/platform/logging/correlation.service.ts

@@ -0,0 +1,28 @@
+import { InjectIds } from "@modules/platform/ids"
+import type { Ids } from "@modules/platform/ids"
+import type { CorrelationHeaders, CorrelationWork } from "./correlation.contracts"
+import { correlationFromHeaders, runWithCorrelation } from "./correlation.policy"
+import type { CorrelationIds, CorrelationRunner } from "./correlation.port"
+
+/** Owns inbound identity resolution and logging scopes; business code receives explicit identities. */
+export class CorrelationService implements CorrelationIds, CorrelationRunner {
+    constructor(@InjectIds() private readonly ids: Ids) {}
+
+    /** Chooses an inbound identity, minting through Ids when both headers are absent or invalid. */
+    fromHeaders(headers: CorrelationHeaders): string {
+        return correlationFromHeaders(headers, this.ids)
+    }
+
+    /** Starts work that has no inbound identity through the deterministic Ids port. */
+    create(): string {
+        return this.ids.next()
+    }
+
+    /** Applies only to logging; callers still pass the identity to outgoing envelopes explicitly. */
+    run<T>(correlationId: string, work: CorrelationWork<T>): T {
+        return runWithCorrelation(correlationId, work)
+    }
+}
+
+/** Builds an infrastructure logging runner for bootstrap and test worlds without a Nest container. */
+export const createCorrelationRunner = (ids: Ids): CorrelationRunner => new CorrelationService(ids)

package/templates/be/skeleton/src/modules/platform/logging/index.ts

@@ -1,5 +1,18 @@
 export { createJsonLogger } from "./json-logger.service"
-export { InjectLogger, LOGGER } from "./logging.decorators"
+export {
+    InjectLogger,
+    LOGGER,
+    CORRELATION_IDS,
+    CORRELATION_RUNNER,
+    InjectCorrelationIds,
+    InjectCorrelationRunner,
+} from "./logging.decorators"
+export { applyCorrelation, correlationMiddleware } from "./correlation-request.policy"
+export type { CorrelationIds, CorrelationRunner } from "./correlation.port"
+export type { CorrelationHeaders, CorrelationRequest } from "./correlation.contracts"
+export { createCorrelationRunner } from "./correlation.service"
+export { isCorrelationId } from "./correlation.policy"
 export { LoggingLogEvent } from "./logging.log-events"
 export { LoggingModule } from "./logging.module"
 export type { Logger } from "./logging.port"
+export { createNestLogger } from "./nest-logger.service"

package/templates/be/skeleton/src/modules/platform/logging/json-logger.service.spec.ts

@@ -1,10 +1,12 @@
 import type { Writable } from "node:stream"
-import { FakeClock, mock } from "@starci/jest-preset"
+import { FakeClock, fakeIds, mock } from "@starci/jest-preset"
 import { CLOCK } from "@modules/platform/clock"
+import { IDS } from "@modules/platform/ids"
 import { Test } from "@nestjs/testing"
 import { createJsonLogger, JsonLoggerService } from "./json-logger.service"
 import { LOG_ERR, LOG_OUT } from "./logging.decorators"
 import { LoggingLogEvent } from "./logging.log-events"
+import { runWithCorrelation } from "./correlation.policy"
 
 type WrittenLine = { stream: "out" | "err"; line: string }
 
@@ -29,9 +31,10 @@ const build = async () => {
             { provide: CLOCK, useValue: clock },
             { provide: LOG_OUT, useValue: out },
             { provide: LOG_ERR, useValue: err },
+            { provide: IDS, useValue: fakeIds() },
         ],
     }).compile()
-    return { logger: moduleRef.get(JsonLoggerService), clock, written }
+    return { logger: moduleRef.get<JsonLoggerService>(JsonLoggerService), clock, written }
 }
 
 describe("JsonLoggerService", () => {
@@ -41,7 +44,7 @@ describe("JsonLoggerService", () => {
         expect(written).toEqual([
             {
                 stream: "out",
-                line: `${JSON.stringify({ personId: "p-1", level: "info", event: "cart.opened", time: "2026-05-06T07:08:09.000Z" })}\n`,
+                line: `${JSON.stringify({ personId: "p-1", correlationId: "00000000-0000-4000-8000-000000000001", level: "info", event: "cart.opened", time: "2026-05-06T07:08:09.000Z" })}\n`,
             },
         ])
     })
@@ -54,6 +57,7 @@ describe("JsonLoggerService", () => {
             level: "warn",
             event: LoggingLogEvent.StartupFailed,
             time: "2026-05-06T07:08:10.000Z",
+            correlationId: "00000000-0000-4000-8000-000000000001",
         })
         expect(written[0]?.stream).toBe("err")
     })
@@ -72,6 +76,7 @@ describe("JsonLoggerService error details", () => {
             level: "error",
             event: "db.failed",
             time: "2026-05-06T07:08:09.000Z",
+            correlationId: "00000000-0000-4000-8000-000000000001",
         })
         expect(written[0]?.stream).toBe("err")
     })
@@ -88,6 +93,7 @@ describe("JsonLoggerService error details", () => {
             level: "error",
             event: "db.failed",
             time: "2026-05-06T07:08:09.000Z",
+            correlationId: "00000000-0000-4000-8000-000000000001",
         })
     })
 
@@ -130,12 +136,39 @@ describe("createJsonLogger", () => {
         const lines: Array<string> = []
         jest.spyOn(process.stdout, "write").mockImplementation((chunk) => lines.push(`out:${String(chunk)}`) > 0)
         jest.spyOn(process.stderr, "write").mockImplementation((chunk) => lines.push(`err:${String(chunk)}`) > 0)
-        const logger = createJsonLogger(new FakeClock("2026-05-06T07:08:09.000Z"))
+        const logger = createJsonLogger(new FakeClock("2026-05-06T07:08:09.000Z"), fakeIds())
         logger.info(LoggingLogEvent.ServerStarted)
         logger.warn(LoggingLogEvent.StartupFailed)
         expect(lines).toEqual([
-            `out:${JSON.stringify({ level: "info", event: LoggingLogEvent.ServerStarted, time: "2026-05-06T07:08:09.000Z" })}\n`,
-            `err:${JSON.stringify({ level: "warn", event: LoggingLogEvent.StartupFailed, time: "2026-05-06T07:08:09.000Z" })}\n`,
+            `out:${JSON.stringify({ correlationId: "00000000-0000-4000-8000-000000000001", level: "info", event: LoggingLogEvent.ServerStarted, time: "2026-05-06T07:08:09.000Z" })}\n`,
+            `err:${JSON.stringify({ correlationId: "00000000-0000-4000-8000-000000000001", level: "warn", event: LoggingLogEvent.StartupFailed, time: "2026-05-06T07:08:09.000Z" })}\n`,
+        ])
+    })
+})
+
+describe("JsonLoggerService correlation", () => {
+    it("stamps every level with the active identity and refuses caller overrides", async () => {
+        const { logger, written } = await build()
+        runWithCorrelation("request-id", () => {
+            logger.info(LoggingLogEvent.ServerStarted, { correlationId: "override" })
+            logger.warn(LoggingLogEvent.StartupFailed)
+            logger.error(LoggingLogEvent.StartupFailed, new Error("failed"))
+        })
+        expect(written).toHaveLength(3)
+        expect(written.every(({ line }) => readJsonLine(line).correlationId === "request-id")).toBe(true)
+    })
+})
+
+describe("JsonLogger outside a correlation scope", () => {
+    it("stamps every line with one root identity drawn once", async () => {
+        const { logger, written } = await build()
+
+        logger.info("cart.opened")
+        logger.warn("cart.slow")
+
+        expect(written.map((entry) => entry.line)).toEqual([
+            `${JSON.stringify({ level: "info", event: "cart.opened", time: "2026-05-06T07:08:09.000Z", correlationId: "00000000-0000-4000-8000-000000000001" })}\n`,
+            `${JSON.stringify({ level: "warn", event: "cart.slow", time: "2026-05-06T07:08:09.000Z", correlationId: "00000000-0000-4000-8000-000000000001" })}\n`,
         ])
     })
 })