@qlever-llc/trellis 0.8.3 → 0.9.0-rc.10

package/src/server/internal_jobs/active-job.ts

@@ -0,0 +1,115 @@
+import type { Job, JobContext, JobLogEntry, JobProgress } from "./types.js";
+
+export class ActiveJobRuntimeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ActiveJobRuntimeError";
+  }
+}
+
+export type ActiveJobRuntimeMetadata = {
+  redeliveryCount: number;
+};
+
+export class JobCancellationToken {
+  readonly #controller = new AbortController();
+  #reason: "none" | "job" | "shutdown" = "none";
+
+  cancel(): void {
+    if (this.#reason === "shutdown") {
+      return;
+    }
+    this.#reason = "job";
+    this.#controller.abort("job");
+  }
+
+  cancelForShutdown(): void {
+    this.#reason = "shutdown";
+    this.#controller.abort("shutdown");
+  }
+
+  get signal(): AbortSignal {
+    return this.#controller.signal;
+  }
+
+  isCancelled(): boolean {
+    return this.#reason !== "none";
+  }
+
+  isJobCancelled(): boolean {
+    return this.#reason === "job";
+  }
+
+  isHostShutdown(): boolean {
+    return this.#reason === "shutdown";
+  }
+}
+
+type ActiveJobHooks = {
+  updateProgress: (progress: JobProgress) => Promise<void>;
+  log: (entry: JobLogEntry) => Promise<void>;
+  heartbeat: () => Promise<void>;
+};
+
+export class ActiveJob<TPayload = unknown, TResult = unknown> {
+  readonly #job: Job<TPayload, TResult>;
+  readonly #cancellation: JobCancellationToken;
+  readonly #hooks: ActiveJobHooks;
+  readonly #metadata: ActiveJobRuntimeMetadata;
+
+  constructor(
+    job: Job<TPayload, TResult>,
+    cancellation: JobCancellationToken,
+    hooks: ActiveJobHooks,
+    metadata: ActiveJobRuntimeMetadata,
+  ) {
+    this.#job = job;
+    this.#cancellation = cancellation;
+    this.#hooks = hooks;
+    this.#metadata = metadata;
+  }
+
+  job(): Readonly<Job<TPayload, TResult>> {
+    return this.#job;
+  }
+
+  context(): Readonly<JobContext> {
+    return this.#job.context;
+  }
+
+  get signal(): AbortSignal {
+    return this.#cancellation.signal;
+  }
+
+  isCancelled(): boolean {
+    return this.#cancellation.isCancelled();
+  }
+
+  cancellationToken(): JobCancellationToken {
+    return this.#cancellation;
+  }
+
+  redeliveryCount(): number {
+    return this.#metadata.redeliveryCount;
+  }
+
+  isRedelivery(): boolean {
+    return this.#metadata.redeliveryCount > 0;
+  }
+
+  heartbeat(): Promise<void> {
+    return this.#hooks.heartbeat();
+  }
+
+  updateProgress(progress: JobProgress): Promise<void> {
+    return this.#hooks.updateProgress(progress);
+  }
+
+  log(level: JobLogEntry["level"], message: string): Promise<void> {
+    return this.#hooks.log({
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+    });
+  }
+}

package/src/server/internal_jobs/bindings.ts

@@ -0,0 +1,26 @@
+export type JobsQueueBinding = {
+  queueType: string;
+  publishPrefix: string;
+  workSubject: string;
+  consumerName: string;
+  payload: { schema: string };
+  result?: { schema: string };
+  maxDeliver: number;
+  backoffMs: number[];
+  ackWaitMs: number;
+  defaultDeadlineMs?: number;
+  progress: boolean;
+  logs: boolean;
+  dlq: boolean;
+  concurrency: number;
+};
+
+export type JobsBinding = {
+  namespace: string;
+  queues: Record<string, JobsQueueBinding>;
+};
+
+export type JobsRuntimeBinding = {
+  jobs: JobsBinding;
+  workStream: string;
+};

package/src/server/internal_jobs/cancellation-registry.ts

