@starci/hfs 4.0.8 → 4.0.10

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

@@ -0,0 +1,6 @@
+import { Module } from "@nestjs/common"
+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 {}

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

@@ -0,0 +1 @@
+export { @@Channel@@GraphqlModule } from "./transport/graphql/@@channel@@-graphql.module"

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

@@ -0,0 +1,12 @@
+import { Field, ID, InputType } from "@nestjs/graphql"
+import { IsUUID, MaxLength } from "class-validator"
+
+@InputType()
+/** The @@channelCamel@@Changed arguments: what the caller follows. */
+export class @@Channel@@Input {
+    /** The id of the thing the caller follows. */
+    @Field(() => ID)
+    @IsUUID()
+    @MaxLength(36)
+    id!: string
+}

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

@@ -0,0 +1,51 @@
+import { mock } from "@starci/jest-preset"
+import { Test } from "@nestjs/testing"
+import { @@service@@ } from "@@serviceModule@@"
+import { REALTIME_HUB } from "@modules/platform/realtime"
+import type { RealtimeHub, RealtimeTopic } from "@modules/platform/realtime"
+import { @@Channel@@Subscription } from "./@@channel@@.subscription"
+
+const emptyStream = (): AsyncIterable<never> => (async function* () {})()
+
+/** A hub whose subscribe records the names of the topics it was asked for and answers one stream. */
+const hubAnswering = (stream: AsyncIterable<never>) => {
+    const topics: Array<string> = []
+    const hub = mock<RealtimeHub>({
+        subscribe: <T extends object>(topic: RealtimeTopic<T>): AsyncIterable<T> => {
+            topics.push(topic.name)
+            return stream
+        },
+    })
+    return { hub, topics }
+}
+
+const build = async (hub: RealtimeHub) => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [@@Channel@@Subscription, { provide: REALTIME_HUB, useValue: hub }],
+    }).compile()
+    return moduleRef.get(@@Channel@@Subscription)
+}
+
+describe("@@Channel@@Subscription", () => {
+    describe("@@channelCamel@@Changed", () => {
+        it("subscribes the client to the topic of its own principal and returns the hub stream", async () => {
+            const frames = emptyStream()
+            const { hub, topics } = hubAnswering(frames)
+            const door = await build(hub)
+
+            const stream = door.@@channelCamel@@Changed({ id: "p-1", roles: ["member"] }, { id: "x-1" })
+
+            expect(stream).toBe(frames)
+            expect(topics).toEqual([@@service@@("p-1", "x-1").name])
+        })
+
+        it("subscribes another principal to another topic, so it cannot receive the first one's frames", async () => {
+            const { hub, topics } = hubAnswering(emptyStream())
+            const door = await build(hub)
+
+            door.@@channelCamel@@Changed({ id: "p-2", roles: ["member"] }, { id: "x-1" })
+
+            expect(topics).not.toContain(@@service@@("p-1", "x-1").name)
+        })
+    })
+})

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

@@ -0,0 +1,32 @@
+import { Args, Resolver, Subscription } from "@nestjs/graphql"
+import { CurrentPrincipal, Roles } from "@modules/domain/identity"
+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 { @@Channel@@ChangedType } from "./dto/@@channel@@-changed.type"
+import { @@Channel@@Input } from "./dto/@@channel@@.input"
+
+@Resolver()
+/**
+ * The push door of the @@channel@@ channel: it subscribes the client to the topic of the hub and writes nothing. `@@service@@` of
+ * the domain module builds the topic from the principal, so a client can only listen to a channel its principal owns; the same
+ * module exports the `@@Channel@@Frame` type of what travels on it.
+ */
+export class @@Channel@@Subscription {
+    constructor(@InjectRealtimeHub() private readonly hub: RealtimeHub) {}
+
+    /** The changes pushed as they happen; the topic is built from the principal, so another subscriber receives nothing. */
+    @Subscription(() => @@Channel@@ChangedType, {
+        name: "@@channelCamel@@Changed",
+        resolve: (frame: @@Channel@@Frame): @@Channel@@ChangedType => frame,
+    })
+    @Roles("member")
+    @@channelCamel@@Changed(
+        @CurrentPrincipal() principal: Principal,
+        @Args("input") input: @@Channel@@Input,
+    ): AsyncIterable<@@Channel@@Frame> {
+        return this.hub.subscribe(@@service@@(principal.id, input.id))
+    }
+}

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

