@starci/hfs 4.7.32 → 4.7.33

package/templates/be/skeleton/apps/__app__/src/compose/platform.ts

@@ -8,6 +8,8 @@ import { DATABASE_ERROR_KINDS, DatabaseModule } from "@modules/platform/database
 import { ERRORS_MESSAGES, ErrorsModule } from "@modules/platform/errors"
 import { HTTP_SECURITY_ERROR_KINDS, HTTP_SECURITY_MESSAGES, HttpSecurityModule } from "@modules/platform/http-security"
 import { I18nModule } from "@modules/platform/i18n"
+import { IdsModule } from "@modules/platform/ids"
+import { HTTP_ERROR_KINDS, HTTP_MESSAGES, HttpModule } from "@modules/platform/http"
 import { LoggingModule } from "@modules/platform/logging"
 import { RetryModule } from "@modules/platform/retry"
 import type { {{appPascal}}Options } from "../{{app}}.options"
@@ -20,14 +22,17 @@ import type { {{appPascal}}Options } from "../{{app}}.options"
 export const platformModules = (options: {{appPascal}}Options): Array<DynamicModule> => [
     ClockModule.register({ isGlobal: true }),
     RetryModule.register({ isGlobal: true }),
+    IdsModule.register({ isGlobal: true }),
     LoggingModule.register({ isGlobal: true }),
+    HttpModule.register({ isGlobal: true }),
     I18nModule.register({
         isGlobal: true,
-        bundles: [ERRORS_MESSAGES, HTTP_SECURITY_MESSAGES, IDENTITY_MESSAGES],
+        bundles: [HTTP_MESSAGES, ERRORS_MESSAGES, HTTP_SECURITY_MESSAGES, IDENTITY_MESSAGES],
     }),
     ErrorsModule.register({
         isGlobal: true,
         kinds: [
+            HTTP_ERROR_KINDS,
             CONFIG_ERROR_KINDS,
             DATABASE_ERROR_KINDS,
             HTTP_SECURITY_ERROR_KINDS,

package/templates/be/skeleton/apps/__app__/src/main.ts

@@ -2,7 +2,8 @@ import { NestFactory } from "@nestjs/core"
 import { SystemClockService } from "@modules/platform/clock"
 import { EnvSource } from "@modules/platform/config"
 import { applyHttpSecurity } from "@modules/platform/http-security"
-import { createJsonLogger, LoggingLogEvent } from "@modules/platform/logging"
+import { SystemIds } from "@modules/platform/ids"
+import { applyCorrelation, createJsonLogger, createNestLogger, LoggingLogEvent } from "@modules/platform/logging"
 import { AppModule } from "./app.module"
 import { read{{appPascal}}Env } from "./{{app}}.env"
 
@@ -10,17 +11,19 @@ import { read{{appPascal}}Env } from "./{{app}}.env"
 const bootstrap = async (): Promise<void> => {
     const env = EnvSource.fromProcess()
     const options = read{{appPascal}}Env(env)
-    const app = await NestFactory.create(AppModule.register(options), { rawBody: true })
+    const logger = createJsonLogger(new SystemClockService(), new SystemIds())
+    const app = await NestFactory.create(AppModule.register(options), { rawBody: true, logger: createNestLogger(logger) })
+    applyCorrelation(app)
     applyHttpSecurity(app, options.httpSecurity, { trustProxy: 1 })
     app.enableShutdownHooks()
     await app.listen(options.server.port)
-    createJsonLogger(new SystemClockService()).info(LoggingLogEvent.ServerStarted, {
+    logger.info(LoggingLogEvent.ServerStarted, {
         service: "{{app}}",
         port: options.server.port,
     })
 }
 
 bootstrap().catch((error: unknown) => {
-    createJsonLogger(new SystemClockService()).error(LoggingLogEvent.StartupFailed, error, { service: "{{app}}" })
+    createJsonLogger(new SystemClockService(), new SystemIds()).error(LoggingLogEvent.StartupFailed, error, { service: "{{app}}" })
     process.exitCode = 1
 })

package/templates/be/skeleton/apps/cli/src/compose/platform.ts

@@ -3,6 +3,8 @@ import { noteEntities, noteMigrations } from "@modules/domain/note"
 import { ClockModule } from "@modules/platform/clock"
 import { DatabaseModule } from "@modules/platform/database"
 import type { DatabaseConnectionConfig, DatabaseConnectionOptions } from "@modules/platform/database"
+import { IdsModule } from "@modules/platform/ids"
+import { HTTP_ERROR_KINDS, HTTP_MESSAGES, HttpModule } from "@modules/platform/http"
 import { LoggingModule } from "@modules/platform/logging"
 import type { CliAppOptions } from "../cli.options"
 
@@ -16,7 +18,9 @@ const primaryConnectionOf = (primary: DatabaseConnectionConfig): DatabaseConnect
 /** The clock, logger and declared database connections shared by CLI commands. */
 export const platformModules = (options: CliAppOptions): Array<DynamicModule> => [
     ClockModule.register({ isGlobal: true }),
+    IdsModule.register({ isGlobal: true }),
     LoggingModule.register({ isGlobal: true }),
+    HttpModule.register({ isGlobal: true }),
     DatabaseModule.register({
         isGlobal: true,
         connections: [primaryConnectionOf(options.database)],

package/templates/be/skeleton/apps/cli/src/main.ts

@@ -2,16 +2,17 @@ import "reflect-metadata"
 import { CommandFactory } from "nest-commander"
 import { SystemClockService } from "@modules/platform/clock"
 import { EnvSource } from "@modules/platform/config"
-import { createJsonLogger, LoggingLogEvent } from "@modules/platform/logging"
+import { SystemIds } from "@modules/platform/ids"
+import { createJsonLogger, createNestLogger, LoggingLogEvent } from "@modules/platform/logging"
 import { AppModule } from "./app.module"
 import { readCliEnv } from "./cli.env"
 import { createCliAppOptions } from "./cli.options"
 
 /** The command line of the back end: reads the environment once and runs the command its arguments name (`cli migrate run`). */
 async function bootstrap(): Promise<void> {
-    const logger = createJsonLogger(new SystemClockService())
+    const logger = createJsonLogger(new SystemClockService(), new SystemIds())
     await CommandFactory.run(AppModule.register(createCliAppOptions(readCliEnv(EnvSource.fromProcess()))), {
-        logger: false,
+        logger: createNestLogger(logger),
         errorHandler: (error: Error) => {
             logger.error(LoggingLogEvent.StartupFailed, error, { service: "cli" })
             process.exit(1)
@@ -20,6 +21,8 @@ async function bootstrap(): Promise<void> {
 }
 
 bootstrap().catch((error: unknown) => {
-    createJsonLogger(new SystemClockService()).error(LoggingLogEvent.StartupFailed, error, { service: "cli" })
+    createJsonLogger(new SystemClockService(), new SystemIds()).error(LoggingLogEvent.StartupFailed, error, {
+        service: "cli",
+    })
     process.exit(1)
 })

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

@@ -5,7 +5,7 @@ export { MigrationRunnerService } from "./migration-runner.service"
 export { DEFAULT_SEED_ENV } from "./seed-connections.client"
 export { SeedRunnerService } from "./seed-runner.service"
 export type { DatabaseConnectionConfig, DatabaseConnectionOptions } from "./database.options"
-export { LIST_ROWS_MAX, sql } from "./database.sql"
+export { BATCH_ROWS, LIST_ROWS_MAX, sql } from "./database.sql"
 export { DATABASE_ERROR_KINDS } from "./errors/database.error"
 export { parsePrimaryDatabaseConfig } from "./primary.config"
 export { InjectPrimaryEntityManager, PRIMARY_ENTITY_MANAGER } from "./primary.decorators"

package/templates/be/skeleton/src/modules/platform/http/errors/http.error.ts

@@ -0,0 +1,22 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the http capability: how an outbound call failed before an answer could be used. */
+export enum HttpErrorCode {
+    /** The other side did not answer within the deadline. */
+    Timeout = "HTTP_TIMEOUT",
+    /** The other side could not be reached. */
+    Network = "HTTP_NETWORK",
+    /** The other side answered with a body that is not JSON. */
+    BodyUnreadable = "HTTP_BODY_UNREADABLE",
+}
+
+/** How each http code travels. */
+export const HTTP_ERROR_KINDS: Record<HttpErrorCode, ErrorKind> = {
+    [HttpErrorCode.Timeout]: "unavailable",
+    [HttpErrorCode.Network]: "unavailable",
+    [HttpErrorCode.BodyUnreadable]: "internal",
+}
+
+/** The one error class of the http capability. */
+export class HttpError extends DomainError<HttpErrorCode> {}

package/templates/be/skeleton/src/modules/platform/http/fetch-http-client.client.spec.ts

@@ -0,0 +1,235 @@
+import { Test } from "@nestjs/testing"
+import { mock } from "@starci/jest-preset"
+import { HttpErrorCode } from "./errors/http.error"
+import { FetchHttpClient } from "./fetch-http-client.client"
+
+/** Asymmetric matchers read as `unknown`: jest types them `any`, which may not flow into a property or a typed argument. */
+const anyOf = (type: unknown): unknown => expect.any(type)
+const objectLike = (shape: Record<string, unknown>): unknown => expect.objectContaining(shape)
+
+const build = async (): Promise<FetchHttpClient> => {
+    const moduleRef = await Test.createTestingModule({ providers: [FetchHttpClient] }).compile()
+    return moduleRef.get(FetchHttpClient)
+}
+
+const responseOf = (status = 200) => mock<Response>({ status })
+
+afterEach(() => {
+    jest.restoreAllMocks()
+})
+
+describe("FetchHttpClient JSON requests", () => {
+    it("propagates the explicit id once while preserving unrelated headers", async () => {
+        const client = await build()
+        const response = responseOf()
+        response.text.mockResolvedValue("{}")
+        const send = jest.spyOn(global, "fetch").mockResolvedValue(response)
+
+        await client.request({
+            correlationId: "request-explicit",
+            method: "GET",
+            url: "https://service.test/orders",
+            headers: {
+                "X-Request-ID": "spoofed",
+                "x-request-id": "also-spoofed",
+                TraceParent: "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+                accept: "application/json",
+            },
+            timeoutMs: 2500,
+        })
+
+        expect(send).toHaveBeenCalledWith(
+            "https://service.test/orders",
+            objectLike({ headers: { accept: "application/json", "x-request-id": "request-explicit" } }),
+        )
+    })
+
+    it("sends a JSON request and parses its JSON response", async () => {
+        const client = await build()
+        const response = responseOf(201)
+        response.text.mockResolvedValue('{"created":true}')
+        const send = jest.spyOn(global, "fetch").mockResolvedValue(response)
+
+        await expect(
+            client.request({
+                correlationId: "request-1",
+                method: "POST",
+                url: "https://service.test/orders",
+                headers: { authorization: "Bearer token" },
+                body: { orderId: "order-1" },
+                timeoutMs: 2500,
+            }),
+        ).resolves.toEqual({ status: 201, body: { created: true } })
+
+        expect(send).toHaveBeenCalledWith("https://service.test/orders", {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: "Bearer token", "x-request-id": "request-1" },
+            body: JSON.stringify({ orderId: "order-1" }),
+            signal: anyOf(AbortSignal),
+        })
+    })
+
+    it("returns undefined for an empty response body", async () => {
+        const client = await build()
+        const response = responseOf(204)
+        response.text.mockResolvedValue("")
+        jest.spyOn(global, "fetch").mockResolvedValue(response)
+
+        await expect(
+            client.request({
+                correlationId: "request-1",
+                method: "GET",
+                url: "https://service.test/health",
+                timeoutMs: 2500,
+            }),
+        ).resolves.toEqual({ status: 204, body: undefined })
+
+        expect(fetch).toHaveBeenCalledWith(
+            "https://service.test/health",
+            objectLike({ headers: { "x-request-id": "request-1" } }),
+        )
+        expect(jest.mocked(fetch).mock.calls[0]?.[1]).not.toHaveProperty("body")
+    })
+})
+
+describe("FetchHttpClient form and byte requests", () => {
+    it("encodes form fields and combines a caller cancellation signal with the deadline", async () => {
+        const client = await build()
+        const response = responseOf()
+        response.text.mockResolvedValue("{}")
+        const send = jest.spyOn(global, "fetch").mockResolvedValue(response)
+        const caller = new AbortController()
+
+        await client.request({
+            correlationId: "request-1",
+            method: "POST",
+            url: "https://service.test/token",
+            form: { grant_type: "client_credentials", scope: "orders read" },
+            timeoutMs: 2500,
+            signal: caller.signal,
+        })
+
+        expect(send).toHaveBeenCalledWith(
+            "https://service.test/token",
+            objectLike({
+                headers: { "content-type": "application/x-www-form-urlencoded", "x-request-id": "request-1" },
+                body: "grant_type=client_credentials&scope=orders+read",
+                signal: anyOf(AbortSignal),
+            }),
+        )
+        expect(send.mock.calls[0]?.[1]?.signal).not.toBe(caller.signal)
+    })
+
+    it("sends and receives raw bytes", async () => {
+        const client = await build()
+        const response = responseOf(206)
+        response.arrayBuffer.mockResolvedValue(Uint8Array.from([4, 5, 6]).buffer)
+        const send = jest.spyOn(global, "fetch").mockResolvedValue(response)
+        const bytes = Buffer.from([1, 2, 3])
+
+        await expect(
+            client.request({
+                correlationId: "request-1",
+                method: "PUT",
+                url: "https://service.test/object",
+                bytes,
+                read: "bytes",
+                timeoutMs: 2500,
+            }),
+        ).resolves.toEqual({ status: 206, body: Buffer.from([4, 5, 6]) })
+
+        expect(send).toHaveBeenCalledWith(
+            "https://service.test/object",
+            objectLike({
+                headers: { "content-type": "application/octet-stream", "x-request-id": "request-1" },
+                body: bytes,
+            }),
+        )
+    })
+})
+
+describe("FetchHttpClient response decoding", () => {
+    it("reports a response that is not JSON", async () => {
+        const client = await build()
+        const response = responseOf()
+        response.text.mockResolvedValue("not JSON")
+        jest.spyOn(global, "fetch").mockResolvedValue(response)
+
+        await expect(
+            client.request({
+                correlationId: "request-1",
+                method: "GET",
+                url: "https://service.test/orders",
+                timeoutMs: 2500,
+            }),
+        ).rejects.toMatchObject({ code: HttpErrorCode.BodyUnreadable, cause: anyOf(SyntaxError) })
+    })
+})
+
+describe("FetchHttpClient request failures", () => {
+    it("maps a failure before headers to a network error", async () => {
+        const client = await build()
+        jest.spyOn(global, "fetch").mockRejectedValue("connection refused")
+
+        await expect(
+            client.request({
+                correlationId: "request-1",
+                method: "GET",
+                url: "https://service.test/orders",
+                timeoutMs: 2500,
+            }),
+        ).rejects.toMatchObject({ code: HttpErrorCode.Network, cause: "connection refused" })
+    })
+
+    it("maps a deadline failure before headers to a timeout", async () => {
+        const client = await build()
+        const failure = { name: "TimeoutError" }
+        jest.spyOn(global, "fetch").mockRejectedValue(failure)
+
+        await expect(
+            client.request({
+                correlationId: "request-1",
+                method: "GET",
+                url: "https://service.test/orders",
+                timeoutMs: 2500,
+            }),
+        ).rejects.toMatchObject({ code: HttpErrorCode.Timeout, cause: failure })
+    })
+})
+
+describe("FetchHttpClient response stream failures", () => {
+    it("maps a failure while reading a response to a network error", async () => {
+        const client = await build()
+        const failure = new Error("stream cut")
+        const response = responseOf()
+        response.text.mockRejectedValue(failure)
+        jest.spyOn(global, "fetch").mockResolvedValue(response)
+
+        await expect(
+            client.request({
+                correlationId: "request-1",
+                method: "GET",
+                url: "https://service.test/orders",
+                timeoutMs: 2500,
+            }),
+        ).rejects.toMatchObject({ code: HttpErrorCode.Network, cause: failure })
+    })
+
+    it("maps a deadline while reading bytes to a timeout", async () => {
+        const client = await build()
+        const failure = { name: "TimeoutError" }
+        const response = responseOf()
+        response.arrayBuffer.mockRejectedValue(failure)
+        jest.spyOn(global, "fetch").mockResolvedValue(response)
+
+        await expect(
+            client.request({
+                correlationId: "request-1",
+                method: "GET",
+                url: "https://service.test/object",
+                read: "bytes",
+                timeoutMs: 2500,
+            }),
+        ).rejects.toMatchObject({ code: HttpErrorCode.Timeout, cause: failure })
+    })
+})

package/templates/be/skeleton/src/modules/platform/http/fetch-http-client.client.ts

@@ -0,0 +1,85 @@
+import { Injectable } from "@nestjs/common"
+import { isRecord } from "@modules/platform/primitives"
+import { HttpError, HttpErrorCode } from "./errors/http.error"
+import type { HttpClient, HttpRequest, HttpResponse } from "./http.port"
+
+@Injectable()
+/** The HttpClient adapter over the global `fetch`; the only place outside a spec that calls it. */
+export class FetchHttpClient implements HttpClient {
+    /** Sends `request` with its deadline and reads the body: parsed JSON, or the raw bytes when the request asks for them. */
+    async request(request: HttpRequest): Promise<HttpResponse> {
+        const deadline = AbortSignal.timeout(request.timeoutMs)
+        const signal = request.signal ? AbortSignal.any([deadline, request.signal]) : deadline
+        const response = await this.send(request, signal)
+        if (request.read === "bytes")
+            return {
+                status: response.status,
+                body: await this.received(response.arrayBuffer().then((bytes) => Buffer.from(bytes))),
+            }
+        const text = await this.received(response.text())
+        return { status: response.status, body: text === "" ? undefined : this.parse(text) }
+    }
+
+    /** The body as it arrives; a deadline or a cut while it streams is the same HttpError as one before the headers. */
+    private async received<T>(reading: Promise<T>): Promise<T> {
+        try {
+            return await reading
+        } catch (cause) {
+            throw this.failure(cause)
+        }
+    }
+
+    private failure(cause: unknown): HttpError {
+        // The deadline rejects with a DOMException from the runtime's own realm: compare its name, never its prototype chain.
+        const timedOut = isRecord(cause) && cause.name === "TimeoutError"
+        return new HttpError({ code: timedOut ? HttpErrorCode.Timeout : HttpErrorCode.Network, cause })
+    }
+
+    private async send(request: HttpRequest, signal: AbortSignal): Promise<Response> {
+        try {
+            const body = this.bodyOf(request)
+            return await fetch(request.url, {
+                method: request.method,
+                headers: this.headersOf(request),
+                ...(body === undefined ? {} : { body }),
+                signal,
+            })
+        } catch (cause) {
+            throw this.failure(cause)
+        }
+    }
+
+    /** The explicit id owns correlation; a copied traceparent would take precedence at the receiving logger. */
+    private headersOf(request: HttpRequest): Record<string, string> {
+        const extra = Object.fromEntries(
+            Object.entries(request.headers ?? {}).filter(
+                ([name]) => !["x-request-id", "traceparent"].includes(name.toLowerCase()),
+            ),
+        )
+        return { ...this.contentTypeOf(request), ...extra, "x-request-id": request.correlationId }
+    }
+
+    private contentTypeOf(request: HttpRequest): Record<string, string> {
+        if (request.form !== undefined) return { "content-type": "application/x-www-form-urlencoded" }
+        if (request.bytes !== undefined) return { "content-type": "application/octet-stream" }
+        return request.body === undefined ? {} : { "content-type": "application/json" }
+    }
+
+    private bodyOf(request: HttpRequest): string | Buffer | undefined {
+        return request.bytes ?? this.textOf(request)
+    }
+
+    /** The text body of a request that carries no bytes: the form encoded, else the JSON body, else none. */
+    private textOf(request: HttpRequest): string | undefined {
+        if (request.form !== undefined) return new URLSearchParams(request.form).toString()
+        return request.body === undefined ? undefined : JSON.stringify(request.body)
+    }
+
+    private parse(text: string): unknown {
+        try {
+            return JSON.parse(text)
+        } catch (cause) {
+            throw new HttpError({ code: HttpErrorCode.BodyUnreadable, cause })
+        }
+    }
+}

package/templates/be/skeleton/src/modules/platform/http/graphql-call.mapper.spec.ts

@@ -0,0 +1,92 @@
+import { Test } from "@nestjs/testing"
+import { mock } from "@starci/jest-preset"
+import type { HttpClient } from "./http.port"
+import { callGraphql } from "./graphql-call.mapper"
+
+const SUBJECT: unique symbol = Symbol("http/graphql-call.mapper")
+const subjectFunctions = () => ({ callGraphql })
+
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: SUBJECT, useFactory: subjectFunctions }],
+    }).compile()
+    return moduleRef.get<ReturnType<typeof subjectFunctions>>(SUBJECT)
+}
+
+describe("callGraphql", () => {
+    it("sends the operation and reads its data and string error codes", async () => {
+        const subject = await build()
+
+        const http = mock<HttpClient>()
+        http.request.mockResolvedValue({
+            status: 200,
+            body: {
+                data: { order: { id: "order-1" } },
+                errors: [
+                    { extensions: { code: "ORDER_STALE" } },
+                    { extensions: { code: 7 } },
+                    { extensions: null },
+                    "malformed",
+                ],
+            },
+        })
+
+        await expect(
+            subject.callGraphql(http, {
+                correlationId: "request-1",
+                url: "https://order.test/graphql",
+                query: "query Order($id: ID!) { order(id: $id) { id } }",
+                variables: { id: "order-1" },
+                headers: { authorization: "Bearer token" },
+                timeoutMs: 2500,
+            }),
+        ).resolves.toEqual({ data: { order: { id: "order-1" } }, errorCodes: ["ORDER_STALE"] })
+
+        expect(http.request).toHaveBeenCalledWith({
+            correlationId: "request-1",
+            method: "POST",
+            url: "https://order.test/graphql",
+            headers: { authorization: "Bearer token" },
+            body: {
+                query: "query Order($id: ID!) { order(id: $id) { id } }",
+                variables: { id: "order-1" },
+            },
+            timeoutMs: 2500,
+        })
+    })
+
+    it("returns an empty answer when data and errors do not have GraphQL shapes", async () => {
+        const subject = await build()
+
+        const http = mock<HttpClient>()
+        http.request.mockResolvedValue({ status: 200, body: { data: "malformed", errors: {} } })
+
+        await expect(
+            subject.callGraphql(http, {
+                correlationId: "request-1",
+                url: "https://order.test/graphql",
+                query: "query Health { health }",
+                timeoutMs: 1000,
+            }),
+        ).resolves.toEqual({ data: undefined, errorCodes: [] })
+    })
+
+    it.each([undefined, null, "not a response"])(
+        "returns null when the response body is not an object (%p)",
+        async (body) => {
+            const subject = await build()
+
+            const http = mock<HttpClient>()
+            http.request.mockResolvedValue({ status: 502, body })
+
+            await expect(
+                subject.callGraphql(http, {
+                    correlationId: "request-1",
+                    url: "https://order.test/graphql",
+                    query: "query Health { health }",
+                    timeoutMs: 1000,
+                }),
+            ).resolves.toBeNull()
+        },
+    )
+})

package/templates/be/skeleton/src/modules/platform/http/graphql-call.mapper.ts

@@ -0,0 +1,52 @@
+import { isRecord } from "@modules/platform/primitives"
+import type { HttpClient } from "./http.port"
+
+/** One GraphQL operation sent to another service. */
+export interface GraphqlCall {
+    /** The correlation id of the request or delivery causing this operation. */
+    readonly correlationId: string
+    /** The GraphQL endpoint URL. */
+    readonly url: string
+    /** The operation text. */
+    readonly query: string
+    /** The operation variables. */
+    readonly variables?: Readonly<Record<string, unknown>>
+    /** Extra request headers, such as the bearer token to forward. */
+    readonly headers?: Readonly<Record<string, string>>
+    /** How long to wait for the answer. */
+    readonly timeoutMs: number
+}
+
+/** What a GraphQL service answered: the data object and the codes of the errors it reported. */
+export interface GraphqlAnswer {
+    /** The `data` object, undefined when the operation failed before producing one. */
+    readonly data: Readonly<Record<string, unknown>> | undefined
+    /** The `extensions.code` of every reported error. */
+    readonly errorCodes: ReadonlyArray<string>
+}
+
+/** What a GraphQL call yields: the answer, or null when the body is not a GraphQL response at all. */
+export type GraphqlCallResult = GraphqlAnswer | null
+
+const codesOf = (errors: unknown): Array<string> =>
+    Array.isArray(errors)
+        ? errors.flatMap((error): Array<string> => {
+              const code: unknown = isRecord(error) && isRecord(error.extensions) ? error.extensions.code : undefined
+              return typeof code === "string" ? [code] : []
+          })
+        : []
+
+/** Sends a GraphQL operation and reads the answer; null when the body is not a GraphQL response at all. */
+export const callGraphql = async (http: HttpClient, call: GraphqlCall): Promise<GraphqlCallResult> => {
+    const response = await http.request({
+        correlationId: call.correlationId,
+        method: "POST",
+        url: call.url,
+        ...(call.headers === undefined ? {} : { headers: call.headers }),
+        body: { query: call.query, variables: call.variables },
+        timeoutMs: call.timeoutMs,
+    })
+    const body = response.body
+    if (!isRecord(body)) return null
+    return { data: isRecord(body.data) ? body.data : undefined, errorCodes: codesOf(body.errors) }
+}

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

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

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

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

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

@@ -0,0 +1,19 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { FetchHttpClient } from "./fetch-http-client.client"
+import { HTTP_CLIENT } from "./http.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./http.module-definition"
+
+@Module({})
+/** Provides the HttpClient port backed by `fetch`. */
+export class HttpModule 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: HTTP_CLIENT, useClass: FetchHttpClient }],
+            exports: [HTTP_CLIENT],
+        }
+    }
+}

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

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