From 9156239c8272003b6f228951602ca2b130a55876 Mon Sep 17 00:00:00 2001 From: Spencer Judge Date: Mon, 24 Feb 2025 11:04:12 -0800 Subject: [PATCH] Poller Scaling Decisions (#553) Added a proto that is optionally attached to task responses and contains data for the SDK about whether or not pollers should be scaled up or down. --- openapi/openapiv2.json | 23 +++++++++++++++++++ openapi/openapiv3.yaml | 20 ++++++++++++++++ temporal/api/taskqueue/v1/message.proto | 14 ++++++++++- .../workflowservice/v1/request_response.proto | 8 ++++++- 4 files changed, 63 insertions(+), 2 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index b3f0ae18..0004dce0 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -11281,6 +11281,10 @@ "retryPolicy": { "$ref": "#/definitions/v1RetryPolicy", "description": "This is the retry policy the service uses which may be different from the one provided\n(or not) during activity scheduling. The service can override the provided one if some\nvalues are not specified or exceed configured system limits." + }, + "pollerScalingDecision": { + "$ref": "#/definitions/v1PollerScalingDecision", + "description": "Server-advised information the SDK may use to adjust its poller count." } } }, @@ -11295,6 +11299,10 @@ "request": { "$ref": "#/definitions/apinexusv1Request", "description": "Embedded request as translated from the incoming frontend request." + }, + "pollerScalingDecision": { + "$ref": "#/definitions/v1PollerScalingDecision", + "description": "Server-advised information the SDK may use to adjust its poller count." } } }, @@ -11390,6 +11398,10 @@ "$ref": "#/definitions/v1Message" }, "title": "Protocol messages piggybacking on a WFT as a transport" + }, + "pollerScalingDecision": { + "$ref": "#/definitions/v1PollerScalingDecision", + "description": "Server-advised information the SDK may use to adjust its poller count." } } }, @@ -11417,6 +11429,17 @@ } } }, + "v1PollerScalingDecision": { + "type": "object", + "properties": { + "pollRequestDeltaSuggestion": { + "type": "integer", + "format": "int32", + "description": "How many poll requests to suggest should be added or removed, if any. As of now, server only\nscales up or down by 1. However, SDKs should allow for other values (while staying within\ndefined min/max).\n\nThe SDK is free to ignore this suggestion, EX: making more polls would not make sense because\nall slots are already occupied." + } + }, + "description": "Attached to task responses to give hints to the SDK about how it may adjust its number of\npollers." + }, "v1ProtocolMessageCommandAttributes": { "type": "object", "properties": { diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index b5487bd8..3ba6a9a8 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -8566,6 +8566,10 @@ components: items: $ref: '#/components/schemas/Message' description: Protocol messages piggybacking on a WFT as a transport + pollerScalingDecision: + allOf: + - $ref: '#/components/schemas/PollerScalingDecision' + description: Server-advised information the SDK may use to adjust its poller count. PollerInfo: type: object properties: @@ -8588,6 +8592,22 @@ components: allOf: - $ref: '#/components/schemas/WorkerDeploymentOptions' description: Worker deployment options that SDK sent to server. + PollerScalingDecision: + type: object + properties: + pollRequestDeltaSuggestion: + type: integer + description: |- + How many poll requests to suggest should be added or removed, if any. As of now, server only + scales up or down by 1. However, SDKs should allow for other values (while staying within + defined min/max). + + The SDK is free to ignore this suggestion, EX: making more polls would not make sense because + all slots are already occupied. + format: int32 + description: |- + Attached to task responses to give hints to the SDK about how it may adjust its number of + pollers. QueryRejected: type: object properties: diff --git a/temporal/api/taskqueue/v1/message.proto b/temporal/api/taskqueue/v1/message.proto index 06ea0d49..53ddfec8 100644 --- a/temporal/api/taskqueue/v1/message.proto +++ b/temporal/api/taskqueue/v1/message.proto @@ -323,4 +323,16 @@ message TimestampedBuildIdAssignmentRule { message TimestampedCompatibleBuildIdRedirectRule { CompatibleBuildIdRedirectRule rule = 1; google.protobuf.Timestamp create_time = 2; -} \ No newline at end of file +} + +// Attached to task responses to give hints to the SDK about how it may adjust its number of +// pollers. +message PollerScalingDecision { + // How many poll requests to suggest should be added or removed, if any. As of now, server only + // scales up or down by 1. However, SDKs should allow for other values (while staying within + // defined min/max). + // + // The SDK is free to ignore this suggestion, EX: making more polls would not make sense because + // all slots are already occupied. + int32 poll_request_delta_suggestion = 1; +} diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 5dfeafee..d1976ccf 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -331,6 +331,8 @@ message PollWorkflowTaskQueueResponse { map queries = 14; // Protocol messages piggybacking on a WFT as a transport repeated temporal.api.protocol.v1.Message messages = 15; + // Server-advised information the SDK may use to adjust its poller count. + temporal.api.taskqueue.v1.PollerScalingDecision poller_scaling_decision = 16; } message RespondWorkflowTaskCompletedRequest { @@ -496,6 +498,8 @@ message PollActivityTaskQueueResponse { // (or not) during activity scheduling. The service can override the provided one if some // values are not specified or exceed configured system limits. temporal.api.common.v1.RetryPolicy retry_policy = 17; + // Server-advised information the SDK may use to adjust its poller count. + temporal.api.taskqueue.v1.PollerScalingDecision poller_scaling_decision = 18; } message RecordActivityTaskHeartbeatRequest { @@ -1733,6 +1737,8 @@ message PollNexusTaskQueueResponse { bytes task_token = 1; // Embedded request as translated from the incoming frontend request. temporal.api.nexus.v1.Request request = 2; + // Server-advised information the SDK may use to adjust its poller count. + temporal.api.taskqueue.v1.PollerScalingDecision poller_scaling_decision = 3; } message RespondNexusTaskCompletedRequest { @@ -2106,7 +2112,7 @@ message ListWorkerDeploymentsResponse { bytes next_page_token = 1; // The list of worker deployments. repeated WorkerDeploymentSummary worker_deployments = 2; - + // (-- api-linter: core::0123::resource-annotation=disabled --) // A subset of WorkerDeploymentInfo message WorkerDeploymentSummary {