0
# Task Queue Management
1

2
Worker build ID versioning and task reachability management for gradual deployments, worker compatibility, and safe rollouts of workflow and activity code changes.
3

4
## Capabilities
5

6
### TaskQueueClient (Experimental)
7

8
Client for managing worker versioning and build ID compatibility operations.
9

10
```typescript { .api }
11
/**
12
 * Client for worker versioning operations (Experimental)
13
 */
14
class TaskQueueClient extends BaseClient {
15
  /** Update build ID compatibility for a task queue */
16
  updateBuildIdCompatibility(
17
    taskQueue: string,
18
    operation: BuildIdOperation
19
  ): Promise<void>;
20

21
  /** Get build ID compatibility sets for a task queue */
22
  getBuildIdCompatability(taskQueue: string): Promise<WorkerBuildIdVersionSets>;
23

24
  /** Get worker task reachability information */
25
  getReachability(options: ReachabilityOptions): Promise<ReachabilityResponse>;
26

27
  /** Raw gRPC access to WorkflowService */
28
  readonly workflowService: WorkflowService;
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { TaskQueueClient } from "@temporalio/client";
36

37
const taskQueueClient = new TaskQueueClient();
38

39
// Add new build ID in new default set
40
await taskQueueClient.updateBuildIdCompatibility('my-task-queue', {
41
  operation: 'addNewIdInNewDefaultSet',
42
  buildId: 'build-v1.2.0',
43
});
44

45
// Add compatible build ID to existing set
46
await taskQueueClient.updateBuildIdCompatibility('my-task-queue', {
47
  operation: 'addNewCompatibleVersion',
48
  buildId: 'build-v1.2.1',
49
  existingCompatibleBuildId: 'build-v1.2.0',
50
});
51

52
// Get current build ID compatibility
53
const compatibility = await taskQueueClient.getBuildIdCompatability('my-task-queue');
54
console.log('Default set:', compatibility.defaultSet);
55

56
// Check reachability
57
const reachability = await taskQueueClient.getReachability(
58
  ['build-v1.2.0', 'build-v1.2.1'],
59
  ['my-task-queue']
60
);
61
```
62

63
### Build ID Operations
64

65
Operations for managing build ID compatibility and versioning.
66

67
```typescript { .api }
68
/**
69
 * Operations for build ID management
70
 */
71
type BuildIdOperation =
72
  | AddNewIdInNewDefaultSet
73
  | AddNewCompatibleVersion
74
  | PromoteSetByBuildId
75
  | PromoteBuildIdWithinSet
76
  | MergeSets;
77

78
/**
79
 * Add new build ID in new default set
80
 */
81
interface AddNewIdInNewDefaultSet {
82
  operation: 'addNewIdInNewDefaultSet';
83
  buildId: string;
84
}
85

86
/**
87
 * Add compatible build ID version to existing set
88
 */
89
interface AddNewCompatibleVersion {
90
  operation: 'addNewCompatibleVersion';
91
  buildId: string;
92
  existingCompatibleBuildId: string;
93
  makeSetDefault?: boolean;
94
}
95

96
/**
97
 * Promote set containing build ID to default
98
 */
99
interface PromoteSetByBuildId {
100
  operation: 'promoteSetByBuildId';
101
  buildId: string;
102
}
103

104
/**
105
 * Promote build ID within its set to be the default
106
 */
107
interface PromoteBuildIdWithinSet {
108
  operation: 'promoteBuildIdWithinSet';
109
  buildId: string;
110
}
111

112
/**
113
 * Merge two sets of compatible build IDs
114
 */
115
interface MergeSets {
116
  operation: 'mergeSets';
117
  primaryBuildId: string;
118
  secondaryBuildId: string;
119
}
120
```
121

122
**Usage Examples:**
123

124
```typescript
125
// Gradual rollout workflow
126
const taskQueue = 'production-queue';
127

128
// 1. Add new build ID in non-default set for testing
129
await taskQueueClient.updateBuildIdCompatibility(taskQueue, {
130
  operation: 'addNewIdInNewDefaultSet',
131
  buildId: 'v2.0.0',
132
});
133

134
// 2. Add compatible patch version
135
await taskQueueClient.updateBuildIdCompatibility(taskQueue, {
136
  operation: 'addNewCompatibleVersion',
137
  buildId: 'v2.0.1',
138
  existingCompatibleBuildId: 'v2.0.0',
139
});
140

141
// 3. Promote new version to default after validation
142
await taskQueueClient.updateBuildIdCompatibility(taskQueue, {
143
  operation: 'promoteSetByBuildId',
144
  buildId: 'v2.0.1',
145
});
146
```
147

