@skaile/forge-layer-jobs 0.0.0 → 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/CHANGELOG.md +7 -0
- package/LICENSE +21 -0
- package/README.md +150 -1
- package/app/app.config.ts +5 -0
- package/app/components/JobControls.vue +51 -0
- package/app/components/JobDetailSlideover.vue +88 -0
- package/app/components/JobsActions.vue +10 -0
- package/app/pages/jobs.vue +274 -0
- package/app/utils/jobs.ts +22 -0
- package/nuxt.config.ts +9 -0
- package/package.json +44 -5
- package/server/jobs/actions.ts +266 -0
- package/server/jobs/boss.ts +229 -0
- package/server/jobs/define.ts +103 -0
- package/server/jobs/role.ts +33 -0
- package/server/middleware/worker-role.ts +19 -0
- package/server/plugins/jobs.ts +48 -0
- package/shared/jobs.ts +8 -0
package/package.json
CHANGED
|
@@ -1,9 +1,48 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skaile/forge-layer-jobs",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
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
|
+
},
|
|
5
31
|
"license": "MIT",
|
|
6
|
-
"
|
|
7
|
-
|
|
8
|
-
|
|
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
|
+
}
|
|
9
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
|
+
}
|