@@ -0,0 +1,9 @@
+import { Field, ObjectType } from "@nestjs/graphql"
+
+@ObjectType()
+/** One push of the @@channel@@ channel: what the subscriber may see of a change, nothing else. */
+export class @@Channel@@ChangedType {
+    /** The id of the thing that changed. */
+    @Field()
+    id!: string
+}

package/templates/be/patterns/saga/saga.compensate.command.ts.tpl

@@ -0,0 +1,11 @@
+import { Command } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { SagaTransition } from "@modules/platform/saga"
+import type { Compensate@@Saga@@Request } from "./compensate-@@saga@@.contracts"
+
+/** Asks to compensate the @@saga@@ saga of an id whose answer failed; the @@failed@@ consumer sends it for every delivered event. */
+export class Compensate@@Saga@@Command extends Command<SagaTransition> {
+    constructor(readonly params: PublicExecuteParams<Compensate@@Saga@@Request>) {
+        super()
+    }
+}

package/templates/be/patterns/saga/saga.compensate.contracts.ts.tpl

@@ -0,0 +1,7 @@
+/** What the event that reports the failure carries: the id it is about and the id of the delivery (the inbox dedupe key). */
+export interface Compensate@@Saga@@Request {
+    /** The id the saga run is about. */
+    readonly id: string
+    /** The id of the delivered event. */
+    readonly eventId: string
+}

package/templates/be/patterns/saga/saga.compensate.handler.ts.tpl

@@ -0,0 +1,22 @@
+import { CommandHandler } from "@nestjs/cqrs"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import type { SagaTransition } from "@modules/platform/saga"
+import { @@Saga@@SagaService } from "../@@saga@@.saga.service"
+import { Compensate@@Saga@@Command } from "./compensate-@@saga@@.command"
+
+@CommandHandler(Compensate@@Saga@@Command)
+/** Compensates the @@saga@@ saga of a failed run; the saga decides the fence and the no-op of a redelivery. */
+export class Compensate@@Saga@@Handler extends ICQRSHandler<Compensate@@Saga@@Command, SagaTransition> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly saga: @@Saga@@SagaService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: Compensate@@Saga@@Command): Promise<SagaTransition> {
+        return this.saga.compensate(command.params.request.id, command.params.request.eventId)
+    }
+}

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

@@ -0,0 +1,21 @@
+import { Injectable } from "@nestjs/common"
+import type { CommandBus } from "@nestjs/cqrs"
+import { InjectCommandBus } from "@modules/platform/cqrs"
+import { Undo@@Saga@@Command } from "../application/undo-@@saga@@.command"
+
+@Injectable()
+/** The compensation of the @@step@@ step: asks the domain to undo what the step did. */
+export class @@Step@@Compensation {
+    /** The step this compensation undoes. */
+    readonly step = "@@step@@"
+
+    /** The event that tells the saga to run this compensation (the contract of `@@from@@` says it compensates `@@owner@@.@@step@@`). */
+    readonly event = "@@from@@.@@failed@@"
+
+    constructor(@InjectCommandBus() private readonly commandBus: CommandBus) {}
+
+    /** Dispatches the one command of the compensation. */
+    async run(id: string): Promise<void> {
+        await this.commandBus.execute(new Undo@@Saga@@Command({ request: { id } }))
+    }
+}

package/templates/be/patterns/saga/saga.complete.command.ts.tpl

@@ -0,0 +1,11 @@
+import { Command } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { SagaTransition } from "@modules/platform/saga"
+import type { Complete@@Saga@@Request } from "./complete-@@saga@@.contracts"
+
+/** Asks to complete the @@saga@@ saga of an id whose answer arrived; the @@done@@ consumer sends it for every delivered event. */
+export class Complete@@Saga@@Command extends Command<SagaTransition> {
+    constructor(readonly params: PublicExecuteParams<Complete@@Saga@@Request>) {
+        super()
+    }
+}

