@oatscenter/trellis 0.100.0-rc.1

package/service/runtime/internal_jobs/key-coordinator.d.ts

@@ -0,0 +1,280 @@
+import type { NatsConnection } from "@nats-io/nats-core";
+import type { JobContext, JobEvent, JobState } from "./types.ts";
+export type JobKeyStalePolicy = "fail-stale" | "block";
+export type JobQueueWhenFull = "reject" | "coalesce" | "replace-oldest";
+export type JobKeyConcurrencyBinding = {
+    key: string[];
+    maxActive?: number;
+    heartbeatIntervalMs?: number;
+    heartbeatTtlMs?: number;
+    stalePolicy?: JobKeyStalePolicy;
+};
+export type JobQueuePolicyBinding = {
+    maxQueuedPerKey?: number;
+    whenFull?: JobQueueWhenFull;
+};
+export type NormalizedJobKeyPolicy = {
+    key: string[];
+    maxActive: number;
+    heartbeatIntervalMs: number;
+    heartbeatTtlMs: number;
+    stalePolicy: JobKeyStalePolicy;
+    queue: {
+        maxQueuedPerKey: number;
+        whenFull: JobQueueWhenFull;
+    };
+};
+export type DerivedJobKey = {
+    service: string;
+    jobType: string;
+    key: string;
+    keyHash: string;
+    kvKey: string;
+};
+export type JobKeyQueued = {
+    jobId: string;
+    createdAt: string;
+    requestId: string;
+    context: JobContext;
+    submissionId?: string;
+};
+export type JobKeyActiveSlot = {
+    jobId: string;
+    slotToken: string;
+    instanceId: string;
+    startedAt: string;
+    heartbeatAt: string;
+    leaseExpiresAt: string;
+    tries: number;
+    context: JobContext;
+};
+export type JobKeyState = {
+    version: 1;
+    service: string;
+    jobType: string;
+    key: string;
+    keyHash: string;
+    maxActive: number;
+    maxQueuedPerKey?: number;
+    active: JobKeyActiveSlot[];
+    queued: JobKeyQueued[];
+    staleTakeoverCount: number;
+    updatedAt: string;
+    coalescedBySubmissionId?: Record<string, {
+        existingJobId: string;
+        reason: "queue-full" | "active-limit";
+    }>;
+    acceptedBySubmissionId?: Record<string, {
+        jobId: string;
+    }>;
+    replacedBySubmissionId?: Record<string, ReplacedQueuedJob>;
+};
+export type JobKeyIdentity = {
+    service: string;
+    jobType: string;
+    id: string;
+};
+export type ReplacedQueuedJob = JobKeyIdentity & {
+    createdAt: string;
+    requestId: string;
+    context: JobContext;
+};
+export type JobAdmissionRequest = {
+    service: string;
+    jobType: string;
+    jobId: string;
+    payload: unknown;
+    context: JobContext;
+    createdAt: string;
+    policy: NormalizedJobKeyPolicy;
+    strictCreate: boolean;
+    submissionId?: string;
+};
+export type JobAdmissionOutcome = {
+    kind: "accepted";
+    key: string;
+    keyHash: string;
+    state: JobKeyState;
+} | {
+    kind: "rejected";
+    key: string;
+    reason: "active-limit" | "queue-depth" | "stale-blocked";
+    active: number;
+    queued: number;
+    limit: number;
+} | {
+    kind: "coalesced";
+    key: string;
+    existing: JobKeyIdentity;
+    reason: "queue-full" | "active-limit";
+} | {
+    kind: "replaced";
+    key: string;
+    keyHash: string;
+    replaced: ReplacedQueuedJob;
+    state: JobKeyState;
+};
+export type ActiveSlotAcquireRequest = {
+    service: string;
+    jobType: string;
+    jobId: string;
+    payload: unknown;
+    context: JobContext;
+    workEventType?: JobEvent["eventType"];
+    lifecycleState?: JobState;
+    tries: number;
+    instanceId: string;
+    now: string;
+    policy: NormalizedJobKeyPolicy;
+};
+export type ActiveSlotAcquireOutcome = {
+    kind: "acquired";
+    key: string;
+    keyHash: string;
+    slotToken: string;
+    stale: JobKeyActiveSlot[];
+    state: JobKeyState;
+} | {
+    kind: "blocked";
+    key: string;
+    reason: "active-limit" | "not-queued" | "stale-blocked";
+    active: number;
+    queued: number;
+    limit: number;
+};
+export type ActiveSlotLease = {
+    key: string;
+    keyHash: string;
+    slotToken: string;
+    policy: NormalizedJobKeyPolicy;
+};
+export type ActiveSlotRenewOutcome = {
+    kind: "renewed";
+    state: JobKeyState;
+} | {
+    kind: "lost";
+};
+export type ActiveSlotReleaseOutcome = {
+    kind: "released";
+    state: JobKeyState;
+} | {
+    kind: "staleCompletion";
+};
+export type JobKeyCoordinator = {
+    admitCreate(request: JobAdmissionRequest): Promise<JobAdmissionOutcome>;
+    restoreReplacedQueuedJob(args: {
+        service: string;
+        jobType: string;
+        replacementJobId: string;
+        replaced: ReplacedQueuedJob;
+        payload: unknown;
+        now: string;
+        policy: NormalizedJobKeyPolicy;
+        submissionId?: string;
+    }): Promise<QueuedJobRestoreOutcome>;
+    removeQueuedJob(args: {
+        service: string;
+        jobType: string;
+        jobId: string;
+        payload: unknown;
+        now: string;
+        policy: NormalizedJobKeyPolicy;
+        submissionId?: string;
+    }): Promise<QueuedJobRemovalOutcome>;
+    removeQueuedJobById?(args: {
+        service: string;
+        jobType: string;
+        jobId: string;
+        now: string;
+    }): Promise<QueuedJobRemovalOutcome>;
+    acquireActiveSlot(request: ActiveSlotAcquireRequest): Promise<ActiveSlotAcquireOutcome>;
+    renewHeartbeat(args: {
+        service: string;
+        jobType: string;
+        jobId: string;
+        lease: ActiveSlotLease;
+        now: string;
+    }): Promise<ActiveSlotRenewOutcome>;
+    releaseActiveSlot(args: {
+        service: string;
+        jobType: string;
+        jobId: string;
+        lease: ActiveSlotLease;
+        now: string;
+    }): Promise<ActiveSlotReleaseOutcome>;
+};
+export type QueuedJobRemovalOutcome = {
+    kind: "removed";
+    state: JobKeyState;
+} | {
+    kind: "not-found";
+};
+export type QueuedJobRestoreOutcome = {
+    kind: "restored";
+    state: JobKeyState;
+};
+/** Normalizes keyed queue policy defaults when bindings omit normalized values. */
+export declare function normalizeJobKeyPolicy(args: {
+    keyConcurrency: JobKeyConcurrencyBinding;
+    queue?: JobQueuePolicyBinding;
+}): NormalizedJobKeyPolicy;
+/** Derives the display key and stable hash for a keyed job payload. */
+export declare function deriveJobKey(args: {
+    service: string;
+    jobType: string;
+    payload: unknown;
+    template: string[];
+}): Promise<DerivedJobKey>;
+/** Produces a stable SHA-256 hex hash for a display key. */
+export declare function stableKeyHash(value: string): Promise<string>;
+/** Applies keyed admission policy to an existing key state. */
+export declare function reduceAdmission(args: {
+    state: JobKeyState | undefined;
+    derived: DerivedJobKey;
+    request: Omit<JobAdmissionRequest, "payload" | "policy">;
+    policy: NormalizedJobKeyPolicy;
+}): JobAdmissionOutcome;
+/** Restores the replaced queued reservation when replacement lifecycle publish fails. */
+export declare function reduceRestoreReplacedQueuedJob(args: {
+    state: JobKeyState | undefined;
+    derived: DerivedJobKey;
+    replacementJobId: string;
+    replaced: ReplacedQueuedJob;
+    now: string;
+    policy: NormalizedJobKeyPolicy;
+    submissionId?: string;
+}): QueuedJobRestoreOutcome;
+/** Applies active slot acquisition policy to an existing key state. */
+export declare function reduceAcquireActiveSlot(args: {
+    state: JobKeyState | undefined;
+    derived: DerivedJobKey;
+    request: Omit<ActiveSlotAcquireRequest, "payload" | "policy">;
+    policy: NormalizedJobKeyPolicy;
+    slotToken: string;
+}): ActiveSlotAcquireOutcome;
+/** Removes a queued keyed-job reservation when work is terminal before start. */
+export declare function reduceRemoveQueuedJob(args: {
+    state: JobKeyState | undefined;
+    jobId: string;
+    now: string;
+    submissionId?: string;
+}): QueuedJobRemovalOutcome;
+/** Renews a matching active slot lease in key state. */
+export declare function reduceRenewHeartbeat(args: {
+    state: JobKeyState | undefined;
+    jobId: string;
+    slotToken: string;
+    now: string;
+    policy: NormalizedJobKeyPolicy;
+}): ActiveSlotRenewOutcome;
+/** Releases a matching active slot or reports a stale completion. */
+export declare function reduceReleaseActiveSlot(args: {
+    state: JobKeyState | undefined;
+    jobId: string;
+    slotToken: string;
+    now: string;
+}): ActiveSlotReleaseOutcome;
+/** Creates a NATS KV backed coordinator for the Trellis-owned JOBS_KEYS bucket. */
+export declare function createNatsJobKeyCoordinator(nats: NatsConnection, bucketPrefix?: string): JobKeyCoordinator;
+/** Returns whether an unknown value is a well-formed keyed job coordination state. */
+export declare function isJobKeyState(value: unknown): value is JobKeyState;