@oatscenter/trellis 0.100.0-rc.1

package/service/runtime/internal_jobs/job-manager.d.ts

@@ -0,0 +1,126 @@
+import { type MsgHdrs } from "@nats-io/nats-core";
+import { type JobSnapshot } from "../../../jobs.ts";
+import { ActiveJob, ActiveJobRuntimeError, JobCancellationToken } from "./active-job.ts";
+import type { JobsBinding, JobsQueueBinding } from "./bindings.ts";
+import type { ActiveSlotLease, JobKeyCoordinator } from "./key-coordinator.ts";
+import type { Job, JobContext, JobEvent, JobLogEntry, JobProgress, JobWaitTarget, PreparedJobSubmission } from "./types.ts";
+type Publisher = {
+    publish(subject: string, payload: Uint8Array, opts?: {
+        headers?: MsgHdrs;
+    }): unknown | Promise<unknown>;
+};
+type JobMetaSource = {
+    nextJobId(): string;
+    nowIso(): string;
+};
+type JobManagerContext = {
+    nc: Publisher;
+    jobs?: JobsBinding;
+    keyCoordinator?: JobKeyCoordinator;
+    meta?: JobMetaSource;
+};
+type ActiveJobRuntimeMetadata = {
+    redeliveryCount?: number;
+    instanceId?: string;
+    progressAckIntervalMs?: number;
+    latestState?: Job["state"];
+    workEventType?: JobEvent["eventType"];
+};
+type JobProcessValidation<TPayload, TResult> = {
+    validateResult?: (result: TResult, job: Job<TPayload, TResult>) => Promise<void> | void;
+};
+export declare class JobProcessError extends Error {
+    readonly kind: "retryable" | "failed";
+    constructor(kind: "retryable" | "failed", message: string);
+    static retryable(message: string): JobProcessError;
+    static failed(message: string): JobProcessError;
+}
+export type JobProcessOutcome<TResult> = {
+    outcome: "completed";
+    tries: number;
+    result: TResult;
+} | {
+    outcome: "retry";
+    tries: number;
+    error: string;
+} | {
+    outcome: "dead";
+    tries: number;
+    error: string;
+} | {
+    outcome: "failed";
+    tries: number;
+    error: string;
+} | {
+    outcome: "cancelled";
+    tries: number;
+} | {
+    outcome: "deferred";
+    tries: number;
+    reason: string;
+} | {
+    outcome: "stale_completion_ignored";
+    tries: number;
+} | {
+    outcome: "interrupted";
+    tries: number;
+};
+export type JobManagerSubmitOutcome<TPayload, TResult> = {
+    kind: "accepted";
+    job: Job<TPayload, TResult>;
+    key?: string;
+} | {
+    kind: "rejected";
+    key: string;
+    reason: "active-limit" | "queue-depth" | "stale-blocked";
+    active: number;
+    queued: number;
+    limit: number;
+} | {
+    kind: "coalesced";
+    key: string;
+    existing: {
+        service: string;
+        jobType: string;
+        id: string;
+    };
+    reason: string;
+} | {
+    kind: "replaced";
+    key: string;
+    replaced: {
+        service: string;
+        jobType: string;
+        id: string;
+    };
+    job: Job<TPayload, TResult>;
+};
+export declare class JobManager<TPayload = unknown, TResult = unknown> {
+    #private;
+    constructor(context: JobManagerContext);
+    create(type: string, payload: TPayload): Promise<Job<TPayload, TResult>>;
+    submit(type: string, payload: TPayload): Promise<JobManagerSubmitOutcome<TPayload, TResult>>;
+    createPrepared(submission: PreparedJobSubmission<TPayload>): Promise<Job<TPayload, TResult>>;
+    submitPrepared(submission: PreparedJobSubmission<TPayload>): Promise<JobManagerSubmitOutcome<TPayload, TResult>>;
+    cleanupQueuedKeyedJob(job: Job<TPayload, TResult>): Promise<void>;
+    processWithHeartbeat(job: Job<TPayload, TResult>, cancellation: JobCancellationToken, heartbeat: () => Promise<void>, handler: (job: ActiveJob<TPayload, TResult>) => Promise<TResult>, metadata?: ActiveJobRuntimeMetadata, validation?: JobProcessValidation<TPayload, TResult>): Promise<JobProcessOutcome<TResult>>;
+    emitProgress(job: Job<TPayload, TResult>, progress: JobProgress): Promise<void>;
+    emitLog(job: Job<TPayload, TResult>, log: JobLogEntry): Promise<void>;
+    waitFor<T>(job: Job<TPayload, TResult>, target: JobWaitTarget, fn: () => Promise<T>): Promise<T>;
+    withActiveJobAndHeartbeat<T>(job: Job<TPayload, TResult>, cancellation: JobCancellationToken, heartbeat: () => Promise<void>, f: (job: ActiveJob<TPayload, TResult>) => Promise<T>, metadata?: ActiveJobRuntimeMetadata, lease?: ActiveSlotLease): Promise<T>;
+}
+/** Builds a durable job submission that can be dispatched after a transaction commits. */
+export declare function prepareJobSubmission<TPayload>(args: {
+    submissionId: string;
+    mode: "create" | "submit";
+    service: string;
+    queue: string;
+    jobId: string;
+    payload: TPayload;
+    createdAt: string;
+    context?: JobContext;
+    parent?: JobSnapshot<unknown, unknown>;
+}): PreparedJobSubmission<TPayload>;
+export declare function createJobContext(): JobContext;
+export type { JobsBinding, JobsQueueBinding };
+export { ActiveJob, ActiveJobRuntimeError, JobCancellationToken };