package/templates/be/patterns/saga/saga.complete.contracts.ts.tpl

@@ -0,0 +1,7 @@
+/** What the event that reports the last step done carries: the id it is about and the id of the delivery (the inbox dedupe key). */
+export interface Complete@@Saga@@Request {
+    /** The id the saga run is about. */
+    readonly id: string
+    /** The id of the delivered event. */
+    readonly eventId: string
+}

package/templates/be/patterns/saga/saga.complete.handler.ts.tpl

@@ -0,0 +1,22 @@
+import { CommandHandler } from "@nestjs/cqrs"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import type { SagaTransition } from "@modules/platform/saga"
+import { @@Saga@@SagaService } from "../@@saga@@.saga.service"
+import { Complete@@Saga@@Command } from "./complete-@@saga@@.command"
+
+@CommandHandler(Complete@@Saga@@Command)
+/** Completes the @@saga@@ saga of a run whose last step answered; the saga decides the fence and the no-op of a redelivery. */
+export class Complete@@Saga@@Handler extends ICQRSHandler<Complete@@Saga@@Command, SagaTransition> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly saga: @@Saga@@SagaService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: Complete@@Saga@@Command): Promise<SagaTransition> {
+        return this.saga.complete(command.params.request.id, command.params.request.eventId)
+    }
+}

package/templates/be/patterns/saga/saga.done.consumer.ts.tpl

@@ -0,0 +1,21 @@
+import { Injectable } from "@nestjs/common"
+import type { CommandBus } from "@nestjs/cqrs"
+import { @@Done@@Event } from "@modules/events/@@from@@"
+import { InjectCommandBus } from "@modules/platform/cqrs"
+import type { EventConsumer, EventDelivery } from "@modules/platform/event-bus"
+import { Complete@@Saga@@Command } from "../../application/complete-@@saga@@.command"
+
+@Injectable()
+/** Consumer of `@@from@@.@@done@@`, the last event of the @@saga@@ saga: hands each delivery to the complete command. */
+export class @@Done@@Consumer implements EventConsumer<@@Done@@Event> {
+    readonly event = @@Done@@Event
+
+    constructor(@InjectCommandBus() private readonly commandBus: CommandBus) {}
+
+    /** Dispatches one complete command; the saga takes the delivery through the inbox, so a redelivery is a no-op. */
+    async handle(delivery: EventDelivery<@@Done@@Event>): Promise<void> {
+        await this.commandBus.execute(
+            new Complete@@Saga@@Command({ request: { id: delivery.event.payload.id, eventId: delivery.eventId } }),
+        )
+    }
+}

package/templates/be/patterns/saga/saga.failed.consumer.ts.tpl

@@ -0,0 +1,21 @@
+import { Injectable } from "@nestjs/common"
+import type { CommandBus } from "@nestjs/cqrs"
+import { @@Failed@@Event } from "@modules/events/@@from@@"
+import { InjectCommandBus } from "@modules/platform/cqrs"
+import type { EventConsumer, EventDelivery } from "@modules/platform/event-bus"
+import { Compensate@@Saga@@Command } from "../../application/compensate-@@saga@@.command"
+
+@Injectable()
+/** Consumer of `@@from@@.@@failed@@`, the failure event of the @@saga@@ saga: hands each delivery to the compensate command. */
+export class @@Failed@@Consumer implements EventConsumer<@@Failed@@Event> {
+    readonly event = @@Failed@@Event
+
+    constructor(@InjectCommandBus() private readonly commandBus: CommandBus) {}
+
+    /** Dispatches one compensate command; the saga takes the delivery through the inbox, so a redelivery is a no-op. */
+    async handle(delivery: EventDelivery<@@Failed@@Event>): Promise<void> {
+        await this.commandBus.execute(
+            new Compensate@@Saga@@Command({ request: { id: delivery.event.payload.id, eventId: delivery.eventId } }),
+        )
+    }
+}

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

