@ultimat3/admin 22.14.0 → 23.0.0

package/src/jobs/job-entities.ts

@@ -0,0 +1,118 @@
+// The four things an operator browses — job rows, queues, tasks, workers — declared as the entity
+// SURFACE the admin derives every screen from (`registry.ts`'s `AdminEntity`), so their lists,
+// filters, detail pages, batch bar and MCP tools are the ones an app's own tables get. Hand-built
+// rather than `entity()`: none is an app table, and `entity()` would put them in the app's schema.
+
+import { JOB_STATES } from '@ultimat3/jobs';
+import type { AdminColumn, AdminColumnMeta, AdminEntity } from '../registry';
+
+/** The resource names. `x_` is the framework's table prefix: no app entity is named so. */
+export const JOB_ENTITY = {
+  jobs: 'x_jobs',
+  queues: 'x_job_queues',
+  tasks: 'x_job_tasks',
+  workers: 'x_job_workers',
+} as const;
+
+type Shape = Partial<Omit<AdminColumnMeta, 'kind'>>;
+
+const column = (kind: string, shape: Shape = {}): AdminColumn => ({
+  $meta: {
+    kind,
+    notNull: shape.notNull ?? true,
+    primaryKey: shape.primaryKey ?? false,
+    unique: shape.unique ?? false,
+    index: shape.index ?? false,
+    ...(shape.length === undefined ? {} : { length: shape.length }),
+    ...(shape.values === undefined ? {} : { values: shape.values }),
+  },
+});
+
+/** A bounded line of text — one line in a form, a `contains` the store can answer or refuse. */
+const line = (shape: Shape = {}): AdminColumn => column('text', { length: 200, ...shape });
+const key = (): AdminColumn => line({ primaryKey: true, index: true });
+const optional = (kind: string): AdminColumn => column(kind, { notNull: false });
+
+/**
+ * Read-only by construction: no screen offers a create or an update, and a schema that refuses
+ * every input is what any path that reached one would meet.
+ */
+const READ_ONLY_SCHEMA = {
+  '~standard': {
+    version: 1,
+    vendor: 'ultimate-admin',
+    validate: () => ({
+      issues: [{ message: 'an operator surface is read-only; use its actions' }],
+    }),
+  },
+} as const;
+
+function surface(name: string, columns: Readonly<Record<string, AdminColumn>>): AdminEntity {
+  return {
+    $name: name,
+    $primaryKey: [Object.keys(columns)[0] ?? 'id'],
+    $columns: columns,
+    $schema: READ_ONLY_SCHEMA,
+    $tenantColumn: null,
+    $describe: () => ({
+      columns: Object.keys(columns).map((property) => ({ property, references: null })),
+    }),
+  };
+}
+
+export const jobEntity: AdminEntity = surface(JOB_ENTITY.jobs, {
+  id: key(),
+  name: line({ index: true }),
+  queue: line({ index: true }),
+  state: line({ index: true, values: JOB_STATES }),
+  attempt: column('integer'),
+  maxAttempts: column('integer'),
+  runAt: column('timestamptz'),
+  createdAt: column('timestamptz', { index: true }),
+  updatedAt: column('timestamptz'),
+  tenantId: column('text', { notNull: false, length: 200, index: true }),
+  lastError: optional('text'),
+  lastErrorStack: optional('text'),
+  progress: optional('jsonb'),
+  // What the queue holds, ALREADY redacted by `@ultimat3/jobs` (`inspectJob`): every key the app
+  // declared secret is replaced before the admin sees the value.
+  input: optional('jsonb'),
+  steps: optional('jsonb'),
+  traceparent: optional('text'),
+  enqueuedBy: optional('text'),
+  claimedBy: optional('text'),
+});
+
+export const queueEntity: AdminEntity = surface(JOB_ENTITY.queues, {
+  name: key(),
+  ready: column('integer'),
+  delayed: column('integer'),
+  running: column('integer'),
+  suspended: column('integer'),
+  failed: column('integer'),
+  dead: column('integer'),
+  oldestReadyMs: column('integer'),
+  paused: column('boolean', { index: true }),
+  pausedAt: optional('timestamptz'),
+});
+
+export const taskEntity: AdminEntity = surface(JOB_ENTITY.tasks, {
+  name: key(),
+  cron: line(),
+  tz: line(),
+  catchUp: line(),
+  enqueues: line(),
+  lastFireAt: optional('timestamptz'),
+  nextFireAt: optional('timestamptz'),
+  paused: column('boolean', { index: true }),
+});
+
+export const workerEntity: AdminEntity = surface(JOB_ENTITY.workers, {
+  id: key(),
+  host: line(),
+  queues: line(),
+  concurrency: column('integer'),
+  inFlight: column('integer'),
+  startedAt: column('timestamptz'),
+  heartbeatAt: column('timestamptz'),
+});

