fix: change work item filters from auto opt-in to explicit opt-in

Author: YunchuWang

packages/durabletask-js-azuremanaged/src/worker-builder.ts

@@ -28,7 +28,7 @@ export class DurableTaskAzureManagedWorkerBuilder {
   private _logger: Logger = new ConsoleLogger();
   private _shutdownTimeoutMs?: number;
   private _versioning?: VersioningOptions;
-  private _workItemFilters?: WorkItemFilters | null;
+  private _workItemFilters?: WorkItemFilters | "auto";
 
   /**
    * Creates a new instance of DurableTaskAzureManagedWorkerBuilder.
@@ -223,17 +223,17 @@ export class DurableTaskAzureManagedWorkerBuilder {
   }
 
   /**
-   * Sets work item filters for the worker.
-   * When provided, the sidecar will only send work items matching these filters.
-   * Pass null to explicitly disable filtering and receive all work items.
-   * When not called, filters are auto-generated from the registered orchestrations,
-   * activities, and entities.
+   * Enables work item filters for the worker.
+   * When called without arguments, filters are auto-generated from the registered
+   * orchestrations, activities, and entities.
+   * When called with a WorkItemFilters object, those specific filters are used.
+   * By default (when not called), no filters are sent and the worker processes all work items.
    *
-   * @param filters The work item filters, or null to disable filtering.
+   * @param filters Optional explicit filters. Omit to auto-generate from registry.
    * @returns This builder instance.
    */
-  useWorkItemFilters(filters: WorkItemFilters | null): DurableTaskAzureManagedWorkerBuilder {
-    this._workItemFilters = filters;
+  useWorkItemFilters(filters?: WorkItemFilters): DurableTaskAzureManagedWorkerBuilder {
+    this._workItemFilters = filters ?? "auto";
     return this;
   }
 

packages/durabletask-js/src/worker/task-hub-grpc-worker.ts

@@ -63,12 +63,12 @@ export interface TaskHubGrpcWorkerOptions {
   versioning?: VersioningOptions;
   /**
    * Optional work item filters to control which work items the worker receives.
-   * When set, only work items matching these filters will be dispatched to this worker.
-   * When undefined (default), filters are auto-generated from the registered
-   * orchestrations, activities, and entities.
-   * Set to null to explicitly disable filtering (receive all work items).
+   * By default, no filters are sent and the worker processes all work items.
+   * Set to a WorkItemFilters object to use explicit filters.
+   * Set to "auto" to auto-generate filters from the registered orchestrations,
+   * activities, and entities.
    */
-  workItemFilters?: WorkItemFilters | null;
+  workItemFilters?: WorkItemFilters | "auto";
 }
 
 export class TaskHubGrpcWorker {
@@ -87,7 +87,7 @@ export class TaskHubGrpcWorker {
   private _shutdownTimeoutMs: number;
   private _backoff: ExponentialBackoff;
   private _versioning?: VersioningOptions;
-  private _workItemFilters?: WorkItemFilters | null;
+  private _workItemFilters?: WorkItemFilters | "auto";
 
   /**
    * Creates a new TaskHubGrpcWorker instance.
@@ -135,7 +135,7 @@ export class TaskHubGrpcWorker {
     let resolvedLogger: Logger | undefined;
     let resolvedShutdownTimeoutMs: number | undefined;
     let resolvedVersioning: VersioningOptions | undefined;
-    let resolvedWorkItemFilters: WorkItemFilters | null | undefined;
+    let resolvedWorkItemFilters: WorkItemFilters | "auto" | undefined;
 
     if (typeof hostAddressOrOptions === "object" && hostAddressOrOptions !== null) {
       // Options object constructor
@@ -506,15 +506,18 @@ export class TaskHubGrpcWorker {
 
   /**
    * Builds the GetWorkItemsRequest, attaching work item filters based on configuration.
-   * - null: no filters sent (receive all work items)
-   * - undefined: auto-generate from the registry
+   * - undefined (default): no filters sent, worker receives all work items
+   * - "auto": auto-generate filters from the registry
    * - explicit WorkItemFilters: use as provided
    */
   private _buildGetWorkItemsRequest(): pb.GetWorkItemsRequest {
     const request = new pb.GetWorkItemsRequest();
 
-    if (this._workItemFilters !== null) {
-      const filters = this._workItemFilters ?? generateWorkItemFiltersFromRegistry(this._registry, this._versioning);
+    if (this._workItemFilters !== undefined) {
+      const filters =
+        this._workItemFilters === "auto"
+          ? generateWorkItemFiltersFromRegistry(this._registry, this._versioning)
+          : this._workItemFilters;
       request.setWorkitemfilters(toGrpcWorkItemFilters(filters));
     }
 

packages/durabletask-js/test/work-item-filters.spec.ts

@@ -633,7 +633,7 @@ describe("WorkItemFilters", () => {
   });
 
   describe("TaskHubGrpcWorker._buildGetWorkItemsRequest", () => {
-    it("should auto-generate filters from registry when workItemFilters is undefined", () => {
+    it("should not send filters when workItemFilters is undefined (default)", () => {
       // Arrange
       const worker = new TaskHubGrpcWorker({
         hostAddress: "localhost:4001",
@@ -644,6 +644,22 @@ describe("WorkItemFilters", () => {
       // Act
       const request = (worker as any)._buildGetWorkItemsRequest();
 
+      // Assert — no filters sent by default (opt-in only)
+      expect(request.hasWorkitemfilters()).toBe(false);
+    });
+
+    it("should auto-generate filters from registry when workItemFilters is 'auto'", () => {
+      // Arrange
+      const worker = new TaskHubGrpcWorker({
+        hostAddress: "localhost:4001",
+        workItemFilters: "auto",
+      });
+      worker.addOrchestrator(myOrchestrator);
+      worker.addActivity(myActivity);
+
+      // Act
+      const request = (worker as any)._buildGetWorkItemsRequest();
+
       // Assert
       expect(request.hasWorkitemfilters()).toBe(true);
       const filters = request.getWorkitemfilters()!;
@@ -653,18 +669,17 @@ describe("WorkItemFilters", () => {
       expect(actNames).toContain("myActivity");
     });
 
-    it("should omit filters when workItemFilters is null", () => {
+    it("should not send filters when workItemFilters is not configured (default)", () => {
       // Arrange
       const worker = new TaskHubGrpcWorker({
         hostAddress: "localhost:4001",
-        workItemFilters: null,
       });
       worker.addOrchestrator(myOrchestrator);
 
       // Act
       const request = (worker as any)._buildGetWorkItemsRequest();
 
-      // Assert
+      // Assert — default is no filters (opt-in only)
       expect(request.hasWorkitemfilters()).toBe(false);
     });
 
@@ -706,6 +721,7 @@ describe("WorkItemFilters", () => {
       // Arrange
       const worker = new TaskHubGrpcWorker({
         hostAddress: "localhost:4001",
+        workItemFilters: "auto",
         versioning: {
           version: "3.0.0",
           matchStrategy: VersionMatchStrategy.Strict,

test/e2e-azuremanaged/orchestration.spec.ts

@@ -66,9 +66,9 @@ function createWorkerWithVersioning(
     ? new DurableTaskAzureManagedWorkerBuilder().connectionString(connectionString)
     : new DurableTaskAzureManagedWorkerBuilder().endpoint(endpoint, taskHub, null);
 
-  // Disable auto-generated work item filters so version mismatches are handled
-  // by the SDK's local versioning logic, not by server-side filter enforcement.
-  return builder.versioning({ version, matchStrategy, failureStrategy }).useWorkItemFilters(null).build();
+  // No need to disable work item filters — they are opt-in (off by default),
+  // so version mismatches are handled by the SDK's local versioning logic.
+  return builder.versioning({ version, matchStrategy, failureStrategy }).build();
 }
 
 describe("Durable Task Scheduler (DTS) E2E Tests", () => {

test/e2e-azuremanaged/work-item-filters.spec.ts

@@ -67,9 +67,9 @@ describe("Work Item Filters E2E Tests", () => {
     await taskHubClient.stop();
   });
 
-  describe("Disabled filters (null)", () => {
-    it("should process all orchestrations when filters are explicitly disabled", async () => {
-      // Arrange — worker with filters explicitly set to null (receive all work items)
+  describe("Default behavior (no filters)", () => {
+    it("should process all orchestrations when no filters are configured (default)", async () => {
+      // Arrange — worker with default config (no useWorkItemFilters call)
       const echo = async (_: ActivityContext, input: string) => input;
 
       const echoOrchestrator: TOrchestrator = async function* (ctx: OrchestrationContext, input: string): any {
@@ -80,7 +80,6 @@ describe("Work Item Filters E2E Tests", () => {
       taskHubWorker = createWorkerBuilder()
         .addOrchestrator(echoOrchestrator)
         .addActivity(echo)
-        .useWorkItemFilters(null)
         .build();
       await taskHubWorker.start();
 
@@ -139,7 +138,7 @@ describe("Work Item Filters E2E Tests", () => {
         return "registered";
       };
 
-      taskHubWorker = createWorkerBuilder().addOrchestrator(registeredOrch).build();
+      taskHubWorker = createWorkerBuilder().addOrchestrator(registeredOrch).useWorkItemFilters().build();
       await taskHubWorker.start();
 
       // Act — schedule an orchestration by name that doesn't match any filter