@@ -0,0 +1 @@
+export { @@Saga@@MessageModule } from "./transport/message/@@saga@@-message.module"

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

@@ -0,0 +1,23 @@
+import { Module } from "@nestjs/common"
+import type { OnModuleInit } from "@nestjs/common"
+import { InjectEventConsumerRegistry } from "@modules/platform/event-bus"
+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"
+
+@Module({ imports: [@@Saga@@Module], 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 {
+    constructor(
+        @InjectEventConsumerRegistry() private readonly registry: EventConsumerRegistry,
+        private readonly @@doneCamel@@Consumer: @@Done@@Consumer,
+        private readonly @@failedCamel@@Consumer: @@Failed@@Consumer,
+    ) {}
+
+    /** Hands every consumer to the registry. */
+    onModuleInit(): void {
+        this.registry.add(this.@@doneCamel@@Consumer)
+        this.registry.add(this.@@failedCamel@@Consumer)
+    }
+}

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

@@ -0,0 +1,20 @@
+import { Module } from "@nestjs/common"
+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"
+import { @@Step@@Compensation } from "./compensations/@@step@@.compensation"
+import { @@Saga@@SagaService } from "./@@saga@@.saga.service"
+import { @@Step@@Step } from "./steps/@@step@@.saga-step"
+
+@Module({
+    providers: [
+        Compensate@@Saga@@Handler,
+        Complete@@Saga@@Handler,
+        Undo@@Saga@@Handler,
+        @@Saga@@SagaService,
+        @@Step@@Step,
+        @@Step@@Compensation,
+    ],
+})
+/** The @@saga@@ saga: its orchestrator, its step and compensation, and the handlers of the commands the consumers dispatch. */
+export class @@Saga@@Module {}

package/templates/be/patterns/saga/saga.service.spec.ts.tpl

@@ -0,0 +1,70 @@
+import { Test } from "@nestjs/testing"
+import { mock } from "@starci/jest-preset"
+import { @@sagaUpper@@_SAGA } from "@@serviceModule@@"
+import { SAGA_SERVICE } from "@modules/platform/saga"
+import type { SagaService } from "@modules/platform/saga"
+import { @@Step@@Compensation } from "./compensations/@@step@@.compensation"
+import { @@Saga@@SagaService } from "./@@saga@@.saga.service"
+import { @@Step@@Step } from "./steps/@@step@@.saga-step"
+
+const build = async () => {
+    const sagas = mock<SagaService>()
+    const compensation = mock<@@Step@@Compensation>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            @@Saga@@SagaService,
+            { provide: SAGA_SERVICE, useValue: sagas },
+            @@Step@@Step,
+            { provide: @@Step@@Compensation, useValue: compensation },
+        ],
+    }).compile()
+    return { saga: moduleRef.get(@@Saga@@SagaService), sagas, compensation }
+}
+
+describe("@@Saga@@SagaService", () => {
+    describe("compensate", () => {
+        it("hands the run and the compensation of its step to the saga state machine", async () => {
+            const { saga, sagas, compensation } = await build()
+            sagas.compensate.mockResolvedValue("applied")
+
+            expect(await saga.compensate("x-1", "e-1")).toBe("applied")
+
+            expect(sagas.compensate).toHaveBeenCalledWith({
+                saga: @@sagaUpper@@_SAGA,
+                correlationId: "x-1",
+                eventId: "e-1",
+                step: expect.any(@@Step@@Step),
+                compensation,
+            })
+        })
+    })
+
+    describe("complete", () => {
+        it("hands the run to the saga state machine to settle as completed", async () => {
+            const { saga, sagas } = await build()
+            sagas.complete.mockResolvedValue("applied")
+
+            expect(await saga.complete("x-1", "e-2")).toBe("applied")
+
+            expect(sagas.complete).toHaveBeenCalledWith({ saga: @@sagaUpper@@_SAGA, correlationId: "x-1", eventId: "e-2" })
+        })
+    })
+
+    describe("stateOf", () => {
+        it("answers the persisted state of the run", async () => {
+            const { saga, sagas } = await build()
+            sagas.state.mockResolvedValue({ correlationId: "x-1", status: "running", version: 1 })
+
+            expect(await saga.stateOf("x-1")).toEqual({ correlationId: "x-1", status: "running", version: 1 })
+
+            expect(sagas.state).toHaveBeenCalledWith({ saga: @@sagaUpper@@_SAGA, correlationId: "x-1" })
+        })
+
+        it("answers null when the id never started a run", async () => {
+            const { saga, sagas } = await build()
+            sagas.state.mockResolvedValue(null)
+
+            expect(await saga.stateOf("x-9")).toBeNull()
+        })
+    })
+})

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

