@arbitro/client 0.4.1 → 0.5.2

package/dist/index.js

@@ -115,6 +115,7 @@ var init_constants = __esm({
       Action2[Action2["ListStreams"] = 1028] = "ListStreams";
       Action2[Action2["PurgeStream"] = 1029] = "PurgeStream";
       Action2[Action2["DrainSubject"] = 1030] = "DrainSubject";
+      Action2[Action2["DeleteMessage"] = 1031] = "DeleteMessage";
       Action2[Action2["CreateConsumer"] = 1281] = "CreateConsumer";
       Action2[Action2["DeleteConsumer"] = 1282] = "DeleteConsumer";
       Action2[Action2["GetConsumer"] = 1283] = "GetConsumer";
@@ -267,6 +268,7 @@ __export(index_exports, {
   AckPolicy: () => AckPolicy,
   ArbitroClient: () => ArbitroClient,
   ArbitroError: () => ArbitroError,
+  COMPENSATION_BIT: () => COMPENSATION_BIT,
   Codec: () => Codec,
   Consumer: () => Consumer,
   CronBuilder: () => CronBuilder,
@@ -280,6 +282,8 @@ __export(index_exports, {
   StringCodec: () => StringCodec,
   Subscription: () => Subscription,
   Topic: () => Topic,
+  WorkflowBuilder: () => WorkflowBuilder,
+  WorkflowHandle: () => WorkflowHandle,
   decodeJson: () => decodeJson,
   decodeString: () => decodeString,
   encodeJson: () => encodeJson,
@@ -559,6 +563,7 @@ var packDrainSubject = (seq, name, subject) => packCold2(1030 /* DrainSubject */
   name: bytesArr(name),
   subject: bytesArr(subject)
 });
+var packDeleteMessage = (seq, name, msgSeq) => packCold2(1031 /* DeleteMessage */, seq, { name: bytesArr(name), seq: Number(msgSeq) });
 var packListStreams = (seq, offset = 0, limit = 1e3) => packCold2(1028 /* ListStreams */, seq, { offset: offset >>> 0, limit: limit >>> 0 });
 function packCreateConsumer(seq, opts) {
   const limits = (opts.subjectLimits ?? []).map((l) => ({
@@ -1222,6 +1227,10 @@ var Consumer = class {
     }
     return this.client.getPending(this.streamName, this.name);
   }
+  /** Tombstone a single message by seq. Returns true if found. */
+  deleteMessage(seq) {
+    return this.client.deleteMessage(this.streamName, seq);
+  }
   subscribe(codecOrCb, cbOrOpts, opts) {
     if (!codecOrCb || typeof codecOrCb === "function") {
       return this.client.subscribe(
@@ -1311,6 +1320,10 @@ var Stream = class {
   request(subject, data, timeoutMs) {
     return this.client.request(this.name, subject, data, timeoutMs);
   }
+  /** Tombstone a single message by seq. Returns true if found. */
+  deleteMessage(seq) {
+    return this.client.deleteMessage(this.name, seq);
+  }
   // ── Context factories ───────────────────────────────────────────────────
   consumer(overrides) {
     const config = {
@@ -1698,6 +1711,19 @@ var ArbitroClient = class {
     );
     return Number(refSeq);
   }
+  /**
+   * Tombstone a single message by sequence number.
+   *
+   * The broker marks the entry as deleted — it will never be delivered
+   * to any consumer. Returns `true` if the message was found and
+   * tombstoned, `false` if not found or already tombstoned.
+   */
+  async deleteMessage(streamName, seq) {
+    const refSeq = await this.conn.sendExpectReply(
+      packDeleteMessage(this.conn.nextSeq(), Buffer.from(streamName), seq)
+    );
+    return refSeq > 0n;
+  }
   // ── Consumer management ───────────────────────────────────────────────────
   async createConsumer(streamName, config) {
     const consumerId = await this.createConsumerRaw(streamName, config);
@@ -1706,7 +1732,7 @@ var ArbitroClient = class {
   async createConsumerRaw(streamName, config) {
     const sid = await this.resolveStreamId(streamName);
     const name = Buffer.from(config.name ?? streamName);
-    const group = Buffer.from(config.name ?? streamName);
+    const group = Buffer.from(config.group ?? config.name ?? streamName);
     const filter = Buffer.from(config.filter ?? "");
     const ackPolicyByte = config.ackPolicy === "none" /* None */ ? 0 : 1;
     const opts = {
@@ -1916,6 +1942,257 @@ function streamId(name) {
   return h >>> 0;
 }
 
+// src/workflow/task.ts
+var TASK_HEADER = 7;
+var COMPENSATION_BIT = 32768;
+function encodeTask(instanceId, stepIndex, attempt, context) {
+  const buf = Buffer.allocUnsafe(TASK_HEADER + context.length);
+  buf.writeUInt32LE(instanceId, 0);
+  buf.writeUInt16LE(stepIndex, 4);
+  buf[6] = attempt;
+  context.copy(buf, TASK_HEADER);
+  return buf;
+}
+function decodeTask(payload) {
+  if (payload.length < TASK_HEADER) return void 0;
+  return {
+    instanceId: payload.readUInt32LE(0),
+    stepIndex: payload.readUInt16LE(4),
+    attempt: payload[6],
+    context: payload.subarray(TASK_HEADER)
+  };
+}
+
+// src/workflow/handle.ts
+var nextInstanceId = 1;
+function allocInstanceId() {
+  return nextInstanceId++;
+}
+var WorkflowHandle = class {
+  constructor(workflowName, taskStreamName, dlqStreamName, sub, triggerSub) {
+    this.workflowName = workflowName;
+    this.taskStreamName = taskStreamName;
+    this.dlqStreamName = dlqStreamName;
+    this.sub = sub;
+    this.triggerSub = triggerSub;
+  }
+  get name() {
+    return this.workflowName;
+  }
+  get taskStream() {
+    return this.taskStreamName;
+  }
+  get dlqStream() {
+    return this.dlqStreamName;
+  }
+  async trigger(client, context) {
+    const instanceId = allocInstanceId();
+    const msgId = `wf:${instanceId}:0:0`;
+    const subject = `_wf.${this.workflowName}.step.0`;
+    const task = encodeTask(instanceId, 0, 0, context);
+    await client.publish(this.taskStreamName, subject, task, { msgId });
+    return instanceId;
+  }
+};
+
+// src/workflow/processor.ts
+async function processMessage(cfg, msg) {
+  const task = decodeTask(msg.data());
+  if (!task) {
+    msg.ack();
+    return;
+  }
+  if (task.context.length > cfg.maxContextSize) {
+    msg.ack();
+    return;
+  }
+  const isCompensation = (task.stepIndex & COMPENSATION_BIT) !== 0;
+  if (isCompensation) {
+    await runCompensation(cfg, msg, task);
+    return;
+  }
+  if (task.stepIndex >= cfg.steps.length) {
+    msg.ack();
+    return;
+  }
+  await runStep(cfg, msg, task);
+}
+async function runCompensation(cfg, msg, task) {
+  const idx = task.stepIndex & ~COMPENSATION_BIT;
+  const comp = cfg.steps[idx]?.compensation;
+  if (comp) {
+    try {
+      await comp({ name: cfg.name, instanceId: task.instanceId, stepIndex: idx, attempt: task.attempt, context: task.context });
+    } catch {
+    }
+  }
+  msg.ack();
+}
+async function runStep(cfg, msg, task) {
+  const handler = cfg.steps[task.stepIndex].handler;
+  try {
+    const result = await handler({
+      name: cfg.name,
+      instanceId: task.instanceId,
+      stepIndex: task.stepIndex,
+      attempt: task.attempt,
+      context: task.context
+    });
+    if (result.context.length > cfg.maxContextSize) {
+      msg.nack();
+      return;
+    }
+    await advance(cfg, msg, task, result);
+  } catch (err) {
+    await onFailure(cfg, msg, task, err);
+  }
+}
+async function advance(cfg, msg, task, result) {
+  const nextStep = task.stepIndex + 1;
+  if (nextStep < cfg.steps.length) {
+    const msgId = `wf:${task.instanceId}:${nextStep}:0`;
+    const subject = `_wf.${cfg.name}.step.${nextStep}`;
+    const buf = encodeTask(task.instanceId, nextStep, 0, result.context);
+    await cfg.client.publish(cfg.taskStreamName, subject, buf, { msgId });
+  }
+  msg.ack();
+}
+async function onFailure(cfg, msg, task, err) {
+  if (task.attempt >= cfg.maxRetries) {
+    await publishDlq(cfg, task, err);
+    await publishCompensations(cfg, task);
+    msg.ack();
+  } else {
+    msg.nack();
+  }
+}
+async function publishDlq(cfg, task, err) {
+  const dlqSubject = `_wf.${cfg.name}.dlq.${task.stepIndex}`;
+  const errBytes = Buffer.from(String(err));
+  const buf = Buffer.allocUnsafe(7 + 4 + errBytes.length + task.context.length);
+  buf.writeUInt32LE(task.instanceId, 0);
+  buf.writeUInt16LE(task.stepIndex, 4);
+  buf[6] = task.attempt;
+  buf.writeUInt32LE(errBytes.length, 7);
+  errBytes.copy(buf, 11);
+  task.context.copy(buf, 11 + errBytes.length);
+  const msgId = `wf:${task.instanceId}:dlq:${task.stepIndex}`;
+  await cfg.client.publish(cfg.dlqStreamName, dlqSubject, buf, { msgId }).catch(() => {
+  });
+}
+async function publishCompensations(cfg, task) {
+  for (let i = task.stepIndex - 1; i >= 0; i--) {
+    const compStep = COMPENSATION_BIT | i;
+    const subject = `_wf.${cfg.name}.compensate.${i}`;
+    const buf = encodeTask(task.instanceId, compStep, 0, task.context);
+    const msgId = `wf:${task.instanceId}:comp:${i}`;
+    await cfg.client.publish(cfg.taskStreamName, subject, buf, { msgId }).catch(() => {
+    });
+  }
+}
+
+// src/workflow/workflow.ts
+var nextWorkerUid = 1;
+var WorkflowBuilder = class {
+  constructor(client, workflowName) {
+    this.client = client;
+    this.workflowName = workflowName;
+  }
+  triggerSubject;
+  triggerStreamName;
+  steps = [];
+  ackWaitMs = 3e4;
+  maxInflightVal = 10;
+  maxRetriesVal = 3;
+  maxContextSizeVal = 256 * 1024;
+  trigger(subject) {
+    this.triggerSubject = subject;
+    return this;
+  }
+  triggerStream(streamName) {
+    this.triggerStreamName = streamName;
+    return this;
+  }
+  step(name, handler) {
+    this.steps.push({ name, handler, compensation: void 0 });
+    return this;
+  }
+  /** Compensation handler for the most recently added step. */
+  compensate(_stepName, handler) {
+    const last = this.steps[this.steps.length - 1];
+    if (last) last.compensation = handler;
+    return this;
+  }
+  ackWait(ms) {
+    this.ackWaitMs = ms;
+    return this;
+  }
+  inflight(n) {
+    this.maxInflightVal = n;
+    return this;
+  }
+  maxRetries(n) {
+    this.maxRetriesVal = n;
+    return this;
+  }
+  maxContextSize(bytes) {
+    this.maxContextSizeVal = bytes;
+    return this;
+  }
+  async start() {
+    if (!this.triggerSubject) throw new Error("trigger subject required");
+    if (this.steps.length === 0) throw new Error("at least one step required");
+    const name = this.workflowName;
+    const taskStream = `_wf.${name}.tasks`;
+    const taskSubject = `_wf.${name}.>`;
+    const dlqStream = `_wf.${name}.dlq`;
+    const dlqSubject = `_wf.${name}.dlq.>`;
+    await this.client.upsertStream(taskStream, { subjectFilter: taskSubject, idempotencyWindowMs: 3e5 });
+    await this.client.upsertStream(dlqStream, { subjectFilter: dlqSubject });
+    const cfg = {
+      client: this.client,
+      name,
+      taskStreamName: taskStream,
+      dlqStreamName: dlqStream,
+      steps: this.steps,
+      maxContextSize: this.maxContextSizeVal,
+      maxRetries: this.maxRetriesVal
+    };
+    const sub = await this.subscribeWorker(cfg, taskStream, taskSubject);
+    const triggerSub = await this.subscribeTrigger(taskStream, name);
+    return new WorkflowHandle(name, taskStream, dlqStream, sub, triggerSub);
+  }
+  async subscribeWorker(cfg, taskStream, taskSubject) {
+    const uid = nextWorkerUid++;
+    return this.client.subscribe(taskStream, {
+      name: `_wf_${cfg.name}_w${uid}`,
+      group: `_wf_${cfg.name}_workers`,
+      filter: taskSubject,
+      ackPolicy: "explicit" /* Explicit */,
+      ackWaitMs: this.ackWaitMs,
+      maxAckPending: this.maxInflightVal
+    }, (msg) => {
+      void processMessage(cfg, msg);
+    });
+  }
+  async subscribeTrigger(taskStream, name) {
+    if (!this.triggerSubject || !this.triggerStreamName) return void 0;
+    const subject = this.triggerSubject;
+    return this.client.subscribe(this.triggerStreamName, {
+      name: `_wf_${name}_trigger`,
+      filter: subject,
+      ackPolicy: "explicit" /* Explicit */,
+      ackWaitMs: this.ackWaitMs,
+      maxAckPending: 1
+    }, async (msg) => {
+      const id = allocInstanceId();
+      const taskBuf = encodeTask(id, 0, 0, msg.data());
+      await this.client.publish(taskStream, `_wf.${name}.step.0`, taskBuf, { msgId: `wf:${id}:0:0` });
+      msg.ack();
+    });
+  }
+};
+
 // src/utils/zod.ts
 var import_msgpackr2 = require("msgpackr");
 var packr = new import_msgpackr2.Packr({ structuredClone: false, useRecords: false });
@@ -1937,6 +2214,7 @@ function zodCodec(zodSchema) {
   AckPolicy,
   ArbitroClient,
   ArbitroError,
+  COMPENSATION_BIT,
   Codec,
   Consumer,
   CronBuilder,
@@ -1950,6 +2228,8 @@ function zodCodec(zodSchema) {
   StringCodec,
   Subscription,
   Topic,
+  WorkflowBuilder,
+  WorkflowHandle,
   decodeJson,
   decodeString,
   encodeJson,