@starci/hfs 4.10.0 → 4.11.0

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

@@ -0,0 +1,65 @@
+import { SchedulerRegistry } from "@nestjs/schedule"
+import { Test } from "@nestjs/testing"
+import { FakeClock, fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { LOGGER } from "@modules/platform/logging"
+import { QUEUE_OUTBOX } from "@modules/platform/queue"
+import type { JobTick } from "./job-ticks.contracts"
+import { JOBS_MANAGERS } from "./jobs.decorators"
+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 AT = "2026-02-03T04:05:06.000Z"
+const TICK: JobTick = { name: "nightly-digest", cron: "0 2 * * *", timeZone: "UTC", queue: "digests", payload: { kind: "nightly" } }
+
+const build = async (claimed: boolean) => {
+    const transaction = fakeTransaction(mockEntityManager({ query: [[LOCK_TICK, []], [CLAIM_TICK, [{ claimed }]]] }))
+    const outbox = { write: jest.fn().mockResolvedValue(undefined) }
+    const registry = { addCronJob: jest.fn() }
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            JobTickService,
+            { provide: SchedulerRegistry, useValue: registry },
+            { provide: JOBS_MANAGERS, useValue: [transaction.em] },
+            { provide: QUEUE_OUTBOX, useValue: outbox },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+            { provide: LOGGER, useValue: { info: jest.fn(), warn: jest.fn(), error: jest.fn() } },
+        ],
+    }).compile()
+    return { ticks: moduleRef.get(JobTickService), transaction, outbox, registry }
+}
+
+describe("JobTickService", () => {
+    it("names a tick's slot by its UTC minute", () => {
+        expect(tickMinute(new Date(AT))).toBe("2026-02-03T04:05")
+    })
+
+    it("locks the tick, claims its minute and enqueues one job in the same transaction", async () => {
+        const { ticks, transaction, outbox } = await build(true)
+
+        await expect(ticks.fire(TICK)).resolves.toBe(true)
+
+        expect(transaction.em.query).toHaveBeenNthCalledWith(1, LOCK_TICK, ["tick:nightly-digest"])
+        expect(transaction.em.query).toHaveBeenNthCalledWith(2, CLAIM_TICK, ["nightly-digest", "2026-02-03T04:05"])
+        expect(outbox.write).toHaveBeenCalledWith(expect.anything(), "digests", { kind: "nightly" }, "tick:nightly-digest:2026-02-03T04:05")
+    })
+
+    it("enqueues nothing when another replica already fired the tick this minute", async () => {
+        const { ticks, outbox } = await build(false)
+
+        await expect(ticks.fire(TICK)).resolves.toBe(false)
+
+        expect(outbox.write).not.toHaveBeenCalled()
+    })
+
+    it("registers no cron job while the tick list is empty", async () => {
+        const { ticks, registry } = await build(true)
+
+        ticks.onApplicationBootstrap()
+
+        expect(registry.addCronJob).not.toHaveBeenCalled()
+    })
+})

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

@@ -0,0 +1,78 @@
+import { Injectable } from "@nestjs/common"
+import type { OnApplicationBootstrap } from "@nestjs/common"
+import { SchedulerRegistry } from "@nestjs/schedule"
+import { CronJob } from "cron"
+import type { EntityManager } from "typeorm"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { advisoryXactLock, callDbFunction } from "@modules/platform/database"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { InjectQueueOutbox } from "@modules/platform/queue"
+import type { QueueOutbox } from "@modules/platform/queue"
+import { JobsError, JobsErrorCode } from "./errors/jobs.error"
+import { JOB_TICKS } from "./job-ticks.contracts"
+import type { JobTick } from "./job-ticks.contracts"
+import { InjectJobsManagers } from "./jobs.decorators"
+import { JobsLogEvent } from "./jobs.log-events"
+
+/** The record job_tick_claim returns. */
+interface TickClaim {
+    /** True when this firing moved the tick to its minute and must enqueue. */
+    readonly claimed: boolean
+}
+
+/** The UTC minute of `at` (`YYYY-MM-DDTHH:MM`): the slot a tick fires once in. */
+export const tickMinute = (at: Date): string => at.toISOString().slice(0, 16)
+
+@Injectable()
+/**
+ * The one scheduler of the app (R335): @nestjs/schedule fires every tick of JOB_TICKS on every replica, and each firing takes
+ * advisoryXactLock("tick:<name>"), claims the tick's minute through job_tick_claim and, only when it moved the tick, writes one
+ * job into the queue outbox in the same transaction, so the deployment enqueues the tick once per minute.
+ */
+export class JobTickService implements OnApplicationBootstrap {
+    constructor(
+        private readonly registry: SchedulerRegistry,
+        @InjectJobsManagers() private readonly managers: ReadonlyArray<EntityManager>,
+        @InjectQueueOutbox() private readonly outbox: QueueOutbox,
+        @InjectClock() private readonly clock: Clock,
+        @InjectLogger() private readonly logger: Logger,
+    ) {}
+
+    /** Registers one cron job per tick, read in the tick's time zone; a failed firing is logged and the next one runs. */
+    onApplicationBootstrap(): void {
+        for (const tick of JOB_TICKS) {
+            this.registry.addCronJob(tick.name, CronJob.from({
+                cronTime: tick.cron,
+                timeZone: tick.timeZone,
+                onTick: async () => {
+                    await this.fire(tick)
+                },
+                errorHandler: (cause: unknown) => {
+                    this.logger.error(JobsLogEvent.TickFailed, cause, { tick: tick.name })
+                },
+                start: true,
+            }))
+        }
+    }
+
+    /** Fires the tick for the current minute; true when this replica enqueued its job, false when another one already had. */
+    async fire(tick: JobTick): Promise<boolean> {
+        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])
+            if (claim?.claimed !== true) return false
+            await this.outbox.write(tx, tick.queue, tick.payload, `tick:${tick.name}:${minute}`)
+            return true
+        })
+    }
+
+    /** The entity manager of the connection that holds the tick table. */
+    private writer(): EntityManager {
+        const [manager] = this.managers
+        if (manager === undefined) throw new JobsError({ code: JobsErrorCode.ConnectionMissing })
+        return manager
+    }
+}