@@ -0,0 +1,44 @@
+import { Injectable } from "@nestjs/common"
+import { @@sagaUpper@@_SAGA } from "@@serviceModule@@"
+import { InjectSagaService } from "@modules/platform/saga"
+import type { SagaService, SagaTransition } from "@modules/platform/saga"
+import type { Find@@Saga@@SagaResult } from "./@@saga@@.saga-state"
+import { @@Step@@Compensation } from "./compensations/@@step@@.compensation"
+import { @@Step@@Step } from "./steps/@@step@@.saga-step"
+
+@Injectable()
+/**
+ * The orchestrator of the @@saga@@ saga: the list of its steps and, for each, the compensation that undoes it. It decides nothing:
+ * the state machine, the version fence and the `Compensating` log are `platform/saga`'s, the work of each compensation is a
+ * command. The run starts in the transaction of the domain (`@@sagaUpper@@_SAGA`, written by @@service@@ together with the event the
+ * step puts on the wire) and ends when the answer arrives: the done event completes it, the failed event compensates every step
+ * in reverse order.
+ */
+export class @@Saga@@SagaService {
+    constructor(
+        @InjectSagaService() private readonly sagas: SagaService,
+        private readonly @@stepCamel@@Step: @@Step@@Step,
+        private readonly @@stepCamel@@Compensation: @@Step@@Compensation,
+    ) {}
+
+    /** Compensates the run of an id after the event that reports its failure; the store takes the delivery through the inbox. */
+    compensate(id: string, eventId: string): Promise<SagaTransition> {
+        return this.sagas.compensate({
+            saga: @@sagaUpper@@_SAGA,
+            correlationId: id,
+            eventId,
+            step: this.@@stepCamel@@Step,
+            compensation: this.@@stepCamel@@Compensation,
+        })
+    }
+
+    /** Where the run of an id stands, or null when it never started one. */
+    stateOf(id: string): Promise<Find@@Saga@@SagaResult> {
+        return this.sagas.state({ saga: @@sagaUpper@@_SAGA, correlationId: id })
+    }
+
+    /** Completes the run of an id after the event that reports its last step done; the store takes the delivery through the inbox. */
+    complete(id: string, eventId: string): Promise<SagaTransition> {
+        return this.sagas.complete({ saga: @@sagaUpper@@_SAGA, correlationId: id, eventId })
+    }
+}

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

@@ -0,0 +1,14 @@
+import type { SagaStatus } from "@modules/platform/saga"
+
+/** The persisted state of one run of the @@saga@@ saga: one row per run, moved only through its version (the fence of `platform/saga`). */
+export interface @@Saga@@SagaState {
+    /** The id the run is about. */
+    readonly correlationId: string
+    /** Where the run stands: running its steps, compensating, compensated or completed. */
+    readonly status: SagaStatus
+    /** The fence: every transition names the version it read and moves it by one. */
+    readonly version: number
+}
+
+/** The state of the run of an id, or null when it never started one. */
+export type Find@@Saga@@SagaResult = @@Saga@@SagaState | null

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

