@superdurable/dex 1.14.0 → 1.15.0

package/README.md

@@ -214,9 +214,13 @@ Flow type names must be unique within one Dex server. `maxConcurrentTasks`
 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, so it can hold up to
-`(1 + F) * (idleStreamsPerQueue + maxConcurrentTasks)` streams, where `F` is the
-number of registered Flow types. Size both options for the server's stream cap.
+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
+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.
 
 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
@@ -246,6 +250,41 @@ remaining drain deadline. A handler that ignores cancellation can delay shutdown
 `StepOptions.waitForMethodTimeoutMs` and `executeMethodTimeoutMs` bound the two
 handler calls. Timer and channel conditions determine how long a Step waits.
 
+#### Reserved RPC capacity
+
+Set `reservedRpcTasks` when synchronous RPC latency must stay responsive behind
+long-running Steps. When unset, it reserves one slot if the resolved task limit
+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
+count reaches the task limit minus the reserve. API-direct and transactional
+InvokeWorkerRPC tasks can use the full limit.
+
+```ts
+const pull: PullWorkerOptions = { maxConcurrentTasks: 8, reservedRpcTasks: 2 };
+```
+
+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.
+
+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.
+
 ### Canceling Step executions
 
 A successful Step can cancel queued or active executions while continuing with

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

@@ -117,6 +117,12 @@ export declare enum PendingStepMethodPhase {
     PENDING_STEP_METHOD_PHASE_STARTED = 2,
     UNRECOGNIZED = -1
 }
+export declare enum PullRoutingSource {
+    PULL_ROUTING_SOURCE_UNSPECIFIED = 0,
+    PULL_ROUTING_SOURCE_STICKY_QUEUE = 1,
+    PULL_ROUTING_SOURCE_FLOW_TYPE_QUEUE = 2,
+    UNRECOGNIZED = -1
+}
 export declare enum ActiveStepPhase {
     ACTIVE_STEP_PHASE_UNSPECIFIED = 0,
     ACTIVE_STEP_PHASE_ACTIVE = 1,
@@ -897,6 +903,7 @@ export interface FlowContinuedStart {
     };
     attributes: KV[];
     completedSteps: StepCompletionOutput[];
+    stickyAppWorkerId: string;
 }
 export interface FlowContinuedStart_PendingChannelMessagesEntry {
     key: string;
@@ -908,6 +915,7 @@ export interface FlowClosedHistoryEvent {
     errorType: FlowErrorType;
     errorMessage: string;
     continuedToRunId: string;
+    stickyAppWorkerId: string;
 }
 /** StepMethodPendingEvent describes a regular Step activity unresolved at flow closure. */
 export interface StepMethodPendingEvent {
@@ -919,6 +927,7 @@ export interface StepMethodFailure {
     backendError: string;
     details: ServiceErrorResponse | undefined;
     attempt: number;
+    pullRouting: PullRouting | undefined;
 }
 export interface StepMethodOptions {
     timeoutSeconds: number;
@@ -932,6 +941,11 @@ export interface StepMethodEventInput {
     attributes: KV[];
     stepExecutionLocals: KV[];
 }
+export interface PullRouting {
+    stickyAppWorkerId: string;
+    servedByAppWorkerId: string;
+    source: PullRoutingSource;
+}
 export interface StepMethodEventContext {
     stepExecutionId: string;
     fromStepExecutionId: string;
@@ -942,6 +956,7 @@ export interface StepMethodEventContext {
     duration: Duration | undefined;
     methodOptions: StepMethodOptions | undefined;
     lastFailureInfo: StepMethodFailure | undefined;
+    pullRouting: PullRouting | undefined;
 }
 export interface StepWaitForCompletedOutput {
     waitForCondition: WaitingCondition | undefined;
@@ -996,6 +1011,7 @@ export interface RpcExecutionCompletedEvent {
     publishToChannel: ChannelMessage[];
     isSetAttributeApi: boolean;
     deleteFromChannel: ChannelMessageDeletion[];
+    servedByAppWorkerId: string;
 }
 export interface ChannelExternalPublishEvent {
     messages: ChannelMessage[];
@@ -1024,6 +1040,8 @@ export interface ActiveStepExecutionState {
     stepExecutionLocals: KV[];
     timers: TimerInfo[];
     lastFailureInfo: StepMethodFailure | undefined;
+    waitForPullRouting: PullRouting | undefined;
+    executePullRouting: PullRouting | undefined;
 }
 export interface GetFlowStateRequest {
     flowId: string;
@@ -1038,6 +1056,7 @@ export interface GetFlowStateResponse {
         [key: string]: ChannelValues;
     };
     completedSteps: StepCompletionOutput[];
+    stickyAppWorkerId: string;
 }
 export interface GetFlowStateResponse_PendingChannelMessagesEntry {
     key: string;
@@ -1182,6 +1201,7 @@ export interface InternalActivityError {
     serverDetail: string;
     workerGrpcStatus: number;
     workerError: InternalWorkerError | undefined;
+    pullRouting: PullRouting | undefined;
 }
 export interface InternalWorkerError {
     detail: string;
@@ -1468,6 +1488,7 @@ export interface StepExecutionResumeInfo {
     completedConditions: StepExecutionCompletedConditions | undefined;
     waitingCondition: WaitingConditionState | undefined;
     stepExeLocals: KV[];
+    waitForPullRouting: PullRouting | undefined;
 }
 export interface StepExecutionCounterInfo {
     stepTypeStartedCount: {
@@ -1557,6 +1578,7 @@ export interface InvokeWaitForMethodActivityOutput {
     response: InvokeWaitForMethodResponse | undefined;
     /** Identifies the Worker that completed this pull task for sticky routing. */
     servedByAppWorkerId: string;
+    pullRouting: PullRouting | undefined;
 }
 export interface InvokeExecuteMethodActivityInput {
     workerTarget: WorkerTarget | undefined;
@@ -1578,11 +1600,13 @@ export interface InternalLocalStepActivityFailure {
     methodOptions: StepMethodOptions | undefined;
     attempt: number;
     activityError: InternalActivityError | undefined;
+    pullRouting: PullRouting | undefined;
 }
 export interface InvokeExecuteMethodActivityOutput {
     response: InvokeExecuteMethodResponse | undefined;
     /** Identifies the Worker that completed this pull task for sticky routing. */
     servedByAppWorkerId: string;
+    pullRouting: PullRouting | undefined;
 }
 export interface DumpFlowForContinueAsNewActivityInput {
     request: ContinueAsNewDumpRequest | undefined;
@@ -1648,6 +1672,7 @@ export interface ExecuteRpcSignalRequest {
     deleteFromChannel: ChannelMessageDeletion[];
     isDeleteChannelMessageApi: boolean;
     actionPermissionMappings: ActionPermissionMappings | undefined;
+    servedByAppWorkerId: string;
 }
 export interface SkipTimerSignalRequest {
     stepExecutionId: string;
@@ -1814,6 +1839,7 @@ export declare const StepMethodPendingEvent: MessageFns<StepMethodPendingEvent>;
 export declare const StepMethodFailure: MessageFns<StepMethodFailure>;
 export declare const StepMethodOptions: MessageFns<StepMethodOptions>;
 export declare const StepMethodEventInput: MessageFns<StepMethodEventInput>;
+export declare const PullRouting: MessageFns<PullRouting>;
 export declare const StepMethodEventContext: MessageFns<StepMethodEventContext>;
 export declare const StepWaitForCompletedOutput: MessageFns<StepWaitForCompletedOutput>;
 export declare const StepExecuteCompletedOutput: MessageFns<StepExecuteCompletedOutput>;