@focus-reactive/payload-plugin-translator 0.3.0 → 0.4.0

package/dist/server/features/cancel/handler.d.ts

@@ -1,5 +1,5 @@
-import type { PayloadRequest } from 'payload';
-import type { TaskRunnerProvider } from '../../modules/task-runner';
+import type { PayloadRequest } from "payload";
+import type { TaskRunnerProvider } from "../../modules/task-runner";
 /**
  * Cancels and deletes translation tasks by IDs
  */

package/dist/server/features/cancel/handler.js

@@ -1,5 +1,5 @@
-import { ServerResponse } from '../../shared';
-import { CancelInputSchema } from './model';
+import { ServerResponse } from "../../shared";
+import { CancelInputSchema } from "./model";
 /**
  * Cancels and deletes translation tasks by IDs
  */ export class CancelHandler {
@@ -9,7 +9,7 @@ import { CancelInputSchema } from './model';
     }
     async handle(req) {
         const validationResult = CancelInputSchema.safeParse(await req.json?.());
-        if (validationResult.error) return ServerResponse.validationError(validationResult.error.errors);
+        if (validationResult.error) return ServerResponse.validationError(validationResult.error.issues);
         const { ids } = validationResult.data;
         const runner = this.taskRunnerFactory.create(req.payload);
         await runner.cancel(ids);

package/dist/server/features/cancel-by-collection/handler.d.ts

@@ -1,6 +1,6 @@
-import type { PayloadRequest } from 'payload';
-import type { TaskRunnerProvider } from '../../modules/task-runner';
-import { type CancelConfig } from './model';
+import type { PayloadRequest } from "payload";
+import type { TaskRunnerProvider } from "../../modules/task-runner";
+import type { CancelConfig } from './model';
 /**
  * Cancels all pending translation tasks for a collection
  */

package/dist/server/features/cancel-by-collection/handler.js

@@ -1,5 +1,5 @@
-import { ServerResponse } from '../../shared';
-import { isCollectionAvailable } from '../_lib/collection-utils';
+import { ServerResponse } from "../../shared";
+import { isCollectionAvailable } from "../_lib/collection-utils";
 import { CancelByCollectionInputSchema } from './model';
 /**
  * Cancels all pending translation tasks for a collection
@@ -12,13 +12,13 @@ import { CancelByCollectionInputSchema } from './model';
     }
     async handle(req) {
         const validationResult = CancelByCollectionInputSchema.safeParse(req.routeParams);
-        if (validationResult.error) return ServerResponse.validationError(validationResult.error.errors);
+        if (validationResult.error) return ServerResponse.validationError(validationResult.error.issues);
         const collectionSlug = isCollectionAvailable(validationResult.data.collection_slug, this.config.availableCollections);
-        if (!collectionSlug) return ServerResponse.badRequest('Collection not available for translation');
+        if (!collectionSlug) return ServerResponse.badRequest("Collection not available for translation");
         const runner = this.taskRunnerFactory.create(req.payload);
         const tasks = await runner.findByCollection(collectionSlug);
         if (tasks.length === 0) return ServerResponse.noContent();
-        const pendingTaskIds = tasks.filter((task)=>task.status === 'pending').map((task)=>task.id);
+        const pendingTaskIds = tasks.filter((task)=>task.status === "pending").map((task)=>task.id);
         if (pendingTaskIds.length === 0) return ServerResponse.noContent();
         await runner.cancel(pendingTaskIds);
         return ServerResponse.noContent();

package/dist/server/features/enqueue-translation/handler.d.ts

@@ -1,6 +1,6 @@
-import type { PayloadRequest } from 'payload';
-import type { TaskRunnerProvider } from '../../modules/task-runner';
-import { type EnqueueConfig } from './model';
+import type { PayloadRequest } from "payload";
+import type { TaskRunnerProvider } from "../../modules/task-runner";
+import type { EnqueueConfig } from './model';
 /**
  * Enqueues translation tasks for documents
  */

package/dist/server/features/enqueue-translation/handler.js

@@ -1,5 +1,5 @@
-import { ServerResponse } from '../../shared';
-import { isCollectionAvailable, getAllCollectionIds } from '../_lib/collection-utils';
+import { ServerResponse } from "../../shared";
+import { isCollectionAvailable, getAllCollectionIds } from "../_lib/collection-utils";
 import { EnqueueInputSchema } from './model';
 /**
  * Enqueues translation tasks for documents
@@ -12,10 +12,10 @@ import { EnqueueInputSchema } from './model';
     }
     async handle(req) {
         const validationResult = EnqueueInputSchema.safeParse(await req.json?.());
-        if (validationResult.error) return ServerResponse.validationError(validationResult.error.errors);
+        if (validationResult.error) return ServerResponse.validationError(validationResult.error.issues);
         const { source_lng, target_lng, collection_slug, collection_id, select_all, strategy, publish_on_translation } = validationResult.data;
         const collectionSlug = isCollectionAvailable(collection_slug, this.config.availableCollections);
-        if (!collectionSlug) return ServerResponse.badRequest('Content of this collection is not available for translation');
+        if (!collectionSlug) return ServerResponse.badRequest("Content of this collection is not available for translation");
         const collectionIds = select_all ? await getAllCollectionIds(req.payload, collectionSlug) : collection_id;
         const runner = this.taskRunnerFactory.create(req.payload);
         const tasks = collectionIds.map((id)=>({

package/dist/server/features/get-collection-status/handler.d.ts

@@ -1,6 +1,6 @@
-import type { PayloadRequest } from 'payload';
-import type { TaskRunnerProvider } from '../../modules/task-runner';
-import { type GetCollectionStatusConfig } from './model';
+import type { PayloadRequest } from "payload";
+import type { TaskRunnerProvider } from "../../modules/task-runner";
+import type { GetCollectionStatusConfig } from './model';
 /**
  * Gets translation status for all documents in a collection
  */

package/dist/server/features/get-collection-status/handler.js

@@ -1,5 +1,5 @@
-import { ServerResponse } from '../../shared';
-import { isCollectionAvailable } from '../_lib/collection-utils';
+import { ServerResponse } from "../../shared";
+import { isCollectionAvailable } from "../_lib/collection-utils";
 import { GetCollectionStatusInputSchema } from './model';
 /**
  * Gets translation status for all documents in a collection
@@ -12,9 +12,9 @@ import { GetCollectionStatusInputSchema } from './model';
     }
     async handle(req) {
         const validationResult = GetCollectionStatusInputSchema.safeParse(req.routeParams);
-        if (validationResult.error) return ServerResponse.validationError(validationResult.error.errors);
+        if (validationResult.error) return ServerResponse.validationError(validationResult.error.issues);
         const collectionSlug = isCollectionAvailable(validationResult.data.collection_slug, this.config.availableCollections);
-        if (!collectionSlug) return ServerResponse.badRequest('Collection not available for translation');
+        if (!collectionSlug) return ServerResponse.badRequest("Collection not available for translation");
         const runner = this.taskRunnerFactory.create(req.payload);
         const tasks = await runner.findByCollection(collectionSlug);
         return ServerResponse.success({

package/dist/server/features/get-document-status/handler.d.ts

@@ -1,6 +1,6 @@
-import type { PayloadRequest } from 'payload';
-import type { TaskRunnerProvider } from '../../modules/task-runner';
-import { type GetDocumentStatusConfig } from './model';
+import type { PayloadRequest } from "payload";
+import type { TaskRunnerProvider } from "../../modules/task-runner";
+import type { GetDocumentStatusConfig } from './model';
 /**
  * Gets the translation status for a specific document
  */

package/dist/server/features/get-document-status/handler.js

@@ -1,5 +1,5 @@
-import { ServerResponse } from '../../shared';
-import { isCollectionAvailable } from '../_lib/collection-utils';
+import { ServerResponse } from "../../shared";
+import { isCollectionAvailable } from "../_lib/collection-utils";
 import { GetDocumentStatusInputSchema, taskToJobStatusOutput } from './model';
 /**
  * Gets the translation status for a specific document
@@ -12,10 +12,10 @@ import { GetDocumentStatusInputSchema, taskToJobStatusOutput } from './model';
     }
     async handle(req) {
         const validationResult = GetDocumentStatusInputSchema.safeParse(req.routeParams);
-        if (validationResult.error) return ServerResponse.validationError(validationResult.error.errors);
+        if (validationResult.error) return ServerResponse.validationError(validationResult.error.issues);
         const { collection_slug, collection_id } = validationResult.data;
         const collectionSlug = isCollectionAvailable(collection_slug, this.config.availableCollections);
-        if (!collectionSlug) return ServerResponse.badRequest('Collection not available for translation');
+        if (!collectionSlug) return ServerResponse.badRequest("Collection not available for translation");
         const runner = this.taskRunnerFactory.create(req.payload);
         const tasks = await runner.findByCollection(collectionSlug, [
             collection_id

package/dist/server/features/run-translation/handler.d.ts

@@ -1,5 +1,5 @@
-import type { PayloadRequest } from 'payload';
-import type { TaskRunnerProvider } from '../../modules/task-runner';
+import type { PayloadRequest } from "payload";
+import type { TaskRunnerProvider } from "../../modules/task-runner";
 /**
  * Runs a translation task by ID
  */

package/dist/server/features/run-translation/handler.js

@@ -1,5 +1,5 @@
-import { ServerResponse } from '../../shared';
-import { RunInputSchema } from './model';
+import { ServerResponse } from "../../shared";
+import { RunInputSchema } from "./model";
 /**
  * Runs a translation task by ID
  */ export class RunTranslationHandler {
@@ -9,16 +9,16 @@ import { RunInputSchema } from './model';
     }
     async handle(req) {
         const validationResult = RunInputSchema.safeParse(req.routeParams);
-        if (validationResult.error) return ServerResponse.validationError(validationResult.error.errors);
+        if (validationResult.error) return ServerResponse.validationError(validationResult.error.issues);
         const { id } = validationResult.data;
         const runner = this.taskRunnerFactory.create(req.payload);
         const result = await runner.run(id);
         if (!result.success) {
-            if (result.error === 'not_found' || result.error === 'already_completed') {
-                return ServerResponse.notFound('Queued task not found');
+            if (result.error === "not_found" || result.error === "already_completed") {
+                return ServerResponse.notFound("Queued task not found");
             }
-            if (result.error === 'already_running') {
-                return ServerResponse.tooManyRequests('Translation task is already in progress');
+            if (result.error === "already_running") {
+                return ServerResponse.tooManyRequests("Translation task is already in progress");
             }
         }
         return ServerResponse.noContent();

package/dist/server/modules/task-runner/TaskRunnerProvider.interface.d.ts

@@ -41,6 +41,7 @@ export interface TaskRunnerProvider {
     /**
      * Configures the runner and returns a Payload config modifier.
      * The modifier adds necessary tasks, jobs, queues to Payload config.
+     * Implementations may also install a `config.onInit` hook for boot-time initialization (e.g. stale-lock recovery).
      */
     configure(context: TaskRunnerContext): (config: Config) => Config;
 }

package/dist/server/modules/task-runner/payload-jobs-runner/PayloadJobsRunnerProvider.js

@@ -4,11 +4,13 @@ const defaultAutoRun = {
     cron: "* * * * *",
     limit: 50
 };
+const DEFAULT_STALE_JOB_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 const defaultValues = {
     taskName: "translate_document",
     queueName: "translations",
     jobsCollection: "payload-jobs",
     autoRun: defaultAutoRun,
+    staleJobTimeoutMs: DEFAULT_STALE_JOB_TIMEOUT_MS,
     retries: {
         attempts: 3,
         backoff: {
@@ -28,11 +30,16 @@ const defaultValues = {
             ...defaultAutoRun,
             ...options.autoRun
         } : defaultAutoRun;
+        const staleJobTimeoutMs = options?.staleJobTimeoutMs ?? defaultValues.staleJobTimeoutMs;
+        if (!Number.isFinite(staleJobTimeoutMs) || staleJobTimeoutMs <= 0) {
+            throw new Error(`[payload-plugin-translator] staleJobTimeoutMs must be a positive finite number (got ${staleJobTimeoutMs})`);
+        }
         this.config = {
             taskName: options?.taskName ?? defaultValues.taskName,
             queueName: options?.queueName ?? defaultValues.queueName,
             jobsCollection: options?.jobsCollection ?? defaultValues.jobsCollection,
             autoRun,
+            staleJobTimeoutMs,
             retries: options?.retries ?? defaultValues.retries
         };
     }
@@ -141,6 +148,25 @@ const defaultValues = {
                     ];
                 }
             }
+            // Reset stale locks on boot so jobs abandoned by a killed process
+            // (deploy/crash/timeout) become eligible for the autorun picker again.
+            // The picker requires processing:false, no error, and no pending waitUntil;
+            // a mid-run casualty (no error, no waitUntil) satisfies the rest, so
+            // clearing processing is sufficient for that case. Threshold-based, so a
+            // job genuinely in flight on another live instance (fresh updatedAt) is
+            // left alone. Wrapped so a reclaim failure never blocks startup.
+            const existingOnInit = config.onInit;
+            config.onInit = async (payload)=>{
+                if (existingOnInit) await existingOnInit(payload);
+                try {
+                    await new PayloadJobsTaskRunner(payload, this.config).reclaimStaleJobs();
+                } catch (err) {
+                    payload.logger?.error?.({
+                        err,
+                        msg: "[translator] failed to reclaim stale translation jobs"
+                    });
+                }
+            };
             return config;
         };
     }

package/dist/server/modules/task-runner/payload-jobs-runner/PayloadJobsTaskRunner.d.ts

@@ -14,6 +14,35 @@ export declare class PayloadJobsTaskRunner implements TaskRunner {
     enqueue(tasks: TaskInput[]): Promise<void>;
     cancel(taskIds: string[]): Promise<void>;
     run(taskId: string): Promise<RunResult>;
+    /**
+     * Reset stale processing locks so abandoned jobs become eligible for the
+     * autorun picker again. The picker requires processing:false, no error, and
+     * no pending waitUntil; a job abandoned mid-run (no error, no waitUntil)
+     * satisfies the rest, so clearing processing is sufficient for that case.
+     * A job that already exhausted retries (hasError:true) stays excluded from
+     * autorun and is only recoverable via a manual run().
+     *
+     * A job is stale when it is still `processing: true`, not yet completed, and
+     * its `updatedAt` is older than `staleJobTimeoutMs` — i.e. a process was
+     * killed mid-run (deploy/crash/timeout). Threshold-based, so a job genuinely
+     * in flight on another live instance (fresh `updatedAt`) is left alone.
+     * Filters on real `payload-jobs` columns only (no JSON-path traversal), so
+     * the drizzle SQLite issue in `findByCollection` does not apply here.
+     * @returns the number of jobs reclaimed.
+     */
+    reclaimStaleJobs(): Promise<number>;
+    /**
+     * Clear the `processing` lock on every job matching `where`, returning how
+     * many were reset. Shared by the per-job reset in `run()` (a stale lock) and
+     * the bulk boot/recovery reset in `reclaimStaleJobs()`. `depth: 0` because
+     * only the count is needed — no relationships to populate.
+     */
+    private resetProcessing;
+    /**
+     * A processing lock is stale once `updatedAt` is older than the configured
+     * timeout — the owning run is presumed dead.
+     */
+    private isStale;
     /**
      * Find translation jobs for a collection, optionally narrowed by document IDs.
      *

package/dist/server/modules/task-runner/payload-jobs-runner/PayloadJobsTaskRunner.js

@@ -63,19 +63,114 @@ import { normalizeJob } from "./normalizeJob";
             };
         }
         if (task.status === "running") {
-            return {
-                success: false,
-                error: "already_running"
-            };
+            // A genuinely in-flight job is refused. A stale processing lock (left by
+            // a process killed mid-run) is reclaimable: clear it first so the queue
+            // picker below — which only selects `processing: false` — can re-run it.
+            if (!this.isStale(task.updatedAt)) {
+                return {
+                    success: false,
+                    error: "already_running"
+                };
+            }
+            await this.resetProcessing({
+                id: {
+                    equals: taskId
+                }
+            });
         }
-        this.payload.jobs.runByID({
-            id: taskId
+        // Execute synchronously via the queue + `where` picker so the job runs to
+        // completion within this request (nothing is abandoned after the HTTP
+        // response — reliable on serverless too).
+        //
+        // NOT `payload.jobs.runByID({ id })`: on the drizzle adapter the id-path
+        // (`db.updateJobs({ id })`) writes `processing: true` but returns no rows,
+        // so `runJobs` reports `noJobsRemaining` and the handler never runs —
+        // leaving the job stuck at `processing: true` forever. The `where`-based
+        // picker selects, runs, and finalizes the job correctly (verified against
+        // sqlite). The picker also enforces processing:false / no-error / no
+        // pending waitUntil, so a failed (max-retries) job is not re-run here.
+        await this.payload.jobs.run({
+            queue: this.config.queueName,
+            where: {
+                id: {
+                    equals: taskId
+                }
+            },
+            limit: 1
         });
         return {
             success: true
         };
     }
     /**
+   * Reset stale processing locks so abandoned jobs become eligible for the
+   * autorun picker again. The picker requires processing:false, no error, and
+   * no pending waitUntil; a job abandoned mid-run (no error, no waitUntil)
+   * satisfies the rest, so clearing processing is sufficient for that case.
+   * A job that already exhausted retries (hasError:true) stays excluded from
+   * autorun and is only recoverable via a manual run().
+   *
+   * A job is stale when it is still `processing: true`, not yet completed, and
+   * its `updatedAt` is older than `staleJobTimeoutMs` — i.e. a process was
+   * killed mid-run (deploy/crash/timeout). Threshold-based, so a job genuinely
+   * in flight on another live instance (fresh `updatedAt`) is left alone.
+   * Filters on real `payload-jobs` columns only (no JSON-path traversal), so
+   * the drizzle SQLite issue in `findByCollection` does not apply here.
+   * @returns the number of jobs reclaimed.
+   */ async reclaimStaleJobs() {
+        const cutoff = new Date(Date.now() - this.config.staleJobTimeoutMs).toISOString();
+        return this.resetProcessing({
+            and: [
+                {
+                    taskSlug: {
+                        equals: this.config.taskName
+                    }
+                },
+                {
+                    processing: {
+                        equals: true
+                    }
+                },
+                {
+                    completedAt: {
+                        exists: false
+                    }
+                },
+                {
+                    updatedAt: {
+                        less_than: cutoff
+                    }
+                }
+            ]
+        });
+    }
+    /**
+   * Clear the `processing` lock on every job matching `where`, returning how
+   * many were reset. Shared by the per-job reset in `run()` (a stale lock) and
+   * the bulk boot/recovery reset in `reclaimStaleJobs()`. `depth: 0` because
+   * only the count is needed — no relationships to populate.
+   */ async resetProcessing(where) {
+        const result = await this.payload.update({
+            collection: this.config.jobsCollection,
+            depth: 0,
+            where,
+            data: {
+                processing: false
+            }
+        });
+        return result.docs.length;
+    }
+    /**
+   * A processing lock is stale once `updatedAt` is older than the configured
+   * timeout — the owning run is presumed dead.
+   */ isStale(updatedAt) {
+        const parsed = Date.parse(updatedAt);
+        // Unknown/corrupt timestamp → treat as stale so the job can be recovered
+        // rather than permanently refused as already-running.
+        if (Number.isNaN(parsed)) return true;
+        return Date.now() - parsed > this.config.staleJobTimeoutMs;
+    }
+    /**
    * Find translation jobs for a collection, optionally narrowed by document IDs.
    *
    * Narrowing is by `taskSlug` only in SQL; the collection slug and document

package/dist/server/modules/task-runner/payload-jobs-runner/types.d.ts

@@ -40,6 +40,22 @@ export type PayloadJobsRunnerOptions = {
      * @default { cron: '* * * * *', limit: 50 }
      */
     autoRun?: false | AutoRunConfig;
+    /**
+     * How long (ms) a job may stay `processing: true` before its lock is
+     * considered stale and the job becomes eligible to be re-run.
+     *
+     * A process killed mid-run (deploy, crash, request timeout) leaves a job
+     * stuck at `processing: true`; the autorun picker only takes
+     * `processing: false`, so without recovery such a job would hang forever.
+     * On boot the runner resets stale locks, and manual `run()` will re-claim a
+     * stale-locked job instead of refusing it as already-running.
+     *
+     * MUST be larger than the longest a single document translation can
+     * legitimately take, otherwise a genuinely in-flight job could be reclaimed
+     * and run twice (safe under the idempotent `overwrite` strategy, but wasteful).
+     * @default 300000 (5 minutes)
+     */
+    staleJobTimeoutMs?: number;
     /**
      * Retry configuration for failed jobs.
      */
@@ -59,6 +75,7 @@ export type PayloadJobsRunnerConfig = {
     queueName: string;
     jobsCollection: CollectionSlug;
     autoRun: false | Required<AutoRunConfig>;
+    staleJobTimeoutMs: number;
     retries?: PayloadJobsRunnerOptions["retries"];
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@focus-reactive/payload-plugin-translator",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Translation plugin for Payload CMS 3.x. Automatically translate your localized content using any translation provider.",
   "type": "module",
   "license": "MIT",