@@ -0,0 +1,71 @@
+import type { JobCancellationToken } from "./active-job.js";
+
+export class ActiveJobCancellationGuard {
+  readonly #key: string;
+  readonly #token: JobCancellationToken;
+  readonly #registry: ActiveJobCancellationRegistry;
+  #disposed = false;
+
+  constructor(
+    key: string,
+    token: JobCancellationToken,
+    registry: ActiveJobCancellationRegistry,
+  ) {
+    this.#key = key;
+    this.#token = token;
+    this.#registry = registry;
+  }
+
+  dispose(): void {
+    if (this.#disposed) {
+      return;
+    }
+    this.#disposed = true;
+    this.#registry.unregister(this.#key, this.#token);
+  }
+}
+
+export class ActiveJobCancellationRegistry {
+  readonly #tokens = new Map<string, Set<JobCancellationToken>>();
+  readonly #pending = new Set<string>();
+
+  register(
+    key: string,
+    token: JobCancellationToken,
+  ): ActiveJobCancellationGuard {
+    const tokens = this.#tokens.get(key) ?? new Set<JobCancellationToken>();
+    tokens.add(token);
+    this.#tokens.set(key, tokens);
+    if (this.#pending.delete(key)) {
+      token.cancel();
+    }
+    return new ActiveJobCancellationGuard(key, token, this);
+  }
+
+  cancel(key: string): boolean {
+    const tokens = this.#tokens.get(key);
+    if (!tokens || tokens.size === 0) {
+      this.#pending.add(key);
+      return false;
+    }
+    for (const token of tokens) {
+      token.cancel();
+    }
+    return true;
+  }
+
+  clearPending(key: string): void {
+    this.#pending.delete(key);
+  }
+
+  unregister(key: string, token: JobCancellationToken): void {
+    const tokens = this.#tokens.get(key);
+    if (!tokens) {
+      return;
+    }
+    tokens.delete(token);
+    if (tokens.size === 0) {
+      this.#tokens.delete(key);
+    }
+  }
+}

package/src/server/internal_jobs/heartbeat.ts

@@ -0,0 +1,120 @@
+import type { WorkerHeartbeat } from "./types.js";
+
+type HeartbeatPublisher = {
+  publish(subject: string, payload: Uint8Array): void | Promise<void>;
+};
+
+type WorkerHeartbeatOptions = {
+  service: string;
+  jobType: string;
+  instanceId: string;
+  concurrency?: number;
+  version?: string;
+  timestamp: string;
+};
+
+type WorkerHeartbeatLoopOptions = {
+  publisher: HeartbeatPublisher;
+  service: string;
+  jobType: string;
+  instanceId: string;
+  concurrency?: number;
+  version?: string;
+  intervalMs?: number;
+  nowIso?: () => string;
+};
+
+export class WorkerHeartbeatLoopError extends AggregateError {
+  constructor(errors: unknown[]) {
+    super(errors, "worker heartbeat loop failed");
+    this.name = "WorkerHeartbeatLoopError";
+  }
+}
+
+export function workerHeartbeatSubject(
+  service: string,
+  jobType: string,
+  instanceId: string,
+): string {
+  return `trellis.jobs.workers.${service}.${jobType}.${instanceId}.heartbeat`;
+}
+
+export function newWorkerHeartbeat(
+  options: WorkerHeartbeatOptions,
+): WorkerHeartbeat {
+  return {
+    service: options.service,
+    jobType: options.jobType,
+    instanceId: options.instanceId,
+    ...(options.concurrency !== undefined
+      ? { concurrency: options.concurrency }
+      : {}),
+    ...(options.version !== undefined ? { version: options.version } : {}),
+    timestamp: options.timestamp,
+  };
+}
+
+export async function publishWorkerHeartbeat(
+  publisher: HeartbeatPublisher,
+  heartbeat: WorkerHeartbeat,
+): Promise<void> {
+  await publisher.publish(
+    workerHeartbeatSubject(
+      heartbeat.service,
+      heartbeat.jobType,
+      heartbeat.instanceId,
+    ),
+    new TextEncoder().encode(JSON.stringify(heartbeat)),
+  );
+}
+
+export async function startWorkerHeartbeatLoop(
+  options: WorkerHeartbeatLoopOptions,
+): Promise<{ stop(): Promise<void> }> {
+  const nowIso = options.nowIso ?? (() => new Date().toISOString());
+  const intervalMs = options.intervalMs ?? 30000;
+  const errors: unknown[] = [];
+  const inFlight = new Set<Promise<void>>();
+
+  const publish = async () => {
+    await publishWorkerHeartbeat(
+      options.publisher,
+      newWorkerHeartbeat({
+        service: options.service,
+        jobType: options.jobType,
+        instanceId: options.instanceId,
+        ...(options.concurrency !== undefined
+          ? { concurrency: options.concurrency }
+          : {}),
+        ...(options.version !== undefined ? { version: options.version } : {}),
+        timestamp: nowIso(),
+      }),
+    );
+  };
+
+  const publishSafely = (): void => {
+    const task = publish()
+      .catch((error) => {
+        errors.push(error);
+      })
+      .finally(() => {
+        inFlight.delete(task);
+      });
+    inFlight.add(task);
+  };
+
+  await publish();
+  const timer = setInterval(() => {
+    publishSafely();
+  }, intervalMs);
+
+  return {
+    async stop(): Promise<void> {
+      clearInterval(timer);
+      await Promise.all(inFlight);
+      if (errors.length > 0) {
+        throw new WorkerHeartbeatLoopError(errors);
+      }
+    },
+  };
+}