@ferricstore/ferricstore 0.1.5 → 0.1.6

package/README.md

@@ -34,7 +34,7 @@ const { FerricStoreClient, JsonCodec } = require("@ferricstore/ferricstore");
 docker run -p 6388:6388 \
   -e FERRICSTORE_PROTECTED_MODE=false \
   -v ferricstore_data:/data \
-  ghcr.io/ferricstore/ferricstore:0.7.2
+  ghcr.io/ferricstore/ferricstore:0.7.5
 ```
 
 ## Cluster-aware client
@@ -171,6 +171,25 @@ for (const job of jobs) {
 }
 ```
 
+FIFO Flow state policy is opt-in per state:
+
+```ts
+await flow.installPolicy("email", {
+  states: {
+    queued: { mode: "fifo" }
+  }
+});
+
+await flow.create("email-3", {
+  partitionKey: "tenant-a:email",
+  payload: Buffer.from("welcome"),
+  state: "queued",
+  type: "email"
+});
+```
+
+FIFO states require a `partitionKey`; priority is for parallel states.
+
 ## FerricStore KV And Data Structures
 
 The same client exposes typed helpers for FerricStore's Redis-compatible store commands:

package/dist/index.cjs

@@ -574,14 +574,64 @@ function commandExec(args) {
   if (args.length === 0) {
     throw new FerricStoreError("command requires at least one argument");
   }
+  const commandArgs = args.slice(1);
+  const payload = {
+    args: commandArgs,
+    command: asText(args[0]).toUpperCase()
+  };
+  if (commandArgs.length >= 2 && commandTokenIs(commandArgs[commandArgs.length - 2], "REQUEST_CONTEXT")) {
+    const requestContext = normalizeRequestContext(commandArgs[commandArgs.length - 1]);
+    payload.args = commandArgs.slice(0, -2);
+    if (requestContext != null) {
+      payload.request_context = requestContext;
+    }
+  }
   return {
     opcode: OPCODES.commandExec,
-    payload: {
-      args: args.slice(1),
-      command: asText(args[0]).toUpperCase()
-    }
+    payload
   };
 }