package/templates/be/patterns/jobs/platform-lite/job-ticks.contracts.ts.tpl

@@ -0,0 +1,16 @@
+/** One recurring tick of platform/jobs: at each minute its cron expression names, one job of `queue` is enqueued with `payload` (R335). */
+export interface JobTick {
+    /** The stable name: the advisory lock key, the minute claim and the correlation id carry it. */
+    readonly name: string
+    /** The five-field cron expression of the minutes the tick fires at. */
+    readonly cron: string
+    /** The time zone the expression is read in; ticks run in UTC. */
+    readonly timeZone: "UTC"
+    /** The queue the tick enqueues one job of. */
+    readonly queue: string
+    /** The payload of that job: ids and literals only. */
+    readonly payload: object
+}
+
+/** The ticks of this app, as data: JobTickService registers one cron job per entry. */
+export const JOB_TICKS: ReadonlyArray<JobTick> = []

package/templates/be/patterns/jobs/platform-lite/jobs.module.ts.tpl

@@ -0,0 +1,40 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { ScheduleModule } from "@nestjs/schedule"
+import type { EntityManager } from "typeorm"
+import { JOB_CLAIMS, JOB_PROCESSOR_REGISTRY, JOBS_MANAGERS } from "./jobs.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./jobs.module-definition"
+import { JobClaimService } from "./job-claim.service"
+import { JobRunnerService } from "./job-runner.service"
+import { JobTickService } from "./job-tick.service"
+
+@Module({})
+/**
+ * The fenced jobs of a service: the claim service that owns the job row, the runner that subscribes processors to their queues and
+ * the one tick scheduler (R335), which composes @nestjs/schedule here and nowhere else. Needs the queue capability registered in
+ * the same app.
+ */
+export class JobsModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app that runs jobs. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            imports: [...(base.imports ?? []), ScheduleModule.forRoot()],
+            providers: [
+                ...(base.providers ?? []),
+                {
+                    provide: JOBS_MANAGERS,
+                    useFactory: (manager: EntityManager) => [manager],
+                    inject: [options.connection],
+                },
+                JobClaimService,
+                JobRunnerService,
+                JobTickService,
+                { provide: JOB_CLAIMS, useExisting: JobClaimService },
+                { provide: JOB_PROCESSOR_REGISTRY, useExisting: JobRunnerService },
+            ],
+            exports: [JOB_CLAIMS, JOB_PROCESSOR_REGISTRY],
+        }
+    }
+}

package/templates/be/patterns/jobs/platform-lite/jobs.sql.tpl

@@ -93,3 +93,47 @@ revoke all on function public.job_complete(uuid, bigint, timestamptz) from publi
 grant execute on function public.job_complete(uuid, bigint, timestamptz) to app_be;
 revoke all on function public.job_fail(uuid, bigint, text, timestamptz) from public;
 grant execute on function public.job_fail(uuid, bigint, text, timestamptz) to app_be;
+
+-- The scheduler ticks of platform/jobs (R335): one row per tick holds the last UTC minute it fired. Every replica's
+-- @nestjs/schedule fires the tick; under advisoryXactLock('tick:<name>') job_tick_claim moves the row to the new minute and
+-- answers claimed, so exactly one replica enqueues the tick's job per minute and a replica that comes later answers not claimed.
+create table public.job_ticks (
+    name varchar(200) not null,
+    minute varchar(16) not null,
+    constraint job_ticks_pkey primary key (name)
+);
+
+alter table public.job_ticks enable row level security;
+alter table public.job_ticks force row level security;
+
+create policy job_ticks_app_be_select
+on public.job_ticks for select to app_be
+using (name is not null);
+
+create policy job_ticks_app_be_insert
+on public.job_ticks for insert to app_be
+with check (name is not null);
+
+create policy job_ticks_app_be_update
+on public.job_ticks for update to app_be
+using (name is not null)
+with check (name is not null);
+
+revoke all on table public.job_ticks from public, anon, authenticated;
+grant select, insert, update on table public.job_ticks to app_be;
+
+create function public.job_tick_claim(p_name varchar, p_minute varchar)
+returns table (claimed boolean)
+language sql
+as $$
+    with moved as (
+        insert into public.job_ticks as t (name, minute) values (p_name, p_minute)
+        on conflict (name) do update set minute = excluded.minute
+         where t.minute < excluded.minute
+        returning true as claimed
+    )
+    select coalesce((select m.claimed from moved as m), false)
+$$;
+
+revoke all on function public.job_tick_claim(varchar, varchar) from public;
+grant execute on function public.job_tick_claim(varchar, varchar) to app_be;

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

@@ -1,6 +1,7 @@
 /**
  * The entity list of the primary connection: each capability's `<c>Entities` array (its `persistence/entities/index.ts`), by
- * name, no glob. Only an app's composition root imports this file, from the deep path `@modules/platform/database/entities`;
- * DatabaseModule and the database barrel never do, since the capability barrels import the database capability back.
+ * name, no glob (the entity registry, slot be.platform.database.entities). Only app composition and the test world import this
+ * file, from the deep path `@modules/platform/database/entities`; DatabaseModule and the database barrel never do, since the
+ * capability barrels import the database capability back.
  */
 export const PRIMARY_ENTITIES: ReadonlyArray<Function> = []