@core / jobs

1.1.0 ▾

1.1.0

verificadoMIT

GitHub

Tareas en segundo plano sobre Postgres: cola durable, reintentos con backoff, cron y endpoint para serverless

Código9 archivosContexto~696 tokensescaneo superado

~696 tokens→ src/lib/jobs/AGENTS.md→ .cursor/rules/genpm-core-jobs.mdc

Esto es exactamente lo que lee tu IA cuando trabaja en src/lib/jobs. No se añade nada más a su contexto.

@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`.

El árbol exacto que se inyectará, tras aplicar .genpmignore. Anclado a

src/lib/jobs/registry.tssolo lectura · 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();
}