@orion-js/dogs 4.6.7 → 4.6.9

package/dist/repos/JobsRepo.d.ts

@@ -40,6 +40,7 @@ export declare class JobsRepo {
         priority: number;
         lockId?: string;
     }): Promise<boolean>;
+    rescheduleAfterExecutionGuardAcquisitionFailure(jobId: string, lockId: string, nextRunAt: Date): Promise<boolean>;
     deleteEventJob(jobId: string, lockId?: string): Promise<boolean>;
     /**
      * Marks an event job as having reached its maximum tries limit.

package/dist/services/Executor.d.ts

@@ -1,5 +1,6 @@
 import { Blackbox } from '@orion-js/schema';
 import { EventJobDefinition, JobDefinition, JobsDefinition } from '../types/JobsDefinition';
+import { WorkerExecutionGuard, WorkerExecutionGuardLease } from '../types/StartConfig';
 import { ExecutionContext, JobToRun } from '../types/Worker';
 /**
  * Configuration for job execution including max tries settings.
@@ -9,6 +10,8 @@ export interface ExecuteJobConfig {
     maxTries?: number;
     maxTriesReachedRetentionMs?: number | null;
     onMaxTriesReached?: (job: JobToRun) => Promise<void>;
+    executionGuard?: WorkerExecutionGuard;
+    executionGuardRetryDelayMs?: number;
 }
 export declare class Executor {
     private readonly jobsRepo;
@@ -40,5 +43,8 @@ export declare class Executor {
         jobToRun: JobToRun;
     }): Promise<void>;
     afterExecutionSuccess(job: JobDefinition, jobToRun: JobToRun, context: ExecutionContext): Promise<boolean>;
+    handleExecutionGuardAcquisitionFailure(error: unknown, config: ExecuteJobConfig, jobToRun: JobToRun, context: ExecutionContext): Promise<void>;
+    releaseExecutionGuardLease(lease: WorkerExecutionGuardLease, jobToRun: JobToRun, context: ExecutionContext): Promise<void>;
+    runGuardedResolver(job: JobDefinition, jobToRun: JobToRun, context: ExecutionContext, lease: WorkerExecutionGuardLease): Promise<any>;
     executeJob(config: ExecuteJobConfig, jobToRun: JobToRun, onExecutionStale: () => void): Promise<void>;
 }

package/dist/services/WorkerService.d.ts

@@ -3,6 +3,7 @@ import { JobDefinitionWithName, JobsDefinition } from '../types/JobsDefinition';
 import { StartWorkersConfig } from '../types/StartConfig';
 import { JobToRun, WorkersInstance } from '../types/Worker';
 import { ExecuteJobConfig } from './Executor';
+import { PendingFilterChecks } from './jobFilters';
 interface TrackedExecution {
     job: JobToRun;
     promise: Promise<void>;
@@ -14,6 +15,7 @@ interface InternalWorkersInstance extends WorkersInstance {
     activeExecutions: Map<string, TrackedExecution>;
     staleExecutions: Map<string, TrackedExecution>;
     runningJobsByName: Map<string, number>;
+    pendingFilterChecks: PendingFilterChecks;
     jobAcquisitionHint: JobAcquisitionHint;
     jobAcquisitionHintProbeCycle: number;
     hasCompletedInitialJobAcquisitionHintProbe: boolean;
@@ -38,6 +40,7 @@ export declare class WorkerService {
     private partitionReconcilerJitterMs;
     private partitionReconcilerBatchPauseMs;
     private partitionReconcilerBatchSize;
+    private jobsFilterTimeoutMs;
     private jobsRepo;
     private executor;
     getJobNames(jobs: JobsDefinition): string[];

package/dist/services/jobFilters.d.ts

@@ -0,0 +1,21 @@
+import { JobsDefinition } from '../types/JobsDefinition';
+import { GetJobsFilter } from '../types/StartConfig';
+export declare const DEFAULT_JOBS_FILTER_TIMEOUT_MS = 5000;
+/**
+ * Checks that are still running, keyed by check name. A timed out check stays here until it
+ * settles so later claims skip it immediately instead of waiting for the timeout again.
+ */
+export type PendingFilterChecks = Map<string, Promise<unknown>>;
+interface TakeableJobNamesOptions {
+    jobs: JobsDefinition;
+    getJobsFilter?: GetJobsFilter;
+    jobNames: string[];
+    timeoutMs?: number;
+    pendingChecks?: PendingFilterChecks;
+}
+/**
+ * Applies the global getJobsFilter and each job's canTakeJobs to decide which jobs can be claimed.
+ * Any error or timeout excludes the affected jobs.
+ */
+export declare function getTakeableJobNames(inputOptions: TakeableJobNamesOptions): Promise<string[]>;
+export {};

