From c4d31e27d8ce6ac1facd6ea95298fe4e23507f7a Mon Sep 17 00:00:00 2001 From: Spencer Judge Date: Mon, 19 Aug 2024 17:42:38 -0700 Subject: [PATCH 1/2] Add sync match hint --- openapi/openapiv2.json | 12 ++++++++++++ openapi/openapiv3.yaml | 7 +++++++ .../api/workflowservice/v1/request_response.proto | 12 ++++++++++++ 3 files changed, 31 insertions(+) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index ca3639d6..a4a63d59 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -8941,6 +8941,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." + }, + "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." } } }, @@ -8955,6 +8959,10 @@ "request": { "$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." } } }, @@ -9050,6 +9058,10 @@ "$ref": "#/definitions/v1Message" }, "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." } } }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 217b6edd..fefb74f7 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -6617,6 +6617,13 @@ 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 + 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. PollerInfo: type: object properties: diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index d75d1078..af9d6c06 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -315,6 +315,10 @@ 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; } message RespondWorkflowTaskCompletedRequest { @@ -447,6 +451,10 @@ 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; } message RecordActivityTaskHeartbeatRequest { @@ -1588,6 +1596,10 @@ 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; } message RespondNexusTaskCompletedRequest { From 3a7c223a60281771c4f2835ac4fb942218e94e82 Mon Sep 17 00:00:00 2001 From: Spencer Judge Date: Tue, 20 Aug 2024 14:01:10 -0700 Subject: [PATCH 2/2] Dedicated message, MOAR info --- openapi/openapiv2.json | 36 ++++++++++++++----- openapi/openapiv3.yaml | 34 ++++++++++++++---- temporal/api/taskqueue/v1/message.proto | 15 ++++++++ .../workflowservice/v1/request_response.proto | 21 +++++------ 4 files changed, 79 insertions(+), 27 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index a4a63d59..bd6ec0b8 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -8942,9 +8942,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." } } }, @@ -8960,9 +8960,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." } } }, @@ -9059,9 +9059,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." } } }, @@ -10908,6 +10908,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 index fefb74f7..c7f6f1d7 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -6617,13 +6617,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: @@ -8311,6 +8310,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 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 af9d6c06..17e7397a 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -315,10 +315,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 { @@ -451,10 +450,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 { @@ -1596,10 +1594,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 {