@contractspec/lib.jobs 1.57.0 → 1.59.0

package/dist/node/jobs.capability.js

@@ -0,0 +1,28 @@
+// src/jobs.capability.ts
+import { defineCapability, StabilityEnum } from "@contractspec/lib.contracts";
+var JobsCapability = defineCapability({
+  meta: {
+    key: "jobs",
+    version: "1.0.0",
+    kind: "api",
+    stability: StabilityEnum.Experimental,
+    description: "Background job processing",
+    owners: ["@platform.core"],
+    tags: ["jobs", "background", "async"]
+  }
+});
+var SchedulerCapability = defineCapability({
+  meta: {
+    key: "scheduler",
+    version: "1.0.0",
+    kind: "api",
+    stability: StabilityEnum.Experimental,
+    description: "Scheduled job execution",
+    owners: ["@platform.core"],
+    tags: ["scheduler", "cron", "jobs"]
+  }
+});
+export {
+  SchedulerCapability,
+  JobsCapability
+};

package/dist/node/jobs.feature.js

@@ -0,0 +1,46 @@
+// src/jobs.feature.ts
+import { defineFeature } from "@contractspec/lib.contracts";
+var JobsFeature = defineFeature({
+  meta: {
+    key: "jobs",
+    title: "Background Jobs",
+    description: "Background job processing, scheduling, and queue management",
+    domain: "platform",
+    owners: ["@platform.jobs"],
+    tags: ["jobs", "queue", "background", "scheduler"],
+    stability: "stable",
+    version: "1.0.0"
+  },
+  operations: [
+    { key: "jobs.enqueue", version: "1.0.0" },
+    { key: "jobs.cancel", version: "1.0.0" },
+    { key: "jobs.get", version: "1.0.0" },
+    { key: "jobs.stats", version: "1.0.0" },
+    { key: "jobs.schedule.create", version: "1.0.0" },
+    { key: "jobs.schedule.toggle", version: "1.0.0" },
+    { key: "jobs.schedule.list", version: "1.0.0" }
+  ],
+  events: [
+    { key: "job.enqueued", version: "1.0.0" },
+    { key: "job.started", version: "1.0.0" },
+    { key: "job.completed", version: "1.0.0" },
+    { key: "job.failed", version: "1.0.0" },
+    { key: "job.retrying", version: "1.0.0" },
+    { key: "job.dead_lettered", version: "1.0.0" },
+    { key: "job.cancelled", version: "1.0.0" },
+    { key: "scheduler.job_triggered", version: "1.0.0" }
+  ],
+  presentations: [],
+  opToPresentation: [],
+  presentationsTargets: [],
+  capabilities: {
+    provides: [
+      { key: "jobs", version: "1.0.0" },
+      { key: "scheduler", version: "1.0.0" }
+    ],
+    requires: []
+  }
+});
+export {
+  JobsFeature
+};

package/dist/node/queue/gcp-cloud-tasks.js

@@ -0,0 +1,66 @@
+// src/queue/types.ts
+export * from "@contractspec/lib.contracts/jobs/queue";
+import {
+  calculateBackoff,
+  DEFAULT_RETRY_POLICY
+} from "@contractspec/lib.contracts/jobs/queue";
+
+// src/queue/gcp-cloud-tasks.ts
+import { randomUUID } from "node:crypto";
+class GcpCloudTasksQueue {
+  options;
+  handlers = new Map;
+  constructor(options) {
+    this.options = options;
+  }
+  async enqueue(jobType, payload, options = {}) {
+    const now = new Date;
+    const enqueueTime = options.delaySeconds != null ? { seconds: Math.floor(Date.now() / 1000) + options.delaySeconds } : undefined;
+    const body = Buffer.from(JSON.stringify({
+      id: randomUUID(),
+      type: jobType,
+      payload
+    }), "utf-8");
+    await this.options.client.createTask({
+      parent: `projects/${this.options.projectId}/locations/${this.options.location}/queues/${this.options.queue}`,
+      task: {
+        httpRequest: {
+          httpMethod: "POST",
+          url: this.options.resolveUrl(jobType),
+          body,
+          headers: { "Content-Type": "application/json" },
+          oidcToken: this.options.serviceAccountEmail ? { serviceAccountEmail: this.options.serviceAccountEmail } : undefined
+        },
+        scheduleTime: enqueueTime
+      }
+    });
+    return {
+      id: randomUUID(),
+      type: jobType,
+      version: "1.0.0",
+      payload,
+      status: "pending",
+      priority: options.priority ?? 0,
+      attempts: 0,
+      maxRetries: options.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
+      createdAt: now,
+      updatedAt: now,
+      scheduledAt: options.delaySeconds ? new Date(now.getTime() + options.delaySeconds * 1000) : now,
+      dedupeKey: options.dedupeKey,
+      tenantId: options.tenantId,
+      userId: options.userId,
+      traceId: options.traceId,
+      metadata: options.metadata
+    };
+  }
+  register(jobType, handler) {
+    this.handlers.set(jobType, handler);
+  }
+  start() {}
+  async stop() {
+    this.handlers.clear();
+  }
+}
+export {
+  GcpCloudTasksQueue
+};

