@starci/hfs 4.11.12 → 4.11.15

package/templates/be/skeleton-lite/src/modules/platform/http-security/rate-limit.guard.spec.ts

@@ -5,7 +5,7 @@ import { Reflector } from "@nestjs/core"
 import { Test } from "@nestjs/testing"
 import { In, LessThanOrEqual, MoreThan } from "typeorm"
 import { FakeClock, mock, mockEntityManager, queueQueryBuilders } from "@starci/jest-preset"
-import type { MockEntityManager } from "@starci/jest-preset"
+import type { FakeQueryBuilder, MockEntityManager } from "@starci/jest-preset"
 import { CLOCK } from "@modules/platform/clock"
 import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
 import { HttpSecurityErrorCode } from "./errors/http-security.error"
@@ -23,20 +23,31 @@ const options: HttpSecurityOptions = {
     webhooks: {},
 }
 
-/** The caller's live window holding `hits`. */
+/** The caller's window holding `hits`. */
 const windowOf = (hits: number): RateWindowEntity => ({ key: "default:127.0.0.1", hits, resetAt: new Date(RESET_AT) })
 
-/** The answers of a store whose live window of the caller holds `hits` after this hit's increment. */
-const liveWindow = (hits: number) =>
-    ({ increment: [RateWindowEntity, { affected: 1 }], findOneBy: [RateWindowEntity, windowOf(hits)] }) as const
+/** A store with a live window of the caller, and the builder of the UPDATE that counted this hit in it. */
+interface LiveWindow {
+    readonly entityManager: MockEntityManager
+    readonly counting: FakeQueryBuilder | undefined
+}
+
+/** A store whose live window of the caller holds `hits` after this hit: the counting UPDATE returns them. */
+const liveWindow = (hits: number): LiveWindow => {
+    const entityManager = mockEntityManager()
+    const [counting] = queueQueryBuilders(entityManager, [{ execute: { raw: [{ hits }] } }])
+    return { entityManager, counting }
+}
 
 /** The answers of a store where this hit opens the caller's window (no live or ended one) and the prune finds none ended. */
 const OPENING_WINDOW = {
-    increment: [RateWindowEntity, { affected: 0 }],
     update: [RateWindowEntity, { affected: 0 }],
     find: [RateWindowEntity, []],
 } as const
 
