Dedicated message, MOAR info

temporalio · Aug 20, 2024 · f6bdb51 · f6bdb51
1 parent 3e9e185
commit f6bdb51
Show file tree

Hide file tree

Showing 4 changed files with 79 additions and 27 deletions.
diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json
@@ -8869,9 +8869,9 @@
           "$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."
         },
-        "syncMatchWaitDuration": {
-          "type": "string",
-          "description": "This field is set if the task was delivered as a result of a sync match, and it is set to the\namount of time we waited to make such a match. If the task was delievered from the blacklog,\nthen the field is unset."
+        "taskResponseData": {
+          "$ref": "#/definitions/v1TaskResponsePollingData",
+          "description": "See `TaskResponsePollingData`\nNOTE: Not yet implemented. Update this docstring when released with version."
         }
       }
     },
@@ -8887,9 +8887,9 @@
           "$ref": "#/definitions/apinexusv1Request",
           "description": "Embedded request as translated from the incoming frontend request."
         },
-        "syncMatchWaitDuration": {
-          "type": "string",
-          "description": "This field is set if the task was delivered as a result of a sync match, and it is set to the\namount of time we waited to make such a match. If the task was delievered from the blacklog,\nthen the field is unset."
+        "taskResponseData": {
+          "$ref": "#/definitions/v1TaskResponsePollingData",
+          "description": "See `TaskResponsePollingData`\nNOTE: Not yet implemented. Update this docstring when released with version."
         }
       }
     },
@@ -8986,9 +8986,9 @@
           },
           "title": "Protocol messages piggybacking on a WFT as a transport"
         },
-        "syncMatchWaitDuration": {
-          "type": "string",
-          "description": "This field is set if the task was delivered as a result of a sync match, and it is set to the\namount of time we waited to make such a match. If the task was delievered from the blacklog,\nthen the field is unset."
+        "taskResponseData": {
+          "$ref": "#/definitions/v1TaskResponsePollingData",
+          "description": "See `TaskResponsePollingData`\nNOTE: Not yet implemented. Update this docstring when released with version."
         }
       }
     },
@@ -10819,6 +10819,24 @@
       "default": "TASK_REACHABILITY_UNSPECIFIED",
       "description": "Specifies which category of tasks may reach a worker on a versioned task queue.\nUsed both in a reachability query and its response.\nDeprecated.\n\n - TASK_REACHABILITY_NEW_WORKFLOWS: There's a possiblity for a worker to receive new workflow tasks. Workers should *not* be retired.\n - TASK_REACHABILITY_EXISTING_WORKFLOWS: There's a possiblity for a worker to receive existing workflow and activity tasks from existing workflows. Workers\nshould *not* be retired.\nThis enum value does not distinguish between open and closed workflows.\n - TASK_REACHABILITY_OPEN_WORKFLOWS: There's a possiblity for a worker to receive existing workflow and activity tasks from open workflows. Workers\nshould *not* be retired.\n - TASK_REACHABILITY_CLOSED_WORKFLOWS: There's a possiblity for a worker to receive existing workflow tasks from closed workflows. Workers may be\nretired dependending on application requirements. For example, if there's no need to query closed workflows."
     },
+    "v1TaskResponsePollingData": {
+      "type": "object",
+      "properties": {
+        "wasSyncMatch": {
+          "type": "boolean",
+          "description": "Set to true if the returned task was a result of a sync match."
+        },
+        "timePollerWaited": {
+          "type": "string",
+          "description": "Set to the amount of time a poll call waited for a task to be available. This value is allowed to be unset\nif the match was not sync. It is useful to help the SDK understand if it may reduce the number of pollers, since\nany substantial wait time here means the backlog is drained, and poll calls are idling waiting for tasks."
+        },
+        "stats": {
+          "$ref": "#/definitions/v1TaskQueueStats",
+          "description": "See `TaskQueueStats`. This field is only set if the poll hit the root partition, where the data is readily\navailable. SDKs should cache this data, and explicitly refresh it with a call to `DescribeTaskQueue` if some\nTTL has expired."
+        }
+      },
+      "description": "Data attached to successful poll responses (for any task type) which the SDK can use to optimize its polling\nstrategy."
+    },
     "v1TerminateWorkflowExecutionResponse": {
       "type": "object"
     },

diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml
@@ -6590,13 +6590,12 @@ components:
           items:
             $ref: '#/components/schemas/Message'
           description: Protocol messages piggybacking on a WFT as a transport
-        syncMatchWaitDuration:
-          pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
-          type: string
+        taskResponseData:
+          allOf:
+            - $ref: '#/components/schemas/TaskResponsePollingData'
           description: |-
