@corvohq/worker 0.2.0

package/dist/gen/corvo/v1/worker_pb.js

@@ -0,0 +1,133 @@
+// @generated by protoc-gen-es v2.11.0 with parameter "target=ts"
+// @generated from file corvo/v1/worker.proto (package corvo.v1, syntax proto3)
+/* eslint-disable */
+import { fileDesc, messageDesc, serviceDesc } from "@bufbuild/protobuf/codegenv2";
+import { file_google_protobuf_timestamp } from "@bufbuild/protobuf/wkt";
+/**
+ * Describes the file corvo/v1/worker.proto.
+ */
+export const file_corvo_v1_worker = /*@__PURE__*/ fileDesc("ChVjb3J2by92MS93b3JrZXIucHJvdG8SCGNvcnZvLnYxIlsKDkVucXVldWVSZXF1ZXN0Eg0KBXF1ZXVlGAEgASgJEhQKDHBheWxvYWRfanNvbhgCIAEoCRIkCgVhZ2VudBgDIAEoCzIVLmNvcnZvLnYxLkFnZW50Q29uZmlnIkoKD0VucXVldWVSZXNwb25zZRIOCgZqb2JfaWQYASABKAkSDgoGc3RhdHVzGAIgASgJEhcKD3VuaXF1ZV9leGlzdGluZxgDIAEoCCJbCgxGZXRjaFJlcXVlc3QSDgoGcXVldWVzGAEgAygJEhEKCXdvcmtlcl9pZBgCIAEoCRIQCghob3N0bmFtZRgDIAEoCRIWCg5sZWFzZV9kdXJhdGlvbhgEIAEoBSLiAQoNRmV0Y2hSZXNwb25zZRINCgVmb3VuZBgBIAEoCBIOCgZqb2JfaWQYAiABKAkSDQoFcXVldWUYAyABKAkSFAoMcGF5bG9hZF9qc29uGAQgASgJEg8KB2F0dGVtcHQYBSABKAUSEwoLbWF4X3JldHJpZXMYBiABKAUSFgoObGVhc2VfZHVyYXRpb24YByABKAUSFwoPY2hlY2twb2ludF9qc29uGAggASgJEhEKCXRhZ3NfanNvbhgJIAEoCRIjCgVhZ2VudBgKIAEoCzIULmNvcnZvLnYxLkFnZW50U3RhdGUibwoRRmV0Y2hCYXRjaFJlcXVlc3QSDgoGcXVldWVzGAEgAygJEhEKCXdvcmtlcl9pZBgCIAEoCRIQCghob3N0bmFtZRgDIAEoCRIWCg5sZWFzZV9kdXJhdGlvbhgEIAEoBRINCgVjb3VudBgFIAEoBSLTAQoNRmV0Y2hCYXRjaEpvYhIOCgZqb2JfaWQYASABKAkSDQoFcXVldWUYAiABKAkSFAoMcGF5bG9hZF9qc29uGAMgASgJEg8KB2F0dGVtcHQYBCABKAUSEwoLbWF4X3JldHJpZXMYBSABKAUSFgoObGVhc2VfZHVyYXRpb24YBiABKAUSFwoPY2hlY2twb2ludF9qc29uGAcgASgJEhEKCXRhZ3NfanNvbhgIIAEoCRIjCgVhZ2VudBgJIAEoCzIULmNvcnZvLnYxLkFnZW50U3RhdGUiOwoSRmV0Y2hCYXRjaFJlc3BvbnNlEiUKBGpvYnMYASADKAsyFy5jb3J2by52MS5GZXRjaEJhdGNoSm9iIqcBCgtVc2FnZVJlcG9ydBIUCgxpbnB1dF90b2tlbnMYASABKAMSFQoNb3V0cHV0X3Rva2VucxgCIAEoAxIdChVjYWNoZV9jcmVhdGlvbl90b2tlbnMYAyABKAMSGQoRY2FjaGVfcmVhZF90b2tlbnMYBCABKAMSDQoFbW9kZWwYBSABKAkSEAoIcHJvdmlkZXIYBiABKAkSEAoIY29zdF91c2QYByABKAEirwEKCkFja1JlcXVlc3QSDgoGam9iX2lkGAEgASgJEhMKC3Jlc3VsdF9qc29uGAIgASgJEiQKBXVzYWdlGAMgASgLMhUuY29ydm8udjEuVXNhZ2VSZXBvcnQSFwoPY2hlY2twb2ludF9qc29uGAQgASgJEhQKDGFnZW50X3N0YXR1cxgFIAEoCRITCgtob2xkX3JlYXNvbhgGIAEoCRISCgp0cmFjZV9qc29uGAcgASgJIg0KC0Fja1Jlc3BvbnNlIlkKDEFja0JhdGNoSXRlbRIOCgZqb2JfaWQYASABKAkSEwoLcmVzdWx0X2pzb24YAiABKAkSJAoFdXNhZ2UYAyABKAsyFS5jb3J2by52MS5Vc2FnZVJlcG9ydCI4Cg9BY2tCYXRjaFJlcXVlc3QSJQoFaXRlbXMYASADKAsyFi5jb3J2by52MS5BY2tCYXRjaEl0ZW0iIQoQQWNrQmF0Y2hSZXNwb25zZRINCgVhY2tlZBgBIAEoBSLmAQoWTGlmZWN5Y2xlU3RyZWFtUmVxdWVzdBISCgpyZXF1ZXN0X2lkGAEgASgEEg4KBnF1ZXVlcxgCIAMoCRIRCgl3b3JrZXJfaWQYAyABKAkSEAoIaG9zdG5hbWUYBCABKAkSFgoObGVhc2VfZHVyYXRpb24YBSABKAUSEwoLZmV0Y2hfY291bnQYBiABKAUSJAoEYWNrcxgHIAMoCzIWLmNvcnZvLnYxLkFja0JhdGNoSXRlbRIwCghlbnF1ZXVlcxgIIAMoCzIeLmNvcnZvLnYxLkxpZmVjeWNsZUVucXVldWVJdGVtImEKFExpZmVjeWNsZUVucXVldWVJdGVtEg0KBXF1ZXVlGAEgASgJEhQKDHBheWxvYWRfanNvbhgCIAEoCRIkCgVhZ2VudBgDIAEoCzIVLmNvcnZvLnYxLkFnZW50Q29uZmlnIlYKC0FnZW50Q29uZmlnEhYKDm1heF9pdGVyYXRpb25zGAEgASgFEhQKDG1heF9jb3N0X3VzZBgCIAEoARIZChFpdGVyYXRpb25fdGltZW91dBgDIAEoCSKAAQoKQWdlbnRTdGF0ZRIWCg5tYXhfaXRlcmF0aW9ucxgBIAEoBRIUCgxtYXhfY29zdF91c2QYAiABKAESGQoRaXRlcmF0aW9uX3RpbWVvdXQYAyABKAkSEQoJaXRlcmF0aW9uGAQgASgFEhYKDnRvdGFsX2Nvc3RfdXNkGAUgASgBIqEBChdMaWZlY3ljbGVTdHJlYW1SZXNwb25zZRISCgpyZXF1ZXN0X2lkGAEgASgEEiUKBGpvYnMYAiADKAsyFy5jb3J2by52MS5GZXRjaEJhdGNoSm9iEg0KBWFja2VkGAMgASgFEg0KBWVycm9yGAQgASgJEhgKEGVucXVldWVkX2pvYl9pZHMYBSADKAkSEwoLbGVhZGVyX2FkZHIYBiABKAkiPwoLRmFpbFJlcXVlc3QSDgoGam9iX2lkGAEgASgJEg0KBWVycm9yGAIgASgJEhEKCWJhY2t0cmFjZRgDIAEoCSJvCgxGYWlsUmVzcG9uc2USDgoGc3RhdHVzGAEgASgJEjMKD25leHRfYXR0ZW1wdF9hdBgCIAEoCzIaLmdvb2dsZS5wcm90b2J1Zi5UaW1lc3RhbXASGgoSYXR0ZW1wdHNfcmVtYWluaW5nGAMgASgFIoABChJIZWFydGJlYXRKb2JVcGRhdGUSFQoNcHJvZ3Jlc3NfanNvbhgBIAEoCRIXCg9jaGVja3BvaW50X2pzb24YAiABKAkSJAoFdXNhZ2UYAyABKAsyFS5jb3J2by52MS5Vc2FnZVJlcG9ydBIUCgxzdHJlYW1fZGVsdGEYBCABKAkikQEKEEhlYXJ0YmVhdFJlcXVlc3QSMgoEam9icxgBIAMoCzIkLmNvcnZvLnYxLkhlYXJ0YmVhdFJlcXVlc3QuSm9ic0VudHJ5GkkKCUpvYnNFbnRyeRILCgNrZXkYASABKAkSKwoFdmFsdWUYAiABKAsyHC5jb3J2by52MS5IZWFydGJlYXRKb2JVcGRhdGU6AjgBIiYKFEhlYXJ0YmVhdEpvYlJlc3BvbnNlEg4KBnN0YXR1cxgBIAEoCSKVAQoRSGVhcnRiZWF0UmVzcG9uc2USMwoEam9icxgBIAMoCzIlLmNvcnZvLnYxLkhlYXJ0YmVhdFJlc3BvbnNlLkpvYnNFbnRyeRpLCglKb2JzRW50cnkSCwoDa2V5GAEgASgJEi0KBXZhbHVlGAIgASgLMh4uY29ydm8udjEuSGVhcnRiZWF0Sm9iUmVzcG9uc2U6AjgBMrIECg1Xb3JrZXJTZXJ2aWNlEkAKB0VucXVldWUSGC5jb3J2by52MS5FbnF1ZXVlUmVxdWVzdBoZLmNvcnZvLnYxLkVucXVldWVSZXNwb25zZSIAEjoKBUZldGNoEhYuY29ydm8udjEuRmV0Y2hSZXF1ZXN0GhcuY29ydm8udjEuRmV0Y2hSZXNwb25zZSIAEkkKCkZldGNoQmF0Y2gSGy5jb3J2by52MS5GZXRjaEJhdGNoUmVxdWVzdBocLmNvcnZvLnYxLkZldGNoQmF0Y2hSZXNwb25zZSIAEjQKA0FjaxIULmNvcnZvLnYxLkFja1JlcXVlc3QaFS5jb3J2by52MS5BY2tSZXNwb25zZSIAEkMKCEFja0JhdGNoEhkuY29ydm8udjEuQWNrQmF0Y2hSZXF1ZXN0GhouY29ydm8udjEuQWNrQmF0Y2hSZXNwb25zZSIAElwKD1N0cmVhbUxpZmVjeWNsZRIgLmNvcnZvLnYxLkxpZmVjeWNsZVN0cmVhbVJlcXVlc3QaIS5jb3J2by52MS5MaWZlY3ljbGVTdHJlYW1SZXNwb25zZSIAKAEwARI3CgRGYWlsEhUuY29ydm8udjEuRmFpbFJlcXVlc3QaFi5jb3J2by52MS5GYWlsUmVzcG9uc2UiABJGCglIZWFydGJlYXQSGi5jb3J2by52MS5IZWFydGJlYXRSZXF1ZXN0GhsuY29ydm8udjEuSGVhcnRiZWF0UmVzcG9uc2UiAGIGcHJvdG8z", [file_google_protobuf_timestamp]);
+/**
+ * Describes the message corvo.v1.EnqueueRequest.
+ * Use `create(EnqueueRequestSchema)` to create a new message.
+ */
+export const EnqueueRequestSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 0);
+/**
+ * Describes the message corvo.v1.EnqueueResponse.
+ * Use `create(EnqueueResponseSchema)` to create a new message.
+ */
+export const EnqueueResponseSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 1);
+/**
+ * Describes the message corvo.v1.FetchRequest.
+ * Use `create(FetchRequestSchema)` to create a new message.
+ */
+export const FetchRequestSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 2);
+/**
+ * Describes the message corvo.v1.FetchResponse.
+ * Use `create(FetchResponseSchema)` to create a new message.
+ */
+export const FetchResponseSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 3);
+/**
+ * Describes the message corvo.v1.FetchBatchRequest.
+ * Use `create(FetchBatchRequestSchema)` to create a new message.
+ */
+export const FetchBatchRequestSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 4);
+/**
+ * Describes the message corvo.v1.FetchBatchJob.
+ * Use `create(FetchBatchJobSchema)` to create a new message.
+ */
+export const FetchBatchJobSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 5);
+/**
+ * Describes the message corvo.v1.FetchBatchResponse.
+ * Use `create(FetchBatchResponseSchema)` to create a new message.
+ */
+export const FetchBatchResponseSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 6);
+/**
+ * Describes the message corvo.v1.UsageReport.
+ * Use `create(UsageReportSchema)` to create a new message.
+ */
+export const UsageReportSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 7);
+/**
+ * Describes the message corvo.v1.AckRequest.
+ * Use `create(AckRequestSchema)` to create a new message.
+ */
+export const AckRequestSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 8);
+/**
+ * Describes the message corvo.v1.AckResponse.
+ * Use `create(AckResponseSchema)` to create a new message.
+ */
+export const AckResponseSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 9);
+/**
+ * Describes the message corvo.v1.AckBatchItem.
+ * Use `create(AckBatchItemSchema)` to create a new message.
+ */
+export const AckBatchItemSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 10);
+/**
+ * Describes the message corvo.v1.AckBatchRequest.
+ * Use `create(AckBatchRequestSchema)` to create a new message.
+ */
+export const AckBatchRequestSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 11);
+/**
+ * Describes the message corvo.v1.AckBatchResponse.
+ * Use `create(AckBatchResponseSchema)` to create a new message.
+ */
+export const AckBatchResponseSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 12);
+/**
+ * Describes the message corvo.v1.LifecycleStreamRequest.
+ * Use `create(LifecycleStreamRequestSchema)` to create a new message.
+ */
+export const LifecycleStreamRequestSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 13);
+/**
+ * Describes the message corvo.v1.LifecycleEnqueueItem.
+ * Use `create(LifecycleEnqueueItemSchema)` to create a new message.
+ */
+export const LifecycleEnqueueItemSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 14);
+/**
+ * Describes the message corvo.v1.AgentConfig.
+ * Use `create(AgentConfigSchema)` to create a new message.
+ */
+export const AgentConfigSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 15);
+/**
+ * Describes the message corvo.v1.AgentState.
+ * Use `create(AgentStateSchema)` to create a new message.
+ */
+export const AgentStateSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 16);
+/**
+ * Describes the message corvo.v1.LifecycleStreamResponse.
+ * Use `create(LifecycleStreamResponseSchema)` to create a new message.
+ */
+export const LifecycleStreamResponseSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 17);
+/**
+ * Describes the message corvo.v1.FailRequest.
+ * Use `create(FailRequestSchema)` to create a new message.
+ */
+export const FailRequestSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 18);
+/**
+ * Describes the message corvo.v1.FailResponse.
+ * Use `create(FailResponseSchema)` to create a new message.
+ */
+export const FailResponseSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 19);
+/**
+ * Describes the message corvo.v1.HeartbeatJobUpdate.
+ * Use `create(HeartbeatJobUpdateSchema)` to create a new message.
+ */
+export const HeartbeatJobUpdateSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 20);
+/**
+ * Describes the message corvo.v1.HeartbeatRequest.
+ * Use `create(HeartbeatRequestSchema)` to create a new message.
+ */
+export const HeartbeatRequestSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 21);
+/**
+ * Describes the message corvo.v1.HeartbeatJobResponse.
+ * Use `create(HeartbeatJobResponseSchema)` to create a new message.
+ */
+export const HeartbeatJobResponseSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 22);
+/**
+ * Describes the message corvo.v1.HeartbeatResponse.
+ * Use `create(HeartbeatResponseSchema)` to create a new message.
+ */
+export const HeartbeatResponseSchema = /*@__PURE__*/ messageDesc(file_corvo_v1_worker, 23);
+/**
+ * @generated from service corvo.v1.WorkerService
+ */
+export const WorkerService = /*@__PURE__*/ serviceDesc(file_corvo_v1_worker, 0);

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { CorvoClient } from "@corvohq/client";
+export { PayloadTooLargeError } from "@corvohq/client";
+export { RpcClient, ResilientLifecycleStream, LifecycleStream, ErrNotLeader } from "./rpc.js";
+export type FetchedJob = {
+    job_id: string;
+    queue: string;
+    payload: Record<string, unknown>;
+    attempt: number;
+    max_retries: number;
+    lease_duration: number;
+    checkpoint?: Record<string, unknown>;
+    tags?: Record<string, string>;
+    agent?: Record<string, unknown>;
+};
+export type WorkerHandler = (job: FetchedJob, ctx: WorkerJobContext) => Promise<void> | void;
+export type WorkerConfig = {
+    queues: string[];
+    workerID: string;
+    hostname?: string;
+    concurrency?: number;
+    shutdownTimeoutMs?: number;
+    fetchBatchSize?: number;
+    ackBatchSize?: number;
+    useRpc?: boolean;
+};
+export type WorkerJobContext = {
+    isCancelled: () => boolean;
+    checkpoint: (checkpoint: Record<string, unknown>) => Promise<void>;
+    progress: (current: number, total: number, message: string) => Promise<void>;
+};
+export declare class CorvoWorker {
+    private readonly client;
+    private readonly cfg;
+    private readonly handlers;
+    private readonly active;
+    private stopping;
+    private readonly fetchBatchSize;
+    private readonly ackBatchSize;
+    constructor(client: CorvoClient, cfg: WorkerConfig);
+    register(queue: string, handler: WorkerHandler): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private rpcFetchLoop;
+    private rpcHeartbeatLoop;
+    private makeJobContext;
+    private fetchLoop;
+    private flushAcks;
+    private heartbeatLoop;
+    private fetchBatch;
+    private ackBatch;
+    private fetch;
+    private fail;
+    private heartbeat;
+    private request;
+}