+function normalizeRequestContext(context) {
+  if (!isPlainObject(context)) {
+    return void 0;
+  }
+  const out = {};
+  const subject = optionalText(context.subject);
+  const tenant = optionalText(context.tenant);
+  const scopes = normalizeRequestContextScopes(context.scopes);
+  if (subject != null) {
+    out.subject = subject;
+  }
+  if (tenant != null) {
+    out.tenant = tenant;
+  }
+  if (scopes.length > 0) {
+    out.scopes = scopes;
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function normalizeRequestContextScopes(scopes) {
+  const values = typeof scopes === "string" || import_node_buffer.Buffer.isBuffer(scopes) || scopes instanceof Uint8Array ? asText(scopes).split(/\s+/u) : Array.isArray(scopes) ? scopes.map((scope) => optionalText(scope)).filter((scope) => scope != null) : [];
+  return [...new Set(values.filter((scope) => scope.length > 0))];
+}
+function optionalText(value) {
+  if (value == null || value === "") {
+    return void 0;
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "bigint" || typeof value === "boolean" || import_node_buffer.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return asText(value);
+  }
+  return void 0;
+}
+function commandTokenIs(value, expected) {
+  if (typeof value === "string") {
+    return value.toUpperCase() === expected;
+  }
+  if (import_node_buffer.Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return asText(value).toUpperCase() === expected;
+  }
+  return false;
+}
 function pipelineCommand(commands) {
   const compact = compactPipelinePayload(commands);
   if (compact != null) {
@@ -4442,6 +4492,59 @@ var FerricStoreClient = class _FerricStoreClient {
     );
     return Array.isArray(response) ? [...response] : [];
   }
+  async invocationDefinitionPut(definition, options = {}) {
+    return normalizeAdminResponse(
+      await this.command(
+        ...commandWithRequestContext(
+          "INVOCATION.DEFINITION.PUT",
+          [jsonArg(definition)],
+          options.requestContext
+        )
+      )
+    );
+  }
+  async invocationDefinitionGet(name, options = {}) {
+    return normalizeAdminResponse(
+      await this.command(
+        ...commandWithRequestContext("INVOCATION.DEFINITION.GET", [name], options.requestContext)
+      )
+    );
+  }
+  async invocationDefinitionList(options = {}) {
+    const response = normalizeAdminResponse(
+      await this.command(
+        ...commandWithRequestContext("INVOCATION.DEFINITION.LIST", [], options.requestContext)
+      )
+    );
+    return Array.isArray(response) ? [...response] : [];
+  }
+  async invocationCreate(name, attrs, options = {}) {
+    const envelope = { attrs };
+    if (options.context != null) {
+      envelope.context = options.context;
+    }
+    if (options.idempotencyKey != null) {
+      envelope.idempotency_key = options.idempotencyKey;
+    }
+    return normalizeAdminResponse(
+      await this.command(
+        ...commandWithRequestContext("INVOCATION.CREATE", [name, jsonArg(envelope)], options.requestContext)
+      )
+    );
+  }
+  async invocationGet(id, options = {}) {
+    return normalizeAdminResponse(
+      await this.command(...commandWithRequestContext("INVOCATION.GET", [id], options.requestContext))
+    );
+  }
+  async invocationPartitionList(name, options = {}) {
+    const args = [name];
+    append(args, "SCOPE", options.scope);
+    const response = normalizeAdminResponse(
+      await this.command(...commandWithRequestContext("INVOCATION.PARTITION.LIST", args, options.requestContext))
+    );
+    return Array.isArray(response) ? [...response] : [];
+  }
   async create(id, options) {
     const currentNowMs = options.nowMs ?? nowMs();
     const args = [
@@ -4474,7 +4577,6 @@ var FerricStoreClient = class _FerricStoreClient {
   async enqueue(id, options) {
     return await this.create(id, {
       ...options,
-      priority: options.priority ?? 0,
       state: options.state ?? "queued"
     });
   }
@@ -4486,7 +4588,6 @@ var FerricStoreClient = class _FerricStoreClient {
       return await this.createMany(options.partitionKey, items, {
         ...options,
         independent: options.independent ?? true,
-        priority: options.priority ?? 0,
         state: options.state ?? "queued"
       });
     }
@@ -4501,7 +4602,6 @@ var FerricStoreClient = class _FerricStoreClient {
       const response = await this.createMany(bucket, groupItems, {
         ...options,
         independent: options.independent ?? true,
-        priority: options.priority ?? 0,
         state: options.state ?? "queued"
       });
       const expanded = expandManyResponse(response, indexedItems.length);
@@ -4654,8 +4754,7 @@ var FerricStoreClient = class _FerricStoreClient {
       ...options,
       includeState: options.includeState ?? false,
       jobOnly: true,
-      limit: options.limit ?? 100,
-      priority: options.priority ?? 0
+      limit: options.limit ?? 100
     });
   }
   async reclaim(type, options) {
@@ -5006,9 +5105,14 @@ var FerricStoreClient = class _FerricStoreClient {
     const args = ["FLOW.POLICY.SET", type];
     append(args, "INDEXED_STATE_META", options.indexedStateMeta);
     append(args, "STATE", options.state);
+    appendPolicyMode(args, options.state, options.mode);
     if (options.retry != null) {
       appendRetryPolicy(args, options.retry);
     }
+    for (const [state, policy] of Object.entries(options.states ?? {})) {
+      args.push("STATE", state);
+      appendFlowStatePolicy(args, policy);
+    }
     append(args, "RETENTION_TTL_MS", options.retentionTtlMs);
     return await this.command(...args);
   }
@@ -5388,6 +5492,16 @@ function appendSearchStateMeta(args, state, stateMeta) {
 function normalizeAdminResponse(value) {
   return normalizeRefMeta(value);
 }
+function jsonArg(value) {
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+function commandWithRequestContext(command, args, requestContext) {
+  const commandArgs = [command, ...args];
+  if (requestContext != null) {
+    commandArgs.push("REQUEST_CONTEXT", requestContext);
+  }
+  return commandArgs;
+}
 function infoText(value) {
   if (typeof value === "string" || Buffer.isBuffer(value)) {
     return text(value);
@@ -5419,6 +5533,19 @@ function managementPairArgs(pairs2) {
   }
   return args;
 }
+function appendFlowStatePolicy(args, policy) {
+  if (isFlowStatePolicy(policy)) {
+    appendPolicyMode(args, "state", policy.mode);
+    if (policy.retry != null) {
+      appendRetryPolicy(args, policy.retry);
+    }
+    return;
+  }
+  appendRetryPolicy(args, policy);
+}
+function isFlowStatePolicy(policy) {
+  return typeof policy === "object" && policy != null && ("mode" in policy || "retry" in policy);
+}
 function ruleArgs(rules) {
   return typeof rules === "string" ? [rules] : [...rules];
 }
@@ -5511,6 +5638,24 @@ function appendRetryPolicy(args, policy) {
   append(args, "JITTER_PCT", policy.jitterPct);
   append(args, "EXHAUSTED_TO", policy.exhaustedTo);
 }
+function appendPolicyMode(args, state, mode) {
+  if (mode == null) {
+    return;
+  }
+  if (state == null) {
+    throw new Error("policy mode requires state");
+  }
+  switch (mode) {
+    case "fifo":
+      args.push("MODE", "FIFO");
+      return;
+    case "parallel":
+      args.push("MODE", "PARALLEL");
+      return;
+    default:
+      throw new Error("policy mode must be 'fifo' or 'parallel'");
+  }
+}
 function appendPayloadRead(args, payload, maxBytes) {
   if (payload === false) {
     args.push("NOPAYLOAD");
@@ -5975,6 +6120,7 @@ var Workflow = class {
       exceptionPolicy: normalizeExceptionPolicy(options.exceptionPolicy),
       handler,
       leaseMs: options.leaseMs ?? 3e4,
+      ...options.mode == null ? {} : { mode: normalizeStateMode(options.mode) },
       name,
       returnRecord: options.returnRecord ?? false,
       valueMaxBytes: options.valueMaxBytes ?? this.valueConfig.valueMaxBytes,
@@ -6009,6 +6155,21 @@ var Workflow = class {
   worker(options = {}) {
     return new WorkflowWorker(this, options);
   }
+  async installPolicy(options = {}) {
+    const states = {};
+    for (const registration of this.states.values()) {
+      if (registration.mode != null || registration.retryPolicy != null) {
+        states[registration.name] = {
+          ...registration.mode == null ? {} : { mode: registration.mode },
+          ...registration.retryPolicy == null ? {} : { retry: registration.retryPolicy }
+        };
+      }
+    }
+    return await this.client.installPolicy(this.type, {
+      ...options,
+      states
+    });
+  }
   stateNames() {
     return [...this.states.keys()];
   }
@@ -6269,13 +6430,15 @@ var WorkflowWorker = class {
   }
   async applyJob(job, registration) {
     const ctx = new WorkflowContext(this.workflow, job, registration.name);
+    let outcome;
     try {
       const value = await registration.handler(ctx);
-      const outcome = isOutcome(value) ? value : complete({ result: value });
-      await applyOutcome(this.workflow.client, ctx, outcome, registration.returnRecord);
+      outcome = isOutcome(value) ? value : complete({ result: value });
     } catch (error) {
       await this.applyHandlerError(ctx, registration, error);
+      return;
     }
+    await applyOutcome(this.workflow.client, ctx, outcome, registration.returnRecord);
   }
   async applyHandlerError(ctx, registration, error) {
     const policy = this.options.exceptionPolicy ?? registration.exceptionPolicy;
@@ -6306,6 +6469,7 @@ async function applyOutcome(client, ctx, outcome, returnRecord) {
   }
 }
 async function applyTransition(client, ctx, outcome, returnRecord) {
+  validateTransitionPolicy(ctx, outcome);
   await client.transition(ctx.id, {
     dropValues: outcome.dropValues,
     fencingToken: ctx.fencingToken,
@@ -6323,6 +6487,12 @@ async function applyTransition(client, ctx, outcome, returnRecord) {
     values: outcome.values
   });
 }
+function validateTransitionPolicy(ctx, outcome) {
+  const target = ctx.workflow.stateRegistration(outcome.toState);
+  if (target?.mode === "fifo" && outcome.priority != null) {
+    throw new Error("priority is not supported for fifo state");
+  }
+}
 async function applyComplete(client, ctx, outcome, returnRecord) {
   await client.complete(ctx.id, {
     dropValues: outcome.dropValues,
@@ -6381,6 +6551,12 @@ function errorToPayload(error) {
   }
   return error;
 }
+function normalizeStateMode(mode) {
+  if (mode === "fifo" || mode === "parallel") {
+    return mode;
+  }
+  throw new Error("state mode must be 'fifo' or 'parallel'");
+}
 function valueRefToString(value) {
   if (typeof value === "string") {
     return value;