148
### Build ID Version Sets
149

150
Types for managing sets of compatible build IDs.
151

152
```typescript { .api }
153
/**
154
 * Sets of compatible build IDs for a task queue
155
 */
156
interface WorkerBuildIdVersionSets {
157
  /** Default build ID set (receives new tasks) */
158
  defaultSet?: BuildIdVersionSet;
159
  /** All build ID sets including non-default */
160
  allSets: BuildIdVersionSet[];
161
}
162

163
/**
164
 * Single set of compatible build IDs
165
 */
166
interface BuildIdVersionSet {
167
  /** Build IDs in this compatibility set */
168
  buildIds: string[];
169
  /** Default build ID within this set */
170
  defaultBuildId?: string;
171
}
172
```
173

174
### Reachability Information
175

176
Types for querying task reachability across different build IDs.
177

178
```typescript { .api }
179
/**
180
 * Stand-in for unversioned workers
181
 */
182
const UnversionedBuildId: unique symbol;
183

184
/**
185
 * Type for unversioned build ID symbol
186
 */
187
type UnversionedBuildIdType = typeof UnversionedBuildId;
188

189
/**
190
 * Options for reachability queries
191
 */
192
type ReachabilityOptions = {
193
  /** Include reachability for unversioned workers */
194
  includeUnversioned?: boolean;
195
};
196

197
/**
198
 * Options for querying build ID reachability
199
 */
200
interface ReachabilityOptions {
201
  /** List of build IDs to query (supports UnversionedBuildId symbol) */
202
  buildIds: (string | UnversionedBuildIdType)[];
203
  /** Task queues to check (optional) */
204
  taskQueues?: string[];
205
  /** Type of reachability to check (optional) */
206
  reachability?: ReachabilityType;
207
}
208

209
/**
210
 * Response from reachability queries
211
 */
212
interface ReachabilityResponse {
213
  /** Reachability information per build ID */
214
  buildIdReachability: BuildIdReachability[];
215
}
216

217
/**
218
 * Reachability info for specific build ID
219
 */
220
interface BuildIdReachability {
221
  /** Build ID or UnversionedBuildId symbol */
222
  buildId: string | typeof UnversionedBuildId;
223
  /** Task queues and their reachability info */
224
  taskQueueReachability: TaskQueueReachability[];
225
}
226

227
/**
228
 * Reachability info for a task queue
229
 */
230
interface TaskQueueReachability {
231
  /** Task queue name */
232
  taskQueue: string;
233
  /** Types of reachability */
234
  reachability: ReachabilityType[];
235
}
236

237
/**
238
 * Types of reachability
239
 */
240
const ReachabilityType = {
241
  /** Can process new workflow tasks */
242
  NEW_WORKFLOWS: 'NEW_WORKFLOWS',
243
  /** Can process existing workflow tasks */
244
  EXISTING_WORKFLOWS: 'EXISTING_WORKFLOWS',
245
  /** Can process open workflows */
246
  OPEN_WORKFLOWS: 'OPEN_WORKFLOWS',
247
  /** Can process closed workflows */
248
  CLOSED_WORKFLOWS: 'CLOSED_WORKFLOWS',
249
} as const;
250

251
type ReachabilityType = typeof ReachabilityType[keyof typeof ReachabilityType];
252
```
253

254
**Usage Examples:**
255

256
```typescript
257
// Check if old build ID can be safely removed
258
const reachability = await taskQueueClient.getReachability(['old-build-v1.0.0']);
259

260
const canRemove = reachability.buildIdReachability.every(buildInfo =>
261
  buildInfo.taskQueueReachability.every(tqInfo =>
262
    !tqInfo.reachability.includes(ReachabilityType.OPEN_WORKFLOWS) &&
263
    !tqInfo.reachability.includes(ReachabilityType.NEW_WORKFLOWS)
264
  )
265
);
266

267
if (canRemove) {
268
  console.log('Safe to remove old build ID');
269
} else {
270
  console.log('Old build ID still needed for open workflows');
271
}
272
```
273