package/dist/index.js

@@ -0,0 +1,405 @@
+import { PayloadTooLargeError } from "@corvohq/client";
+export { PayloadTooLargeError } from "@corvohq/client";
+export { RpcClient, ResilientLifecycleStream, LifecycleStream, ErrNotLeader } from "./rpc.js";
+export class CorvoWorker {
+    constructor(client, cfg) {
+        this.handlers = new Map();
+        this.active = new Map();
+        this.stopping = false;
+        this.client = client;
+        this.cfg = {
+            ...cfg,
+            hostname: cfg.hostname ?? "corvo-worker",
+            concurrency: cfg.concurrency ?? 10,
+            shutdownTimeoutMs: cfg.shutdownTimeoutMs ?? 30000,
+            fetchBatchSize: cfg.fetchBatchSize ?? 1,
+            ackBatchSize: cfg.ackBatchSize ?? 1,
+            useRpc: cfg.useRpc ?? false,
+        };
+        this.fetchBatchSize = cfg.fetchBatchSize ?? 1;
+        this.ackBatchSize = cfg.ackBatchSize ?? 1;
+    }
+    register(queue, handler) {
+        this.handlers.set(queue, handler);
+    }
+    async start() {
+        const onSignal = () => {
+            this.stop().catch(() => { });
+        };
+        if (typeof process !== "undefined") {
+            process.on("SIGINT", onSignal);
+            process.on("SIGTERM", onSignal);
+        }
+        if (this.cfg.useRpc) {
+            const { ResilientLifecycleStream, RpcClient } = await import("./rpc.js");
+            const rpcLoop = this.rpcFetchLoop(ResilientLifecycleStream, RpcClient);
+            const heartbeat = this.rpcHeartbeatLoop(RpcClient);
+            await Promise.race([rpcLoop, heartbeat]);
+        }
+        else {
+            const loops = Array.from({ length: this.cfg.concurrency }, () => this.fetchLoop());
+            const heartbeat = this.heartbeatLoop();
+            await Promise.race([Promise.all(loops), heartbeat]);
+        }
+        if (typeof process !== "undefined") {
+            process.off("SIGINT", onSignal);
+            process.off("SIGTERM", onSignal);
+        }
+    }
+    async stop() {
+        if (this.stopping)
+            return;
+        this.stopping = true;
+        const deadline = Date.now() + this.cfg.shutdownTimeoutMs;
+        while (this.active.size > 0 && Date.now() < deadline) {
+            await sleep(100);
+        }
+        for (const [jobID] of this.active) {
+            await this.fail(jobID, "worker_shutdown");
+        }
+    }
+    // -------------------------------------------------------------------------
+    // RPC fetch loop — single bidi stream replaces N HTTP fetch loops
+    // -------------------------------------------------------------------------
+    async rpcFetchLoop(ResilientLifecycleStreamCtor, _RpcClientCtor) {
+        const stream = new ResilientLifecycleStreamCtor(this.client.baseURL, this.client.auth);
+        const pendingAcks = [];
+        const pendingEnqueues = [];
+        let requestId = 0;
+        const jobPromises = new Set();
+        try {
+            while (!this.stopping) {
+                try {
+                    // Drain completed acks
+                    const acks = pendingAcks.splice(0);
+                    const enqueues = pendingEnqueues.splice(0);
+                    const fetchCount = this.cfg.concurrency - this.active.size;
+                    requestId++;
+                    const resp = await stream.exchange({
+                        requestId,
+                        queues: this.cfg.queues,
+                        workerId: this.cfg.workerID,
+                        hostname: this.cfg.hostname,
+                        leaseDuration: 30,
+                        fetchCount: fetchCount > 0 ? fetchCount : 0,
+                        acks: acks.map((a) => ({
+                            jobId: a.jobId,
+                            resultJson: a.resultJson,
+                        })),
+                        enqueues: enqueues.map((e) => ({
+                            queue: e.queue,
+                            payloadJson: e.payloadJson,
+                        })),
+                    });
+                    // Dispatch fetched jobs
+                    for (const protoJob of resp.jobs) {
+                        const job = protoJobToFetched(protoJob);
+                        const handler = this.handlers.get(job.queue);
+                        if (!handler) {
+                            pendingAcks.push({ jobId: job.job_id, resultJson: "{}" });
+                            continue;
+                        }
+                        this.active.set(job.job_id, { cancelled: false });
+                        const ctx = this.makeJobContext(job.job_id);
+                        const p = (async () => {
+                            try {
+                                await handler(job, ctx);
+                                pendingAcks.push({ jobId: job.job_id, resultJson: "{}" });
+                            }
+                            catch (err) {
+                                const message = err instanceof Error ? err.message : String(err);
+                                await this.fail(job.job_id, message);
+                            }
+                            finally {
+                                this.active.delete(job.job_id);
+                            }
+                        })();
+                        jobPromises.add(p);
+                        p.finally(() => jobPromises.delete(p));
+                    }
+                    // If at capacity, wait for at least one job to finish
+                    if (this.active.size >= this.cfg.concurrency && jobPromises.size > 0) {
+                        await Promise.race(jobPromises);
+                    }
+                }
+                catch {
+                    if (!this.stopping)
+                        await sleep(1000);
+                }
+            }
+        }
+        finally {
+            // Wait for in-flight jobs
+            if (jobPromises.size > 0) {
+                await Promise.allSettled(jobPromises);
+            }
+            stream.close();
+        }
+    }
+    async rpcHeartbeatLoop(RpcClientCtor) {
+        const rpcClient = new RpcClientCtor(this.client.baseURL, this.client.auth);
+        while (!this.stopping) {
+            await sleep(15000);
+            if (this.stopping || this.active.size === 0)
+                continue;
+            const jobs = {};
+            for (const [jobID] of this.active) {
+                jobs[jobID] = { progressJson: "", checkpointJson: "", streamDelta: "" };
+            }
+            try {
+                const result = await rpcClient.heartbeat(jobs);
+                for (const [jobID, info] of Object.entries(result)) {
+                    if (info.status === "cancel") {
+                        const state = this.active.get(jobID);
+                        if (state)
+                            state.cancelled = true;
+                    }
+                }
+            }
+            catch {
+                // Best-effort heartbeat.
+            }
+        }
+    }
+    makeJobContext(jobId) {
+        return {
+            isCancelled: () => this.active.get(jobId)?.cancelled === true,
+            checkpoint: async (checkpoint) => {
+                await this.heartbeat({ [jobId]: { checkpoint } });
+            },
+            progress: async (current, total, message) => {
+                await this.heartbeat({
+                    [jobId]: { progress: { current, total, message } },
+                });
+            },
+        };
+    }
+    // -------------------------------------------------------------------------
+    // HTTP fetch loop (original)
+    // -------------------------------------------------------------------------
+    async fetchLoop() {
+        const ackBuffer = [];
+        while (!this.stopping) {
+            try {
+                await this.flushAcks(ackBuffer);
+                let jobs;
+                if (this.fetchBatchSize > 1) {
+                    const result = await this.fetchBatch();
+                    jobs = result ?? [];
+                }
+                else {
+                    const job = await this.fetch();
+                    jobs = job ? [job] : [];
+                }
+                for (const job of jobs) {
+                    const handler = this.handlers.get(job.queue);
+                    if (!handler) {
+                        ackBuffer.push({ job_id: job.job_id });
+                        continue;
+                    }
+                    this.active.set(job.job_id, { cancelled: false });
+                    const ctx = {
+                        isCancelled: () => this.active.get(job.job_id)?.cancelled === true,
+                        checkpoint: async (checkpoint) => {
+                            await this.heartbeat({ [job.job_id]: { checkpoint } });
+                        },
+                        progress: async (current, total, message) => {
+                            await this.heartbeat({
+                                [job.job_id]: { progress: { current, total, message } },
+                            });
+                        },
+                    };
+                    try {
+                        await handler(job, ctx);
+                        ackBuffer.push({ job_id: job.job_id });
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        await this.fail(job.job_id, message);
+                    }
+                    finally {
+                        this.active.delete(job.job_id);
+                    }
+                }
+                await this.flushAcks(ackBuffer);
+            }
+            catch {
+                await sleep(1000);
+            }
+        }
+        // Flush remaining acks on shutdown.
+        await this.flushAcks(ackBuffer, true);
+    }
+    async flushAcks(buffer, force = false) {
+        while (this.ackBatchSize > 1 && buffer.length >= this.ackBatchSize) {
+            const batch = buffer.splice(0, this.ackBatchSize);
+            await this.ackBatch(batch);
+        }
+        if (force && buffer.length > 0 && this.ackBatchSize > 1) {
+            await this.ackBatch(buffer.splice(0));
+        }
+        if (this.ackBatchSize <= 1 && buffer.length > 0) {
+            for (const item of buffer) {
+                await this.client.ack(item.job_id, item.result ?? {});
+            }
+            buffer.length = 0;
+        }
+    }
+    async heartbeatLoop() {
+        while (!this.stopping) {
+            await sleep(15000);
+            if (this.stopping || this.active.size === 0)
+                continue;
+            const jobs = {};
+            for (const [jobID] of this.active)
+                jobs[jobID] = {};
+            try {
+                const result = await this.heartbeat(jobs);
+                for (const [jobID, info] of Object.entries(result.jobs || {})) {
+                    if (info.status === "cancel") {
+                        const state = this.active.get(jobID);
+                        if (state)
+                            state.cancelled = true;
+                    }
+                }
+            }
+            catch {
+                // Best-effort heartbeat.
+            }
+        }
+    }
+    async fetchBatch() {
+        const result = await this.request("/api/v1/fetch/batch", {
+            method: "POST",
+            body: JSON.stringify({
+                queues: this.cfg.queues,
+                worker_id: this.cfg.workerID,
+                hostname: this.cfg.hostname,
+                timeout: 30,
+                count: this.fetchBatchSize,
+            }),
+        });
+        return result.jobs ?? [];
+    }
+    async ackBatch(acks) {
+        await this.request("/api/v1/ack/batch", {
+            method: "POST",
+            body: JSON.stringify({ acks }),
+        });
+    }
+    async fetch() {
+        const job = await this.request("/api/v1/fetch", {
+            method: "POST",
+            body: JSON.stringify({
+                queues: this.cfg.queues,
+                worker_id: this.cfg.workerID,
+                hostname: this.cfg.hostname,
+                timeout: 30,
+            }),
+        });
+        const j = job;
+        if (!j.job_id)
+            return null;
+        return j;
+    }
+    async fail(jobID, error, backtrace = "") {
+        if (this.cfg.useRpc) {
+            try {
+                const { RpcClient } = await import("./rpc.js");
+                const rpc = new RpcClient(this.client.baseURL, this.client.auth);
+                await rpc.fail(jobID, error, backtrace);
+                return;
+            }
+            catch {
+                // Fall through to HTTP
+            }
+        }
+        await this.request(`/api/v1/fail/${encodeURIComponent(jobID)}`, {
+            method: "POST",
+            body: JSON.stringify({ error, backtrace }),
+        });
+    }
+    async heartbeat(jobs) {
+        return this.request("/api/v1/heartbeat", {
+            method: "POST",
+            body: JSON.stringify({ jobs }),
+        });
+    }
+    async request(path, init) {
+        const authHeaders = await this.client.authHeaders();
+        const res = await this.client.fetchImpl(this.client.baseURL + path, {
+            ...init,
+            headers: {
+                "content-type": "application/json",
+                ...authHeaders,
+                ...(init.headers || {}),
+            },
+        });
+        if (!res.ok) {
+            let details = `HTTP ${res.status}`;
+            let code = "";
+            try {
+                const body = (await res.json());
+                if (body.error)
+                    details = body.error;
+                if (body.code)
+                    code = body.code;
+            }
+            catch {
+                // ignore
+            }
+            if (code === "PAYLOAD_TOO_LARGE")
+                throw new PayloadTooLargeError(details);
+            throw new Error(details);
+        }
+        if (res.status === 204)
+            return {};
+        return (await res.json());
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function protoJobToFetched(j) {
+    let payload = {};
+    if (j.payloadJson) {
+        try {
+            payload = JSON.parse(j.payloadJson);
+        }
+        catch {
+            // leave empty
+        }
+    }
+    let checkpoint;
+    if (j.checkpointJson) {
+        try {
+            checkpoint = JSON.parse(j.checkpointJson);
+        }
+        catch {
+            // ignore
+        }
+    }
+    let tags;
+    if (j.tagsJson) {
+        try {
+            tags = JSON.parse(j.tagsJson);
+        }
+        catch {
+            // ignore
+        }
+    }
+    return {
+        job_id: j.jobId,
+        queue: j.queue,
+        payload,
+        attempt: j.attempt,
+        max_retries: j.maxRetries,
+        lease_duration: j.leaseDuration,
+        checkpoint,
+        tags,
+        agent: j.agent,
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/rpc.d.ts

@@ -0,0 +1,78 @@
+import type { AuthOptions } from "@corvohq/client";
+import { type FetchBatchJob } from "./gen/corvo/v1/worker_pb.js";
+export type { FetchBatchJob, HeartbeatJobUpdate } from "./gen/corvo/v1/worker_pb.js";
+export declare class RpcClient {
+    private readonly client;
+    constructor(baseUrl: string, auth?: AuthOptions);
+    enqueue(queue: string, payloadJson: string): Promise<{
+        jobId: string;
+        status: string;
+        uniqueExisting: boolean;
+    }>;
+    fail(jobId: string, error: string, backtrace?: string): Promise<{
+        status: string;
+    }>;
+    heartbeat(jobs: Record<string, {
+        progressJson?: string;
+        checkpointJson?: string;
+        streamDelta?: string;
+    }>): Promise<Record<string, {
+        status: string;
+    }>>;
+    /** Unary call to StreamLifecycle endpoint (Connect JSON protocol). */
+    lifecycleExchange(body: Record<string, unknown>): Promise<LifecycleRawResponse>;
+}
+export interface AckBatchItem {
+    jobId: string;
+    resultJson: string;
+}
+export interface LifecycleEnqueueItem {
+    queue: string;
+    payloadJson: string;
+}
+export declare class ErrNotLeader extends Error {
+    readonly leaderAddr: string;
+    constructor(leaderAddr: string);
+}
+export type LifecycleRequest = {
+    requestId: number;
+    queues: string[];
+    workerId: string;
+    hostname: string;
+    leaseDuration: number;
+    fetchCount: number;
+    acks: AckBatchItem[];
+    enqueues: LifecycleEnqueueItem[];
+};
+export type LifecycleResponse = {
+    requestId: number;
+    jobs: FetchBatchJob[];
+    acked: number;
+    enqueuedJobIds: string[];
+    error: string;
+    leaderAddr: string;
+};
+interface LifecycleRawResponse {
+    requestId?: number;
+    jobs?: FetchBatchJob[];
+    acked?: number;
+    enqueuedJobIds?: string[];
+    error?: string;
+    leaderAddr?: string;
+}
+export declare class LifecycleStream {
+    private readonly baseUrl;
+    private readonly auth;
+    private closed;
+    constructor(baseUrl: string, auth?: AuthOptions);
+    exchange(req: LifecycleRequest): Promise<LifecycleResponse>;
+    close(): void;
+}
+export declare class ResilientLifecycleStream {
+    private baseUrl;
+    private readonly auth;
+    private stream;
+    constructor(baseUrl: string, auth?: AuthOptions);
+    exchange(req: LifecycleRequest): Promise<LifecycleResponse>;
+    close(): void;
+}