+/** The counting UPDATE of a hit that finds no live window: it returns no row. */
+const NO_LIVE_WINDOW = { execute: { raw: [] } } as const
+
 const build = async (entityManager: MockEntityManager, tier?: RateTier, exceeded?: RateLimitExceeded) => {
     const reflector = mock<Reflector>()
     reflector.getAllAndOverride.mockImplementation((key: unknown) =>
@@ -76,7 +87,7 @@ describe("RateLimit", () => {
     it("marks a door with the tier it declares, and the guard counts it under that tier's limit", async () => {
         class Door {}
         RateLimit(RateTier.Strict)(Door)
-        const entityManager = mockEntityManager(liveWindow(2))
+        const { entityManager, counting } = liveWindow(2)
         const { guard, reflector } = await build(entityManager, RateTier.Strict)
         const handler = () => undefined
 
@@ -85,12 +96,7 @@ describe("RateLimit", () => {
             code: HttpSecurityErrorCode.RateLimited,
         })
         expect(reflector.getAllAndOverride).toHaveBeenCalledWith("platform.http-security.rate-tier", [handler, Door])
-        expect(entityManager.increment).toHaveBeenCalledWith(
-            RateWindowEntity,
-            { key: "strict:127.0.0.1", resetAt: MoreThan(new Date(AT)) },
-            "hits",
-            1,
-        )
+        expect(counting?.callsOf("where")).toEqual([[{ key: "strict:127.0.0.1", resetAt: MoreThan(new Date(AT)) }]])
     })
 
     it("marks a redirect-only door with its exceeded redirect beside the tier", () => {
@@ -113,30 +119,31 @@ describe("RateLimit", () => {
 
 describe("RateLimitGuard", () => {
     it("admits a caller under the default limit of an unmarked door, counting in the shared live window", async () => {
-        const entityManager = mockEntityManager(liveWindow(2))
+        const { entityManager, counting } = liveWindow(2)
         const { guard } = await build(entityManager)
 
         await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
-        expect(entityManager.findOneBy).toHaveBeenCalledWith(RateWindowEntity, { key: "default:127.0.0.1" })
+        expect(counting?.callsOf("update")).toEqual([[]])
+        expect(counting?.callsOf("returning")).toEqual([["hits"]])
+        expect(counting?.callsOf("where")).toEqual([[{ key: "default:127.0.0.1", resetAt: MoreThan(new Date(AT)) }]])
+        expect(entityManager.update).not.toHaveBeenCalled()
     })
 
     it("refuses a caller whose shared window is over the default limit", async () => {
-        const { guard } = await build(mockEntityManager(liveWindow(3)))
+        const { guard } = await build(liveWindow(3).entityManager)
 
         await expect(guard.canActivate(contextOf("127.0.0.1"))).rejects.toMatchObject({
             code: HttpSecurityErrorCode.RateLimited,
         })
     })
 
-    it("refuses the request when the counted window vanished before it was read", async () => {
-        const entityManager = mockEntityManager({
-            increment: [RateWindowEntity, { affected: 1 }],
-            findOneBy: [RateWindowEntity, null],
-        })
+    it("refuses to count from a returned row that is not the window's hits", async () => {
+        const entityManager = mockEntityManager()
+        queueQueryBuilders(entityManager, [{ execute: { raw: [{ hits: "2" }] } }])
         const { guard } = await build(entityManager)
 
         await expect(guard.canActivate(contextOf("127.0.0.1"))).rejects.toMatchObject({
-            code: HttpSecurityErrorCode.RateLimited,
+            code: "DATABASE_RETURNING_ROW_REJECTED",
         })
     })
 })
@@ -145,11 +152,11 @@ describe("RateLimitGuard opening a window", () => {
     it("restarts an ended window at one hit and prunes the ended windows", async () => {
         const ended = windowOf(5)
         const entityManager = mockEntityManager({
-            increment: [RateWindowEntity, {}],
             update: [RateWindowEntity, { affected: 1 }],
             find: [RateWindowEntity, [ended]],
             delete: [RateWindowEntity, { affected: 1 }],
         })
+        queueQueryBuilders(entityManager, [NO_LIVE_WINDOW])
         const { guard } = await build(entityManager)
 
         await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
@@ -172,7 +179,7 @@ describe("RateLimitGuard opening a window", () => {
 
     it("opens a missing window at one hit, ignoring a concurrent opener, and deletes nothing when no window ended", async () => {
         const entityManager = mockEntityManager(OPENING_WINDOW)
-        const [opened] = queueQueryBuilders(entityManager, [{ execute: {} }])
+        const [, opened] = queueQueryBuilders(entityManager, [NO_LIVE_WINDOW, { execute: {} }])
         const { guard } = await build(entityManager)
 
         await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
@@ -185,11 +192,10 @@ describe("RateLimitGuard opening a window", () => {
 
     it("opens a window when the restart answers no affected count", async () => {
         const entityManager = mockEntityManager({
-            increment: [RateWindowEntity, { affected: 0 }],
             update: [RateWindowEntity, {}],
             find: [RateWindowEntity, []],
         })
-        const [opened] = queueQueryBuilders(entityManager, [{ execute: {} }])
+        const [, opened] = queueQueryBuilders(entityManager, [NO_LIVE_WINDOW, { execute: {} }])
         const { guard } = await build(entityManager)
 
         await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
@@ -199,20 +205,22 @@ describe("RateLimitGuard opening a window", () => {
 
 describe("RateLimitGuard keys", () => {
     it("counts a request without an address under the unknown key", async () => {
-        const entityManager = mockEntityManager(liveWindow(2))
+        const { entityManager, counting } = liveWindow(2)
         const { guard } = await build(entityManager)
 
         await expect(guard.canActivate(contextOf(undefined))).resolves.toBe(true)
-        expect(entityManager.findOneBy).toHaveBeenCalledWith(RateWindowEntity, { key: "default:unknown" })
+        expect(counting?.callsOf("where")).toEqual([[{ key: "default:unknown", resetAt: MoreThan(new Date(AT)) }]])
     })
 
     it("bounds the window key to the length the table stores", async () => {
-        const entityManager = mockEntityManager(liveWindow(2))
+        const { entityManager, counting } = liveWindow(2)
         const { guard } = await build(entityManager)
 
         await guard.canActivate(contextOf("f".repeat(300)))
 
-        expect(entityManager.findOneBy).toHaveBeenCalledWith(RateWindowEntity, { key: `default:${"f".repeat(120)}` })
+        expect(counting?.callsOf("where")).toEqual([
+            [{ key: `default:${"f".repeat(120)}`, resetAt: MoreThan(new Date(AT)) }],
+        ])
     })
 })
 
@@ -226,7 +234,7 @@ describe("RateLimitGuard on a redirect-only door", () => {
     }
 
     it("answers the door's own 303 when the caller is over the limit, and still refuses", async () => {
-        const { guard } = await build(mockEntityManager(liveWindow(2)), RateTier.Strict, EXCEEDED)
+        const { guard } = await build(liveWindow(2).entityManager, RateTier.Strict, EXCEEDED)
         const { response, redirect } = responseOf()
 
         await expect(
@@ -237,7 +245,7 @@ describe("RateLimitGuard on a redirect-only door", () => {
 
     it("writes no redirect while the caller is under the limit", async () => {
         const entityManager = mockEntityManager(OPENING_WINDOW)
-        queueQueryBuilders(entityManager, [{ execute: {} }])
+        queueQueryBuilders(entityManager, [NO_LIVE_WINDOW, { execute: {} }])
         const { guard } = await build(entityManager, RateTier.Strict, EXCEEDED)
         const { response, redirect } = responseOf()
 
@@ -248,7 +256,7 @@ describe("RateLimitGuard on a redirect-only door", () => {
     })
 
     it("refuses a GraphQL operation over the limit without writing a redirect", async () => {
-        const { guard } = await build(mockEntityManager(liveWindow(2)), RateTier.Strict, EXCEEDED)
+        const { guard } = await build(liveWindow(2).entityManager, RateTier.Strict, EXCEEDED)
         const { response, redirect } = responseOf()
         const context = contextOf("127.0.0.1", () => undefined, class Door {}, response)
         context.getType.mockReturnValue("graphql")

package/templates/be/skeleton-lite/src/modules/platform/http-security/rate-limit.guard.ts

@@ -8,7 +8,7 @@ import { InjectClock } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
 import { InjectReflector } from "@modules/platform/composition"
 import type { DoorDecorator } from "@modules/platform/composition"
-import { InjectPrimaryEntityManager } from "@modules/platform/database"
+import { InjectPrimaryEntityManager, returnedRows, rowShape } from "@modules/platform/database"
 import { HttpSecurityError, HttpSecurityErrorCode } from "./errors/http-security.error"
 import { requestOf } from "./execution-request.mapper"
 import { InjectHttpSecurityOptions } from "./http-security.decorators"
@@ -35,6 +35,8 @@ const RATE_EXCEEDED_KEY = "platform.http-security.rate-exceeded"
 const KEY_MAX = 128
 /** The most ended windows one fresh window prunes. */
 const PRUNE_BATCH = 100
+/** The row the counting update returns: the hits of the live window, this one included. */
+const isCountedWindow = rowShape({ hits: "number" })
 
 /** A same-site path: one leading slash, never a protocol-relative `//` or `/\` that leaves the site. */
 const isSameSitePath = (location: string): boolean =>
@@ -91,16 +93,20 @@ export class RateLimitGuard implements CanActivate {
     }
 
     /**
-     * Counts one hit in the caller's window and answers the hits it holds: a live window grows by one in one atomic increment,
-     * an ended window restarts at one hit ending at `resetAt`, and a missing one opens at one hit (a concurrent opener's row
-     * wins and this hit is its first). A window that vanished between the writes counts as over every limit.
+     * Counts one hit in the caller's window and answers the hits it holds: a live window grows by one in one UPDATE that
+     * returns its hits, an ended window restarts at one hit ending at `resetAt`, and a missing one opens at one hit (a
+     * concurrent opener's row wins and this hit is its first).
      */
     private async hit(key: string, now: Date, resetAt: Date): Promise<number> {
-        const counted = await this.entityManager.increment(RateWindowEntity, { key, resetAt: MoreThan(now) }, "hits", 1)
-        if ((counted.affected ?? 0) > 0) {
-            const window = await this.entityManager.findOneBy(RateWindowEntity, { key })
-            return window?.hits ?? Number.POSITIVE_INFINITY
-        }
+        const counted = await this.entityManager
+            .createQueryBuilder(RateWindowEntity, "window")
+            .update()
+            .set({ hits: () => "hits + 1" })
+            .where({ key, resetAt: MoreThan(now) })
+            .returning("hits")
+            .execute()
+        const [live] = returnedRows(counted.raw, isCountedWindow)
+        if (live !== undefined) return live.hits
         const restarted = await this.entityManager.update(
             RateWindowEntity,
             { key, resetAt: LessThanOrEqual(now) },

package/templates/be/inbox/database-client.spec.ts.tpl

@@ -1,45 +0,0 @@
-import { mockEntityManager } from "@starci/jest-preset"
-import type { EntityManager } from "typeorm"
-import { DatabaseErrorCode } from "./errors/database.error"
-import { recordWebhookDelivery, webhookReceiptInsert } from "./webhook-inbox.client"
-
-const INSERT = webhookReceiptInsert("spec_inbox")
-const PAYLOAD = { id: "delivery-1" }
-
-const record = (manager: EntityManager, deliveryId: string | undefined) =>
-    recordWebhookDelivery({ manager, table: "spec_inbox", provider: "spec", deliveryId, payload: PAYLOAD })
-
-describe("webhookReceiptInsert", () => {
-    it("refuses a table name that is not a lowercase identifier", () => {
-        expect(() => webhookReceiptInsert("spec; drop table x")).toThrow(TypeError)
-    })
-})
-
-describe("recordWebhookDelivery", () => {
-    it("records a new delivery through the caller's transaction manager", async () => {
-        const manager = mockEntityManager({ query: [INSERT, [{ id: "inbox-1" }]] })
-
-        const receiptId = await record(manager, "  delivery-1  ")
-
-        expect(manager.query).toHaveBeenCalledTimes(1)
-        expect(manager.query).toHaveBeenCalledWith(INSERT, ["spec", "delivery-1", JSON.stringify(PAYLOAD)])
-        expect(receiptId).toBe("inbox-1")
-    })
-
-    it("acknowledges a duplicate without any completion or business write", async () => {
-        const manager = mockEntityManager({ query: [INSERT, []] })
-
-        const receiptId = await record(manager, "delivery-1")
-
-        expect(manager.query).toHaveBeenCalledTimes(1)
-        expect(receiptId).toBeUndefined()
-    })
-
-    it.each([["no", undefined], ["a blank", "   "]])("refuses %s delivery id before writing a receipt", async (_label, deliveryId) => {
-        const manager = mockEntityManager()
-
-        await expect(record(manager, deliveryId)).rejects.toMatchObject({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
-
-        expect(manager.query).not.toHaveBeenCalled()
-    })
-})

package/templates/be/inbox/database-client.ts.tpl

@@ -1,45 +0,0 @@
-import type { EntityManager } from "typeorm"
-import { DatabaseError, DatabaseErrorCode } from "./errors/database.error"
-
-interface RecordWebhookDelivery {
-    readonly manager: EntityManager
-    /** The provider inbox table under public, created by its db migration. */
-    readonly table: string
-    readonly provider: string
-    readonly deliveryId: string | undefined
-    readonly payload: object
-}
-
-type WebhookReceiptId = string | undefined
-
-/** A provider inbox table name: a lowercase identifier, never a value. */
-const TABLE = /^[a-z_][a-z0-9_]*$/
-
-/** The conflict-safe insert of one pending delivery into `public.<table>`, answering its id only to the winning transaction. */
-export const webhookReceiptInsert = (table: string): string => {
-    if (!TABLE.test(table)) throw new TypeError(`${table} is not a provider inbox table name`)
-    return `INSERT INTO public.${table} (provider, delivery_id, payload) VALUES ($1, $2, $3::jsonb) ON CONFLICT (provider, delivery_id) DO NOTHING RETURNING id`
-}
-
-/**
- * Records one pending delivery using the intake's transaction manager and returns its durable receipt identity.
- * Business processing and the completion marker belong to the reactor or job that consumes the committed row.
- */
-export const recordWebhookDelivery = async ({
-    manager,
-    table,
-    provider,
-    deliveryId,
-    payload,
-}: RecordWebhookDelivery): Promise<WebhookReceiptId> => {
-    const normalizedDeliveryId = deliveryId?.trim()
-    if (!normalizedDeliveryId) {
-        throw new DatabaseError({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
-    }
-    const rows: Array<{ readonly id: string }> = await manager.query(webhookReceiptInsert(table), [
-        provider,
-        normalizedDeliveryId,
-        JSON.stringify(payload),
-    ])
-    return rows[0]?.id
-}