diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 454e72c7d..52fe2e881 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -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." } } }, @@ -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." } } }, @@ -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": { diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 657b92dbe..98e2c80ad 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -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: @@ -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: @@ -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: diff --git a/temporal/api/taskqueue/v1/message.proto b/temporal/api/taskqueue/v1/message.proto index 358b9430c..1652f2f70 100644 --- a/temporal/api/taskqueue/v1/message.proto +++ b/temporal/api/taskqueue/v1/message.proto @@ -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 { diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 9fbc6120b..3f139dbc7 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -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 { @@ -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 { @@ -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 { @@ -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 {