@starci/hfs 4.11.0 → 4.11.8

package/templates/be/inbox/platform/migration.sql.tpl

@@ -1,4 +1,4 @@
--- Both the claim and receipt event use the intake transaction; after-commit processing reads the outbox separately.
+-- The claim and the receipt event share the intake transaction; a consumer reads the event from its pgmq queue after commit.
 create table public.inbox (
     source text not null check (source <> ''),
     event_id text not null check (event_id <> ''),
@@ -20,35 +20,16 @@ with check (source <> '');
 revoke all on table public.inbox from public, anon, authenticated;
 grant select, insert on table public.inbox to app_be;
 
-create table public.event_bus (
-    correlation_id varchar(128) not null,
-    event_id text primary key check (event_id <> ''),
-    event_name text not null check (event_name <> ''),
-    payload jsonb not null,
-    recorded_at timestamptz not null default now(),
-    delivered_at timestamptz
-);
-
-alter table public.event_bus enable row level security;
-alter table public.event_bus force row level security;
-
-create policy "event_bus_app_be_select"
-on public.event_bus for select to app_be
-using (event_name <> '');
-
-create policy "event_bus_app_be_insert"
-on public.event_bus for insert to app_be
-with check (event_name <> '');
-
-create policy "event_bus_app_be_update"
-on public.event_bus for update to app_be
-using (event_name <> '')
-with check (event_name <> '');
-
-revoke all on table public.event_bus from public, anon, authenticated;
-grant select, insert, update on table public.event_bus to app_be;
+-- The event bus is pgmq (ruling lite-pgmq-bus-bullmq-jobs; it installs into its own schema pgmq): a publish sends the typed envelope
+-- once to its topic, the event name, in the publisher's own transaction, and pgmq copies it into every consumer queue bound to that
+-- name, so a rolled-back change sends nothing and no relay runs. A reactor's migration declares its consumer: pgmq.create of
+-- '<topic>__<consumer>' and of its dead-letter queue '<topic>__<consumer>__dead', then pgmq.bind_topic('<topic>', '<topic>__<consumer>')
+-- (R258). Each consumer reads its own queue with a visibility timeout, archives a handled message, and moves one past its
+-- maxDeliveries to its dead-letter queue.
+create extension if not exists pgmq;
 
--- The claim of one delivery and the typed envelope write, called through callDbFunction of platform/database (R334).
+-- The claim of one delivery and the bus operations, called through callDbFunction of platform/database (R334). The bus functions are
+-- security definer over pgmq, so the application role holds no grant on the pgmq schema; a read names only a queue bound to a topic.
 create function public.inbox_claim_event(p_source text, p_event_id text)
 returns table (event_id text)
 language sql
@@ -58,14 +39,96 @@ as $$
     returning i.event_id
 $$;
 
-create function public.event_bus_write(p_event_id text, p_event_name text, p_payload jsonb, p_correlation_id varchar)
-returns void
+create function public.event_bus_send(p_event_name text, p_envelope jsonb)
+returns integer
 language sql
+security definer
+set search_path = pg_catalog, pg_temp
+as $$
+    select pgmq.send_topic(p_event_name, p_envelope)
+$$;
+
+create function public.event_bus_read(p_queue text, p_visibility_seconds integer, p_batch integer)
+returns table (msg_id bigint, read_ct integer, message jsonb)
+language sql
+security definer
+set search_path = pg_catalog, pg_temp
+as $$
+    select m.msg_id, m.read_ct, m.message
+      from (select distinct b.queue_name from pgmq.topic_bindings as b where b.queue_name = p_queue) as bound
+     cross join lateral pgmq.read(bound.queue_name, p_visibility_seconds, p_batch) as m
+$$;
+
+create function public.event_bus_archive(p_queue text, p_msg_id bigint)
+returns boolean
+language sql
+security definer
+set search_path = pg_catalog, pg_temp
+as $$
+    select pgmq.archive(p_queue, p_msg_id)
+$$;
+
+create function public.event_bus_bury(p_queue text, p_msg_id bigint, p_read_ct integer, p_message jsonb, p_reason text)
+returns boolean
+language plpgsql
+security definer
+set search_path = pg_catalog, pg_temp
+as $$
+begin
+    if not exists (select 1 from pgmq.topic_bindings as b where b.queue_name = p_queue) then
+        raise exception 'event_bus_bury: % is no consumer queue bound to a topic', p_queue;
+    end if;
+    perform pgmq.send(p_queue || '__dead', jsonb_build_object('readCount', p_read_ct, 'reason', p_reason, 'message', p_message));
+    return pgmq.archive(p_queue, p_msg_id);
+end
+$$;
+
+create function public.event_bus_dead_letters(p_queue text, p_batch integer)
+returns table (msg_id bigint, message jsonb)
+language plpgsql
+security definer
+set search_path = pg_catalog, pg_temp
+as $$
+begin
+    if not exists (select 1 from pgmq.topic_bindings as b where b.queue_name = p_queue) then
+        raise exception 'event_bus_dead_letters: % is no consumer queue bound to a topic', p_queue;
+    end if;
+    return query execute format('select d.msg_id, d.message from pgmq.%I as d order by d.msg_id limit $1', 'q_' || p_queue || '__dead') using p_batch;
+end
+$$;
+
+create function public.event_bus_requeue(p_queue text, p_msg_id bigint)
+returns boolean
+language plpgsql
+security definer
+set search_path = pg_catalog, pg_temp
 as $$
-    insert into public.event_bus (event_id, event_name, payload, correlation_id) values (p_event_id, p_event_name, p_payload, p_correlation_id)
+declare
+    v_dead jsonb;
+begin
+    if not exists (select 1 from pgmq.topic_bindings as b where b.queue_name = p_queue) then
+        raise exception 'event_bus_requeue: % is no consumer queue bound to a topic', p_queue;
+    end if;
+    execute format('delete from pgmq.%I as d where d.msg_id = $1 returning d.message', 'q_' || p_queue || '__dead') into v_dead using p_msg_id;
+    if v_dead is null then
+        return false;
+    end if;
+    perform pgmq.send(p_queue, v_dead -> 'message');
+    return true;
+end
 $$;
 
 revoke all on function public.inbox_claim_event(text, text) from public;
 grant execute on function public.inbox_claim_event(text, text) to app_be;
-revoke all on function public.event_bus_write(text, text, jsonb, varchar) from public;
-grant execute on function public.event_bus_write(text, text, jsonb, varchar) to app_be;
+revoke all on function public.event_bus_send(text, jsonb) from public;
+grant execute on function public.event_bus_send(text, jsonb) to app_be;
+revoke all on function public.event_bus_read(text, integer, integer) from public;
+grant execute on function public.event_bus_read(text, integer, integer) to app_be;
+revoke all on function public.event_bus_archive(text, bigint) from public;
+grant execute on function public.event_bus_archive(text, bigint) to app_be;
+revoke all on function public.event_bus_bury(text, bigint, integer, jsonb, text) from public;
+grant execute on function public.event_bus_bury(text, bigint, integer, jsonb, text) to app_be;
+revoke all on function public.event_bus_dead_letters(text, integer) from public;
+grant execute on function public.event_bus_dead_letters(text, integer) to app_be;
+revoke all on function public.event_bus_requeue(text, bigint) from public;
+grant execute on function public.event_bus_requeue(text, bigint) to app_be;

package/templates/be/inbox/service.spec.ts.tpl

@@ -63,7 +63,7 @@ describe("@@Provider@@InboxService", () => {
 
         it("rolls back the receipt when publishing fails", async () => {
             const { inbox, events, transaction } = await build(true)
-            const failure = new Error("outbox unavailable")
+            const failure = new Error("event bus unavailable")
             events.failNext("publish", failure)
 
             await expect(inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY, correlationId: "request-1" })).rejects.toBe(failure)

package/templates/be/inbox/webhook-door.ts.tpl

@@ -11,8 +11,8 @@ import { @@Event@@Request } from "./dto/@@event@@.request"
 @Controller("webhooks/@@provider@@")
 /**
  * POST /webhooks/@@provider@@, the signed intake door of the @@provider@@ notifier. The signature and replay window are proven
- * first; the verified delivery goes to one domain intake that records a receipt and typed outbox event in its transaction. A separate
- * reactor or job consumes the committed row and dispatches the command.
+ * first; the verified delivery goes to one domain intake that records a receipt and sends its typed event in its transaction. A separate
+ * reactor reads the committed event from its pgmq queue and dispatches the command.
  */
 export class @@Provider@@Webhook {
     constructor(

package/templates/be/patterns/jobs/platform-lite/job-claim.service.spec.ts.tpl

@@ -8,10 +8,10 @@ import { JOBS_MANAGERS } from "./jobs.decorators"
 import { JobClaimService } from "./job-claim.service"
 
 // The statements callDbFunction of platform/database sends for each job function.
-const CLAIM_JOB = "SELECT * FROM job_claim($1, $2, $3, $4, $5, $6)"
-const ADVANCE_JOB = "SELECT * FROM job_advance($1, $2, $3, $4)"
-const COMPLETE_JOB = "SELECT * FROM job_complete($1, $2, $3)"
-const FAIL_JOB = "SELECT * FROM job_fail($1, $2, $3, $4)"
+const CLAIM_JOB = 'SELECT * FROM "public"."job_claim"($1, $2, $3, $4, $5, $6)'
+const ADVANCE_JOB = 'SELECT * FROM "public"."job_advance"($1, $2, $3, $4)'
+const COMPLETE_JOB = 'SELECT * FROM "public"."job_complete"($1, $2, $3)'
+const FAIL_JOB = 'SELECT * FROM "public"."job_fail"($1, $2, $3, $4)'
 
 const AT = "2026-02-03T04:05:06.000Z"
 

package/templates/be/patterns/jobs/platform-lite/job-claim.service.ts.tpl

@@ -46,7 +46,7 @@ export class JobClaimService implements JobClaims {
     /** Claims the delivery; null when the job is done or another worker holds a claim that has not expired. */
     async claim(params: ClaimParams): Promise<ClaimResult> {
         const now = this.clock.now()
-        const rows = await callDbFunction<ClaimedRecord>(this.writer(), "job_claim", [
+        const rows = await callDbFunction<ClaimedRecord>(this.writer(), "public.job_claim", [
             params.kind,
             params.jobKey,
             params.workerId,
@@ -69,17 +69,17 @@ export class JobClaimService implements JobClaims {
 
     /** Records a finished step under the token the caller holds. */
     advance(write: AdvanceWrite): Promise<void> {
-        return this.guarded("job_advance", [write.jobId, write.expectedFencingToken, write.step, this.clock.now()], write)
+        return this.guarded("public.job_advance", [write.jobId, write.expectedFencingToken, write.step, this.clock.now()], write)
     }
 
     /** Completes the job under the token the caller holds. */
     complete(write: GuardedWrite): Promise<void> {
-        return this.guarded("job_complete", [write.jobId, write.expectedFencingToken, this.clock.now()], write)
+        return this.guarded("public.job_complete", [write.jobId, write.expectedFencingToken, this.clock.now()], write)
     }
 
     /** Marks the job failed under the token the caller holds, so BullMQ can retry it. */
     fail(write: FailWrite): Promise<void> {
-        return this.guarded("job_fail", [write.jobId, write.expectedFencingToken, write.reason, this.clock.now()], write)
+        return this.guarded("public.job_fail", [write.jobId, write.expectedFencingToken, write.reason, this.clock.now()], write)
     }
 
     /** The idempotency key of one step of this claim: it includes the token, so a zombie's repeat is a different key than the live worker's. */
@@ -99,7 +99,7 @@ export class JobClaimService implements JobClaims {
 
     /** Runs a guarded function that updates only when the token still matches; no row back means a newer worker owns the job. */
     private async guarded(
-        fn: "job_advance" | "job_complete" | "job_fail",
+        fn: "public.job_advance" | "public.job_complete" | "public.job_fail",
         parameters: Array<unknown>,
         write: GuardedWrite,
     ): Promise<void> {

package/templates/be/patterns/jobs/platform-lite/job-tick.service.spec.ts.tpl

@@ -10,7 +10,7 @@ import { JobTickService, tickMinute } from "./job-tick.service"
 
 // The statements advisoryXactLock and callDbFunction of platform/database send for one firing.
 const LOCK_TICK = "SELECT pg_advisory_xact_lock(hashtextextended($1, 0))"
-const CLAIM_TICK = "SELECT * FROM job_tick_claim($1, $2)"
+const CLAIM_TICK = 'SELECT * FROM "public"."job_tick_claim"($1, $2)'
 
 const AT = "2026-02-03T04:05:06.000Z"
 const TICK: JobTick = { name: "nightly-digest", cron: "0 2 * * *", timeZone: "UTC", queue: "digests", payload: { kind: "nightly" } }

package/templates/be/patterns/jobs/platform-lite/job-tick.service.ts.tpl

@@ -62,7 +62,7 @@ export class JobTickService implements OnApplicationBootstrap {
         const minute = tickMinute(this.clock.now())
         return this.writer().transaction(async (tx) => {
             await advisoryXactLock(tx, `tick:${tick.name}`)
-            const [claim] = await callDbFunction<TickClaim>(tx, "job_tick_claim", [tick.name, minute])
+            const [claim] = await callDbFunction<TickClaim>(tx, "public.job_tick_claim", [tick.name, minute])
             if (claim?.claimed !== true) return false
             await this.outbox.write(tx, tick.queue, tick.payload, `tick:${tick.name}:${minute}`)
             return true

package/templates/be/patterns/queues/platform-lite/queue-outbox.service.spec.ts.tpl

@@ -4,7 +4,7 @@ import { CLOCK } from "@modules/platform/clock"
 import { QueueOutboxService } from "./queue-outbox.service"
 
 // The statement callDbFunction of platform/database sends for queue_write.
-const INSERT_QUEUE_ROW = "SELECT * FROM queue_write($1, $2, $3, $4)"
+const INSERT_QUEUE_ROW = 'SELECT * FROM "public"."queue_write"($1, $2, $3, $4)'
 import { QueueErrorCode } from "./errors/queue.error"
 
 const AT = "2026-02-03T04:05:06.000Z"

package/templates/be/patterns/queues/platform-lite/queue-outbox.service.ts.tpl

@@ -15,6 +15,6 @@ export class QueueOutboxService implements QueueOutbox {
     /** Writes the job in the outbox of the transaction `tx`; the relay adds it to BullMQ after the commit. */
     async write(tx: EntityManager, queue: string, payload: object, correlationId: string): Promise<void> {
         if (!isCorrelationId(correlationId)) throw new QueueError({ code: QueueErrorCode.CorrelationInvalid })
-        await callDbFunction(tx, "queue_write", [queue, JSON.stringify(payload), this.clock.now(), correlationId])
+        await callDbFunction(tx, "public.queue_write", [queue, JSON.stringify(payload), this.clock.now(), correlationId])
     }
 }

package/templates/be/patterns/queues/platform-lite/queue-relay.service.spec.ts.tpl

@@ -11,8 +11,8 @@ import { QueueRelayService } from "./queue-relay.service"
 import type { QueueTransport } from "./queue-transport.port"
 
 // The statements callDbFunction of platform/database sends for the relay's functions.
-const SELECT_WAITING_ROWS = "SELECT * FROM queue_waiting($1)"
-const MARK_ROWS_SENT = "SELECT * FROM queue_mark_sent($1, $2)"
+const SELECT_WAITING_ROWS = 'SELECT * FROM "public"."queue_waiting"($1)'
+const MARK_ROWS_SENT = 'SELECT * FROM "public"."queue_mark_sent"($1, $2)'
 
 const AT = "2026-02-03T04:05:06.000Z"
 

package/templates/be/patterns/queues/platform-lite/queue-relay.service.ts.tpl

@@ -44,7 +44,7 @@ export class QueueRelayService extends OutboxRelayPolicy<QueueRow> {
     }
 
     protected async select(tx: EntityManager): Promise<Array<QueueRow>> {
-        return [...(await callDbFunction<QueueRow>(tx, "queue_waiting", [this.options.relayBatch]))]
+        return [...(await callDbFunction<QueueRow>(tx, "public.queue_waiting", [this.options.relayBatch]))]
     }
 
     protected async deliver(rows: ReadonlyArray<QueueRow>): Promise<void> {
@@ -53,7 +53,7 @@ export class QueueRelayService extends OutboxRelayPolicy<QueueRow> {
     }
 
     protected async mark(tx: EntityManager, rows: ReadonlyArray<QueueRow>): Promise<void> {
-        await callDbFunction(tx, "queue_mark_sent", [rows.map((row) => row.id), this.clock.now()])
+        await callDbFunction(tx, "public.queue_mark_sent", [rows.map((row) => row.id), this.clock.now()])
     }
 
     protected idle(): Promise<void> {

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

@@ -1,6 +1,7 @@
 import type { EnvSource } from "@modules/platform/config"
 import { parseServerConfig } from "@modules/platform/config"
 import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
+import { parseHttpConfig } from "@modules/platform/http"
 import { parseHttpSecurityConfig } from "@modules/platform/http-security"
 
 /** The {{app}} environment values required before composition. */
@@ -9,6 +10,8 @@ export interface {{appPascal}}Env {
     readonly server: ReturnType<typeof parseServerConfig>
     /** The origin allowlist and rate limits. */
     readonly httpSecurity: ReturnType<typeof parseHttpSecurityConfig>
+    /** What the outbound HTTP client trusts beyond Node's bundled certificate authorities. */
+    readonly http: ReturnType<typeof parseHttpConfig>
     /** The primary database connection. */
     readonly database: ReturnType<typeof parsePrimaryDatabaseConfig>
 }
@@ -17,5 +20,6 @@ export interface {{appPascal}}Env {
 export const read{{appPascal}}Env = (env: EnvSource): {{appPascal}}Env => ({
     server: parseServerConfig(env),
     httpSecurity: parseHttpSecurityConfig(env),
+    http: parseHttpConfig(env),
     database: parsePrimaryDatabaseConfig(env),
 })

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

@@ -1,6 +1,7 @@
 import type { HttpSecurityOptions } from "@modules/platform/http-security"
 import type { ServerOptions } from "@modules/platform/config"
 import type { DatabaseConnectionConfig } from "@modules/platform/database"
+import type { HttpOptions } from "@modules/platform/http"
 
 /** Everything the {{app}} app needs from its environment, parsed by `{{app}}.env.ts` and handed to `AppModule.register`. */
 export interface {{appPascal}}Options {
@@ -8,6 +9,8 @@ export interface {{appPascal}}Options {
     readonly server: ServerOptions
     /** The origin allowlist and rate limits. */
     readonly httpSecurity: HttpSecurityOptions
+    /** What the outbound HTTP client trusts beyond Node's bundled certificate authorities. */
+    readonly http: HttpOptions
     /** The primary database connection. */
     readonly database: DatabaseConnectionConfig
 }

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

@@ -30,7 +30,7 @@ export const platformModules = (options: {{appPascal}}Options): Array<DynamicMod
     RetryModule.register({ isGlobal: true }),
     IdsModule.register({ isGlobal: true }),
     LoggingModule.register({ isGlobal: true }),
-    HttpModule.register({ isGlobal: true }),
+    HttpModule.register({ isGlobal: true, ...options.http }),
     I18nModule.register({
         isGlobal: true,
         bundles: [HTTP_MESSAGES, ERRORS_MESSAGES, HTTP_SECURITY_MESSAGES, IDENTITY_MESSAGES],

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

@@ -1,14 +1,19 @@
 import { Test } from "@nestjs/testing"
 import { mock } from "@starci/jest-preset"
+import { Agent } from "undici"
 import { HttpErrorCode } from "./errors/http.error"
 import { FetchHttpClient } from "./fetch-http-client.client"
+import { HTTP_OPTIONS } from "./http.decorators"
+import type { HttpOptions } from "./http.options"
 
 /** 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()
+const build = async (options: HttpOptions = {}): Promise<FetchHttpClient> => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [FetchHttpClient, { provide: HTTP_OPTIONS, useValue: options }],
+    }).compile()
     return moduleRef.get(FetchHttpClient)
 }
 
@@ -233,3 +238,33 @@ describe("FetchHttpClient response stream failures", () => {
         ).rejects.toMatchObject({ code: HttpErrorCode.Timeout, cause: failure })
     })
 })
+
+describe("FetchHttpClient trusted certificate authority", () => {
+    it("sends through fetch's own pool and has nothing to close when no CA is trusted", async () => {
+        const client = await build()
+        const response = responseOf()
+        response.text.mockResolvedValue("{}")
+        const send = jest.spyOn(global, "fetch").mockResolvedValue(response)
+
+        await client.request({ correlationId: "request-1", method: "GET", url: "https://service.test/orders", timeoutMs: 2500 })
+
+        expect(send.mock.calls[0]?.[1]).not.toHaveProperty("dispatcher")
+        await expect(client.onModuleDestroy()).resolves.toBeUndefined()
+    })
+
+    it("sends every request through one pool that trusts the CA, and closes it when the app stops", async () => {
+        const client = await build({ trustedCa: "the run's fake CA" })
+        const response = responseOf()
+        response.text.mockResolvedValue("{}")
+        const send = jest.spyOn(global, "fetch").mockResolvedValue(response)
+
+        await client.request({ correlationId: "request-1", method: "GET", url: "https://idp.test/jwks", timeoutMs: 2500 })
+        await client.request({ correlationId: "request-2", method: "GET", url: "https://service.test/orders", timeoutMs: 2500 })
+
+        const pool = send.mock.calls[0]?.[1]?.dispatcher
+        expect(pool).toBeInstanceOf(Agent)
+        expect(send.mock.calls[1]?.[1]?.dispatcher).toBe(pool)
+        await client.onModuleDestroy()
+        expect(pool).toHaveProperty("closed", true)
+    })
+})

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

@@ -1,11 +1,34 @@
+import { rootCertificates } from "node:tls"
 import { Injectable } from "@nestjs/common"
+import type { OnModuleDestroy } from "@nestjs/common"
+import { Agent } from "undici"
 import { isRecord } from "@modules/platform/primitives"
 import { HttpError, HttpErrorCode } from "./errors/http.error"
+import { InjectHttpOptions } from "./http.decorators"
+import type { HttpOptions } from "./http.options"
 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 {
+export class FetchHttpClient implements HttpClient, OnModuleDestroy {
+    /**
+     * The connection pool that adds `trustedCa` to Node's bundled roots (the CA joins the trusted list, verification stays
+     * on); absent without one, so every request goes through fetch's own default pool as before.
+     */
+    private readonly dispatcher: Agent | undefined
+
+    constructor(@InjectHttpOptions() options: HttpOptions) {
+        this.dispatcher =
+            options.trustedCa === undefined
+                ? undefined
+                : new Agent({ connect: { ca: [...rootCertificates, options.trustedCa] } })
+    }
+
+    /** Closes the pool of the trusted CA, if the app configured one, when the app stops. */
+    async onModuleDestroy(): Promise<void> {
+        await this.dispatcher?.close()
+    }
+
     /** 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)
@@ -38,17 +61,27 @@ export class FetchHttpClient implements HttpClient {
     private async send(request: HttpRequest, signal: AbortSignal): Promise<Response> {
         try {
             const body = this.bodyOf(request)
-            return await fetch(request.url, {
+            const init: RequestInit = {
                 method: request.method,
                 headers: this.headersOf(request),
                 ...(body === undefined ? {} : { body }),
                 signal,
-            })
+            }
+            return await fetch(request.url, this.routed(init))
         } catch (cause) {
             throw this.failure(cause)
         }
     }
 
+    /**
+     * `init` sent through the trusted-CA pool when there is one. @types/node declares fetch over its own copy of undici's
+     * types, which the Agent of the undici package does not match nominally; `Object.assign` keeps the declared type of
+     * `init` and hands fetch the Agent itself.
+     */
+    private routed(init: RequestInit): RequestInit {
+        return this.dispatcher === undefined ? init : Object.assign(init, { dispatcher: this.dispatcher })
+    }
+
     /** 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(

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

@@ -0,0 +1,11 @@
+import type { EnvSource } from "@modules/platform/config"
+import type { HttpOptions } from "./http.options"
+
+/**
+ * Reads the http options: `HTTP_TRUSTED_CA` (or the file `HTTP_TRUSTED_CA_FILE` names) is the PEM of one more certificate
+ * authority the outbound client trusts beside Node's bundled roots; undeclared, the client trusts the bundled roots alone.
+ */
+export const parseHttpConfig = (env: EnvSource): HttpOptions => {
+    const trustedCa = env.optional("HTTP_TRUSTED_CA")
+    return trustedCa === undefined ? {} : { trustedCa }
+}

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

@@ -1,9 +1,16 @@
 import { injector } from "@modules/platform/composition"
 import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { HttpOptions } from "./http.options"
 import type { HttpClient } from "./http.port"
 
+/** Token of the http options, exported so a spec can provide it. */
+export const HTTP_OPTIONS: unique symbol = Symbol("platform.http.options")
+
 /** Token of the HttpClient port. */
 export const HTTP_CLIENT: unique symbol = Symbol("platform.http.client")
 
+/** Injects the options of the http capability. Parameter type: HttpOptions. */
+export const InjectHttpOptions = (): TypedParameterDecorator<HttpOptions> => injector<HttpOptions>(HTTP_OPTIONS)
+
 /** 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

@@ -1,7 +1,9 @@
 import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { HTTP_OPTIONS } from "./http.decorators"
 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()
+export const { ConfigurableModuleClass, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<HttpOptions>({ optionsInjectionToken: HTTP_OPTIONS })
+        .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+        .build()

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

@@ -1,2 +1,9 @@
-/** The http capability takes no options; the empty record keeps `isGlobal` assignable through the configurable module. */
-export type HttpOptions = Record<never, never>
+/** The options of the http capability: what the outbound client trusts beyond Node's bundled certificate authorities. */
+export interface HttpOptions {
+    /**
+     * PEM of one more certificate authority the client trusts, beside Node's bundled roots and never instead of them, so
+     * every other host is still verified as before (the test world passes its per-run fake CA, `w.fake.<name>.ca`).
+     * Absent, the client trusts the bundled roots alone. Verification is never turned off.
+     */
+    readonly trustedCa?: string
+}

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

@@ -1,3 +1,5 @@
 export { HTTP_ERROR_KINDS } from "./errors/http.error"
 export { HTTP_MESSAGES } from "./messages/http.messages"
+export { parseHttpConfig } from "./http.config"
 export { HttpModule } from "./http.module"
+export type { HttpOptions } from "./http.options"

package/templates/be/skeleton-lite/src/modules/platform/database/database.client.spec.ts

@@ -0,0 +1,96 @@
+import { Test } from "@nestjs/testing"
+import { mockEntityManager } from "@starci/jest-preset"
+import { advisoryXactLock, callDbFunction, notify } from "./database.client"
+import { DatabaseError, DatabaseErrorCode } from "./errors/database.error"
+
+const DATABASE_CLIENT = Symbol("database-client")
+
+const setup = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: DATABASE_CLIENT, useFactory: () => ({ advisoryXactLock, callDbFunction, notify }) }],
+    }).compile()
+    return moduleRef.get<{
+        readonly advisoryXactLock: typeof advisoryXactLock
+        readonly callDbFunction: typeof callDbFunction
+        readonly notify: typeof notify
+    }>(DATABASE_CLIENT)
+}
+
+/** What `callDbFunction` throws for `name`, or null when it builds a call. */
+const refusalOf = async (name: string): Promise<unknown> => {
+    const client = await setup()
+    try {
+        await client.callDbFunction(mockEntityManager({ query: ['SELECT * FROM "public"."never"()', []] }), name, [])
+        return null
+    } catch (error) {
+        return error
+    }
+}
+
+describe("callDbFunction", () => {
+    it("calls a schema-qualified function with each part quoted and the arguments as numbered parameters", async () => {
+        const client = await setup()
+        const manager = mockEntityManager({ query: ['SELECT * FROM "public"."job_claim"($1, $2)', [{ id: "job-1" }]] })
+
+        const rows = await client.callDbFunction<{ id: string }>(manager, "public.job_claim", ["mail", 3])
+
+        expect(rows).toEqual([{ id: "job-1" }])
+        expect(manager.query).toHaveBeenCalledWith('SELECT * FROM "public"."job_claim"($1, $2)', ["mail", 3])
+    })
+
+    it("calls a bare pg built-in of the canon's list in pg_catalog", async () => {
+        const client = await setup()
+        const manager = mockEntityManager({ query: ['SELECT * FROM "pg_catalog"."to_regproc"($1)', [{ to_regproc: null }]] })
+
+        const rows = await client.callDbFunction<{ to_regproc: string | null }>(manager, "to_regproc", ["public.job_claim"])
+
+        expect(rows).toEqual([{ to_regproc: null }])
+    })
+
+    it("calls a function of another schema with no arguments", async () => {
+        const client = await setup()
+        const manager = mockEntityManager({ query: ['SELECT * FROM "be_access"."chat_target_member"()', []] })
+
+        const rows = await client.callDbFunction(manager, "be_access.chat_target_member", [])
+
+        expect(rows).toEqual([])
+    })
+
+    it.each([
+        ["a bare name that is not a listed built-in", "job_claim"],
+        ["a pg_catalog name spelt out", "pg_catalog.pg_terminate_backend"],
+        ["a quote inside a part", 'public."job_claim'],
+        ["a second statement smuggled into the name", "public.job_claim(); SELECT 1; --"],
+        ["an upper-case part", "public.Job_Claim"],
+        ["three parts", "db.public.job_claim"],
+        ["an empty schema", ".job_claim"],
+        ["an empty name", ""],
+    ])("refuses %s before any SQL runs", async (_case, name) => {
+        const refusal = await refusalOf(name)
+
+        expect(refusal).toBeInstanceOf(DatabaseError)
+        expect(refusal).toMatchObject({ code: DatabaseErrorCode.IdentifierRejected, params: { name } })
+    })
+})
+
+describe("advisoryXactLock", () => {
+    it("locks the 64-bit hash of the key for the transaction", async () => {
+        const client = await setup()
+        const manager = mockEntityManager({ query: ["SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [{}]] })
+
+        await expect(client.advisoryXactLock(manager, "jobs:mail")).resolves.toBeUndefined()
+
+        expect(manager.query).toHaveBeenCalledWith("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", ["jobs:mail"])
+    })
+})
+
+describe("notify", () => {
+    it("sends the payload on the channel", async () => {
+        const client = await setup()
+        const manager = mockEntityManager({ query: ["SELECT pg_notify($1, $2)", [{}]] })
+
+        await expect(client.notify(manager, "jobs", '{"id":"job-1"}')).resolves.toBeUndefined()
+
+        expect(manager.query).toHaveBeenCalledWith("SELECT pg_notify($1, $2)", ["jobs", '{"id":"job-1"}'])
+    })
+})