@skaile/forge-layer-jobs 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,48 @@
1
1
  {
2
2
  "name": "@skaile/forge-layer-jobs",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Nuxt layer for apps built on forge-template-app: background jobs on pg-boss in the app's own database, defineJob, APP_ROLE web/worker, the jobs.* actions and a Jobs page.",
5
+ "type": "module",
6
+ "main": "./nuxt.config.ts",
7
+ "files": [
8
+ "nuxt.config.ts",
9
+ "app",
10
+ "server",
11
+ "shared",
12
+ "README.md",
13
+ "CHANGELOG.md",
14
+ "LICENSE"
15
+ ],
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "git+https://github.com/skaile-ai/forge.git",
19
+ "directory": "packages/layer-jobs"
20
+ },
21
+ "keywords": [
22
+ "nuxt",
23
+ "nuxt-layer",
24
+ "pg-boss",
25
+ "jobs",
26
+ "skaile"
27
+ ],
28
+ "publishConfig": {
29
+ "access": "public"
30
+ },
31
+ "license": "MIT",
32
+ "scripts": {
33
+ "check": "bun ../../scripts/check-package.ts"
34
+ },
35
+ "peerDependencies": {
36
+ "@nuxt/ui": "^4.11.1",
37
+ "@skaile/forge-app-actions": "^0.6.0",
38
+ "drizzle-orm": "^0.45.0",
39
+ "h3": "^1.15.0",
40
+ "nuxt": "^4.0.0",
41
+ "pg-boss": "^12.0.0",
42
+ "vue": "^3.5.0",
43
+ "zod": "^4.0.0"
44
+ },
45
+ "engines": {
46
+ "node": ">=20"
47
+ }
48
+ }
@@ -0,0 +1,266 @@
1
+ import { createError } from 'h3'
2
+ import * as z from 'zod'
3
+ import type { AppActionContext } from '~~/server/utils/actions/define'
4
+ import { defineAppAction, requireFound } from '~~/server/utils/actions/define'
5
+ import type { Principal } from '~~/server/utils/principal'
6
+ import { requireScope } from '~~/server/utils/principal'
7
+ import type { JobState } from '../../shared/jobs'
8
+ import { JOB_STATES } from '../../shared/jobs'
9
+ import { BOSS_SCHEMA, enqueueJob, jobsReady, parseJobPayload, requireJob } from './boss'
10
+ import type { JobData, JobRequester } from './define'
11
+ import { allJobs } from './define'
12
+
13
+ interface JobRow {
14
+ id: string
15
+ name: string
16
+ state: JobState
17
+ data: JobData | null
18
+ output: unknown
19
+ retryCount: number
20
+ retryLimit: number
21
+ startAfter: Date | string
22
+ createdOn: Date | string
23
+ startedOn: Date | string | null
24
+ completedOn: Date | string | null
25
+ }
26
+
27
+ const JOB_COLUMNS = `id, name, state::text as state, data, output, retry_count as "retryCount", retry_limit as "retryLimit",
28
+ start_after as "startAfter", created_on as "createdOn", started_on as "startedOn", completed_on as "completedOn"`
29
+
30
+ const iso = (value: Date | string | null) => (value === null ? null : new Date(value).toISOString())
31
+
32
+ /** The failure message pg-boss stored in `output` when a handler threw. */
33
+ function errorOf(row: JobRow): string | null {
34
+ if (row.state !== 'failed' && row.state !== 'retry') return null
35
+ const output = row.output
36
+ if (output && typeof output === 'object' && 'message' in output && typeof output.message === 'string')
37
+ return output.message
38
+ return null
39
+ }
40
+
41
+ function jobDto(row: JobRow) {
42
+ return {
43
+ id: row.id,
44
+ name: row.name,
45
+ state: row.state,
46
+ payload: row.data?.payload ?? null,
47
+ requestedBy: row.data?.requestedBy ?? null,
48
+ output: row.output ?? null,
49
+ error: errorOf(row),
50
+ retryCount: row.retryCount,
51
+ retryLimit: row.retryLimit,
52
+ startAfter: iso(row.startAfter)!,
53
+ createdAt: iso(row.createdOn)!,
54
+ startedAt: iso(row.startedOn),
55
+ completedAt: iso(row.completedOn),
56
+ }
57
+ }
58
+ export type JobDto = ReturnType<typeof jobDto>
59
+
60
+ /** Reads pg-boss's own tables through its connection (PGlite adapter or its pool); the same SQL on both engines. */
61
+ async function query<T>(text: string, values: unknown[]): Promise<T[]> {
62
+ const boss = await jobsReady()
63
+ const { rows } = await boss.getDb().executeSql(text, values)
64
+ return rows as T[]
65
+ }
66
+
67
+ async function loadJob(id: string): Promise<JobDto> {
68
+ const [row] = await query<JobRow>(
69
+ `select ${JOB_COLUMNS} from ${BOSS_SCHEMA}.job where id = $1 and name = any($2::text[])`,
70
+ [id, allJobs().map(job => job.name)],
71
+ )
72
+ return jobDto(requireFound(row, 'Job', id))
73
+ }
74
+
75
+ function requesterOf(principal: Principal): JobRequester | null {
76
+ return principal.kind === 'system' ? null : { id: principal.id, name: principal.name }
77
+ }
78
+
79
+ const jobName = z.string().trim().min(1).max(100)
80
+
81
+ async function authorizeEnqueue(input: { name: string; payload: unknown }, ctx: AppActionContext): Promise<void> {
82
+ requireScope(ctx, 'jobs:write')
83
+ const job = requireJob(input.name)
84
+ if (ctx.principal.kind === 'agent' && !job.audience.includes('llm')) {
85
+ throw createError({ statusCode: 403, statusMessage: `${job.name} cannot be enqueued by agents` })
86
+ }
87
+ await job.authorize?.(parseJobPayload(job, input.payload), ctx)
88
+ }
89
+
90
+ export const jobActions = [
91
+ defineAppAction({
92
+ id: 'jobs.list',
93
+ kind: 'query',
94
+ audience: ['user', 'llm'],
95
+ description:
96
+ 'Recent background jobs across all registered job queues, newest first, with state (created, retry, active, completed, cancelled, failed), payload, output and error. Filter by job name and state(s). Returns { items, total, counts (per state), names (registered job names) }.',
97
+ input: z
98
+ .object({
99
+ name: jobName.optional().describe('Only jobs of this registered job name (see jobs.schedules)'),
100
+ state: z
101
+ .union([z.enum(JOB_STATES), z.array(z.enum(JOB_STATES)).min(1)])
102
+ .optional()
103
+ .describe('One state or a list, e.g. ["failed","retry"]'),
104
+ limit: z.number().int().min(1).max(100).default(25).describe('Page size, 1-100 (default 25)'),
105
+ offset: z.number().int().min(0).default(0).describe('Rows to skip (default 0)'),
106
+ })
107
+ .strict(),
108
+ authorize: (_input, ctx) => {
109
+ requireScope(ctx, 'jobs:read')
110
+ },
111
+ run: async input => {
112
+ const names = input.name ? [requireJob(input.name).name] : allJobs().map(job => job.name)
113
+ const states =
114
+ input.state === undefined ? [...JOB_STATES] : Array.isArray(input.state) ? input.state : [input.state]
115
+ const [rows, counts] = await Promise.all([
116
+ query<JobRow>(
117
+ `select ${JOB_COLUMNS} from ${BOSS_SCHEMA}.job
118
+ where name = any($1::text[]) and state::text = any($2::text[])
119
+ order by created_on desc, id desc limit $3 offset $4`,
120
+ [names, states, input.limit, input.offset],
121
+ ),
122
+ query<{ state: JobState; count: number }>(
123
+ `select state::text as state, count(*)::int as count from ${BOSS_SCHEMA}.job where name = any($1::text[]) group by state`,
124
+ [names],
125
+ ),
126
+ ])
127
+ const perState = Object.fromEntries(JOB_STATES.map(state => [state, 0])) as Record<JobState, number>
128
+ for (const row of counts) perState[row.state] = Number(row.count)
129
+ return {
130
+ items: rows.map(jobDto),
131
+ total: states.reduce((sum, state) => sum + perState[state], 0),
132
+ counts: perState,
133
+ names: allJobs().map(job => job.name),
134
+ }
135
+ },
136
+ }),
137
+
138
+ defineAppAction({
139
+ id: 'jobs.get',
140
+ kind: 'query',
141
+ audience: ['user', 'llm'],
142
+ description: "One background job by id: state, payload, who requested it, output (the handler's result) and error.",
143
+ input: z.object({ id: z.uuid().describe('Job id (from jobs.list or jobs.enqueue)') }).strict(),
144
+ authorize: (_input, ctx) => {
145
+ requireScope(ctx, 'jobs:read')
146
+ },
147
+ run: input => loadJob(input.id),
148
+ }),
149
+
150
+ defineAppAction({
151
+ id: 'jobs.enqueue',
152
+ kind: 'effect',
153
+ destructive: false,
154
+ audience: ['user', 'llm'],
155
+ description:
156
+ "Start a registered background job. The payload is validated by the job's own schema (see jobs.schedules › jobs for names, descriptions and payload schemas). " +
157
+ 'Returns { id, name, skipped }; follow progress with jobs.get.',
158
+ input: z
159
+ .object({
160
+ name: jobName.describe('Registered job name (see jobs.schedules)'),
161
+ payload: z.unknown().default({}).describe("The job's payload object (default {})"),
162
+ startAfter: z.iso.datetime({ offset: true }).optional().describe('Run no earlier than this ISO 8601 date-time'),
163
+ })
164
+ .strict(),
165
+ authorize: authorizeEnqueue,
166
+ run: async (input, ctx) => {
167
+ const id = await enqueueJob(input.name, input.payload, {
168
+ requestedBy: requesterOf(ctx.principal),
169
+ startAfter: input.startAfter,
170
+ })
171
+ // `null`: a singleton job of the same slot is already queued.
172
+ return { id, name: input.name, skipped: id === null }
173
+ },
174
+ }),
175
+
176
+ defineAppAction({
177
+ id: 'jobs.retry',
178
+ kind: 'effect',
179
+ destructive: false,
180
+ audience: ['user'],
181
+ description:
182
+ 'Run a failed or cancelled job again (same payload; a job that is not idempotent does its work again). Returns the job.',
183
+ input: z.object({ id: z.uuid().describe('Job id') }).strict(),
184
+ authorize: (_input, ctx) => {
185
+ requireScope(ctx, 'jobs:write')
186
+ },
187
+ run: async input => {
188
+ const job = await loadJob(input.id)
189
+ const boss = await jobsReady()
190
+ if (job.state === 'failed') await boss.retry(job.name, job.id)
191
+ else if (job.state === 'cancelled') await boss.resume(job.name, job.id)
192
+ else
193
+ throw createError({
194
+ statusCode: 409,
195
+ statusMessage: `Only failed or cancelled jobs can be retried (job is ${job.state})`,
196
+ })
197
+ return loadJob(job.id)
198
+ },
199
+ }),
200
+
201
+ defineAppAction({
202
+ id: 'jobs.cancel',
203
+ kind: 'effect',
204
+ destructive: true,
205
+ audience: ['user'],
206
+ description:
207
+ 'Cancel a queued, retrying or running job. A running handler is signalled to stop; work it already did stays. Returns the job.',
208
+ input: z.object({ id: z.uuid().describe('Job id') }).strict(),
209
+ authorize: (_input, ctx) => {
210
+ requireScope(ctx, 'jobs:write')
211
+ },
212
+ run: async input => {
213
+ const job = await loadJob(input.id)
214
+ if (!['created', 'retry', 'active'].includes(job.state)) {
215
+ throw createError({
216
+ statusCode: 409,
217
+ statusMessage: `Only queued or running jobs can be cancelled (job is ${job.state})`,
218
+ })
219
+ }
220
+ const boss = await jobsReady()
221
+ await boss.cancel(job.name, job.id)
222
+ return loadJob(job.id)
223
+ },
224
+ }),
225
+
226
+ defineAppAction({
227
+ id: 'jobs.schedules',
228
+ kind: 'query',
229
+ audience: ['user', 'llm'],
230
+ description:
231
+ 'Cron schedules (job name, cron expression in UTC, next run, last job id) and every registered job with its description and payload JSON schema. Returns { items, jobs }.',
232
+ input: z.object({}).strict(),
233
+ authorize: (_input, ctx) => {
234
+ requireScope(ctx, 'jobs:read')
235
+ },
236
+ run: async () => {
237
+ const boss = await jobsReady()
238
+ const registered = allJobs()
239
+ const schedules = await boss.getSchedules()
240
+ return {
241
+ items: schedules
242
+ .filter(schedule => registered.some(job => job.name === schedule.name))
243
+ .map(schedule => ({
244
+ name: schedule.name,
245
+ key: schedule.key,
246
+ cron: schedule.cron,
247
+ timezone: schedule.timezone,
248
+ description: registered.find(job => job.name === schedule.name)?.description ?? '',
249
+ nextRunAt:
250
+ boss.previewSchedule(schedule.cron, { tz: schedule.timezone, count: 1 })[0]?.toISOString() ?? null,
251
+ lastJobId: schedule.lastJobId,
252
+ updatedAt: new Date(schedule.updatedOn).toISOString(),
253
+ })),
254
+ jobs: registered.map(job => ({
255
+ name: job.name,
256
+ description: job.description,
257
+ schedule: job.schedule ?? null,
258
+ audience: [...job.audience],
259
+ payloadSchema: z.toJSONSchema(job.payload),
260
+ })),
261
+ }
262
+ },
263
+ }),
264
+ ] as const
265
+
266
+ export type JobActions = typeof jobActions
@@ -0,0 +1,229 @@
1
+ import { sql } from 'drizzle-orm'
2
+ import { createError } from 'h3'
3
+ import type { Db as BossDb, ConstructorOptions, DrizzleTransactionLike, Job, SendOptions } from 'pg-boss'
4
+ import { fromDrizzle, fromPglite, PgBoss } from 'pg-boss'
5
+ import * as z from 'zod'
6
+ import type { DbTarget, Tx } from '~~/server/utils/db'
7
+ import { systemPrincipal } from '~~/server/utils/principal'
8
+ import type { JobData, JobDefinition, JobRequester } from './define'
9
+ import { allJobs, findJob } from './define'
10
+ import type { AppRole } from './role'
11
+ import { runsHandlers } from './role'
12
+
13
+ /** pg-boss keeps its tables in this schema, next to Drizzle's `public`. */
14
+ export const BOSS_SCHEMA = 'pgboss'
15
+
16
+ export interface StartJobsOptions {
17
+ role: AppRole
18
+ /** The app's engine (`useDbTarget()`), or a promise of it (`dbReady().then(h => h.target)`). */
19
+ target: DbTarget | Promise<DbTarget>
20
+ /** Worker poll interval in seconds (pg-boss minimum 0.5). Default `JOBS_POLL_SECONDS` or 2. */
21
+ pollingIntervalSeconds?: number
22
+ }
23
+
24
+ interface JobsState {
25
+ ready?: Promise<PgBoss>
26
+ boss?: PgBoss
27
+ role?: AppRole
28
+ }
29
+ declare global {
30
+ var __skaileAppBoss: JobsState | undefined
31
+ }
32
+ const state = (globalThis.__skaileAppBoss ??= {})
33
+
34
+ /**
35
+ * pg-boss on the app's own database: in-process PGlite through `fromPglite`
36
+ * (one connection, shared with Drizzle), or its own `pg` pool on Postgres.
37
+ */
38
+ export function createBoss(target: DbTarget, role: AppRole): PgBoss {
39
+ const handlers = runsHandlers(role)
40
+ const common: ConstructorOptions = {
41
+ schema: BOSS_SCHEMA,
42
+ // Cron and maintenance belong to the processes that run handlers; `web` only sends.
43
+ schedule: handlers,
44
+ supervise: handlers,
45
+ instanceName: `app-${role}`,
46
+ }
47
+ const boss =
48
+ target.kind === 'pglite'
49
+ ? new PgBoss({ ...common, db: fromPglite(target.client), backend: 'pglite' })
50
+ : new PgBoss({ ...common, connectionString: target.url, max: Number(process.env.JOBS_POOL_MAX) || 5 })
51
+ boss.on('error', error => console.error('[jobs] pg-boss error:', error))
52
+ return boss
53
+ }
54
+
55
+ /**
56
+ * Starts pg-boss once per process: installs or migrates its schema, creates a
57
+ * queue per registered job, and, in roles `all` and `worker`, works every
58
+ * queue and (re)registers the cron schedules. Idempotent; a failed start is
59
+ * retried on the next call.
60
+ */
61
+ export function startJobs(options: StartJobsOptions): Promise<PgBoss> {
62
+ state.ready ??= bootJobs(options).catch((error: unknown) => {
63
+ state.ready = undefined
64
+ throw error
65
+ })
66
+ return state.ready
67
+ }
68
+
69
+ async function bootJobs({ role, target, pollingIntervalSeconds }: StartJobsOptions): Promise<PgBoss> {
70
+ const boss = createBoss(await target, role)
71
+ await boss.start()
72
+ try {
73
+ for (const job of allJobs()) await ensureQueue(boss, job)
74
+ if (runsHandlers(role)) {
75
+ const interval = pollingIntervalSeconds ?? (Number(process.env.JOBS_POLL_SECONDS) || 2)
76
+ for (const job of allJobs()) {
77
+ await boss.work<JobData>(job.name, { batchSize: 1, pollingIntervalSeconds: interval }, ([item]) =>
78
+ runJob(job, item!),
79
+ )
80
+ }
81
+ await syncSchedules(boss)
82
+ }
83
+ } catch (error) {
84
+ await boss.stop({ graceful: false, close: true })
85
+ throw error
86
+ }
87
+ state.boss = boss
88
+ state.role = role
89
+ return boss
90
+ }
91
+
92
+ async function ensureQueue(boss: PgBoss, job: JobDefinition): Promise<void> {
93
+ const options = {
94
+ ...(job.retry?.limit !== undefined && { retryLimit: job.retry.limit }),
95
+ ...(job.retry?.delay !== undefined && { retryDelay: job.retry.delay }),
96
+ ...(job.retry?.backoff !== undefined && { retryBackoff: job.retry.backoff }),
97
+ ...(job.expireInSeconds !== undefined && { expireInSeconds: job.expireInSeconds }),
98
+ }
99
+ // createQueue leaves an existing queue alone; updateQueue applies changed retry settings on deploy.
100
+ await boss.createQueue(job.name, options)
101
+ if (Object.keys(options).length > 0) await boss.updateQueue(job.name, options)
102
+ }
103
+
104
+ /** Every registered job with a `schedule` gets it; registered jobs that lost theirs are unscheduled. */
105
+ async function syncSchedules(boss: PgBoss): Promise<void> {
106
+ const existing = await boss.getSchedules()
107
+ for (const job of allJobs()) {
108
+ if (job.schedule) {
109
+ const data: JobData = { payload: job.payload.parse({}), requestedBy: null }
110
+ await boss.schedule(job.name, job.schedule, data, { ...singletonOptions(job), tz: 'UTC' })
111
+ } else if (existing.some(schedule => schedule.name === job.name)) {
112
+ await boss.unschedule(job.name)
113
+ }
114
+ }
115
+ }
116
+
117
+ /** Parses the stored payload again (rows can be written by anyone with database access) and runs the handler as the system. */
118
+ async function runJob(job: JobDefinition, item: Job<JobData>): Promise<object | undefined> {
119
+ const parsed = job.payload.safeParse(item.data?.payload)
120
+ if (!parsed.success) throw new Error(`Invalid payload for ${job.name}: ${z.prettifyError(parsed.error)}`)
121
+ const result = await job.handler(parsed.data, {
122
+ principal: systemPrincipal(`worker:${job.name}`),
123
+ job: { id: item.id, name: item.name, retryCount: item.retryCount },
124
+ requestedBy: item.data?.requestedBy ?? null,
125
+ signal: item.signal,
126
+ })
127
+ if (result === undefined || result === null) return undefined
128
+ return typeof result === 'object' && !Array.isArray(result) ? result : { value: result }
129
+ }
130
+
131
+ /** Stops workers (waiting up to 10 s for running handlers) and closes pg-boss's pool. Safe to call when not started. */
132
+ export async function stopJobs(): Promise<void> {
133
+ const ready = state.ready
134
+ state.ready = undefined
135
+ state.boss = undefined
136
+ state.role = undefined
137
+ const boss = await ready?.catch(() => undefined)
138
+ await boss?.stop({ graceful: true, timeout: 10_000, close: true })
139
+ }
140
+
141
+ /** The started boss; 503 while it is still starting or when the process runs without jobs. */
142
+ export async function jobsReady(): Promise<PgBoss> {
143
+ if (!state.ready) throw createError({ statusCode: 503, statusMessage: 'Jobs are not running in this process' })
144
+ try {
145
+ return await state.ready
146
+ } catch (error) {
147
+ throw createError({
148
+ statusCode: 503,
149
+ statusMessage: `Jobs unavailable: ${error instanceof Error ? error.message : String(error)}`,
150
+ })
151
+ }
152
+ }
153
+
154
+ /** The role the running boss was started with, if any. */
155
+ export function jobsRole(): AppRole | undefined {
156
+ return state.role
157
+ }
158
+
159
+ function singletonOptions(job: JobDefinition): SendOptions {
160
+ return job.singleton ? { singletonKey: job.singleton.key ?? job.name, singletonSeconds: job.singleton.seconds } : {}
161
+ }
162
+
163
+ export function requireJob(name: string): JobDefinition {
164
+ const job = findJob(name)
165
+ if (!job) {
166
+ const known =
167
+ allJobs()
168
+ .map(j => j.name)
169
+ .join(', ') || 'none'
170
+ throw createError({ statusCode: 400, statusMessage: `Unknown job "${name}". Registered jobs: ${known}` })
171
+ }
172
+ return job
173
+ }
174
+
175
+ /** Validates `payload` with the job's schema: 400 with `data.issues` like an action input. */
176
+ export function parseJobPayload<P>(job: JobDefinition, payload: unknown): P {
177
+ const parsed = job.payload.safeParse(payload)
178
+ if (!parsed.success) {
179
+ throw createError({
180
+ statusCode: 400,
181
+ statusMessage: `Invalid payload for ${job.name}: ${z.prettifyError(parsed.error)}`,
182
+ data: { issues: parsed.error.issues },
183
+ })
184
+ }
185
+ return parsed.data as P
186
+ }
187
+
188
+ export interface EnqueueOptions {
189
+ requestedBy?: JobRequester | null
190
+ /** Run no earlier than this (Date, ISO string or seconds from now). */
191
+ startAfter?: Date | string | number
192
+ /** @internal a pg-boss database adapter; use {@link enqueueInTx} instead. */
193
+ db?: BossDb
194
+ }
195
+
196
+ /**
197
+ * Enqueues a registered job after validating its payload. Returns the job id,
198
+ * or `null` when a `singleton` job of the same slot already exists.
199
+ * NEVER call it inside `withTx`/`db.transaction` on PGlite: use {@link enqueueInTx}.
200
+ */
201
+ export async function enqueueJob(name: string, payload: unknown, options: EnqueueOptions = {}): Promise<string | null> {
202
+ const job = requireJob(name)
203
+ const data: JobData = { payload: parseJobPayload(job, payload), requestedBy: options.requestedBy ?? null }
204
+ const boss = await jobsReady()
205
+ return boss.send(name, data, {
206
+ ...singletonOptions(job),
207
+ ...(options.startAfter !== undefined && { startAfter: options.startAfter }),
208
+ ...(options.db && { db: options.db }),
209
+ })
210
+ }
211
+
212
+ /**
213
+ * Enqueues inside a Drizzle transaction: the job exists only if `tx` commits.
214
+ * The PGlite rule: inside a transaction every query must go through `tx`, and
215
+ * that includes pg-boss. A plain `boss.send()` (or `useDb()`) inside
216
+ * `withTx(...)` waits for the very lock the transaction holds and hangs the
217
+ * process without an error. On Postgres the same mistake does not hang, but
218
+ * the job is silently not transactional. So: inside `withTx`, always this.
219
+ */
220
+ export function enqueueInTx(
221
+ tx: Tx,
222
+ name: string,
223
+ payload: unknown,
224
+ options: Omit<EnqueueOptions, 'db'> = {},
225
+ ): Promise<string | null> {
226
+ // Drizzle types a raw `execute` result as `unknown`; the adapter reads rows from either engine's shape itself.
227
+ const adapter = tx as unknown as DrizzleTransactionLike
228
+ return enqueueJob(name, payload, { ...options, db: fromDrizzle(adapter, sql) })
229
+ }
@@ -0,0 +1,103 @@
1
+ import type { ServerActionAudience } from '@skaile/forge-app-actions/server'
2
+ import type * as z from 'zod'
3
+ import type { AppActionContext } from '~~/server/utils/actions/define'
4
+ import type { Principal } from '~~/server/utils/principal'
5
+
6
+ /** Who asked for a job: the person (or token owner) behind `jobs.enqueue`, `null` for cron and system code. */
7
+ export interface JobRequester {
8
+ id: string
9
+ name: string
10
+ }
11
+
12
+ /** What a job row stores in pg-boss's `data`: the validated payload and who enqueued it. */
13
+ export interface JobData<P = unknown> {
14
+ payload: P
15
+ requestedBy: JobRequester | null
16
+ }
17
+
18
+ export interface JobContext {
19
+ /** `systemPrincipal('worker:<job>')`: owner rights, every scope; pass it to `runAction(...)`. */
20
+ principal: Principal
21
+ job: { id: string; name: string; retryCount: number }
22
+ requestedBy: JobRequester | null
23
+ /** Aborted when pg-boss gives up on the job (expiry, shutdown). */
24
+ signal: AbortSignal
25
+ }
26
+
27
+ export interface JobRetry {
28
+ /** Retries after the first attempt (pg-boss default 2). */
29
+ limit?: number
30
+ /** Seconds between attempts. */
31
+ delay?: number
32
+ /** Exponential backoff from `delay`. */
33
+ backoff?: boolean
34
+ }
35
+
36
+ export interface JobSingleton {
37
+ /** Throttle key; default the job name. */
38
+ key?: string
39
+ /** At most one job per key in each slot of this many seconds (pg-boss `singletonSeconds`). */
40
+ seconds: number
41
+ }
42
+
43
+ export interface DefineJobArgs<Name extends string, P extends z.ZodType, R> {
44
+ /** Queue name, `<area>.<verb>` like actions. */
45
+ name: Name
46
+ /** What it does and what its output holds. Written for people and LLMs (shown by `jobs.schedules`). */
47
+ description: string
48
+ /** Strict Zod payload; `jobs.enqueue` and the handler both parse it. */
49
+ payload: P
50
+ // Method syntax on purpose: a concrete job stays assignable to `JobDefinition` (the registry's type).
51
+ handler(payload: z.output<P>, ctx: JobContext): Promise<R>
52
+ retry?: JobRetry
53
+ /** 5-field cron expression (UTC); registered with `boss.schedule` by the processes that run handlers. */
54
+ schedule?: string
55
+ singleton?: JobSingleton
56
+ /**
57
+ * Who may enqueue it through `jobs.enqueue`: `llm` lets agent principals
58
+ * (agent tokens) enqueue it too. Default `['user']`.
59
+ */
60
+ audience?: readonly ServerActionAudience[]
61
+ /** Extra check on top of `jobs:write` before `jobs.enqueue` sends it (e.g. `requireScope(ctx, 'tasks:write')`). */
62
+ authorize?(payload: z.output<P>, ctx: AppActionContext): void | Promise<void>
63
+ /** Seconds a run may take before pg-boss expires it (default 15 min). */
64
+ expireInSeconds?: number
65
+ }
66
+
67
+ export interface JobDefinition<Name extends string = string, P extends z.ZodType = z.ZodType, R = unknown>
68
+ extends DefineJobArgs<Name, P, R> {
69
+ audience: readonly ServerActionAudience[]
70
+ }
71
+
72
+ /** The one way to define a background job. Register it with {@link registerJobs} from a Nitro plugin. */
73
+ export function defineJob<const Name extends string, P extends z.ZodType, R>(
74
+ args: DefineJobArgs<Name, P, R>,
75
+ ): JobDefinition<Name, P, R> {
76
+ return { ...args, audience: args.audience ?? ['user'] }
77
+ }
78
+
79
+ declare global {
80
+ var __skaileAppJobs: Map<string, JobDefinition> | undefined
81
+ }
82
+ const jobs = (globalThis.__skaileAppJobs ??= new Map())
83
+
84
+ /**
85
+ * Adds jobs to the registry the boss works from. Call it before the boss
86
+ * starts (from a Nitro plugin); registering the same definition twice is a
87
+ * no-op, a different one under a taken name throws.
88
+ */
89
+ export function registerJobs(list: readonly JobDefinition[]): void {
90
+ for (const job of list) {
91
+ const existing = jobs.get(job.name)
92
+ if (existing && existing !== job) throw new Error(`Job already registered: ${job.name}`)
93
+ jobs.set(job.name, job)
94
+ }
95
+ }
96
+
97
+ export function allJobs(): JobDefinition[] {
98
+ return [...jobs.values()]
99
+ }
100
+
101
+ export function findJob(name: string): JobDefinition | undefined {
102
+ return jobs.get(name)
103
+ }
@@ -0,0 +1,33 @@
1
+ export const APP_ROLES = ['all', 'web', 'worker'] as const
2
+ export type AppRole = (typeof APP_ROLES)[number]
3
+
4
+ /**
5
+ * What this process does with jobs (`APP_ROLE`, default `all`):
6
+ * - `all`: serves the app, enqueues and runs handlers and cron (local, single container);
7
+ * - `web`: serves the app and only enqueues;
8
+ * - `worker`: runs handlers and cron; HTTP answers `/api/health` only.
9
+ */
10
+ export function appRole(env: NodeJS.ProcessEnv = process.env): AppRole {
11
+ const value = (env.APP_ROLE || 'all').trim().toLowerCase()
12
+ if (!(APP_ROLES as readonly string[]).includes(value)) {
13
+ throw new Error(`APP_ROLE must be one of ${APP_ROLES.join(', ')} (got "${env.APP_ROLE}")`)
14
+ }
15
+ return value as AppRole
16
+ }
17
+
18
+ export const runsHandlers = (role: AppRole) => role !== 'web'
19
+ export const servesApp = (role: AppRole) => role !== 'worker'
20
+
21
+ /**
22
+ * PGlite lives inside one process, so a separate worker process cannot reach
23
+ * it (and must not open the same data directory: writes get lost). Throws the
24
+ * operator-facing explanation for `APP_ROLE=worker` (or `web`, whose jobs no
25
+ * process would ever run) without `DATABASE_URL`.
26
+ */
27
+ export function assertRoleFitsDatabase(role: AppRole, env: NodeJS.ProcessEnv = process.env): void {
28
+ if (role === 'all' || env.DATABASE_URL) return
29
+ throw new Error(
30
+ `APP_ROLE=${role} needs Postgres (DATABASE_URL). The local PGlite database runs inside one process, ` +
31
+ 'so web and worker cannot be split: unset APP_ROLE (= all) to run the app and its jobs in this one process.',
32
+ )
33
+ }