Clarify namespace poller group snapshots

openapi/openapiv2.json

@@ -15712,11 +15712,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 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 namespace-level seed for poller group assignment. Clients should initially apply\nit to every task queue in the namespace. A poll response replaces the seed for that task\nqueue only."
         },
         "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 seed for poller group assignment. Clients should\ninitially apply it to every task queue in the namespace. A poll response can replace the\nseed for that task queue only."
         }
       }
     },
@@ -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 poller group IDs the 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."
+          "description": "The weighted, versioned list of poller group IDs the client should use for future polls to\nthis task queue. Client should ignore this if it has already applied a snapshot for this task\nqueue with a version greater than or equal to `poller_groups_info.version`. Client is expected\nto:\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."
         }
       }
     },
@@ -18581,18 +18581,18 @@
         "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."
+          "description": "Monotonically increasing version per task queue. Snapshots with a version no greater\nthan the last applied version can be ignored."
         },
         "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": "The weighted list of active poller groups represented by this snapshot."
         }
       },
-      "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 active poller groups. `DescribeNamespaceResponse` provides a namespace-\nlevel seed for all task queues. Poll responses provide task-queue-specific snapshots whose\ngroups and weights may differ. The version is monotonically increasing so that\na snapshot that is older than the one it has already applied can be ignored."
     },
     "v1PollerInfo": {
       "type": "object",

openapi/openapiv3.yaml

@@ -11900,16 +11900,16 @@ components:
           description: |-
             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.
+             The initial namespace-level seed for poller group assignment. Clients should initially apply
+             it to every task queue in the namespace. A poll response replaces the seed for that task
+             queue only.
         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.
+            The initial, versioned namespace-level seed for poller group assignment. Clients should
+             initially apply it to every task queue in the namespace. A poll response can replace the
+             seed for that task queue only.
     DescribeNexusOperationExecutionResponse:
       type: object
       properties:
@@ -14836,7 +14836,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
+             The weighted list of poller group IDs the 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,
@@ -14846,9 +14846,10 @@ 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
-             version greater than or equal to `poller_groups_info.version`. Client is expected to:
+            The weighted, versioned list of poller group IDs the client should use for future polls to
+             this task queue. Client should ignore this if it has already applied a snapshot for this task
+             queue 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
@@ -14867,17 +14868,18 @@ components:
         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.
+            Monotonically increasing version per task queue. Snapshots with a version no greater
+             than the last applied version can be ignored.
         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: The weighted list of active poller groups represented by this snapshot.
       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 active poller groups. `DescribeNamespaceResponse` provides a namespace-
+         level seed for all task queues. Poll responses provide task-queue-specific snapshots whose
+         groups and weights may differ. The version is monotonically increasing so that
+         a snapshot that is older than the one it has already applied can be ignored.
     PollerInfo:
       type: object
       properties:

temporal/api/taskqueue/v1/message.proto

@@ -314,14 +314,15 @@ 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 active poller groups. `DescribeNamespaceResponse` provides a namespace-
+// level seed for all task queues. Poll responses provide task-queue-specific snapshots whose
+// groups and weights may differ. The version is monotonically increasing so that
+// a snapshot that is older than the one it has already applied can be ignored.
 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.
+  // Monotonically increasing version per task queue. Snapshots with a version no greater
+  // than the last applied version can be ignored.
   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 represented by this snapshot.
   repeated PollerGroupInfo poller_groups = 2;
 }
 

temporal/api/workflowservice/v1/request_response.proto

@@ -106,13 +106,13 @@ message DescribeNamespaceResponse {
     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.
+    // The initial namespace-level seed for poller group assignment. Clients should initially apply
+    // it to every task queue in the namespace. A poll response replaces the seed for that task
+    // queue only.
     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 seed for poller group assignment. Clients should
+    // initially apply it to every task queue in the namespace. A poll response can replace the
+    // seed for that task queue only.
     temporal.api.taskqueue.v1.PollerGroupsInfo poller_groups_info = 8;
 }
 
@@ -369,16 +369,17 @@ 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
+    // The weighted list of poller group IDs the 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 [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:
+    // The weighted, versioned list of poller group IDs the client should use for future polls to
+    // this task queue. Client should ignore this if it has already applied a snapshot for this task
+    // queue 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
@@ -597,16 +598,17 @@ 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
+    // The weighted list of poller group IDs the 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 = 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:
+    // The weighted, versioned list of poller group IDs the client should use for future polls to
+    // this task queue. Client should ignore this if it has already applied a snapshot for this task
+    // queue 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
@@ -2048,16 +2050,17 @@ 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
+    // The weighted list of poller group IDs the 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 = 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:
+    // The weighted, versioned list of poller group IDs the client should use for future polls to
+    // this task queue. Client should ignore this if it has already applied a snapshot for this task
+    // queue 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