package/src/jobs/job-labels.ts

@@ -0,0 +1,108 @@
+// The catalog keys the jobs screens are labelled by, spelled out. They are the keys the admin
+// would derive (`admin.<entity>.field.<name>`), named here because a key the FRAMEWORK catalog
+// holds must be named by framework source (`scripts/i18n-catalog.ts`): derived, nothing could
+// tell a live key from a stale one.
+
+import type { AdminFieldOverride } from '../resource-fields';
+
+export const RUN_LABELS = {
+  title: 'admin.x_jobs.title',
+  fields: {
+    id: 'admin.x_jobs.field.id',
+    name: 'admin.x_jobs.field.name',
+    queue: 'admin.x_jobs.field.queue',
+    state: 'admin.x_jobs.field.state',
+    attempt: 'admin.x_jobs.field.attempt',
+    maxAttempts: 'admin.x_jobs.field.maxAttempts',
+    runAt: 'admin.x_jobs.field.runAt',
+    createdAt: 'admin.x_jobs.field.createdAt',
+    updatedAt: 'admin.x_jobs.field.updatedAt',
+    tenantId: 'admin.x_jobs.field.tenantId',
+    lastError: 'admin.x_jobs.field.lastError',
+    lastErrorStack: 'admin.x_jobs.field.lastErrorStack',
+    progress: 'admin.x_jobs.field.progress',
+    input: 'admin.x_jobs.field.input',
+    steps: 'admin.x_jobs.field.steps',
+    traceparent: 'admin.x_jobs.field.traceparent',
+    enqueuedBy: 'admin.x_jobs.field.enqueuedBy',
+    claimedBy: 'admin.x_jobs.field.claimedBy',
+  },
+  columns: { completed: 'admin.x_jobs.column.completed', error: 'admin.x_jobs.column.error' },
+} as const;
+
+export const QUEUE_LABELS = {
+  title: 'admin.x_job_queues.title',
+  fields: {
+    name: 'admin.x_job_queues.field.name',
+    ready: 'admin.x_job_queues.field.ready',
+    delayed: 'admin.x_job_queues.field.delayed',
+    running: 'admin.x_job_queues.field.running',
+    suspended: 'admin.x_job_queues.field.suspended',
+    failed: 'admin.x_job_queues.field.failed',
+    dead: 'admin.x_job_queues.field.dead',
+    oldestReadyMs: 'admin.x_job_queues.field.oldestReadyMs',
+    paused: 'admin.x_job_queues.field.paused',
+    pausedAt: 'admin.x_job_queues.field.pausedAt',
+  },
+  columns: { oldest: 'admin.x_job_queues.column.oldest', jobs: 'admin.x_job_queues.column.jobs' },
+} as const;
+
+export const TASK_LABELS = {
+  title: 'admin.x_job_tasks.title',
+  fields: {
+    name: 'admin.x_job_tasks.field.name',
+    cron: 'admin.x_job_tasks.field.cron',
+    tz: 'admin.x_job_tasks.field.tz',
+    catchUp: 'admin.x_job_tasks.field.catchUp',
+    enqueues: 'admin.x_job_tasks.field.enqueues',
+    lastFireAt: 'admin.x_job_tasks.field.lastFireAt',
+    nextFireAt: 'admin.x_job_tasks.field.nextFireAt',
+    paused: 'admin.x_job_tasks.field.paused',
+  },
+} as const;
+
+export const WORKER_LABELS = {
+  title: 'admin.x_job_workers.title',
+  fields: {
+    id: 'admin.x_job_workers.field.id',
+    host: 'admin.x_job_workers.field.host',
+    queues: 'admin.x_job_workers.field.queues',
+    concurrency: 'admin.x_job_workers.field.concurrency',
+    inFlight: 'admin.x_job_workers.field.inFlight',
+    startedAt: 'admin.x_job_workers.field.startedAt',
+    heartbeatAt: 'admin.x_job_workers.field.heartbeatAt',
+  },
+  columns: {
+    heartbeat: 'admin.x_job_workers.column.heartbeat',
+    running: 'admin.x_job_workers.column.running',
+  },
+} as const;
+
+/** One tab per job state, plus every row. */
+export const SCOPE_LABELS = {
+  all: 'admin.jobs.scope.all',
+  ready: 'admin.jobs.scope.ready',
+  delayed: 'admin.jobs.scope.delayed',
+  running: 'admin.jobs.scope.running',
+  suspended: 'admin.jobs.scope.suspended',
+  done: 'admin.jobs.scope.done',
+  failed: 'admin.jobs.scope.failed',
+  dead: 'admin.jobs.scope.dead',
+  cancelled: 'admin.jobs.scope.cancelled',
+} as const;
+
+/**
+ * The step box of "retry from a step", at the key `action-input.ts` derives for it — the one input
+ * an operator types on these screens. `job-actions.test.ts` pins the derivation to this name.
+ */
+export const RETRY_STEP_LABEL = 'admin.input.job.retry-from-step.step';
+
+/** Each field's label key laid over the field's own overrides. */
+export function labelled(
+  labels: Readonly<Record<string, string>>,
+  overrides: Readonly<Record<string, AdminFieldOverride>> = {},
+): Readonly<Record<string, AdminFieldOverride>> {
+  return Object.fromEntries(
+    Object.entries(labels).map(([name, labelKey]) => [name, { ...overrides[name], labelKey }]),
+  );
+}

