@core / jobs

1.1.0 ▾

1.1.0

認証済みMIT

GitHub

Postgres 上のバックグラウンドジョブ：永続キュー、バックオフ付き再試行、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;