package/dist/types/JobsDefinition.d.ts

@@ -37,6 +37,13 @@ export interface BaseJobDefinition {
      * If not set, the defaultLockTime from config will be used.
      */
     lockTime?: number;
+    /**
+     * Optional function evaluated before each claim to decide if this server can take this job,
+     * for example to stop taking a heavy job while the server is under load.
+     * Must resolve to true to take the job. If it throws or takes more than 5 seconds, the job is not taken.
+     * Running jobs are not affected. It runs before every claim without caching, so keep it cheap.
+     */
+    canTakeJobs?: () => Promise<boolean>;
 }
 export interface RecurrentJobDefinition extends BaseJobDefinition {
     /**

package/dist/types/StartConfig.d.ts

@@ -2,6 +2,32 @@ import { JobsDefinition } from './JobsDefinition';
 import { JobToRun } from './Worker';
 export type LogLevels = 'debug' | 'info' | 'warn' | 'error' | 'none';
 export declare const DEFAULT_MAX_TRIES_REACHED_RETENTION_MS: number;
+/**
+ * A lease held for the duration of one job resolver execution.
+ */
+export interface WorkerExecutionGuardLease {
+    release(): Promise<void>;
+}
+/**
+ * Acquires infrastructure protection for a claimed job before its resolver starts.
+ */
+export interface WorkerExecutionGuard {
+    acquire(job: JobToRun): Promise<WorkerExecutionGuardLease>;
+}
+/**
+ * Job names this server can take. Undefined properties are ignored; an empty allow list takes nothing.
+ */
+export interface JobsFilter {
+    /**
+     * Only these jobs can be taken.
+     */
+    allow?: string[];
+    /**
+     * These jobs can't be taken.
+     */
+    deny?: string[];
+}
+export type GetJobsFilter = () => Promise<JobsFilter>;
 export interface StartWorkersConfig {
     /**
      * Object map of the jobs that this scheduler will execute.
@@ -24,6 +50,19 @@ export interface StartWorkersConfig {
      * configured retention period expires.
      */
     onMaxTriesReached?: (job: JobToRun) => Promise<void>;
+    /**
+     * Optional infrastructure guard acquired after a job is claimed and before its resolver starts.
+     * The returned lease is held until the resolver's Promise settles, including late stale
+     * executions. Acquisition failures safely requeue the job without consuming a business try.
+     */
+    executionGuard?: WorkerExecutionGuard;
+    /**
+     * Optional function evaluated before each claim to decide which jobs this server can take,
+     * for example to stop taking heavy jobs while the server is under load.
+     * If it throws or takes more than 5 seconds, no jobs are taken on that claim.
+     * Running jobs are not affected. It runs before every claim without caching, so keep it cheap.
+     */
+    getJobsFilter?: GetJobsFilter;
     /**
      * Time in milliseconds to wait between each look without results for a job
      * to run at the database. Default is 3000.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orion-js/dogs",
-  "version": "4.6.7",
+  "version": "4.6.9",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",