diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 25b78769..3e31d90b 100644 --- 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." + }, + "timePollerWaiter": { + "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 index 27d19e9a..42f219e9 100644 --- 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. + timePollerWaiter: + 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 index 0971ee4e..c389f708 100644 --- 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; } \ No newline at end of file diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index c7b4772a..8a9f4484 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -313,10 +313,9 @@ message PollWorkflowTaskQueueResponse { map 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 {