package/src/jobs/job-repo.ts

@@ -0,0 +1,103 @@
+// The job rows as an `AdminRepo`: a page is ONE `JobIntrospection.list` call, newest first and
+// keyset by `(createdAt, id)` — the store's own order, and the only one it answers — and a detail
+// is the store's own trace, its input already redacted. Read-only: every change is an action.
+
+import { assert } from '@ultimat3/core';
+import { inspectJob, type JobRecord, jobCursor, MAX_JOB_PAGE } from '@ultimat3/jobs';
+import { AdminFilterInvalidError } from '../errors';
+import type { AdminListQuery, AdminRepo, AdminRow, KeysetBound } from '../registry';
+import { JOBS_RESOURCE, jobWhere } from './job-where';
+import { jobsOperator } from './operator';
+
+/** The one order the store pages in. Any other is refused, never answered in this one. */
+export const JOB_SORT = { field: 'createdAt', direction: 'desc' } as const;
+
+const at = (ms: number | undefined): Date | null => (ms === undefined ? null : new Date(ms));
+
+/** A row as a list shows it: no payload and no stack — those are the detail page's. */
+export function jobRow(record: JobRecord): AdminRow {
+  return {
+    id: record.id,
+    name: record.name,
+    queue: record.queue,
+    state: record.state,
+    attempt: record.attempt,
+    maxAttempts: record.maxAttempts,
+    runAt: at(record.runAt),
+    createdAt: at(record.createdAt),
+    updatedAt: at(record.updatedAt),
+    tenantId: record.tenantId ?? null,
+    lastError: record.lastError ?? null,
+    progress: record.progress ?? null,
+    traceparent: record.traceparent ?? null,
+    enqueuedBy: record.enqueuedBy ?? null,
+    claimedBy: record.claimedBy ?? null,
+  };
+}
+
+/** A keyset bound as the store's cursor: the bound row's instant in ms, and its id. */
+const cursorOf = (bound: KeysetBound): string =>
+  jobCursor({ createdAt: Date.parse(bound.value), id: bound.id });
+
+function assertOrder(query: AdminListQuery): void {
+  const { field, direction } = query.sort;
+  if (field === JOB_SORT.field && direction === JOB_SORT.direction) return;
+  throw new AdminFilterInvalidError({
+    entity: JOBS_RESOURCE,
+    asked: `sort=${field}:${direction}`,
+    cause: 'is not an order the job store pages in — a job list is newest first',
+    known: [`sort=${JOB_SORT.field}:${JOB_SORT.direction}`],
+  });
+}
+
+async function list(query: AdminListQuery): Promise<readonly AdminRow[]> {
+  assertOrder(query);
+  const where = jobWhere(query.where ?? []);
+  if (where.empty) return [];
+  const { introspect } = jobsOperator();
+  const records = await introspect.list({
+    ...where.filter,
+    // The admin asks one row past its page to learn whether there is a next one; the store's page
+    // is bounded, and a full store page simply reads as "maybe more".
+    limit: Math.min(query.limit, MAX_JOB_PAGE),
+    ...(query.after === undefined ? {} : { after: cursorOf(query.after) }),
+    ...(query.before === undefined ? {} : { before: cursorOf(query.before) }),
+  });
+  const exact = where.exactId;
+  return (exact === undefined ? records : records.filter((record) => record.id === exact)).map(
+    jobRow,
+  );
+}
+
+/** The detail: the row, plus what `inspectJob` says of it — redacted input, steps, the stack. */
+async function find(id: string): Promise<AdminRow | null> {
+  const { driver, introspect } = jobsOperator();
+  const [record, trace] = await Promise.all([introspect.job(id), inspectJob(driver, id)]);
+  if (record === undefined || trace === undefined) return null;
+  return {
+    ...jobRow(record),
+    input: trace.input ?? null,
+    lastErrorStack: trace.stack,
+    steps: trace.steps,
+  };
+}
+
+/**
+ * Unreachable through the admin — the resource offers list and detail only (`job-resources.ts`) —
+ * so a call here is a caller that went round the route table: an invariant, not a refusal.
+ */
+const readOnly = async (): Promise<never> => {
+  assert(
+    false,
+    'a job row was written through the admin repo, and the jobs resource offers no write',
+    'change a job through its actions: admin.action.job.retry, .run-now, .cancel, .remove',
+  );
+};
+
+export const jobRepo: AdminRepo<AdminRow> = {
+  list,
+  find,
+  create: readOnly,
+  update: readOnly,
+  destroy: readOnly,
+};