274
### Task Queue Errors
275

276
Specialized error types for task queue operations.
277

278
```typescript { .api }
279
/**
280
 * Build ID not found error
281
 */
282
class BuildIdNotFoundError extends Error {
283
  readonly buildId: string;
284
  readonly taskQueue: string;
285

286
  constructor(buildId: string, taskQueue: string) {
287
    super(`Build ID '${buildId}' not found in task queue '${taskQueue}'`);
288
    this.buildId = buildId;
289
    this.taskQueue = taskQueue;
290
  }
291
}
292
```
293

294
## Common Usage Patterns
295

296
### Safe Deployment Strategy
297

298
```typescript
299
class SafeDeploymentManager {
300
  private taskQueueClient: TaskQueueClient;
301

302
  constructor() {
303
    this.taskQueueClient = new TaskQueueClient();
304
  }
305

306
  async deployNewVersion(taskQueue: string, buildId: string) {
307
    // 1. Add new build ID in non-default set
308
    await this.taskQueueClient.updateBuildIdCompatibility(taskQueue, {
309
      operation: 'addNewIdInNewDefaultSet',
310
      buildId,
311
    });
312

313
    console.log(`Deployed ${buildId} to ${taskQueue} (non-default)`);
314

315
    // 2. Monitor and validate the new version
316
    await this.validateDeployment(taskQueue, buildId);
317

318
    // 3. Promote to default after validation
319
    await this.taskQueueClient.updateBuildIdCompatibility(taskQueue, {
320
      operation: 'promoteSetByBuildId',
321
      buildId,
322
    });
323

324
    console.log(`Promoted ${buildId} to default for ${taskQueue}`);
325
  }
326

327
  async validateDeployment(taskQueue: string, buildId: string): Promise<void> {
328
    // Wait and check metrics, health, etc.
329
    await new Promise(resolve => setTimeout(resolve, 60000)); // Wait 1 minute
330

331
    // Check reachability
332
    const reachability = await this.taskQueueClient.getReachability([buildId], [taskQueue]);
333

334
    const hasNewWorkflowCapability = reachability.buildIdReachability.some(info =>
335
      info.buildId === buildId &&
336
      info.taskQueueReachability.some(tq =>
337
        tq.reachability.includes(ReachabilityType.NEW_WORKFLOWS)
338
      )
339
    );
340

341
    if (!hasNewWorkflowCapability) {
342
      throw new Error(`Build ${buildId} cannot process new workflows`);
343
    }
344
  }
345

346
  async rollback(taskQueue: string, fallbackBuildId: string) {
347
    await this.taskQueueClient.updateBuildIdCompatibility(taskQueue, {
348
      operation: 'promoteSetByBuildId',
349
      buildId: fallbackBuildId,
350
    });
351

352
    console.log(`Rolled back to ${fallbackBuildId} for ${taskQueue}`);
353
  }
354
}
355
```
356

357
### Build ID Cleanup
358

359
```typescript
360
class BuildIdCleanup {
361
  private taskQueueClient: TaskQueueClient;
362

363
  constructor() {
364
    this.taskQueueClient = new TaskQueueClient();
365
  }
366

367
  async cleanupOldBuildIds(taskQueue: string, buildIds: string[]) {
368
    const reachability = await this.taskQueueClient.getReachability(buildIds, [taskQueue]);
369

370
    for (const buildInfo of reachability.buildIdReachability) {
371
      if (typeof buildInfo.buildId === 'string') {
372
        const canCleanup = buildInfo.taskQueueReachability.every(tqInfo =>
373
          !tqInfo.reachability.includes(ReachabilityType.OPEN_WORKFLOWS) &&
374
          !tqInfo.reachability.includes(ReachabilityType.NEW_WORKFLOWS)
375
        );
376

377
        if (canCleanup) {
378
          console.log(`Build ID ${buildInfo.buildId} can be safely removed`);
379
          // Note: Actual removal would require additional task queue management APIs
380
        } else {
381
          console.log(`Build ID ${buildInfo.buildId} still needed for active workflows`);
382
        }
383
      }
384
    }
385
  }
386
}
387
```