@superdurable/dex 1.20.0 → 1.23.0

package/README.md

@@ -215,12 +215,15 @@ defaults to the logical CPU count, and `idleStreamsPerQueue` defaults to one.
 Each stream runs one task at a time. When all slots are busy, the Worker rejects
 additional assignments for reassignment. The Worker keeps idle streams on each
 queue even when all slots are busy. After tasks finish, it gracefully closes surplus
-idle streams while preserving readiness. With `F` registered Flow types, the
+idle streams while preserving readiness. The SDK sends an upstream Pong every
+20 seconds while a task runs and stops before its final frame. This interval is
+internal and needs no Worker option. With `F` registered Flow types, the
 steady-state bound after load drops is
-`maxConcurrentTasks + (1 + F) * idleStreamsPerQueue` streams. The transient peak
-during a burst remains bounded by the matching caps. Size both options for
-`matching.maxConcurrentTasksCap` per app Worker ID per matching owner and
-`matching.maxStreams` per Matching instance.
+`maxConcurrentTasks + (1 + F) * idleStreamsPerQueue` streams.
+Allow up to `1 + F` additional streams for 30 seconds after reserve declines.
+The transient peak during a burst remains bounded by the matching caps. Size
+both options for `matching.maxConcurrentTasksCap` per app Worker ID per matching
+owner and `matching.maxStreams` per Matching instance.
 
 The Worker rejects an unregistered Step or RPC by name. Dex retries that task
 on another pull Worker without consuming a Step attempt, including when the
@@ -258,11 +261,11 @@ is at least two, otherwise zero. With the CPU-count default, Steps get one fewer
 slot than before. Set it explicitly to zero to opt out. With one slot and no
 explicit reserve, Worker start logs one warning: RPCs may wait behind
 long-running Steps; use a limit of at least two or set the reserve explicitly.
-Flows must stay responsive; Dex cannot prioritize synchronous RPCs like workflow
-engines prioritize reads. The value must be nonnegative and less than
-`maxConcurrentTasks` after its CPU-count default is resolved; invalid values
-fail construction. RPC and Step handlers count together: WaitFor and Execute
-tasks, including local attempts, are declined with `NO_CAPACITY` when the busy
+Flows must stay responsive because RPCs share Worker task capacity with Steps.
+The value must be nonnegative and less than `maxConcurrentTasks` after its
+CPU-count default is resolved; invalid values fail construction. RPC and Step
+handlers count together. WaitFor and Execute tasks, including local attempts,
+are declined with `NO_CAPACITY` when the busy
 count reaches the task limit minus the reserve. API-direct and transactional
 InvokeWorkerRPC tasks can use the full limit.
 
@@ -274,16 +277,21 @@ A decline lets Dex try another Worker without consuming an attempt. If all
 Workers remain at their Step limit, a Step can wait until the dispatch wait
 expires, then receive `NO_WORKER_AVAILABLE`, consume an attempt, and follow its
 retry policy, as when all Workers are full. Local attempts wait the local
-dispatch wait, then fall back according to their policy. Each queue still keeps
-its configured idle streams; a reserve decline does not close a stream or change
-registration readiness.
+dispatch wait, then fall back according to their policy. A queue that declines
+a Step for reserved RPC capacity keeps one additional idle stream until 30
+seconds after its last decline. Other queues retain their configured count.
+The Worker does not open the extra stream while all task slots are busy. Set
+`idleStreamsPerQueue` to at least two for heavy Step backlogs. A reserve decline
+does not close a stream or change registration readiness.
 
 Each reserve decline records the Flow type through node:util debuglog under
 dex:pull (enable with NODE_DEBUG=dex:pull). Export the cumulative
 `pullReservedRpcDeclines` Worker value to distinguish reserve pressure from
-full-capacity rejections. The count excludes full-capacity rejections and
-unknown names, never resets, and remains available after shutdown. Listening
-Workers return zero.
+full-capacity rejections. The count excludes full-capacity rejections and unknown
+names. It counts decline events, including repeated declines of the same Step
+dispatch while Dex retries it. Read its rate to assess reserve pressure. It never
+resets and remains available after shutdown.
+Listening Workers return zero.
 
 ### Canceling Step executions
 

package/dist/src/gen/dex.d.ts