@@ -0,0 +1,11 @@
+import { Injectable } from "@nestjs/common"
+
+@Injectable()
+/** The first step of the @@saga@@ saga: the domain does its work in the transaction that starts the run and announces `@@owner@@.@@step@@`. */
+export class @@Step@@Step {
+    /** The name the compensation of this step carries. */
+    readonly name = "@@step@@"
+
+    /** The event this step puts on the wire (the contract `be/contracts/<service>/events.json`). */
+    readonly event = "@@owner@@.@@step@@"
+}

package/templates/be/patterns/saga/saga.undo.command.ts.tpl

@@ -0,0 +1,10 @@
+import { Command } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { Undo@@Saga@@Request } from "./undo-@@saga@@.contracts"
+
+/** Asks to undo what the @@saga@@ saga did for an id; the compensation of its step sends it. */
+export class Undo@@Saga@@Command extends Command<void> {
+    constructor(readonly params: PublicExecuteParams<Undo@@Saga@@Request>) {
+        super()
+    }
+}

package/templates/be/patterns/saga/saga.undo.contracts.ts.tpl

@@ -0,0 +1,5 @@
+/** What undoing the @@saga@@ saga takes. */
+export interface Undo@@Saga@@Request {
+    /** The id the saga run is about. */
+    readonly id: string
+}

package/templates/be/patterns/saga/saga.undo.handler.ts.tpl

@@ -0,0 +1,21 @@
+import { CommandHandler } from "@nestjs/cqrs"
+import { @@service@@ } from "@@serviceModule@@"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { Undo@@Saga@@Command } from "./undo-@@saga@@.command"
+
+@CommandHandler(Undo@@Saga@@Command)
+/** Undoes the @@saga@@ saga for an id; @@service@@ decides the transaction and the no-op of a redelivery (`undo@@Saga@@`). */
+export class Undo@@Saga@@Handler extends ICQRSHandler<Undo@@Saga@@Command, void> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly domain: @@service@@,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: Undo@@Saga@@Command): Promise<void> {
+        return this.domain.undo@@Saga@@({ id: command.params.request.id })
+    }
+}

package/templates/be/patterns/webhooks/webhook.door.spec.ts.tpl

@@ -0,0 +1,72 @@
+import { createHmac } from "node:crypto"
+import { FakeClock, mock } from "@starci/jest-preset"
+import type { RawBodyRequest } from "@nestjs/common"
+import { Test } from "@nestjs/testing"
+import type { Request } from "express"
+import { @@service@@ } from "@@serviceModule@@"
+import { CLOCK } from "@modules/platform/clock"
+import { Secret } from "@modules/platform/config"
+import { HttpSecurityModule } from "@modules/platform/http-security"
+import { @@Event@@Request } from "./dto/@@event@@.request"
+import { @@Provider@@Webhook } from "./@@provider@@.webhook"
+
+const AT = "2026-01-02T03:04:05.000Z"
+const SECRET = "spec-webhook-secret"
+const SIGNED_AT = String(new Date(AT).getTime())
+
+/** The delivery the notifier sends: the validated request class, as the pipe builds it. */
+const deliveryOf = (): @@Event@@Request => {
+    const delivery = new @@Event@@Request()
+    delivery.id = "delivery-1"
+    return delivery
+}
+
+const DELIVERY = deliveryOf()
+const RAW_BODY = Buffer.from(JSON.stringify(DELIVERY))
+const REQUEST = mock<RawBodyRequest<Request>>({ rawBody: RAW_BODY })
+
+const sign = (rawBody: Buffer, timestamp: string): string =>
+    `sha256=${createHmac("sha256", SECRET).update(`${timestamp}.`).update(rawBody).digest("hex")}`
+
+const build = async (deliveries: @@service@@) => {
+    const moduleRef = await Test.createTestingModule({
+        imports: [
+            HttpSecurityModule.register({
+                allowedOrigins: [],
+                rateLimit: { windowMs: 60_000, defaultLimit: 100, strictLimit: 100 },
+                webhooks: { "@@provider@@": { secret: new Secret(SECRET), toleranceMs: 300_000 } },
+            }),
+        ],
+        controllers: [@@Provider@@Webhook],
+        providers: [
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+            { provide: @@service@@, useValue: deliveries },
+        ],
+    }).compile()
+    return moduleRef.get(@@Provider@@Webhook)
+}
+
+describe("@@Provider@@Webhook", () => {
+    describe("receive", () => {
+        it("proves the delivery on its raw body and headers, then hands it to the intake once", async () => {
+            const deliveries = mock<@@service@@>()
+            const door = await build(deliveries)
+
+            await door.receive(REQUEST, sign(RAW_BODY, SIGNED_AT), SIGNED_AT, DELIVERY)
+
+            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledTimes(1)
+            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledWith(DELIVERY)
+        })
+
+        it("never reaches the intake when the signature is not the provider's", async () => {
+            const deliveries = mock<@@service@@>()
+            const door = await build(deliveries)
+
+            await expect(
+                door.receive(REQUEST, sign(Buffer.from("other body"), SIGNED_AT), SIGNED_AT, DELIVERY),
+            ).rejects.toMatchObject({ code: "HTTP_SECURITY_WEBHOOK_SIGNATURE_INVALID" })
+
+            expect(deliveries.accept@@Provider@@Delivery).not.toHaveBeenCalled()
+        })
+    })
+})

