From 8df4826847632b0960052946a522e37280b91ef2 Mon Sep 17 00:00:00 2001 From: Andrew Yuan Date: Thu, 17 Sep 2026 18:01:38 +0800 Subject: [PATCH] Clarify namespace poller group snapshots --- openapi/openapiv2.json | 10 +++---- openapi/openapiv3.yaml | 20 +++++++------- temporal/api/taskqueue/v1/message.proto | 8 +++--- .../workflowservice/v1/request_response.proto | 26 ++++++++----------- 4 files changed, 29 insertions(+), 35 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 0b643ceb7..861e7c196 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -15716,7 +15716,7 @@ }, "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." + "description": "The initial, versioned namespace-level snapshot for poller group assignment. Poll responses\ncan update it. Clients should use the highest version received." } } }, @@ -18555,11 +18555,11 @@ "type": "object", "$ref": "#/definitions/v1PollerGroupInfo" }, - "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." + "description": "Deprecated. Use `poller_groups_info` instead, which carries a version so the client can\nignore stale updates.\nThe weighted list of active poller groups for the namespace. 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." + "description": "The weighted, versioned list of active poller groups for the namespace. Client should ignore\nthis 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." } } }, @@ -18589,10 +18589,10 @@ "type": "object", "$ref": "#/definitions/v1PollerGroupInfo" }, - "description": "The weighted list of poller groups the client should use for future polls to this task queue." + "description": "The weighted list of active poller groups for the namespace." } }, - "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." + "description": "A versioned snapshot of the namespace's active poller groups. It applies to all task queues in\nthe namespace. The version is monotonically increasing so that a client can ignore a snapshot\nthat is older than the one it has already applied." }, "v1PollerInfo": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 2aa7c45bf..1dc7d824c 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -11907,9 +11907,8 @@ components: 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. + The initial, versioned namespace-level snapshot for poller group assignment. Poll responses + can update it. Clients should use the highest version received. DescribeNexusOperationExecutionResponse: type: object properties: @@ -14836,8 +14835,7 @@ components: description: |- 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: + The weighted list of active poller groups for the namespace. 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 @@ -14846,8 +14844,8 @@ components: 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 + The weighted, versioned list of active poller groups for the namespace. 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, @@ -14873,11 +14871,11 @@ components: 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: The weighted list of active poller groups for the namespace. 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. + A versioned snapshot of the namespace's active poller groups. It applies to all task queues in + the namespace. 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: diff --git a/temporal/api/taskqueue/v1/message.proto b/temporal/api/taskqueue/v1/message.proto index 6ab668fdb..d34f75f5c 100644 --- a/temporal/api/taskqueue/v1/message.proto +++ b/temporal/api/taskqueue/v1/message.proto @@ -314,14 +314,14 @@ 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. +// A versioned snapshot of the namespace's active poller groups. It applies to all task queues in +// the namespace. 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. + // The weighted list of active poller groups for the namespace. repeated PollerGroupInfo poller_groups = 2; } diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 1aae988d8..7042f0a16 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -110,9 +110,8 @@ message DescribeNamespaceResponse { // 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 [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. + // The initial, versioned namespace-level snapshot for poller group assignment. Poll responses + // can update it. Clients should use the highest version received. temporal.api.taskqueue.v1.PollerGroupsInfo poller_groups_info = 8; } @@ -369,15 +368,14 @@ message PollWorkflowTaskQueueResponse { 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: + // The weighted list of active poller groups for the namespace. 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 [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 + // The weighted, versioned list of active poller groups for the namespace. 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, @@ -597,15 +595,14 @@ message PollActivityTaskQueueResponse { temporal.api.common.v1.Priority priority = 19; // The run ID of the activity execution, only set for standalone activities. string activity_run_id = 20; - // The weighted list of poller groups IDs that client should use for future polls to this task - // queue. Client is expected to: + // The weighted list of active poller groups for the namespace. 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 = 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 + // The weighted, versioned list of active poller groups for the namespace. 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, @@ -2048,15 +2045,14 @@ message PollNexusTaskQueueResponse { // Corresponding `RespondNexusTaskCompleted` and `RespondNexusTaskFailed` calls should pass this // value for proper response routing. string poller_group_id = 4; - // The weighted list of poller groups IDs that client should use for future polls to this task - // queue. Client is expected to: + // The weighted list of active poller groups for the namespace. 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 = 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 + // The weighted, versioned list of active poller groups for the namespace. 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,