Skip to content

Add versioned PollerGroupsInfo, deprecate poller_group_infos #819

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cbsandeep10 merged 1 commit into from
Jul 7, 2026
+117 −8
Merged

Add versioned PollerGroupsInfo, deprecate poller_group_infos #819

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 29 additions & 2 deletions openapi/openapiv2.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15242,7 +15242,11 @@
"type": "object",
"$ref": "#/definitions/v1PollerGroupInfo"
},
"description": "The initial info that client should use for poller group assignment. This information is\nupdated through poll response. Client is supposed to use the info received in the latest\npoll response."
"description": "Deprecated. Use `poller_groups_info` instead, which carries a version so the client can\nignore stale updates.\nThe initial info that client should use for poller group assignment. This information is\nupdated through poll response. Client is supposed to use the info received in the latest\npoll response."
},
"pollerGroupsInfo": {
"$ref": "#/definitions/v1PollerGroupsInfo",
"description": "The initial, versioned info that client should use for poller group assignment. This\ninformation is updated through poll responses. Client is supposed to use the info with the\nhighest version it has received."
}
}
},
Expand Down Expand Up @@ -17943,7 +17947,11 @@
"type": "object",
"$ref": "#/definitions/v1PollerGroupInfo"
},
"description": "The weighted list of poller groups IDs that client should use for future polls to this task\nqueue. Client is expected to:\n 1. Maintain minimum number of pollers no less than the number of groups.\n 2. Try to assign the next poll to a group without any pending polls,\n 3. If every group has some pending polls, assign the next poll to a group randomly\n according to the weights."
"description": "Deprecated. Use `poller_groups_info` instead, which carries a version so the client can\nignore stale updates.\nThe weighted list of poller groups IDs that client should use for future polls to this task\nqueue. Client is expected to:\n 1. Maintain minimum number of pollers no less than the number of groups.\n 2. Try to assign the next poll to a group without any pending polls,\n 3. If every group has some pending polls, assign the next poll to a group randomly\n according to the weights."
},
"pollerGroupsInfo": {
"$ref": "#/definitions/v1PollerGroupsInfo",
"description": "The weighted, versioned list of poller groups IDs that client should use for future polls to\nthis task queue. Client should ignore this if it has already applied a snapshot with a\nversion greater than or equal to `poller_groups_info.version`. Client is expected to:\n 1. Maintain minimum number of pollers no less than the number of groups.\n 2. Try to assign the next poll to a group without any pending polls,\n 3. If every group has some pending polls, assign the next poll to a group randomly\n according to the weights."
}
}
},
Expand All @@ -17959,6 +17967,25 @@
}
}
},
"v1PollerGroupsInfo": {
"type": "object",
"properties": {
"version": {
"type": "string",
"format": "int64",
"description": "Monotonically increasing version of this snapshot. A client should ignore any snapshot whose\nversion is not greater than the one it last applied."
},
"pollerGroups": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1PollerGroupInfo"
},
"description": "The weighted list of poller groups the client should use for future polls to this task queue."
}
},
"description": "A versioned snapshot of the poller groups the client should use for future polls to a task\nqueue. The version is monotonically increasing so that a client can ignore a snapshot that is\nolder than the one it has already applied."
},
"v1PollerInfo": {
"type": "object",
"properties": {
Expand Down
43 changes: 41 additions & 2 deletions openapi/openapiv3.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11683,9 +11683,18 @@ components:
items:
$ref: '#/components/schemas/PollerGroupInfo'
description: |-
The initial info that client should use for poller group assignment. This information is
Deprecated. Use `poller_groups_info` instead, which carries a version so the client can
ignore stale updates.
The initial info that client should use for poller group assignment. This information is
updated through poll response. Client is supposed to use the info received in the latest
poll response.
pollerGroupsInfo:
allOf:
- $ref: '#/components/schemas/PollerGroupsInfo'
description: |-
The initial, versioned info that client should use for poller group assignment. This
information is updated through poll responses. Client is supposed to use the info with the
highest version it has received.
DescribeNexusOperationExecutionResponse:
type: object
properties:
Expand Down Expand Up @@ -14377,12 +14386,25 @@ components:
items:
$ref: '#/components/schemas/PollerGroupInfo'
description: |-
The weighted list of poller groups IDs that client should use for future polls to this task
Deprecated. Use `poller_groups_info` instead, which carries a version so the client can
ignore stale updates.
The weighted list of poller groups IDs that client should use for future polls to this task
queue. Client is expected to:
1. Maintain minimum number of pollers no less than the number of groups.
2. Try to assign the next poll to a group without any pending polls,
3. If every group has some pending polls, assign the next poll to a group randomly
according to the weights.
pollerGroupsInfo:
allOf:
- $ref: '#/components/schemas/PollerGroupsInfo'
description: |-
The weighted, versioned list of poller groups IDs that client should use for future polls to
this task queue. Client should ignore this if it has already applied a snapshot with a
version greater than or equal to `poller_groups_info.version`. Client is expected to:
1. Maintain minimum number of pollers no less than the number of groups.
2. Try to assign the next poll to a group without any pending polls,
3. If every group has some pending polls, assign the next poll to a group randomly
according to the weights.
PollerGroupInfo:
type: object
properties:
Expand All @@ -14391,6 +14413,23 @@ components:
weight:
type: number
format: float
PollerGroupsInfo:
type: object
properties:
version:
type: string
description: |-
Monotonically increasing version of this snapshot. A client should ignore any snapshot whose
version is not greater than the one it last applied.
pollerGroups:
type: array
items:
$ref: '#/components/schemas/PollerGroupInfo'
description: The weighted list of poller groups the client should use for future polls to this task queue.
description: |-
A versioned snapshot of the poller groups the client should use for future polls to a task
queue. The version is monotonically increasing so that a client can ignore a snapshot that is
older than the one it has already applied.
PollerInfo:
type: object
properties:
Expand Down
11 changes: 11 additions & 0 deletions temporal/api/taskqueue/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -308,6 +308,17 @@ message PollerGroupInfo {
float weight = 2;
}

// A versioned snapshot of the poller groups the client should use for future polls to a task
// queue. The version is monotonically increasing so that a client can ignore a snapshot that is
// older than the one it has already applied.
message PollerGroupsInfo {
// Monotonically increasing version of this snapshot. A client should ignore any snapshot whose
// version is not greater than the one it last applied.
int64 version = 1;
// The weighted list of poller groups the client should use for future polls to this task queue.
repeated PollerGroupInfo poller_groups = 2;
}

// Attached to task responses to give hints to the SDK about how it may adjust its number of
// pollers.
message PollerScalingDecision {
Expand Down
40 changes: 36 additions & 4 deletions temporal/api/workflowservice/v1/request_response.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,10 +102,16 @@ message DescribeNamespaceResponse {
// Contains the historical state of failover_versions for the cluster, truncated to contain only the last N
// states to ensure that the list does not grow unbounded.
repeated temporal.api.replication.v1.FailoverStatus failover_history = 6;
// Deprecated. Use `poller_groups_info` instead, which carries a version so the client can
// ignore stale updates.
// The initial info that client should use for poller group assignment. This information is
// updated through poll response. Client is supposed to use the info received in the latest
// poll response.
repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 7;
repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 7 [deprecated = true];
// The initial, versioned info that client should use for poller group assignment. This
// information is updated through poll responses. Client is supposed to use the info with the
// highest version it has received.
temporal.api.taskqueue.v1.PollerGroupsInfo poller_groups_info = 8;
}

message UpdateNamespaceRequest {
Expand Down Expand Up @@ -357,13 +363,23 @@ message PollWorkflowTaskQueueResponse {
// This poller group ID identifies the owner of the workflow task awaiting for query response.
// Corresponding RespondQueryTaskCompleted should pass this value for proper routing.
string poller_group_id = 17;
// Deprecated. Use `poller_groups_info` instead, which carries a version so the client can
// ignore stale updates.
// The weighted list of poller groups IDs that client should use for future polls to this task
// queue. Client is expected to:
// 1. Maintain minimum number of pollers no less than the number of groups.
// 2. Try to assign the next poll to a group without any pending polls,
// 3. If every group has some pending polls, assign the next poll to a group randomly
// according to the weights.
repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 18;
repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 18 [deprecated = true];
// The weighted, versioned list of poller groups IDs that client should use for future polls to
// this task queue. Client should ignore this if it has already applied a snapshot with a
// version greater than or equal to `poller_groups_info.version`. Client is expected to:
// 1. Maintain minimum number of pollers no less than the number of groups.
// 2. Try to assign the next poll to a group without any pending polls,
// 3. If every group has some pending polls, assign the next poll to a group randomly
// according to the weights.
temporal.api.taskqueue.v1.PollerGroupsInfo poller_groups_info = 19;
}

message RespondWorkflowTaskCompletedRequest {
Expand Down Expand Up @@ -583,7 +599,15 @@ message PollActivityTaskQueueResponse {
// 2. Try to assign the next poll to a group without any pending polls,
// 3. If every group has some pending polls, assign the next poll to a group randomly
// according to the weights.
repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 21;
repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 21 [deprecated = true];
// The weighted, versioned list of poller groups IDs that client should use for future polls to
// this task queue. Client should ignore this if it has already applied a snapshot with a
// version greater than or equal to `poller_groups_info.version`. Client is expected to:
// 1. Maintain minimum number of pollers no less than the number of groups.
// 2. Try to assign the next poll to a group without any pending polls,
// 3. If every group has some pending polls, assign the next poll to a group randomly
// according to the weights.
temporal.api.taskqueue.v1.PollerGroupsInfo poller_groups_info = 22;
}

message RecordActivityTaskHeartbeatRequest {
Expand Down Expand Up @@ -2006,7 +2030,15 @@ message PollNexusTaskQueueResponse {
// 2. Try to assign the next poll to a group without any pending polls,
// 3. If every group has some pending polls, assign the next poll to a group randomly
// according to the weights.
repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 5;
repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 5 [deprecated = true];
// The weighted, versioned list of poller groups IDs that client should use for future polls to
// this task queue. Client should ignore this if it has already applied a snapshot with a
// version greater than or equal to `poller_groups_info.version`. Client is expected to:
// 1. Maintain minimum number of pollers no less than the number of groups.
// 2. Try to assign the next poll to a group without any pending polls,
// 3. If every group has some pending polls, assign the next poll to a group randomly
// according to the weights.
temporal.api.taskqueue.v1.PollerGroupsInfo poller_groups_info = 6;
}

message RespondNexusTaskCompletedRequest {
Expand Down
Loading