package/templates/be/patterns/webhooks/webhook.door.ts.tpl

@@ -0,0 +1,36 @@
+import { Body, Controller, Headers, HttpCode, HttpStatus, Post, Req } from "@nestjs/common"
+import type { RawBodyRequest } from "@nestjs/common"
+import type { Request } from "express"
+import { Public, PublicReason } from "@modules/domain/identity"
+import { @@service@@ } from "@@serviceModule@@"
+import { InjectWebhookSignature, RateLimit, RateTier } from "@modules/platform/http-security"
+import type { WebhookSignatureService } from "@modules/platform/http-security"
+import { @@Event@@Request } from "./dto/@@event@@.request"
+
+@Controller("webhooks/@@provider@@")
+/**
+ * POST /webhooks/@@provider@@, the signed intake door of the @@provider@@ notifier. The signature and the replay window are proven
+ * first; the verified delivery goes to exactly one intake method of @@service@@ (`accept@@Provider@@Delivery`), which records it
+ * once and publishes the event in its own transaction.
+ */
+export class @@Provider@@Webhook {
+    constructor(
+        @InjectWebhookSignature() private readonly signature: WebhookSignatureService,
+        private readonly deliveries: @@service@@,
+    ) {}
+
+    /** Acknowledges with 204 and no body: the notifier learns only that the delivery was accepted. */
+    @Post()
+    @HttpCode(HttpStatus.NO_CONTENT)
+    @Public({ reason: PublicReason.SignedWebhook })
+    @RateLimit(RateTier.Strict)
+    async receive(
+        @Req() request: RawBodyRequest<Request>,
+        @Headers("x-@@provider@@-signature") signature: string | undefined,
+        @Headers("x-@@provider@@-timestamp") timestamp: string | undefined,
+        @Body() delivery: @@Event@@Request,
+    ): Promise<void> {
+        this.signature.verify({ provider: "@@provider@@", rawBody: request.rawBody, signature, timestamp })
+        await this.deliveries.accept@@Provider@@Delivery(delivery)
+    }
+}

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

@@ -0,0 +1,6 @@
+import { Module } from "@nestjs/common"
+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 {}

package/templates/be/patterns/webhooks/webhook.index.ts.tpl

@@ -0,0 +1 @@
+export { @@Provider@@HttpModule } from "./transport/http/@@provider@@-http.module"

package/templates/be/patterns/webhooks/webhook.request.ts.tpl

@@ -0,0 +1,9 @@
+import { IsString, MaxLength } from "class-validator"
+
+/** The delivery the @@provider@@ notifier sends, as the validation pipe builds it: the fields the intake reads, bounded; add the provider's other fields here. */
+export class @@Event@@Request {
+    /** The provider's id of this delivery: the dedupe key of the intake. */
+    @IsString()
+    @MaxLength(64)
+    id!: string
+}