package/src/jobs/job-resources.ts

@@ -0,0 +1,211 @@
+// The jobs dashboard as `defineAdmin()` input: four resources over the queue's operator surface,
+// each an ordinary `AdminResourceOptions` — a `repo:`, scopes, a row scope, computed columns,
+// sections — and `job-actions.ts`'s actions, attached by `entity` as an app's are. `defineAdmin`
+// declares them for every app, so `/admin/jobs/*` exists with no app code.
+
+import { JOB_STATES } from '@ultimat3/jobs';
+import type { AdminActor } from '../authz';
+import { listHref } from '../list-request';
+import type { AdminAction, AdminEntity, AdminFilter } from '../registry';
+import { type AdminResourceOptions, adminResource } from '../resource';
+import type { AdminRowScope, AdminScopeOptions } from '../resource-list';
+import { queueRepo, taskRepo, workerRepo } from './fleet-repo';
+import { jobActions, queueActions, taskActions } from './job-actions';
+import { JOB_ENTITY, jobEntity, queueEntity, taskEntity, workerEntity } from './job-entities';
+import {
+  labelled,
+  QUEUE_LABELS,
+  RUN_LABELS,
+  SCOPE_LABELS,
+  TASK_LABELS,
+  WORKER_LABELS,
+} from './job-labels';
+import { JOB_SORT, jobRepo } from './job-repo';
+
+/** The permission noun every jobs resource shares: `job:read` lists any of them. */
+export const JOB_PERMISSION_NOUN = 'job';
+/** Where the jobs screens sit under the admin's base path. The overview is this path itself. */
+export const JOBS_PATH = '/jobs';
+export const JOBS_GROUP = 'admin.group.jobs';
+
+/**
+ * An org-scoped operator — an actor with an `orgId` — sees that org's job rows and nothing else.
+ * A platform operator is the actor without one, and sees every row.
+ */
+export const jobRowScope: AdminRowScope = (actor: AdminActor): readonly AdminFilter[] =>
+  actor.orgId === undefined ? [] : [{ field: 'tenantId', op: 'eq', value: actor.orgId }];
+
+/**
+ * Queues, tasks and workers are the FLEET, shared by every tenant: an org-scoped operator who
+ * paused a queue would pause it for every org. So they are a platform operator's rows only — the
+ * predicate below holds for no row, because every row of these three has a key.
+ */
+const platformOnly =
+  (key: string): AdminRowScope =>
+  (actor) =>
+    actor.orgId === undefined ? [] : [{ field: key, op: 'is-null', value: true }];
+
+/** One tab per state, plus every row. Counts are the overview's tiles (`stats()`), not the tabs. */
+const stateScopes: Readonly<Record<string, AdminScopeOptions>> = Object.fromEntries([
+  ['all', { where: [], default: true, labelKey: SCOPE_LABELS.all }],
+  ...JOB_STATES.map((state) => [
+    state,
+    { where: [{ field: 'state', op: 'eq', value: state }], labelKey: SCOPE_LABELS[state] },
+  ]),
+]);
+
+/** A choice the store answers by equality — never the `contains` a free-text column defaults to. */
+const exact = { type: 'enum', sortable: false } as const;
+const unsorted = { sortable: false } as const;
+const unsearched = { searchable: false } as const;
+
+function runsOptions(): AdminResourceOptions {
+  return {
+    repo: jobRepo,
+    path: `${JOBS_PATH}/runs`,
+    titleKey: RUN_LABELS.title,
+    permission: JOB_PERMISSION_NOUN,
+    group: JOBS_GROUP,
+    // The list's search box is the label's filter: an id pasted from a log line, by its prefix.
+    labelField: 'id',
+    fields: labelled(RUN_LABELS.fields, {
+      id: { searchable: true, sortable: false, hintKey: 'admin.jobs.hint.id' },
+      name: exact,
+      queue: exact,
+      tenantId: exact,
+      attempt: unsorted,
+      maxAttempts: unsorted,
+      runAt: unsorted,
+      updatedAt: unsorted,
+      // Free text the store cannot search: the admin's search asks only what it can answer.
+      lastError: unsearched,
+      lastErrorStack: unsearched,
+      traceparent: unsearched,
+      enqueuedBy: unsearched,
+      claimedBy: unsearched,
+    }),
+    listFields: ['id', 'name', 'state', 'queue', 'attempt', 'runAt'],
+    columns: {
+      // `progress` itself is the column (JSON, on the detail page); the list shows `done / total`.
+      completed: {
+        value: (row) => {
+          const progress = row['progress'];
+          if (typeof progress !== 'object' || progress === null) return '';
+          const { done, total } = progress as { done?: unknown; total?: unknown };
+          return `${String(done)} / ${String(total)}`;
+        },
+        render: 'truncate',
+        labelKey: RUN_LABELS.columns.completed,
+      },
+      error: {
+        value: (row) => row['lastError'],
+        render: 'truncate',
+        labelKey: RUN_LABELS.columns.error,
+      },
+    },
+    scopes: stateScopes,
+    rows: jobRowScope,
+    sections: [
+      {
+        titleKey: 'admin.jobs.section.run',
+        fields: ['name', 'queue', 'state', 'attempt', 'maxAttempts', 'runAt', 'createdAt'],
+      },
+      { titleKey: 'admin.jobs.section.failure', fields: ['lastError', 'lastErrorStack'] },
+      { titleKey: 'admin.jobs.section.work', fields: ['input', 'progress', 'steps'] },
+      {
+        titleKey: 'admin.jobs.section.trace',
+        fields: ['tenantId', 'traceparent', 'enqueuedBy', 'claimedBy', 'updatedAt'],
+      },
+    ],
+    defaultSort: JOB_SORT,
+    pageSize: 50,
+    operations: ['list', 'detail', 'search'],
+  };
+}
+
+/** The whole dashboard as `defineAdmin` input, its links under `basePath`. */
+export function jobsAdmin(basePath: string): {
+  readonly entities: readonly AdminEntity[];
+  readonly resources: Readonly<Record<string, AdminResourceOptions>>;
+  readonly actions: readonly AdminAction[];
+} {
+  // Built once more here only to spell links through the list's own URL grammar (`listHref`).
+  const runs = adminResource(jobEntity, runsOptions());
+  const runsOf = (field: string, value: string): string =>
+    listHref(basePath, runs, { filters: [{ field, op: 'eq', value }] });
+  const fleet = {
+    permission: JOB_PERMISSION_NOUN,
+    group: JOBS_GROUP,
+    operations: ['list', 'detail', 'search'],
+  } as const;
+  return {
+    entities: [jobEntity, queueEntity, taskEntity, workerEntity],
+    resources: {
+      [JOB_ENTITY.jobs]: runsOptions(),
+      [JOB_ENTITY.queues]: {
+        ...fleet,
+        repo: queueRepo,
+        path: `${JOBS_PATH}/queues`,
+        titleKey: QUEUE_LABELS.title,
+        fields: labelled(QUEUE_LABELS.fields),
+        labelField: 'name',
+        listFields: ['name', 'ready', 'delayed', 'running', 'dead', 'failed', 'paused'],
+        columns: {
+          oldest: {
+            value: (row) => `${String(row['oldestReadyMs'])} ms`,
+            render: 'truncate',
+            labelKey: QUEUE_LABELS.columns.oldest,
+          },
+          jobs: {
+            value: (row) => ({
+              href: runsOf('queue', String(row['name'])),
+              label: String(row['name']),
+            }),
+            render: 'link',
+            labelKey: QUEUE_LABELS.columns.jobs,
+          },
+        },
+        defaultSort: { field: 'name', direction: 'asc' },
+        rows: platformOnly('name'),
+      },
+      [JOB_ENTITY.tasks]: {
+        ...fleet,
+        repo: taskRepo,
+        path: `${JOBS_PATH}/tasks`,
+        titleKey: TASK_LABELS.title,
+        fields: labelled(TASK_LABELS.fields),
+        labelField: 'name',
+        listFields: ['name', 'cron', 'tz', 'lastFireAt', 'nextFireAt', 'paused'],
+        defaultSort: { field: 'name', direction: 'asc' },
+        rows: platformOnly('name'),
+      },
+      [JOB_ENTITY.workers]: {
+        ...fleet,
+        repo: workerRepo,
+        path: `${JOBS_PATH}/workers`,
+        titleKey: WORKER_LABELS.title,
+        fields: labelled(WORKER_LABELS.fields),
+        labelField: 'id',
+        listFields: ['id', 'host', 'queues', 'inFlight', 'concurrency', 'startedAt'],
+        columns: {
+          heartbeat: {
+            value: (row) => row['heartbeatAt'],
+            render: 'relative-time',
+            labelKey: WORKER_LABELS.columns.heartbeat,
+          },
+          running: {
+            value: (row) => ({
+              href: listHref(basePath, runs, { scope: 'running' }),
+              label: String(row['inFlight']),
+            }),
+            render: 'link',
+            labelKey: WORKER_LABELS.columns.running,
+          },
+        },
+        defaultSort: { field: 'id', direction: 'asc' },
+        rows: platformOnly('id'),
+      },
+    },
+    actions: [...jobActions, ...queueActions, ...taskActions],
+  };
+}