@@ -36,7 +36,7 @@ export declare enum PollWorkerTaskRejectReason {
 }
 /**
  * Distinguishes no available Worker, a disconnected Worker, and a missing Step or RPC registration.
- * Go Server internals; server-zd does not serve or persist them.
+ * Go persists; server-zd does not.
  */
 export declare enum DispatchTaskErrorReason {
     DISPATCH_TASK_ERROR_REASON_UNSPECIFIED = 0,
@@ -481,6 +481,8 @@ export interface DispatchTaskResponse {
     servedByAppWorkerId: string;
     /** Identifies a Worker that rejected the task's Step type or RPC name. */
     rejectedByAppWorkerId: string;
+    /** Actual queue served; absent on older matching nodes, so consumers may infer it from Worker IDs. */
+    queueSource: PullRoutingSource;
 }
 /**
  * Reports a failure before Dex receives a Worker result.
@@ -1293,6 +1295,7 @@ export interface ServiceErrorResponse {
     originalWorkerErrorType: string;
     originalWorkerErrorStatus: number;
     originalWorkerErrorStackTrace: string;
+    dispatchTaskErrorReason: DispatchTaskErrorReason;
 }
 export interface WorkerErrorResponse {
     detail: string;
@@ -1307,6 +1310,7 @@ export interface InternalActivityError {
     workerGrpcStatus: number;
     workerError: InternalWorkerError | undefined;
     pullRouting: PullRouting | undefined;
+    dispatchTaskErrorReason: DispatchTaskErrorReason;
 }
 export interface InternalWorkerError {
     detail: string;

package/dist/src/gen/dex.js

@@ -44,7 +44,7 @@ export var PollWorkerTaskRejectReason;
 })(PollWorkerTaskRejectReason || (PollWorkerTaskRejectReason = {}));
 /**
  * Distinguishes no available Worker, a disconnected Worker, and a missing Step or RPC registration.
- * Go Server internals; server-zd does not serve or persist them.
+ * Go persists; server-zd does not.
  */
 export var DispatchTaskErrorReason;
 (function (DispatchTaskErrorReason) {
@@ -1337,7 +1337,7 @@ export const DispatchTaskRequest = {
     },
 };
 function createBaseDispatchTaskResponse() {
-    return { output: undefined, servedByAppWorkerId: "", rejectedByAppWorkerId: "" };
+    return { output: undefined, servedByAppWorkerId: "", rejectedByAppWorkerId: "", queueSource: 0 };
 }
 export const DispatchTaskResponse = {
     encode(message, writer = new BinaryWriter()) {
@@ -1370,6 +1370,9 @@ export const DispatchTaskResponse = {
         if (message.rejectedByAppWorkerId !== "") {
             writer.uint32(74).string(message.rejectedByAppWorkerId);
         }
+        if (message.queueSource !== 0) {
+            writer.uint32(80).int32(message.queueSource);
+        }
         return writer;
     },
     decode(input, length) {
@@ -1442,6 +1445,13 @@ export const DispatchTaskResponse = {
                     message.rejectedByAppWorkerId = reader.string();
                     continue;
                 }
+                case 10: {
+                    if (tag !== 80) {
+                        break;
+                    }
+                    message.queueSource = reader.int32();
+                    continue;
+                }
             }
             if ((tag & 7) === 4 || tag === 0) {
                 break;
@@ -1501,6 +1511,7 @@ export const DispatchTaskResponse = {
         }
         message.servedByAppWorkerId = object.servedByAppWorkerId ?? "";
         message.rejectedByAppWorkerId = object.rejectedByAppWorkerId ?? "";
+        message.queueSource = object.queueSource ?? 0;
         return message;
     },
 };
@@ -9720,6 +9731,7 @@ function createBaseServiceErrorResponse() {
         originalWorkerErrorType: "",
         originalWorkerErrorStatus: 0,
         originalWorkerErrorStackTrace: "",
+        dispatchTaskErrorReason: 0,
     };
 }
 export const ServiceErrorResponse = {
@@ -9742,6 +9754,9 @@ export const ServiceErrorResponse = {
         if (message.originalWorkerErrorStackTrace !== "") {
             writer.uint32(50).string(message.originalWorkerErrorStackTrace);
         }
+        if (message.dispatchTaskErrorReason !== 0) {
+            writer.uint32(56).int32(message.dispatchTaskErrorReason);
+        }
         return writer;
     },
     decode(input, length) {
@@ -9793,6 +9808,13 @@ export const ServiceErrorResponse = {
                     message.originalWorkerErrorStackTrace = reader.string();
                     continue;
                 }
+                case 7: {
+                    if (tag !== 56) {
+                        break;
+                    }
+                    message.dispatchTaskErrorReason = reader.int32();
+                    continue;
+                }
             }
             if ((tag & 7) === 4 || tag === 0) {
                 break;
@@ -9812,6 +9834,7 @@ export const ServiceErrorResponse = {
         message.originalWorkerErrorType = object.originalWorkerErrorType ?? "";
         message.originalWorkerErrorStatus = object.originalWorkerErrorStatus ?? 0;
         message.originalWorkerErrorStackTrace = object.originalWorkerErrorStackTrace ?? "";
+        message.dispatchTaskErrorReason = object.dispatchTaskErrorReason ?? 0;
         return message;
     },
 };
@@ -9901,7 +9924,13 @@ export const WorkerErrorResponse = {
     },
 };
 function createBaseInternalActivityError() {
-    return { serverDetail: "", workerGrpcStatus: 0, workerError: undefined, pullRouting: undefined };
+    return {
+        serverDetail: "",
+        workerGrpcStatus: 0,
+        workerError: undefined,
+        pullRouting: undefined,
+        dispatchTaskErrorReason: 0,
+    };
 }
 export const InternalActivityError = {
     encode(message, writer = new BinaryWriter()) {
@@ -9917,6 +9946,9 @@ export const InternalActivityError = {
         if (message.pullRouting !== undefined) {
             PullRouting.encode(message.pullRouting, writer.uint32(34).fork()).join();
         }
+        if (message.dispatchTaskErrorReason !== 0) {
+            writer.uint32(40).int32(message.dispatchTaskErrorReason);
+        }
         return writer;
     },
     decode(input, length) {
@@ -9954,6 +9986,13 @@ export const InternalActivityError = {
                     message.pullRouting = PullRouting.decode(reader, reader.uint32());
                     continue;
                 }
+                case 5: {
+                    if (tag !== 40) {
+                        break;
+                    }
+                    message.dispatchTaskErrorReason = reader.int32();
+                    continue;
+                }
             }
             if ((tag & 7) === 4 || tag === 0) {
                 break;
@@ -9975,6 +10014,7 @@ export const InternalActivityError = {
         message.pullRouting = (object.pullRouting !== undefined && object.pullRouting !== null)
             ? PullRouting.fromPartial(object.pullRouting)
             : undefined;
+        message.dispatchTaskErrorReason = object.dispatchTaskErrorReason ?? 0;
         return message;
     },
 };