@core / jobs

1.1.0 ▾

1.1.0

已验证MIT

GitHub

基于 Postgres 的后台任务：持久队列、退避重试、cron 计划和无服务器 cron 端点

代码9 个文件上下文约 696 个 token扫描通过

约 696 个 token→ src/lib/jobs/AGENTS.md→ .cursor/rules/genpm-core-jobs.mdc

这正是你的 AI 在 src/lib/jobs 中工作时读取的内容。不会向其上下文添加其他任何内容。

@core/jobs — rules for AI agents

Purpose

Durable background jobs on the same Postgres: queue (FOR UPDATE SKIP LOCKED), retries with exponential backoff, timeouts, de-duplication keys, cron schedules (5 fields, with timezone) and an HTTP endpoint so serverless hosts can run due jobs from their cron. No Redis, no extra service. Table owner of jobs and job_schedules.

Map

index.ts — public API: defineJob, enqueue, schedule, unschedule, runDue, runWorker, retryJob, pruneJobs.
queue.ts — claim/run logic. registry.ts — in-memory job types. schema.ts — tables.
adapters/hono.ts — cronRoutes(). adapters/next.ts — cronRoute (GET/POST).

Integration

Env: CRON_SECRET (≥ 32 random chars). Generate and apply migrations (see src/lib/db/AGENTS.md).

Define jobs in one module imported by every process (web and worker), e.g. src/jobs.ts:

import { z } from 'zod';
import { defineJob } from './lib/jobs/index.ts';
export const sendWelcome = defineJob('email.welcome', z.object({ userId: z.string() }), async ({ userId }, { signal }) => { /* … */ });

Enqueue: await sendWelcome.enqueue({ userId }, { dedupeKey: welcome:${userId} }).

Run them, one of:
- Serverless (Vercel, Netlify, Workers): mount the cron endpoint (app.route('/api/cron', cronRoutes()) or app/api/cron/route.ts with export { cronRoute as GET, cronRoute as POST }) and call it every minute with Authorization: Bearer $CRON_SECRET (Vercel Cron sends it automatically when CRON_SECRET is set).
- Long-running Node: a worker process calling runWorker({ concurrency: 4 }).
Recurring work: await schedule('report.daily', '0 8 * * *', { timezone: 'Europe/Madrid' }) once at startup.
Verify: enqueue a job, call the cron endpoint, the jobs row becomes done.

Conventions

Handlers must be idempotent: a job can run more than once (retries, expired locks).
Expired locks count as attempts: a job whose worker dies on its last attempt is marked failed with lastError = 'lock expired' (failExhaustedJobs, run by runDue) instead of being reclaimed forever.
Each schedule tick is claimed with one conditional UPDATE (claimScheduleTick), so overlapping cron calls enqueue it once.
Payloads carry IDs and small values; load fresh data inside the handler. Never put secrets in payloads.
Pass ctx.signal to fetch() and long operations so timeouts stop them.
Job types are dotted lowercase names owned by a module (newsletter.send-batch).

Don't

Don't call slow external APIs (email, suppliers, payments) inside a request when a job fits.
Don't edit jobs rows by hand; use retryJob for failed ones.
Don't expose the cron endpoint without CRON_SECRET.

# @core/jobs — rules for AI agents

## Purpose
Durable background jobs on the same Postgres: queue (`FOR UPDATE SKIP LOCKED`), retries with exponential backoff,
timeouts, de-duplication keys, cron schedules (5 fields, with timezone) and an HTTP endpoint so serverless hosts can
run due jobs from their cron. No Redis, no extra service. Table owner of `jobs` and `job_schedules`.

## Map
- `index.ts` — public API: `defineJob`, `enqueue`, `schedule`, `unschedule`, `runDue`, `runWorker`, `retryJob`, `pruneJobs`.
- `queue.ts` — claim/run logic. `registry.ts` — in-memory job types. `schema.ts` — tables.
- `adapters/hono.ts` — `cronRoutes()`. `adapters/next.ts` — `cronRoute` (GET/POST).

## Integration
1. Env: `CRON_SECRET` (≥ 32 random chars). Generate and apply migrations (see `src/lib/db/AGENTS.md`).
2. Define jobs in one module imported by every process (web and worker), e.g. `src/jobs.ts`:
   ```ts
   import { z } from 'zod';
   import { defineJob } from './lib/jobs/index.ts';
   export const sendWelcome = defineJob('email.welcome', z.object({ userId: z.string() }), async ({ userId }, { signal }) => { /* … */ });
   ```
   Enqueue: `await sendWelcome.enqueue({ userId }, { dedupeKey: `welcome:${userId}` })`.
3. Run them, one of:
   - Serverless (Vercel, Netlify, Workers): mount the cron endpoint (`app.route('/api/cron', cronRoutes())` or
     `app/api/cron/route.ts` with `export { cronRoute as GET, cronRoute as POST }`) and call it every minute with
     `Authorization: Bearer $CRON_SECRET` (Vercel Cron sends it automatically when `CRON_SECRET` is set).
   - Long-running Node: a worker process calling `runWorker({ concurrency: 4 })`.
4. Recurring work: `await schedule('report.daily', '0 8 * * *', { timezone: 'Europe/Madrid' })` once at startup.
5. Verify: enqueue a job, call the cron endpoint, the `jobs` row becomes `done`.

## Conventions
- Handlers must be idempotent: a job can run more than once (retries, expired locks).
- Expired locks count as attempts: a job whose worker dies on its last attempt is marked `failed` with
  `lastError = 'lock expired'` (`failExhaustedJobs`, run by `runDue`) instead of being reclaimed forever.
- Each schedule tick is claimed with one conditional `UPDATE` (`claimScheduleTick`), so overlapping cron calls enqueue it once.
- Payloads carry IDs and small values; load fresh data inside the handler. Never put secrets in payloads.
- Pass `ctx.signal` to `fetch()` and long operations so timeouts stop them.
- Job types are dotted lowercase names owned by a module (`newsletter.send-batch`).

## Don't
- Don't call slow external APIs (email, suppliers, payments) inside a request when a job fits.
- Don't edit `jobs` rows by hand; use `retryJob` for failed ones.
- Don't expose the cron endpoint without `CRON_SECRET`.

应用 .genpmignore 后将被注入的确切目录树。固定于

src/lib/jobs/registry.ts只读 · eef017d

// Registro en memoria de tipos de tarea. Cada proceso (web y worker) importa los mismos `defineJob`.
import type { ZodType } from 'zod';

export type JobContext = {
  jobId: string;
  /** Intento actual (1 = primero). */
  attempt: number;
  /** Se aborta al vencer `timeoutMs`; pásala a fetch() y a operaciones largas. */
  signal: AbortSignal;
};

export type JobDefinition<P> = {
  type: string;
  schema: ZodType<P>;
  handler: (payload: P, ctx: JobContext) => Promise<void>;
  maxAttempts: number;
  timeoutMs: number;
};

const registry = new Map<string, JobDefinition<unknown>>();

export function registerJob<P>(def: JobDefinition<P>): void {
  if (!/^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/.test(def.type)) throw new Error(`invalid job type: ${def.type}`);
  registry.set(def.type, def as JobDefinition<unknown>);
}

export function getJob(type: string): JobDefinition<unknown> | undefined {
  return registry.get(type);
}

/** Solo tests. */
export function clearJobs(): void {
  registry.clear();
}