Skip to content

Commit a036ecd

Browse files
committed
Merge remote-tracking branch 'origin/main' into chore/hyper-fetch-9
2 parents d5e4985 + 8871cd9 commit a036ecd

10 files changed

Lines changed: 670 additions & 5 deletions

File tree

‎.cursor/rules/background-work.mdc‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
description: Background work on the backend, cron jobs in the scheduler vs tasks in the Postgres queue, transactional enqueue, retries, idempotent handlers
3+
globs: apps/backend/src/**/*
4+
alwaysApply: false
5+
---
6+
7+
# Background Work
8+
9+
Two tools, two questions. The scheduler (`src/libs/scheduler`) answers **when**. The task queue (`src/libs/queue`) answers **how much at once**.
10+
11+
| | Job | Task |
12+
| --- | --- | --- |
13+
| What | a cron entry | one queued unit of work |
14+
| Registered in | `src/jobs/index.ts` | `src/queues/index.ts` |
15+
| Runs | once per fire across all instances | on any instance, up to the queue's `concurrency` each |
16+
| Good for | sweeps, digests, cleanup, "every night at 3" | parsing an upload, calling a model, sending a batch |
17+
| Must be | fast: it holds a database transaction while it runs | safe to run twice |
18+
19+
If a job finds slow work, it enqueues tasks and returns. It never does the slow work itself.
20+
21+
## Defining a queue
22+
23+
```ts
24+
// src/features/reports/queues/render-report.queue.ts
25+
export const renderReportQueue = defineQueue({
26+
name: "render-report",
27+
schema: z.object({ reportId: z.string() }),
28+
concurrency: 2,
29+
exclusive: true,
30+
run: async ({ data, signal }) => {
31+
await renderReport(data.reportId, signal);
32+
},
33+
onExhausted: async ({ data }) => {
34+
await markReportFailed(data.reportId);
35+
},
36+
});
37+
```
38+
39+
Then add it to the array in `src/queues/index.ts`. `enqueue` throws for a queue that is not registered there.
40+
41+
## Enqueue in the same transaction as the row
42+
43+
```ts
44+
await postgres.qb.transaction().execute(async (trx) => {
45+
await trx.insertInto("report").values(report).execute();
46+
await enqueue(renderReportQueue, { reportId: report.id }, { trx, key: report.id });
47+
});
48+
```
49+
50+
The task commits or rolls back with the row. A row can never sit in `queued` with nothing behind it. Never enqueue before the transaction, and never after it in a separate step.
51+
52+
## Rules
53+
54+
- **Payloads are ids, not data.** Put `{ reportId }` in the task and read the row in the handler. The row is the truth, the payload is a pointer.
55+
- **Status lives in your table.** Keep a status column the UI can read. The queue is plumbing, not a place the frontend looks.
56+
- **Handlers run twice sometimes.** A crash or a deploy mid-run means a retry. Checkpoint progress in your own tables and resume from it.
57+
- **Errors a retry cannot fix are not thrown.** Bad file, unsupported format: write the failure to your row and return. Throw only when trying again could help.
58+
- **`onExhausted` marks the row failed.** It fires once, after the last retry. Sentry gets the error either way.
59+
- **Pass `signal` to slow calls.** It aborts on expiry and on shutdown.
60+
- **No `try/catch` to swallow errors in a handler.** Same rule as routes: let it throw, the queue logs, retries, and reports.
61+
- **Use `exclusive` with a `key`** when the task is "process row X", so a double click cannot process it twice.
62+
63+
## Testing
64+
65+
Workers are off under `NODE_ENV=test`, so nothing runs behind a test's back. `setupIntegrationTest()` starts the queue, which means code under test can enqueue. To test a handler, call the queue's `run` directly with a task object. To test the queue itself, see `src/libs/queue/queue.spec.ts`.
66+
67+
## Where tasks run
68+
69+
Inside the backend process, next to the API and the scheduler. `main.ts` starts it with `startQueues({ queues, postgres })`, and it runs on that connection, so it opens no pool of its own. The queue is free until used: with nothing in `src/queues/index.ts` it opens no connections and creates no schema. There is no separate worker to deploy. Every instance works tasks, each up to the queue's `concurrency`, so adding a backend replica adds capacity. Keep `concurrency` low for anything memory-heavy: it shares the process with your requests.

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ Features arrive when you ask for them. The CLI writes whole features into your r
7676
- 📡 **HyperFetch SDK**: typed HTTP and WebSocket client generated from your Hono routes
7777
- 🗄️ **Postgres + Prisma**: migrations, Kysely queries, pgvector ready
7878
- ⏰ **Cron scheduler**: in-process jobs with exactly-once runs and catch-up after downtime
79+
- 📬 **Task queue**: Postgres-backed (pg-boss), retries with backoff, runs inside the API process
7980
- 🌍 **i18n ready**: Paraglide wired into every app, backend responses included
8081
- 🎨 **UI ready**: Tailwind v4 + shadcn/ui on web, NativeWind on mobile. CSR or SSR with a script switch
8182
- ⚡ **Rust-powered DX**: OXC lint/format, React Compiler through oxc, Vite 8 HMR in milliseconds
@@ -272,7 +273,7 @@ Every client imports `@internal/backend` as a workspace dependency. Change a res
272273
| Mobile | Expo SDK 57, Expo Router, NativeWind |
273274
| Extension | Vite build for Chrome, Edge and Firefox |
274275
| Desktop | Electron Forge (macOS, Windows, Linux) |
275-
| Backend | Hono, Prisma 7, Kysely, Zod, croner, Resend |
276+
| Backend | Hono, Prisma 7, Kysely, Zod, croner, pg-boss, Resend |
276277
| Data layer | HyperFetch SDK, typed HTTP and WebSocket bridge |
277278
| Database | PostgreSQL 17 + pgvector |
278279
| Cache | Valkey (Redis-compatible) |

