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

@@ -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": {

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:

temporal/api/taskqueue/v1/message.proto

@@ -323,4 +323,16 @@ message TimestampedBuildIdAssignmentRule {
 message TimestampedCompatibleBuildIdRedirectRule {
     CompatibleBuildIdRedirectRule rule = 1;
     google.protobuf.Timestamp create_time = 2;
-}
+}
+
+// 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;
+}

temporal/api/workflowservice/v1/request_response.proto

@@ -331,6 +331,8 @@ message PollWorkflowTaskQueueResponse {
     map<string, temporal.api.query.v1.WorkflowQuery> 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 {