Skip to content

Commit 690ca72

Browse files
authored
Merge pull request #4 from BetterTyped/chore/remove-process-role
Chore/remove process role
2 parents 0e147b7 + 46770ae commit 690ca72

11 files changed

Lines changed: 73 additions & 120 deletions

File tree

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

Lines changed: 3 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
description: Background work on the backend, cron jobs in the scheduler vs tasks in the Postgres queue, transactional enqueue, retries, idempotent handlers, PROCESS_ROLE for running a separate worker
2+
description: Background work on the backend, cron jobs in the scheduler vs tasks in the Postgres queue, transactional enqueue, retries, idempotent handlers
33
globs: apps/backend/src/**/*
44
alwaysApply: false
55
---
@@ -64,14 +64,6 @@ The task commits or rolls back with the row. A row can never sit in `queued` wit
6464

6565
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`.
6666

67-
## Running a separate worker
67+
## Where tasks run
6868

69-
`PROCESS_ROLE` picks what a process does. Same image, same start command.
70-
71-
| Role | API routes | Cron jobs | Task workers |
72-
| --- | --- | --- | --- |
73-
| `all` (default) | yes | yes | yes |
74-
| `web` | yes | no | no |
75-
| `worker` | `/health` only | yes | yes |
76-
77-
Start with `all`. When background work starts slowing requests down, deploy the backend a second time with `PROCESS_ROLE=worker` (same database, bucket, and provider keys, no public domain, no migration command) and set the public one to `web`. The two never talk to each other. Postgres is the hand-off, so you can run as many workers as you need.
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: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +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 in-process or as a separate worker with one env var
79+
- 📬 **Task queue**: Postgres-backed (pg-boss), retries with backoff, runs inside the API process
8080
- 🌍 **i18n ready**: Paraglide wired into every app, backend responses included
8181
- 🎨 **UI ready**: Tailwind v4 + shadcn/ui on web, NativeWind on mobile. CSR or SSR with a script switch
8282
- ⚡ **Rust-powered DX**: OXC lint/format, React Compiler through oxc, Vite 8 HMR in milliseconds

‎apps/backend/.env.example‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -26,14 +26,6 @@ RUSTFS_ENDPOINT=http://localhost:9000
2626
RUSTFS_ACCESS_KEY=rustfsadmin
2727
RUSTFS_SECRET_KEY=rustfsadmin
2828

29-
# -----------------
30-
# Process role
31-
# -----------------
32-
33-
# all (default): API, cron, and task workers in one process.
34-
# To move background work off the API, run this image twice: web on one, worker on the other.
35-
# PROCESS_ROLE=all
36-
3729
# -----------------
3830
# External Services
3931
# -----------------

‎apps/backend/src/config/env/env.config.ts‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,6 @@ export const envSchema = z.object({
2121
RESEND_API_KEY: z.string(),
2222
// # Sentry
2323
SENTRY_DSN: z.string(),
24-
// # Process role: "all" runs the API, cron, and task workers together; split them with "web" + "worker"
25-
PROCESS_ROLE: z.enum(["all", "web", "worker"]).optional(),
2624
});
2725

2826
export type Env = z.infer<typeof envSchema>;

‎apps/backend/src/libs/queue/process-role.spec.ts‎

Lines changed: 0 additions & 34 deletions
This file was deleted.

‎apps/backend/src/libs/queue/process-role.ts‎

Lines changed: 0 additions & 30 deletions
This file was deleted.

‎apps/backend/src/libs/queue/queue.spec.ts‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,9 @@ describe("task queue", () => {
8484
// is a no-op while an instance is up, so swap it for this spec's queues in a throwaway schema.
8585
const start = async (workers: boolean) => {
8686
await stopQueues();
87-
await startQueues([plain, failing, capped, exclusive], {
87+
await startQueues({
88+
queues: [plain, failing, capped, exclusive],
89+
postgres: env.postgres,
8890
workers,
8991
pollingIntervalSeconds: 0.5,
9092
boss: { schema: SCHEMA },
@@ -103,6 +105,18 @@ describe("task queue", () => {
103105
await sql`drop schema if exists ${sql.id(SCHEMA)} cascade`.execute(env.db);
104106
});
105107

108+
it("costs nothing until a queue is registered: no schema, and a clear error on enqueue", async () => {
109+
await stopQueues();
110+
111+
await startQueues({ queues: [], postgres: env.postgres, boss: { schema: SCHEMA } });
112+
113+
const schemas = await sql<{ count: string }>`
114+
select count(*) as count from information_schema.schemata where schema_name = ${SCHEMA}
115+
`.execute(env.db);
116+
expect(Number(schemas.rows[0]?.count)).toBe(0);
117+
await expect(enqueue(plain, { value: "nowhere to go" })).rejects.toThrow(/task queue is not running/);
118+
});
119+
106120
it("runs an enqueued task with its payload and attempt number", async () => {
107121
await start(true);
108122
await enqueue(plain, { value: "hello" });

‎apps/backend/src/libs/queue/queue.ts‎

Lines changed: 44 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
import { captureException } from "@sentry/node";
2-
import type { Transaction } from "kysely";
3-
import { fromKysely, PgBoss, type ConstructorOptions, type JobWithMetadata } from "pg-boss";
2+
import { CompiledQuery, type Kysely, type Transaction } from "kysely";
3+
import { fromKysely, PgBoss, type ConstructorOptions, type Db, type JobWithMetadata } from "pg-boss";
44
import type { z } from "zod";
55

66
import type { DB } from "../../db/postgres/types/types";
77
import { logger } from "../logger/logger";
8-
import { runsWorkers } from "./process-role";
98

109
/**
1110
* Task queue on Postgres (pg-boss).
@@ -14,12 +13,15 @@ import { runsWorkers } from "./process-role";
1413
* tick that should return fast; anything slow or heavy (parsing an upload, calling a model,
1514
* sending a batch) belongs here as a task:
1615
*
17-
* - Tasks live in Postgres, in their own `pgboss` schema, so there is nothing extra to deploy.
16+
* - Tasks live in Postgres, in their own `pgboss` schema, so there is nothing extra to deploy. The
17+
* queue runs on the connection it is handed (`startQueues({ queues, postgres })`), so it opens no
18+
* pool of its own, and the schema only appears once a queue is registered; until then this
19+
* module does nothing at all.
1820
* `enqueue` accepts the caller's transaction: the task commits or rolls back together with the
1921
* row it is about, so a row can never sit "queued" with no task behind it.
20-
* - Every backend instance works tasks, with a per-queue concurrency cap per instance. Adding a
21-
* replica adds capacity. To split the load off the API, run the same image a second time with
22-
* PROCESS_ROLE=worker and set the API to PROCESS_ROLE=web. See `process-role.ts`.
22+
* - Tasks run inside the backend process, with a per-queue concurrency cap. Every instance works
23+
* them, so adding a replica adds capacity. Nothing here assumes the server is the only place
24+
* that can work them: anything that has a database connection can call `startQueues`.
2325
* - A failed run is retried with backoff up to `retryLimit`, then `onExhausted` fires once so the
2426
* feature can mark its own row as failed. A handler that hits an error no retry can fix (bad
2527
* file, unsupported format) should record that itself and return normally.
@@ -80,7 +82,11 @@ export type EnqueueOptions = {
8082
};
8183

8284
export type StartQueuesOptions = {
83-
/** Overrides the role and test-environment default. Specs turn workers on to exercise retries. */
85+
/** The queues to register, normally the array from src/queues/index.ts. */
86+
queues: AnyQueueDefinition[];
87+
/** The backend's database handle. The queue runs on its connections instead of opening a pool. */
88+
postgres: { qb: Kysely<DB> };
89+
/** Work tasks in this process. Defaults to true, and to false under NODE_ENV=test. */
8490
workers?: boolean;
8591
/** Seconds between polls of an idle queue. Defaults to 2. */
8692
pollingIntervalSeconds?: number;
@@ -154,19 +160,34 @@ const registerQueue = async (instance: PgBoss, queue: AnyQueueDefinition): Promi
154160
};
155161

156162
/**
157-
* Connect, install or migrate the `pgboss` schema, register every queue, and (unless this process
158-
* is web-only or under test) start working them. Every role calls this, because every role may
159-
* enqueue. Safe to call once per process; call `stopQueues` on shutdown.
163+
* pg-boss speaks plain SQL through one method, so it can run on the backend's own connections. The
164+
* plugins come off for it: CamelCasePlugin would rename the columns pg-boss reads back.
160165
*/
161-
export const startQueues = async (queues: AnyQueueDefinition[], options: StartQueuesOptions = {}): Promise<void> => {
166+
const toBossDb = (postgres: StartQueuesOptions["postgres"]): Db => {
167+
const raw = postgres.qb.withoutPlugins();
168+
return {
169+
executeSql: async (text, values = []) => {
170+
const result = await raw.executeQuery(CompiledQuery.raw(text, values));
171+
return { rows: result.rows };
172+
},
173+
};
174+
};
175+
176+
/**
177+
* Install or migrate the `pgboss` schema, register every queue, and (unless under test) start
178+
* working them. Safe to call once per process; call `stopQueues` on shutdown.
179+
*/
180+
export const startQueues = async (options: StartQueuesOptions): Promise<void> => {
181+
const { queues } = options;
162182
if (boss) return;
183+
// Free until used: a project with no queue gets no `pgboss` schema and no polling. The registry
184+
// ships empty, and the first pack that adds a queue turns this on.
185+
if (queues.length === 0) return;
163186
assertValidQueues(queues);
164187

165188
const instance = new PgBoss({
166-
connectionString: process.env.DATABASE_URL,
189+
db: toBossDb(options.postgres),
167190
schema: SCHEMA,
168-
// Small on purpose: this pool sits next to the Prisma and Kysely pools on the same database.
169-
max: 4,
170191
// Cron stays with the scheduler module; one clock is enough.
171192
schedule: false,
172193
...options.boss,
@@ -182,7 +203,7 @@ export const startQueues = async (queues: AnyQueueDefinition[], options: StartQu
182203
boss = instance;
183204
registered = new Set(queues.map((queue) => queue.name));
184205

185-
const working = options.workers ?? (runsWorkers() && process.env.NODE_ENV !== "test");
206+
const working = options.workers ?? process.env.NODE_ENV !== "test";
186207
if (working) {
187208
await Promise.all(
188209
queues.map((queue) =>
@@ -216,7 +237,12 @@ export const enqueue = async <T>(
216237
data: T,
217238
options: EnqueueOptions = {},
218239
): Promise<string | null> => {
219-
if (!boss) throw new Error("Queue: enqueue called before startQueues");
240+
if (!boss) {
241+
throw new Error(
242+
`Queue: cannot enqueue "${queue.name}", the task queue is not running. ` +
243+
"Register the queue in src/queues/index.ts (it only starts when at least one is registered).",
244+
);
245+
}
220246
if (!registered.has(queue.name)) {
221247
throw new Error(`Queue: "${queue.name}" is not registered in src/queues/index.ts`);
222248
}
@@ -230,7 +256,7 @@ export const enqueue = async <T>(
230256
});
231257
};
232258

233-
/** Lets in-flight tasks finish (up to 30s), then closes the pool. */
259+
/** Lets in-flight tasks finish (up to 30s). The database connection belongs to the caller and stays open. */
234260
export const stopQueues = async (): Promise<void> => {
235261
if (!boss) return;
236262
const instance = boss;

‎apps/backend/src/main.ts‎

Lines changed: 7 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,13 @@ import { Hono } from "hono";
66
import { cors } from "hono/cors";
77

88
import { Env, validateEnv } from "./config/env/env.config";
9-
import { setupContext } from "./context";
9+
import { postgres, setupContext } from "./context";
1010
import { createAppSwapper, createBootApp } from "./libs/boot/boot-app";
1111
import { BootState, BootStage, getBootState, setBootError } from "./libs/boot/boot-state";
1212
import { logger } from "./libs/logger/logger";
1313
import { ApplicationError, AuthorizationError, DatabaseError, ValidationError } from "./middleware/error";
1414
import { AuthError } from "./middleware/error/auth-error/types";
1515
import { errorMiddleware, onError } from "./middleware/error/error-middleware";
16-
import { getProcessRole, runsWorkers, servesApi } from "./libs/queue/process-role";
1716
import { startQueues, stopQueues } from "./libs/queue/queue";
1817
import { startScheduler, stopScheduler } from "./libs/scheduler/scheduler";
1918
import { m } from "./paraglide/messages.js";
@@ -72,20 +71,16 @@ const initialize = async (server: ReturnType<typeof serve>): Promise<Hono> => {
7271
app.get("/ping/*", (c) => {
7372
return c.json<{ message: string; success: boolean }>({ message: m.pong(), success: true });
7473
});
75-
// PROCESS_ROLE=worker keeps /health for the platform's checks and serves nothing else.
76-
if (servesApi()) {
77-
registerSockets(app);
78-
registerRoutes(app);
79-
}
74+
registerSockets(app);
75+
registerRoutes(app);
8076

81-
// Every role connects to the task queue, because every role may enqueue; only roles that run
82-
// workers pick tasks up. Queues are registered in src/queues/index.ts.
83-
await startQueues(queues);
77+
// The task queue lives in Postgres, so it starts after context setup; queues are registered in
78+
// src/queues/index.ts and worked by this same process.
79+
await startQueues({ queues, postgres });
8480

8581
// The scheduler needs the database (advisory locks, job_run bookkeeping), so it starts after
8682
// context setup; jobs are registered in src/jobs/index.ts.
87-
if (runsWorkers()) startScheduler(jobs);
88-
logger.info(`Process role: ${getProcessRole()}`);
83+
startScheduler(jobs);
8984

9085
/* -------------------------------------------------------------------------------------------------
9186
* Handlers

‎apps/backend/src/queues/index.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import type { AnyQueueDefinition } from "../libs/queue/queue";
33
/**
44
* Registered task queues. Ships empty on purpose: feature packs append entries at install time
55
* through the CLI's queues codemod, and app code can add its own the same way. Every entry gets
6-
* workers on each instance that runs them (see PROCESS_ROLE); see the queue module for retries,
7-
* transactional enqueue, and why handlers must be safe to run twice.
6+
* workers in this process; see the queue module for retries, transactional enqueue, and why
7+
* handlers must be safe to run twice.
88
*/
99
export const queues: AnyQueueDefinition[] = [];

0 commit comments

Comments
 (0)