@starci/hfs 4.3.0 → 4.4.1

package/templates/be/patterns/queues/platform/queue.module-definition.ts.tpl

@@ -1,9 +1,9 @@
 import { ConfigurableModuleBuilder } from "@nestjs/common"
 import { QUEUE_OPTIONS } from "./queue.decorators"
-import type { QueueOptions } from "./queue.options"
+import type { QueueRegistrationOptions } from "./queue.options"
 
 /** The configurable-module base of the queues; `isGlobal` is decided by the app root. */
-export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<QueueOptions>({
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<QueueRegistrationOptions>({
     optionsInjectionToken: QUEUE_OPTIONS,
 })
     .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))

package/templates/be/patterns/queues/platform/queue.module.ts.tpl

@@ -28,6 +28,17 @@ export class QueueModule extends ConfigurableModuleClass {
     /** Registers the capability once per app that enqueues or processes jobs. */
     static register(options: typeof OPTIONS_TYPE): DynamicModule {
         const base = super.register(options)
+        if (options.outboxOnly === true) {
+            return {
+                ...base,
+                providers: [
+                    ...(base.providers ?? []),
+                    QueueOutboxService,
+                    { provide: QUEUE_OUTBOX, useExisting: QueueOutboxService },
+                ],
+                exports: [QUEUE_OUTBOX],
+            }
+        }
         return {
             ...base,
             providers: [

package/templates/be/patterns/queues/platform/queue.options.ts.tpl

@@ -3,6 +3,8 @@ import type { QueueSchedulerDefinition } from "./queue.contracts"
 
 /** What the queues of one app need: where Redis is, how the relay and the workers run, which connections hold an outbox, and the schedulers it registers. */
 export interface QueueOptions {
+    /** The runtime registration owns the relay, workers and schedulers. */
+    readonly outboxOnly?: false
     /** The Redis host BullMQ talks to. */
     readonly redisHost: string
     /** The Redis port. */
@@ -22,3 +24,11 @@ export interface QueueOptions {
     /** The job schedulers the app registers at boot; BullMQ upserts them by id, so a pool of replicas fires each one once per interval. */
     readonly schedulers: ReadonlyArray<QueueSchedulerDefinition>
 }
+
+/** A one-off producer writes an outbox row and exits; the running app owns delivery. */
+export interface QueueOutboxOnlyOptions {
+    readonly outboxOnly: true
+}
+
+/** Registers either the running queue capability or only its transactional writer. */
+export type QueueRegistrationOptions = QueueOptions | QueueOutboxOnlyOptions

package/templates/be/patterns/queues/queue.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Queue@@Options } from "./@@queue@@.options"
+
+/** The configurable-module base of the @@queue@@ module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Queue@@Options>().setClassMethodName("register").build()

package/templates/be/patterns/queues/queue.module.ts.tpl

@@ -1,6 +1,7 @@
 import { Module } from "@nestjs/common"
+import { ConfigurableModuleClass } from "./@@queue@@.module-definition"
 import { @@Queue@@Queue } from "./@@queue@@.queue"
 
 @Module({ providers: [@@Queue@@Queue], exports: [@@Queue@@Queue] })
 /** The @@queue@@ queue: its typed producer, imported by the domain module whose service enqueues. */
-export class @@Queue@@Module {}
+export class @@Queue@@Module extends ConfigurableModuleClass {}

package/templates/be/patterns/queues/queue.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The @@queue@@ module takes no options yet. */
+export type @@Queue@@Options = Record<string, never>

package/templates/be/patterns/reactors/message.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Reactor@@MessageOptions } from "./@@reactor@@-message.options"
+
+/** The configurable-module base of the @@reactor@@-message module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Reactor@@MessageOptions>().setClassMethodName("register").build()

package/templates/be/patterns/reactors/message.module.ts.tpl

@@ -4,14 +4,17 @@ import { InjectEventConsumerRegistry } from "@modules/platform/event-bus"
 import type { EventConsumerRegistry } from "@modules/platform/event-bus"
 import { @@Reactor@@Module } from "../../@@reactor@@.module"
 import { @@Event@@Consumer } from "./@@event@@.consumer"
+import { ConfigurableModuleClass } from "./@@reactor@@-message.module-definition"
 
-@Module({ imports: [@@Reactor@@Module], providers: [@@Event@@Consumer] })
+@Module({ imports: [@@Reactor@@Module.register({})], providers: [@@Event@@Consumer] })
 /** The message transport of the @@reactor@@ reactor: registers its consumers with the event bus; a worker or api app composes it. */
-export class @@Reactor@@MessageModule implements OnModuleInit {
+export class @@Reactor@@MessageModule extends ConfigurableModuleClass implements OnModuleInit {
     constructor(
         @InjectEventConsumerRegistry() private readonly registry: EventConsumerRegistry,
         private readonly @@eventCamel@@Consumer: @@Event@@Consumer,
-    ) {}
+    ) {
+        super()
+    }
 
     /** Hands every consumer to the registry. */
     onModuleInit(): void {

package/templates/be/patterns/reactors/message.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The @@reactor@@-message module takes no options yet. */
+export type @@Reactor@@MessageOptions = Record<string, never>

package/templates/be/patterns/reactors/reactor.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Reactor@@Options } from "./@@reactor@@.options"
+
+/** The configurable-module base of the @@reactor@@ module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Reactor@@Options>().setClassMethodName("register").build()

package/templates/be/patterns/reactors/reactor.module.ts.tpl

@@ -1,6 +1,7 @@
 import { Module } from "@nestjs/common"
+import { ConfigurableModuleClass } from "./@@reactor@@.module-definition"
 import { @@Action@@Handler } from "./application/@@action@@.handler"
 
 @Module({ providers: [@@Action@@Handler] })
 /** The @@reactor@@ reactor: the handler its consumers dispatch to. */
-export class @@Reactor@@Module {}
+export class @@Reactor@@Module extends ConfigurableModuleClass {}

package/templates/be/patterns/reactors/reactor.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The @@reactor@@ module takes no options yet. */
+export type @@Reactor@@Options = Record<string, never>

package/templates/be/patterns/realtime/channel.gateway.spec.ts.tpl

@@ -0,0 +1,188 @@
+import { Test } from "@nestjs/testing"
+import { MESSAGE_MAPPING_METADATA } from "@nestjs/websockets/constants"
+import { @@service@@ } from "@@serviceModule@@"
+import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
+import { SupabaseErrorCode } from "@modules/integrations/supabase"
+import type { Principal } from "@modules/platform/cqrs"
+import { ok, refused } from "@modules/platform/primitives"
+import { REALTIME_HUB } from "@modules/platform/realtime"
+import type { RealtimeHub, RealtimeTopic } from "@modules/platform/realtime"
+import { @@Channel@@Gateway } from "./@@channel@@.gateway"
+import { @@Channel@@WebsocketModule } from "./@@channel@@-websocket.module"
+import type { @@Channel@@Namespace, @@Channel@@Socket } from "./@@channel@@-websocket.module"
+
+const principal: Principal = { id: "p-1", role: "authenticated" }
+
+/** A recording hub whose stream ends when the transport returns its iterator. */
+const hubAnswering = (frame: unknown = undefined) => {
+    const topics: Array<string> = []
+    const released: Array<string> = []
+    const hub: RealtimeHub = {
+        publish: () => undefined,
+        subscriberCount: () => 0,
+        subscribe: <T extends object>(topic: RealtimeTopic<T>): AsyncIterable<T> => {
+            topics.push(topic.name)
+            let release: () => void = () => undefined
+            const closed = new Promise<void>((resolve) => { release = resolve })
+            let sent = false
+            return {
+                [Symbol.asyncIterator]: () => ({
+                    next: async (): Promise<IteratorResult<T>> => {
+                        if (!sent && topic.accepts(frame)) {
+                            sent = true
+                            return { done: false, value: frame }
+                        }
+                        await closed
+                        return { done: true, value: undefined }
+                    },
+                    return: async (): Promise<IteratorResult<T>> => {
+                        released.push(topic.name)
+                        release()
+                        return { done: true, value: undefined }
+                    },
+                }),
+            }
+        },
+    }
+    return { hub, topics, released }
+}
+
+/** The adapter calls middleware first and only then announces a connection. */
+const namespaceAnswering = () => {
+    let middleware: Parameters<@@Channel@@Namespace["use"]>[0] = (_client, next) => next(new Error("Uninitialized"))
+    let connect: Parameters<@@Channel@@Namespace["on"]>[1] = () => undefined
+    const namespace: @@Channel@@Namespace = {
+        use: (listener) => { middleware = listener },
+        on: (_event, listener) => { connect = listener },
+    }
+    const authenticate = (client: @@Channel@@Socket) => new Promise<void>((resolve, reject) => {
+        middleware(client, (error) => error === undefined ? resolve() : reject(error))
+    })
+    return { namespace, authenticate, connect: (client: @@Channel@@Socket) => connect(client) }
+}
+
+const socketOf = (id: string, auth: Readonly<Record<string, unknown>> = { accessToken: "signed-token" }) => {
+    let connected = true
+    let disconnect: () => void = () => undefined
+    let delivered: () => void = () => undefined
+    const pushed = new Promise<void>((resolve) => { delivered = resolve })
+    const data: { principal?: Principal } = {}
+    const socket = {
+        id,
+        get connected(): boolean { return connected },
+        handshake: { auth },
+        data,
+        emit: jest.fn(() => delivered()),
+        once: (_event: "disconnect", listener: () => void) => { disconnect = listener },
+        disconnect: jest.fn((_close: boolean) => { connected = false; disconnect() }),
+    } satisfies @@Channel@@Socket
+    return { socket, pushed }
+}
+
+const build = async (hub: RealtimeHub, verify: VerifySupabaseAccessToken) => {
+    const moduleRef = await Test.createTestingModule({
+        imports: [@@Channel@@WebsocketModule.register({ verifyAccessToken: verify })],
+    })
+        .useMocker((token) => token === REALTIME_HUB ? hub : undefined)
+        .compile()
+    const door = moduleRef.get(@@Channel@@Gateway)
+    const transport = moduleRef.get(@@Channel@@WebsocketModule)
+    const adapter = namespaceAnswering()
+    door.namespace = adapter.namespace
+    transport.onModuleInit()
+    return { door, transport, adapter }
+}
+
+describe("@@Channel@@Gateway", () => {
+    it("builds the topic only from the verified principal, ignoring handshake principal and topic claims", async () => {
+        const { hub, topics } = hubAnswering()
+        const verify: VerifySupabaseAccessToken = jest.fn().mockResolvedValue(ok(principal))
+        const { transport, adapter } = await build(hub, verify)
+        const { socket } = socketOf("socket-1", { accessToken: "signed-token", principal: { id: "p-2" }, topic: "foreign" })
+
+        await adapter.authenticate(socket)
+        adapter.connect(socket)
+
+        expect(verify).toHaveBeenCalledWith("signed-token")
+        expect(socket.data.principal).toEqual(principal)
+        expect(topics).toEqual([@@service@@(principal.id).name])
+        await transport.onModuleDestroy()
+    })
+
+    it("isolates another authenticated principal's topic", async () => {
+        const { hub, topics } = hubAnswering()
+        const verify: VerifySupabaseAccessToken = jest.fn().mockResolvedValue(ok({ id: "p-2", role: "authenticated" }))
+        const { transport, adapter } = await build(hub, verify)
+        const { socket } = socketOf("socket-2")
+
+        await adapter.authenticate(socket)
+        adapter.connect(socket)
+
+        expect(topics).toEqual([@@service@@("p-2").name])
+        expect(topics).not.toContain(@@service@@(principal.id).name)
+        await transport.onModuleDestroy()
+    })
+
+    it("pushes a hub frame automatically and releases the iterator on disconnect", async () => {
+        const frame = { id: "x-1" }
+        const { hub, released } = hubAnswering(frame)
+        const verify: VerifySupabaseAccessToken = jest.fn().mockResolvedValue(ok(principal))
+        const { transport, adapter } = await build(hub, verify)
+        const { socket, pushed } = socketOf("socket-1")
+
+        await adapter.authenticate(socket)
+        adapter.connect(socket)
+        await pushed
+        socket.disconnect(true)
+
+        expect(socket.emit).toHaveBeenCalledWith("@@channelCamel@@Changed", frame)
+        expect(released).toEqual([@@service@@(principal.id).name])
+        await transport.onModuleDestroy()
+    })
+
+    it.each([{}, { accessToken: "" }, { accessToken: 42 }])("refuses a missing or malformed access token without invoking the verifier", async (auth) => {
+        const { hub, topics } = hubAnswering()
+        const verify: VerifySupabaseAccessToken = jest.fn()
+        const { adapter } = await build(hub, verify)
+        const { socket } = socketOf("socket-1", auth)
+        socket.data.principal = principal
+
+        await expect(adapter.authenticate(socket)).rejects.toThrow("Unauthorized")
+
+        expect(verify).not.toHaveBeenCalled()
+        expect(socket.data.principal).toBeUndefined()
+        expect(topics).toEqual([])
+    })
+
+    it("refuses a rejected token and clears a prior principal", async () => {
+        const { hub, topics } = hubAnswering()
+        const verify: VerifySupabaseAccessToken = jest.fn().mockResolvedValue(refused(SupabaseErrorCode.AccessTokenInvalid))
+        const { adapter } = await build(hub, verify)
+        const { socket } = socketOf("socket-1")
+        socket.data.principal = principal
+
+        await expect(adapter.authenticate(socket)).rejects.toThrow("Unauthorized")
+
+        expect(socket.data.principal).toBeUndefined()
+        expect(topics).toEqual([])
+    })
+
+    it("refuses a connection that bypasses authentication without opening a hub stream", async () => {
+        const { hub, topics } = hubAnswering()
+        const { adapter } = await build(hub, jest.fn())
+        const { socket } = socketOf("socket-1")
+
+        adapter.connect(socket)
+
+        expect(socket.disconnect).toHaveBeenCalledWith(true)
+        expect(topics).toEqual([])
+    })
+
+    it("has no inbound application message handler", async () => {
+        const { hub } = hubAnswering()
+        const { door } = await build(hub, jest.fn())
+
+        expect(Reflect.getMetadata(MESSAGE_MAPPING_METADATA, door.frames)).toBeUndefined()
+        expect(Object.getOwnPropertyNames(@@Channel@@Gateway.prototype)).toEqual(["constructor", "frames"])
+    })
+})

package/templates/be/patterns/realtime/channel.gateway.ts.tpl

@@ -0,0 +1,22 @@
+import { WebSocketGateway, WebSocketServer } from "@nestjs/websockets"
+import { @@service@@ } from "@@serviceModule@@"
+import type { @@Channel@@Frame } from "@@serviceModule@@"
+import type { Principal } from "@modules/platform/cqrs"
+import { InjectRealtimeHub } from "@modules/platform/realtime"
+import type { RealtimeHub } from "@modules/platform/realtime"
+import type { @@Channel@@Namespace } from "./@@channel@@-websocket.module"
+
+@WebSocketGateway({ namespace: "/@@channel@@", transports: ["websocket"] })
+/** The push-only @@channel@@ door: its module authenticates each connection before opening the principal's stream. */
+export class @@Channel@@Gateway {
+    /** The namespace created by the app's socket.io adapter; the module installs authentication before the app listens. */
+    @WebSocketServer()
+    namespace!: @@Channel@@Namespace
+
+    constructor(@InjectRealtimeHub() private readonly hub: RealtimeHub) {}
+
+    /** The domain contract builds this principal-wide topic; the reactor publishes through the same builder. */
+    frames(principal: Principal): AsyncIterable<@@Channel@@Frame> {
+        return this.hub.subscribe(@@service@@(principal.id))
+    }
+}

package/templates/be/patterns/realtime/channel.graphql.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Channel@@GraphqlOptions } from "./@@channel@@-graphql.options"
+
+/** The configurable-module base of the @@channel@@-graphql module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Channel@@GraphqlOptions>().setClassMethodName("register").build()

package/templates/be/patterns/realtime/channel.graphql.module.ts.tpl

@@ -1,6 +1,7 @@
 import { Module } from "@nestjs/common"
+import { ConfigurableModuleClass } from "./@@channel@@-graphql.module-definition"
 import { @@Channel@@Subscription } from "./@@channel@@.subscription"
 
 @Module({ providers: [@@Channel@@Subscription] })
 /** The GraphQL transport of the @@channel@@ channel: its subscription door; the hub comes from the app's realtime capability. */
-export class @@Channel@@GraphqlModule {}
+export class @@Channel@@GraphqlModule extends ConfigurableModuleClass {}

package/templates/be/patterns/realtime/channel.graphql.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The @@channel@@-graphql module takes no options yet. */
+export type @@Channel@@GraphqlOptions = Record<string, never>

package/templates/be/patterns/realtime/channel.websocket.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Channel@@WebsocketOptions } from "./@@channel@@-websocket.options"
+
+/** The configurable-module base of the @@channel@@-websocket module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Channel@@WebsocketOptions>().setClassMethodName("register").build()

package/templates/be/patterns/realtime/channel.websocket.module.ts.tpl

@@ -0,0 +1,110 @@
+import { Module } from "@nestjs/common"
+import type { OnModuleDestroy, OnModuleInit } from "@nestjs/common"
+import type { @@Channel@@Frame } from "@@serviceModule@@"
+import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
+import { injector } from "@modules/platform/composition"
+import type { Principal } from "@modules/platform/cqrs"
+import { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } from "./@@channel@@-websocket.module-definition"
+import type { @@Channel@@WebsocketOptions } from "./@@channel@@-websocket.options"
+import { @@Channel@@Gateway } from "./@@channel@@.gateway"
+
+const ACCESS_TOKEN_VERIFIER: unique symbol = Symbol("@@channel@@.access-token-verifier")
+
+/** The socket.io surface used here; the adapter and the socket library remain owned by platform/realtime. */
+export interface @@Channel@@Socket {
+    /** The adapter's connection identifier. */
+    readonly id: string
+    /** Whether the connection is still open. */
+    readonly connected: boolean
+    /** Untrusted handshake input: only its access token is read. */
+    readonly handshake: { readonly auth: Readonly<Record<string, unknown>> }
+    /** Server-side state: middleware replaces any previous principal with verified claims. */
+    readonly data: { principal?: Principal }
+    /** Sends one frame to this authenticated socket. */
+    emit(event: "@@channelCamel@@Changed", frame: @@Channel@@Frame): void
+    /** Releases the stream when the connection ends. */
+    once(event: "disconnect", listener: () => void): void
+    /** Closes a refused or failed connection. */
+    disconnect(close: boolean): void
+}
+
+/** A namespace from the app's socket.io adapter. No inbound application events are registered. */
+export interface @@Channel@@Namespace {
+    /** Runs authentication before the connection event. */
+    use(middleware: (client: @@Channel@@Socket, next: (error?: Error) => void) => void): void
+    /** Automatically opens the authenticated client's push stream. */
+    on(event: "connection", listener: (client: @@Channel@@Socket) => void): void
+}
+
+@Module({
+    providers: [
+        @@Channel@@Gateway,
+        { provide: ACCESS_TOKEN_VERIFIER, useFactory: (options: @@Channel@@WebsocketOptions) => options.verifyAccessToken, inject: [MODULE_OPTIONS_TOKEN] },
+    ],
+})
+/** The socket transport: verifies each connection, forwards hub frames and releases every disconnected subscription. */
+export class @@Channel@@WebsocketModule extends ConfigurableModuleClass implements OnModuleInit, OnModuleDestroy {
+    private readonly streams = new Map<string, AsyncIterator<@@Channel@@Frame>>()
+
+    constructor(
+        private readonly gateway: @@Channel@@Gateway,
+        @injector<VerifySupabaseAccessToken>(ACCESS_TOKEN_VERIFIER)
+        private readonly verifyAccessToken: VerifySupabaseAccessToken,
+    ) {
+        super()
+    }
+
+    /** Nest creates gateway namespaces before module initialization and starts listening afterwards. */
+    onModuleInit(): void {
+        this.gateway.namespace.use((client, next) => {
+            void this.authenticate(client).then(() => next(), () => next(new Error("Unauthorized")))
+        })
+        this.gateway.namespace.on("connection", (client) => {
+            void this.push(client).catch(() => client.disconnect(true))
+        })
+    }
+
+    /** Releases all hub iterators when the app shuts down. */
+    async onModuleDestroy(): Promise<void> {
+        await Promise.all([...this.streams.keys()].map((id) => this.release(id)))
+    }
+
+    private async authenticate(client: @@Channel@@Socket): Promise<void> {
+        client.data.principal = undefined
+        const token = client.handshake.auth.accessToken
+        if (typeof token !== "string" || token.length === 0) throw new Error("Unauthorized")
+        const verified = await this.verifyAccessToken(token)
+        if (verified.kind !== "ok" || verified.value.role !== "authenticated" || verified.value.id.length === 0) {
+            throw new Error("Unauthorized")
+        }
+        client.data.principal = verified.value
+    }
+
+    private async push(client: @@Channel@@Socket): Promise<void> {
+        const principal = client.data.principal
+        if (principal === undefined) {
+            client.disconnect(true)
+            return
+        }
+        const iterator = this.gateway.frames(principal)[Symbol.asyncIterator]()
+        this.streams.set(client.id, iterator)
+        client.once("disconnect", () => {
+            void this.release(client.id).catch(() => client.disconnect(true))
+        })
+        try {
+            while (client.connected) {
+                const frame = await iterator.next()
+                if (frame.done || !client.connected) break
+                client.emit("@@channelCamel@@Changed", frame.value)
+            }
+        } finally {
+            await this.release(client.id)
+        }
+    }
+
+    private async release(id: string): Promise<void> {
+        const iterator = this.streams.get(id)
+        this.streams.delete(id)
+        await iterator?.return?.()
+    }
+}

package/templates/be/patterns/realtime/channel.websocket.options.ts.tpl

@@ -0,0 +1,7 @@
+import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
+
+/** The options of the @@channel@@ socket transport: the cryptographic verifier that authenticates each connection. */
+export interface @@Channel@@WebsocketOptions {
+    /** Verifies the access token of a handshake with the same verifier identity uses. */
+    readonly verifyAccessToken: VerifySupabaseAccessToken
+}

package/templates/be/patterns/saga/saga.message.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Saga@@MessageOptions } from "./@@saga@@-message.options"
+
+/** The configurable-module base of the @@saga@@-message module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Saga@@MessageOptions>().setClassMethodName("register").build()

package/templates/be/patterns/saga/saga.message.module.ts.tpl

@@ -5,15 +5,18 @@ import type { EventConsumerRegistry } from "@modules/platform/event-bus"
 import { @@Saga@@Module } from "../../@@saga@@.module"
 import { @@Done@@Consumer } from "./@@done@@.consumer"
 import { @@Failed@@Consumer } from "./@@failed@@.consumer"
+import { ConfigurableModuleClass } from "./@@saga@@-message.module-definition"
 
-@Module({ imports: [@@Saga@@Module], providers: [@@Done@@Consumer, @@Failed@@Consumer] })
+@Module({ imports: [@@Saga@@Module.register({})], providers: [@@Done@@Consumer, @@Failed@@Consumer] })
 /** The message transport of the @@saga@@ saga: registers its consumers with the event bus. */
-export class @@Saga@@MessageModule implements OnModuleInit {
+export class @@Saga@@MessageModule extends ConfigurableModuleClass implements OnModuleInit {
     constructor(
         @InjectEventConsumerRegistry() private readonly registry: EventConsumerRegistry,
         private readonly @@doneCamel@@Consumer: @@Done@@Consumer,
         private readonly @@failedCamel@@Consumer: @@Failed@@Consumer,
-    ) {}
+    ) {
+        super()
+    }
 
     /** Hands every consumer to the registry. */
     onModuleInit(): void {

package/templates/be/patterns/saga/saga.message.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The @@saga@@-message module takes no options yet. */
+export type @@Saga@@MessageOptions = Record<string, never>

package/templates/be/patterns/saga/saga.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Saga@@Options } from "./@@saga@@.options"
+
+/** The configurable-module base of the @@saga@@ module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Saga@@Options>().setClassMethodName("register").build()

package/templates/be/patterns/saga/saga.module.ts.tpl

@@ -1,4 +1,5 @@
 import { Module } from "@nestjs/common"
+import { ConfigurableModuleClass } from "./@@saga@@.module-definition"
 import { Compensate@@Saga@@Handler } from "./application/compensate-@@saga@@.handler"
 import { Complete@@Saga@@Handler } from "./application/complete-@@saga@@.handler"
 import { Undo@@Saga@@Handler } from "./application/undo-@@saga@@.handler"
@@ -17,4 +18,4 @@ import { @@Step@@Step } from "./steps/@@step@@.saga-step"
     ],
 })
 /** The @@saga@@ saga: its orchestrator, its step and compensation, and the handlers of the commands the consumers dispatch. */
-export class @@Saga@@Module {}
+export class @@Saga@@Module extends ConfigurableModuleClass {}

package/templates/be/patterns/saga/saga.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The @@saga@@ module takes no options yet. */
+export type @@Saga@@Options = Record<string, never>

package/templates/be/patterns/webhooks/webhook.http.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Provider@@HttpOptions } from "./@@provider@@-http.options"
+
+/** The configurable-module base of the @@provider@@-http module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Provider@@HttpOptions>().setClassMethodName("register").build()

package/templates/be/patterns/webhooks/webhook.http.module.ts.tpl

@@ -1,6 +1,7 @@
 import { Module } from "@nestjs/common"
+import { ConfigurableModuleClass } from "./@@provider@@-http.module-definition"
 import { @@Provider@@Webhook } from "./@@provider@@.webhook"
 
 @Module({ controllers: [@@Provider@@Webhook] })
 /** The HTTP transport of the @@provider@@ notifier: its webhook door; the intake service and the signature service come from the app's capabilities. */
-export class @@Provider@@HttpModule {}
+export class @@Provider@@HttpModule extends ConfigurableModuleClass {}

package/templates/be/patterns/webhooks/webhook.http.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The @@provider@@-http module takes no options yet. */
+export type @@Provider@@HttpOptions = Record<string, never>