package/dist/node/queue/gcp-pubsub.js

@@ -0,0 +1,54 @@
+// src/queue/types.ts
+export * from "@contractspec/lib.contracts/jobs/queue";
+import {
+  calculateBackoff,
+  DEFAULT_RETRY_POLICY
+} from "@contractspec/lib.contracts/jobs/queue";
+
+// src/queue/gcp-pubsub.ts
+import { randomUUID } from "node:crypto";
+class GcpPubSubQueue {
+  options;
+  handlers = new Map;
+  constructor(options) {
+    this.options = options;
+  }
+  async enqueue(jobType, payload, options = {}) {
+    const now = new Date;
+    await this.options.client.topic(this.options.topicName).publishMessage({
+      data: Buffer.from(JSON.stringify({
+        id: randomUUID(),
+        type: jobType,
+        payload
+      }), "utf-8")
+    });
+    return {
+      id: randomUUID(),
+      type: jobType,
+      version: "1.0.0",
+      payload,
+      status: "pending",
+      priority: options.priority ?? 0,
+      attempts: 0,
+      maxRetries: options.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
+      createdAt: now,
+      updatedAt: now,
+      scheduledAt: options.delaySeconds ? new Date(now.getTime() + options.delaySeconds * 1000) : now,
+      dedupeKey: options.dedupeKey,
+      tenantId: options.tenantId,
+      userId: options.userId,
+      traceId: options.traceId,
+      metadata: options.metadata
+    };
+  }
+  register(jobType, handler) {
+    this.handlers.set(jobType, handler);
+  }
+  start() {}
+  async stop() {
+    this.handlers.clear();
+  }
+}
+export {
+  GcpPubSubQueue
+};

package/dist/node/queue/index.js

