@core / jobs

1.1.0 ▾

1.1.0

인증됨MIT

GitHub

Postgres 기반 백그라운드 작업: 영속 큐, 백오프 재시도, cron 일정, 서버리스 cron 엔드포인트

코드파일 9개컨텍스트약 696토큰검사 통과

약 696토큰→ 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/schema.ts읽기 전용 · eef017d

// Tablas de @core/jobs. Las recoge drizzle-kit vía src/lib/db/drizzle.config.ts.
import { sql } from 'drizzle-orm';
import { index, integer, jsonb, pgTable, text, timestamp, uniqueIndex } from 'drizzle-orm/pg-core';
import { primaryId, timestamps } from '../db/index.ts';

const ts = (name: string) => timestamp(name, { withTimezone: true, mode: 'date' });

export const jobs = pgTable(
  'jobs',
  {
    id: primaryId('job'),
    type: text('type').notNull(),
    payload: jsonb('payload').$type<unknown>().notNull(),
    status: text('status', { enum: ['queued', 'running', 'done', 'failed'] })
      .notNull()
      .default('queued'),
    runAt: ts('run_at').notNull().defaultNow(),
    attempts: integer('attempts').notNull().default(0),
    maxAttempts: integer('max_attempts').notNull().default(5),
    /** Mientras `running`, nadie más la toma hasta esta hora (si el worker muere, se reintenta al vencer). */
    lockedUntil: ts('locked_until'),
    lastError: text('last_error'),
    /** Evita duplicados mientras haya una pendiente o en curso con la misma clave. */
    dedupeKey: text('dedupe_key'),
    finishedAt: ts('finished_at'),
    ...timestamps,
  },
  (t) => [
    index('jobs_due_idx').on(t.status, t.runAt),
    uniqueIndex('jobs_dedupe_idx')
      .on(t.dedupeKey)
      .where(sql`${t.dedupeKey} is not null and ${t.status} in ('queued', 'running')`),
  ],
);

export const jobSchedules = pgTable('job_schedules', {
  /** Un horario por tipo de tarea. */
  type: text('type').primaryKey(),
  cron: text('cron').notNull(),
  timezone: text('timezone').notNull().default('UTC'),
  payload: jsonb('payload').$type<unknown>().notNull(),
  nextRunAt: ts('next_run_at').notNull(),
  lastRunAt: ts('last_run_at'),
  ...timestamps,
});

export type Job = typeof jobs.$inferSelect;
export type JobSchedule = typeof jobSchedules.$inferSelect;