-            This field is set if the task was delivered as a result of a sync match, and it is set to the
-             amount of time we waited to make such a match. If the task was delievered from the blacklog,
-             then the field is unset.
+            See `TaskResponsePollingData`
+             NOTE: Not yet implemented. Update this docstring when released with version.
     PollerInfo:
       type: object
       properties:
@@ -8279,6 +8278,29 @@ components:
              who inherit the parent/previous workflow's Build ID but not its Task Queue. In those cases, make
              sure to query reachability for the parent/previous workflow's Task Queue as well.
           format: enum
+    TaskResponsePollingData:
+      type: object
+      properties:
+        wasSyncMatch:
+          type: boolean
+          description: Set to true if the returned task was a result of a sync match.
+        timePollerWaited:
+          pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
+          type: string
+          description: |-
+            Set to the amount of time a poll call waited for a task to be available. This value is allowed to be unset
+             if the match was not sync. It is useful to help the SDK understand if it may reduce the number of pollers, since
+             any substantial wait time here means the backlog is drained, and poll calls are idling waiting for tasks.
+        stats:
+          allOf:
+            - $ref: '#/components/schemas/TaskQueueStats'
+          description: |-
+            See `TaskQueueStats`. This field is only set if the poll hit the root partition, where the data is readily
+             available. SDKs should cache this data, and explicitly refresh it with a call to `DescribeTaskQueue` if some
+             TTL has expired.
+      description: |-
+        Data attached to successful poll responses (for any task type) which the SDK can use to optimize its polling
+         strategy.
     TerminateWorkflowExecutionRequest:
       type: object
       properties:

diff --git a/temporal/api/taskqueue/v1/message.proto b/temporal/api/taskqueue/v1/message.proto
@@ -257,4 +257,19 @@ message TimestampedBuildIdAssignmentRule {
 message TimestampedCompatibleBuildIdRedirectRule {
     CompatibleBuildIdRedirectRule rule = 1;
     google.protobuf.Timestamp create_time = 2;
+}
+
+// Data attached to successful poll responses (for any task type) which the SDK can use to optimize its polling
+// strategy.
+message TaskResponsePollingData {
+    // Set to true if the returned task was a result of a sync match.
+    bool was_sync_match = 1;
+    // Set to the amount of time a poll call waited for a task to be available. This value is allowed to be unset
+    // if the match was not sync. It is useful to help the SDK understand if it may reduce the number of pollers, since
+    // any substantial wait time here means the backlog is drained, and poll calls are idling waiting for tasks.
+    google.protobuf.Duration time_poller_waited = 2;
+    // See `TaskQueueStats`. This field is only set if the poll hit the root partition, where the data is readily
+    // available. SDKs should cache this data, and explicitly refresh it with a call to `DescribeTaskQueue` if some
+    // TTL has expired.
+    TaskQueueStats stats = 3;
 }
diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto
@@ -313,10 +313,9 @@ 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;
-    // This field is set if the task was delivered as a result of a sync match, and it is set to the
-    // amount of time we waited to make such a match. If the task was delievered from the blacklog,
-    // then the field is unset.
-    google.protobuf.Duration sync_match_wait_duration = 16;
+    // See `TaskResponsePollingData`
+    // NOTE: Not yet implemented. Update this docstring when released with version.
+    temporal.api.taskqueue.v1.TaskResponsePollingData task_response_data = 16;
 }
 
 message RespondWorkflowTaskCompletedRequest {
@@ -449,10 +448,9 @@ 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;
-    // This field is set if the task was delivered as a result of a sync match, and it is set to the
-    // amount of time we waited to make such a match. If the task was delievered from the blacklog,
-    // then the field is unset.
-    google.protobuf.Duration sync_match_wait_duration = 18;
+    // See `TaskResponsePollingData`
+    // NOTE: Not yet implemented. Update this docstring when released with version.
+    temporal.api.taskqueue.v1.TaskResponsePollingData task_response_data = 18;
 }
 
 message RecordActivityTaskHeartbeatRequest {
@@ -1594,10 +1592,9 @@ message PollNexusTaskQueueResponse {
     bytes task_token = 1;
     // Embedded request as translated from the incoming frontend request.
     temporal.api.nexus.v1.Request request = 2;
-    // This field is set if the task was delivered as a result of a sync match, and it is set to the
-    // amount of time we waited to make such a match. If the task was delievered from the blacklog,
-    // then the field is unset.
-    google.protobuf.Duration sync_match_wait_duration = 3;
+    // See `TaskResponsePollingData`
+    // NOTE: Not yet implemented. Update this docstring when released with version.
+    temporal.api.taskqueue.v1.TaskResponsePollingData task_response_data = 3;
 }
 
 message RespondNexusTaskCompletedRequest {