@@ -0,0 +1,478 @@
+// src/queue/register-defined-job.ts
+function registerDefinedJob(queue, def) {
+  const wrapped = async (job) => {
+    const payload = def.schema.parse(job.payload);
+    const typedJob = {
+      ...job,
+      payload
+    };
+    await def.handler(payload, typedJob);
+  };
+  queue.register(def.type, wrapped);
+}
+
+// src/queue/types.ts
+export * from "@contractspec/lib.contracts/jobs/queue";
+import {
+  calculateBackoff,
+  DEFAULT_RETRY_POLICY
+} from "@contractspec/lib.contracts/jobs/queue";
+
+// src/queue/memory-queue.ts
+import { randomUUID } from "node:crypto";
+class MemoryJobQueue {
+  jobs = new Map;
+  handlers = new Map;
+  timer;
+  activeCount = 0;
+  pollIntervalMs;
+  concurrency;
+  retryPolicy;
+  constructor(options = {}) {
+    this.pollIntervalMs = options.pollIntervalMs ?? 200;
+    this.concurrency = options.concurrency ?? 5;
+    this.retryPolicy = options.retryPolicy ?? DEFAULT_RETRY_POLICY;
+  }
+  async enqueue(jobType, payload, options = {}) {
+    if (options.dedupeKey) {
+      const existing = Array.from(this.jobs.values()).find((j) => j.dedupeKey === options.dedupeKey && j.status === "pending");
+      if (existing) {
+        return existing;
+      }
+    }
+    const now = new Date;
+    const scheduledAt = options.delaySeconds ? new Date(now.getTime() + options.delaySeconds * 1000) : now;
+    const job = {
+      id: randomUUID(),
+      type: jobType,
+      version: "1.0.0",
+      payload,
+      status: "pending",
+      priority: options.priority ?? 0,
+      attempts: 0,
+      maxRetries: options.maxRetries ?? this.retryPolicy.maxRetries,
+      createdAt: now,
+      updatedAt: now,
+      scheduledAt,
+      dedupeKey: options.dedupeKey,
+      tenantId: options.tenantId,
+      userId: options.userId,
+      traceId: options.traceId,
+      metadata: options.metadata
+    };
+    if (options.timeoutMs) {
+      job.timeoutAt = new Date(now.getTime() + options.timeoutMs);
+    }
+    this.jobs.set(job.id, job);
+    return job;
+  }
+  register(jobType, handler) {
+    this.handlers.set(jobType, handler);
+  }
+  start() {
+    if (this.timer)
+      return;
+    this.timer = setInterval(() => {
+      this.processNext();
+    }, this.pollIntervalMs);
+  }
+  async stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+    while (this.activeCount > 0) {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+  }
+  async getJob(jobId) {
+    return this.jobs.get(jobId) ?? null;
+  }
+  async cancelJob(jobId) {
+    const job = this.jobs.get(jobId);
+    if (!job || job.status !== "pending") {
+      return false;
+    }
+    job.status = "cancelled";
+    job.updatedAt = new Date;
+    return true;
+  }
+  async getStats() {
+    const stats = {
+      pending: 0,
+      running: 0,
+      completed: 0,
+      failed: 0,
+      deadLetter: 0
+    };
+    for (const job of this.jobs.values()) {
+      switch (job.status) {
+        case "pending":
+          stats.pending++;
+          break;
+        case "running":
+          stats.running++;
+          break;
+        case "completed":
+          stats.completed++;
+          break;
+        case "failed":
+          stats.failed++;
+          break;
+        case "dead_letter":
+          stats.deadLetter++;
+          break;
+      }
+    }
+    return stats;
+  }
+  async processNext() {
+    if (this.activeCount >= this.concurrency)
+      return;
+    const now = new Date;
+    const pendingJobs = Array.from(this.jobs.values()).filter((j) => j.status === "pending" && (!j.scheduledAt || j.scheduledAt <= now)).sort((a, b) => {
+      if (a.priority !== b.priority) {
+        return b.priority - a.priority;
+      }
+      return (a.scheduledAt?.getTime() ?? 0) - (b.scheduledAt?.getTime() ?? 0);
+    });
+    const job = pendingJobs[0];
+    if (!job)
+      return;
+    const handler = this.handlers.get(job.type);
+    if (!handler)
+      return;
+    this.activeCount++;
+    job.status = "running";
+    job.startedAt = new Date;
+    job.updatedAt = new Date;
+    job.attempts += 1;
+    try {
+      const result = await handler(job);
+      job.status = "completed";
+      job.completedAt = new Date;
+      job.result = result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      job.lastError = errorMessage;
+      if (job.attempts >= job.maxRetries) {
+        job.status = "dead_letter";
+      } else {
+        const backoff = calculateBackoff(job.attempts, this.retryPolicy);
+        job.status = "pending";
+        job.scheduledAt = new Date(Date.now() + backoff);
+      }
+    } finally {
+      job.updatedAt = new Date;
+      this.activeCount--;
+    }
+  }
+}
+
+// src/queue/scaleway-sqs-queue.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import {
+  DeleteMessageCommand,
+  ReceiveMessageCommand,
+  SendMessageCommand,
+  SQSClient
+} from "@aws-sdk/client-sqs";
+class ScalewaySqsJobQueue {
+  sqs;
+  queueUrl;
+  waitTimeSeconds;
+  maxNumberOfMessages;
+  visibilityTimeoutSeconds;
+  handlers = new Map;
+  logger;
+  running = false;
+  constructor(config) {
+    this.logger = config.logger;
+    const accessKeyId = config.credentials?.accessKeyId ?? process.env.SCALEWAY_ACCESS_KEY_QUEUE;
+    const secretAccessKey = config.credentials?.secretAccessKey ?? process.env.SCALEWAY_SECRET_KEY_QUEUE;
+    if (!accessKeyId || !secretAccessKey) {
+      throw new Error("Missing SCALEWAY_ACCESS_KEY_QUEUE / SCALEWAY_SECRET_KEY_QUEUE in env");
+    }
+    const region = config.region ?? process.env.SCALEWAY_REGION ?? "par";
+    const endpoint = config.endpoint ?? "https://sqs.mnq.fr-par.scaleway.com";
+    this.sqs = new SQSClient({
+      region,
+      endpoint,
+      credentials: {
+        accessKeyId,
+        secretAccessKey
+      }
+    });
+    this.queueUrl = config.queueUrl;
+    this.waitTimeSeconds = config.waitTimeSeconds ?? 20;
+    this.maxNumberOfMessages = config.maxNumberOfMessages ?? 5;
+    this.visibilityTimeoutSeconds = config.visibilityTimeoutSeconds ?? 60;
+  }
+  async enqueue(jobType, payload, options = {}) {
+    const id = randomUUID2();
+    const now = new Date;
+    const scheduledAt = options.delaySeconds ? new Date(now.getTime() + options.delaySeconds * 1000) : now;
+    const envelope = {
+      id,
+      type: jobType,
+      payload
+    };
+    await this.sqs.send(new SendMessageCommand({
+      QueueUrl: this.queueUrl,
+      MessageBody: JSON.stringify(envelope),
+      DelaySeconds: options.delaySeconds ?? 0
+    }));
+    return {
+      id,
+      type: jobType,
+      version: "1.0.0",
+      payload,
+      status: "pending",
+      priority: options.priority ?? 0,
+      attempts: 0,
+      maxRetries: options.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
+      createdAt: now,
+      updatedAt: now,
+      scheduledAt,
+      dedupeKey: options.dedupeKey,
+      tenantId: options.tenantId,
+      userId: options.userId,
+      traceId: options.traceId,
+      metadata: options.metadata
+    };
+  }
+  register(jobType, handler) {
+    if (this.handlers.has(jobType)) {
+      throw new Error(`Handler already registered for job type "${jobType}"`);
+    }
+    this.handlers.set(jobType, handler);
+  }
+  start() {
+    if (this.running)
+      return;
+    this.running = true;
+    this.pollLoop().catch((error) => {
+      this.logger?.error?.("jobs.queue.scaleway_sqs.poll_loop_fatal", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      this.running = false;
+    });
+  }
+  async stop() {
+    this.running = false;
+  }
+  async pollLoop() {
+    this.logger?.info?.("jobs.queue.scaleway_sqs.started", {
+      queueUrl: this.queueUrl
+    });
+    while (this.running) {
+      try {
+        const res = await this.sqs.send(new ReceiveMessageCommand({
+          QueueUrl: this.queueUrl,
+          MaxNumberOfMessages: this.maxNumberOfMessages,
+          WaitTimeSeconds: this.waitTimeSeconds,
+          VisibilityTimeout: this.visibilityTimeoutSeconds,
+          MessageSystemAttributeNames: ["ApproximateReceiveCount"]
+        }));
+        const messages = res.Messages ?? [];
+        if (messages.length === 0) {
+          continue;
+        }
+        for (const msg of messages) {
+          if (!msg.Body || !msg.ReceiptHandle) {
+            this.logger?.warn?.("jobs.queue.scaleway_sqs.invalid_message", {
+              messageId: msg.MessageId,
+              reason: "missing_body_or_receipt"
+            });
+            continue;
+          }
+          let envelope;
+          try {
+            envelope = JSON.parse(msg.Body);
+          } catch (err) {
+            this.logger?.warn?.("jobs.queue.scaleway_sqs.parse_failed", {
+              messageId: msg.MessageId,
+              error: err instanceof Error ? err.message : String(err)
+            });
+            await this.deleteMessage(msg.ReceiptHandle);
+            continue;
+          }
+          const handler = this.handlers.get(envelope.type);
+          if (!handler) {
+            this.logger?.warn?.("jobs.queue.scaleway_sqs.missing_handler", {
+              jobType: envelope.type,
+              messageId: msg.MessageId
+            });
+            await this.deleteMessage(msg.ReceiptHandle);
+            continue;
+          }
+          const now = new Date;
+          const attempts = parseInt(msg.Attributes?.ApproximateReceiveCount ?? "1", 10);
+          const job = {
+            id: envelope.id,
+            type: envelope.type,
+            version: "1.0.0",
+            payload: envelope.payload,
+            status: "pending",
+            priority: 0,
+            attempts,
+            maxRetries: DEFAULT_RETRY_POLICY.maxRetries,
+            createdAt: now,
+            updatedAt: now
+          };
+          job.status = "running";
+          job.updatedAt = new Date;
+          try {
+            await handler(job);
+            job.status = "completed";
+            job.updatedAt = new Date;
+            await this.deleteMessage(msg.ReceiptHandle);
+          } catch (err) {
+            job.status = "failed";
+            job.lastError = err instanceof Error ? err.message : "Unknown job error";
+            job.updatedAt = new Date;
+            this.logger?.error?.("jobs.queue.scaleway_sqs.job_failed", {
+              jobType: job.type,
+              jobId: job.id,
+              error: err instanceof Error ? err.message : String(err)
+            });
+          }
+        }
+      } catch (err) {
+        this.logger?.error?.("jobs.queue.scaleway_sqs.poll_error", {
+          error: err instanceof Error ? err.message : String(err)
+        });
+        await this.sleep(5000);
+      }
+    }
+    this.logger?.info?.("jobs.queue.scaleway_sqs.stopped", {
+      queueUrl: this.queueUrl
+    });
+  }
+  async deleteMessage(receiptHandle) {
+    try {
+      await this.sqs.send(new DeleteMessageCommand({
+        QueueUrl: this.queueUrl,
+        ReceiptHandle: receiptHandle
+      }));
+    } catch (err) {
+      this.logger?.warn?.("jobs.queue.scaleway_sqs.delete_failed", {
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  async sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+// src/queue/gcp-cloud-tasks.ts
+import { randomUUID as randomUUID3 } from "node:crypto";
+class GcpCloudTasksQueue {
+  options;
+  handlers = new Map;
+  constructor(options) {
+    this.options = options;
+  }
+  async enqueue(jobType, payload, options = {}) {
+    const now = new Date;
+    const enqueueTime = options.delaySeconds != null ? { seconds: Math.floor(Date.now() / 1000) + options.delaySeconds } : undefined;
+    const body = Buffer.from(JSON.stringify({
+      id: randomUUID3(),
+      type: jobType,
+      payload
+    }), "utf-8");
+    await this.options.client.createTask({
+      parent: `projects/${this.options.projectId}/locations/${this.options.location}/queues/${this.options.queue}`,
+      task: {
+        httpRequest: {
+          httpMethod: "POST",
+          url: this.options.resolveUrl(jobType),
+          body,
+          headers: { "Content-Type": "application/json" },
+          oidcToken: this.options.serviceAccountEmail ? { serviceAccountEmail: this.options.serviceAccountEmail } : undefined
+        },
+        scheduleTime: enqueueTime
+      }
+    });
+    return {
+      id: randomUUID3(),
+      type: jobType,
+      version: "1.0.0",
+      payload,
+      status: "pending",
+      priority: options.priority ?? 0,
+      attempts: 0,
+      maxRetries: options.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
+      createdAt: now,
+      updatedAt: now,
+      scheduledAt: options.delaySeconds ? new Date(now.getTime() + options.delaySeconds * 1000) : now,
+      dedupeKey: options.dedupeKey,
+      tenantId: options.tenantId,
+      userId: options.userId,
+      traceId: options.traceId,
+      metadata: options.metadata
+    };
+  }
+  register(jobType, handler) {
+    this.handlers.set(jobType, handler);
+  }
+  start() {}
+  async stop() {
+    this.handlers.clear();
+  }
+}
+
+// src/queue/gcp-pubsub.ts
+import { randomUUID as randomUUID4 } from "node:crypto";
+class GcpPubSubQueue {
+  options;
+  handlers = new Map;
+  constructor(options) {
+    this.options = options;
+  }
+  async enqueue(jobType, payload, options = {}) {
+    const now = new Date;
+    await this.options.client.topic(this.options.topicName).publishMessage({
+      data: Buffer.from(JSON.stringify({
+        id: randomUUID4(),
+        type: jobType,
+        payload
+      }), "utf-8")
+    });
+    return {
+      id: randomUUID4(),
+      type: jobType,
+      version: "1.0.0",
+      payload,
+      status: "pending",
+      priority: options.priority ?? 0,
+      attempts: 0,
+      maxRetries: options.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
+      createdAt: now,
+      updatedAt: now,
+      scheduledAt: options.delaySeconds ? new Date(now.getTime() + options.delaySeconds * 1000) : now,
+      dedupeKey: options.dedupeKey,
+      tenantId: options.tenantId,
+      userId: options.userId,
+      traceId: options.traceId,
+      metadata: options.metadata
+    };
+  }
+  register(jobType, handler) {
+    this.handlers.set(jobType, handler);
+  }
+  start() {}
+  async stop() {
+    this.handlers.clear();
+  }
+}
+export {
+  registerDefinedJob,
+  calculateBackoff,
+  ScalewaySqsJobQueue,
+  MemoryJobQueue,
+  GcpPubSubQueue,
+  GcpCloudTasksQueue,
+  DEFAULT_RETRY_POLICY
+};