‎apps/backend/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@
5353
"kysely": "^0.28.16",
5454
"multer": "^2.1.1",
5555
"pg": "^8.20.0",
56+
"pg-boss": "^12.33.1",
5657
"pino": "^10.3.1",
5758
"pino-pretty": "^13.1.3",
5859
"prisma": "^7.8.0",
Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
import { setupIntegrationTest } from "@backend/testing/setup/test-utils";
2+
import { sql } from "kysely";
3+
import { z } from "zod";
4+
5+
import { defineQueue, enqueue, startQueues, stopQueues, type Task } from "./queue";
6+
7+
// Needs the test Postgres and Valkey (`pnpm test:setup`). The `.integration.test.ts` name is what
8+
// keeps it out of runs that have no services, like a fresh checkout or the registry e2e lanes.
9+
const SCHEMA = "pgboss_spec";
10+
const payload = z.object({ value: z.string() });
11+
type Payload = z.infer<typeof payload>;
12+
13+
const until = (check: () => boolean, timeoutMs = 20_000): Promise<void> =>
14+
vi.waitFor(
15+
() => {
16+
if (!check()) throw new Error("Timed out waiting for the queue");
17+
},
18+
{ timeout: timeoutMs, interval: 100 },
19+
);
20+
21+
describe("task queue", () => {
22+
const env = setupIntegrationTest();
23+
24+
const seen: Task<Payload>[] = [];
25+
const exhausted: Task<Payload>[] = [];
26+
let running = 0;
27+
let peak = 0;
28+
29+
const plain = defineQueue({
30+
name: "spec-plain",
31+
schema: payload,
32+
run: async (task) => {
33+
seen.push(task);
34+
},
35+
});
36+
37+
const failing = defineQueue({
38+
name: "spec-failing",
39+
schema: payload,
40+
retryLimit: 2,
41+
retryDelay: 0,
42+
retryBackoff: false,
43+
run: async (task) => {
44+
seen.push(task);
45+
throw new Error("always fails");
46+
},
47+
onExhausted: async (task) => {
48+
exhausted.push(task);
49+
},
50+
});
51+
52+
const capped = defineQueue({
53+
name: "spec-capped",
54+
schema: payload,
55+
concurrency: 2,
56+
run: async (task) => {
57+
running += 1;
58+
peak = Math.max(peak, running);
59+
await new Promise((resolve) => setTimeout(resolve, 300));
60+
running -= 1;
61+
seen.push(task);
62+
},
63+
});
64+
65+
const exclusive = defineQueue({ name: "spec-exclusive", schema: payload, exclusive: true, run: async () => undefined });
66+
67+
const unregistered = defineQueue({ name: "spec-unregistered", schema: payload, run: async () => undefined });
68+
69+
// The shared test environment already started the app's own (empty) registry, and startQueues
70+
// is a no-op while an instance is up, so swap it for this spec's queues in a throwaway schema.
71+
const start = async (workers: boolean) => {
72+
await stopQueues();
73+
await startQueues({
74+
queues: [plain, failing, capped, exclusive],
75+
postgres: env.postgres,
76+
workers,
77+
pollingIntervalSeconds: 0.5,
78+
boss: { schema: SCHEMA },
79+
});
80+
};
81+
82+
beforeEach(() => {
83+
seen.length = 0;
84+
exhausted.length = 0;
85+
running = 0;
86+
peak = 0;
87+
});
88+
89+
afterEach(async () => {
90+
await stopQueues();
91+
await sql`drop schema if exists ${sql.id(SCHEMA)} cascade`.execute(env.db);
92+
});
93+
94+
it("costs nothing until a queue is registered: no schema, and a clear error on enqueue", async () => {
95+
await stopQueues();
96+
97+
await startQueues({ queues: [], postgres: env.postgres, boss: { schema: SCHEMA } });
98+
99+
const schemas = await sql<{ count: string }>`
100+
select count(*) as count from information_schema.schemata where schema_name = ${SCHEMA}
101+
`.execute(env.db);
102+
expect(Number(schemas.rows[0]?.count)).toBe(0);
103+
await expect(enqueue(plain, { value: "nowhere to go" })).rejects.toThrow(/task queue is not running/);
104+
});
105+
106+
it("runs an enqueued task with its payload and attempt number", async () => {
107+
await start(true);
108+
await enqueue(plain, { value: "hello" });
109+
110+
await until(() => seen.length === 1);
111+
expect(seen[0]?.data).toEqual({ value: "hello" });
112+
expect(seen[0]?.attempt).toBe(1);
113+
});
114+
115+
it("drops the task when the enqueueing transaction rolls back", async () => {
116+
await start(true);
117+
118+
await env.db
119+
.transaction()
120+
.execute(async (trx) => {
121+
await enqueue(plain, { value: "rolled back" }, { trx });
122+
throw new Error("rollback");
123+
})
124+
.catch(() => undefined);
125+
await env.db.transaction().execute(async (trx) => {
126+
await enqueue(plain, { value: "committed" }, { trx });
127+
});
128+
129+
await until(() => seen.length === 1);
130+
// Give a wrongly surviving task two more polls to show up.
131+
await new Promise((resolve) => setTimeout(resolve, 1200));
132+
expect(seen.map((task) => task.data.value)).toEqual(["committed"]);
133+
});
134+
135+
it("retries a failing task up to the limit, then reports it exhausted once", async () => {
136+
await start(true);
137+
await enqueue(failing, { value: "doomed" });
138+
139+
await until(() => exhausted.length === 1);
140+
expect(seen.map((task) => task.attempt)).toEqual([1, 2, 3]);
141+
expect(exhausted[0]?.attempt).toBe(3);
142+
});
143+
144+
it("never runs more tasks at once than the queue's concurrency", async () => {
145+
await start(true);
146+
await Promise.all(["a", "b", "c", "d", "e"].map((value) => enqueue(capped, { value })));
147+
148+
await until(() => seen.length === 5);
149+
expect(peak).toBe(2);
150+
});
151+
152+
it("keeps one task per key on an exclusive queue", async () => {
153+
await start(false);
154+
155+
const first = await enqueue(exclusive, { value: "one" }, { key: "row-1" });
156+
const duplicate = await enqueue(exclusive, { value: "two" }, { key: "row-1" });
157+
const other = await enqueue(exclusive, { value: "three" }, { key: "row-2" });
158+
159+
expect(first).toEqual(expect.any(String));
160+
expect(duplicate).toBeNull();
161+
expect(other).toEqual(expect.any(String));
162+
await expect(enqueue(exclusive, { value: "no key" })).rejects.toThrow(/needs a key/);
163+
});
164+
165+
it("accepts tasks but runs none when workers are off", async () => {
166+
await start(false);
167+
await enqueue(plain, { value: "parked" });
168+
169+
await new Promise((resolve) => setTimeout(resolve, 1500));
170+
expect(seen).toHaveLength(0);
171+
});
172+
173+
it("rejects a bad payload and an unregistered queue", async () => {
174+
await start(false);
175+
176+
await expect(enqueue(plain, { value: 1 } as unknown as Payload)).rejects.toThrow(/expected string/i);
177+
await expect(enqueue(unregistered, { value: "x" })).rejects.toThrow(/not registered/);
178+
});
179+
});
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
import { z } from "zod";
2+
3+
import { assertValidQueues, defineQueue } from "./queue";
4+
5+
const payload = z.object({ value: z.string() });
6+
7+
describe("assertValidQueues", () => {
8+
const queue = (name: string, concurrency?: number) => defineQueue({ name, schema: payload, concurrency, run: async () => undefined });
9+
10+
it("rejects duplicate names", () => {
11+
expect(() => assertValidQueues([queue("same"), queue("same")])).toThrow(/duplicate queue name/);
12+
});
13+
14+
it("rejects empty names", () => {
15+
expect(() => assertValidQueues([queue(" ")])).toThrow(/empty name/);
16+
});
17+
18+
it("rejects a concurrency below 1", () => {
19+
expect(() => assertValidQueues([queue("zero", 0)])).toThrow(/concurrency/);
20+
});
21+
});

0 commit comments

Comments
 (0)