From ccb8b29329b6b90d840c72caaada447aab3e09f2 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Mon, 20 May 2024 10:26:52 -0400 Subject: [PATCH 1/2] Evolve documentation of update polling parameters --- openapi/openapiv2.json | 12 +++++------ openapi/openapiv3.yaml | 20 ++++++------------- temporal/api/update/v1/message.proto | 7 ++----- .../workflowservice/v1/request_response.proto | 19 +++++++----------- 4 files changed, 21 insertions(+), 37 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 24aa3aba..0fd91f3c 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -3457,7 +3457,7 @@ }, "waitPolicy": { "$ref": "#/definitions/v1WaitPolicy", - "description": "Describes when this request should return - basically whether the\nupdate is synchronous, asynchronous, or somewhere in between." + "description": "How long to wait before returning control to the caller." }, "request": { "type": "object", @@ -6775,7 +6775,7 @@ }, "stage": { "$ref": "#/definitions/v1UpdateWorkflowExecutionLifecycleStage", - "description": "The most advanced lifecycle stage that the Update is known to have\nreached, where lifecycle stages are ordered\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.\nUNSPECIFIED will be returned if and only if the server's maximum wait\ntime was reached before the Update reached the stage specified in the\nrequest WaitPolicy, and before the context deadline expired; clients may\nmay then retry the call as needed." + "description": "The most advanced lifecycle stage that the Update is known to have\nreached, where lifecycle stages are ordered\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.\nIf the server's maximum wait time was reached before the stage requested by the client, then\nthe returned stage may be less than the requested stage. Clients may then retry the call as\nneeded." }, "updateRef": { "$ref": "#/definitions/v1UpdateRef", @@ -8907,7 +8907,7 @@ }, "waitPolicy": { "$ref": "#/definitions/v1WaitPolicy", - "description": "Describes when this request should return - basically whether the\nupdate is synchronous, asynchronous, or somewhere in between." + "description": "How long to wait before returning control to the caller." }, "request": { "$ref": "#/definitions/apiupdatev1Request", @@ -8928,7 +8928,7 @@ }, "stage": { "$ref": "#/definitions/v1UpdateWorkflowExecutionLifecycleStage", - "description": "The most advanced lifecycle stage that the Update is known to have\nreached, where lifecycle stages are ordered\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.\nUNSPECIFIED will be returned if and only if the server's maximum wait\ntime was reached before the Update reached the stage specified in the\nrequest WaitPolicy, and before the context deadline expired; clients may\nmay then retry the call as needed." + "description": "The most advanced lifecycle stage that the Update is known to have\nreached, where lifecycle stages are ordered\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.\nIf the server's maximum wait time was reached before the stage requested by the client, then\nthe returned stage may be less than the requested stage. Clients may then retry the call as\nneeded." } } }, @@ -8984,10 +8984,10 @@ "properties": { "lifecycleStage": { "$ref": "#/definitions/v1UpdateWorkflowExecutionLifecycleStage", - "description": "Indicates the update lifecycle stage that the gRPC call should wait for\nbefore returning." + "description": "The update stage that this request should attempt to wait for." } }, - "description": "Specifies to the gRPC server how long the client wants the an update-related\nRPC call to wait before returning control to the caller." + "description": "How long the client wants an update-related RPC call to wait before returning control to the caller." }, "v1WorkerVersionCapabilities": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 0bb6c10b..ac5c72cb 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -6648,9 +6648,7 @@ components: waitPolicy: allOf: - $ref: '#/components/schemas/WaitPolicy' - description: |- - Describes when this request should return - basically whether the - update is synchronous, asynchronous, or somewhere in between. + description: How long to wait before returning control to the caller. request: allOf: - $ref: '#/components/schemas/Request' @@ -6684,14 +6682,12 @@ components: description: |- The most advanced lifecycle stage that the Update is known to have reached, where lifecycle stages are ordered - UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED < UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED < UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED < UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED. - UNSPECIFIED will be returned if and only if the server's maximum wait - time was reached before the Update reached the stage specified in the - request WaitPolicy, and before the context deadline expired; clients may - may then retry the call as needed. + If the server's maximum wait time was reached before the stage requested by the client, then + the returned stage may be less than the requested stage. Clients may then retry the call as + needed. format: enum UpsertWorkflowSearchAttributesEventAttributes: type: object @@ -6728,13 +6724,9 @@ components: - UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED - UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED type: string - description: |- - Indicates the update lifecycle stage that the gRPC call should wait for - before returning. + description: The update stage that this request should attempt to wait for. format: enum - description: |- - Specifies to the gRPC server how long the client wants the an update-related - RPC call to wait before returning control to the caller. + description: How long the client wants an update-related RPC call to wait before returning control to the caller. WorkerVersionCapabilities: type: object properties: diff --git a/temporal/api/update/v1/message.proto b/temporal/api/update/v1/message.proto index db6f9cef..1cb907e3 100644 --- a/temporal/api/update/v1/message.proto +++ b/temporal/api/update/v1/message.proto @@ -35,12 +35,9 @@ import "temporal/api/common/v1/message.proto"; import "temporal/api/enums/v1/update.proto"; import "temporal/api/failure/v1/message.proto"; -// Specifies to the gRPC server how long the client wants the an update-related -// RPC call to wait before returning control to the caller. +// How long the client wants an update-related RPC call to wait before returning control to the caller. message WaitPolicy { - - // Indicates the update lifecycle stage that the gRPC call should wait for - // before returning. + // The update stage that this request should attempt to wait for. temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage lifecycle_stage = 1; } diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 3176cb01..61cd8285 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -1389,8 +1389,7 @@ message UpdateWorkflowExecutionRequest { // part of the same execution chain as this id. string first_execution_run_id = 3; - // Describes when this request should return - basically whether the - // update is synchronous, asynchronous, or somewhere in between. + // How long to wait before returning control to the caller. temporal.api.update.v1.WaitPolicy wait_policy = 4; // The request information that will be delivered all the way down to the @@ -1409,14 +1408,12 @@ message UpdateWorkflowExecutionResponse { // The most advanced lifecycle stage that the Update is known to have // reached, where lifecycle stages are ordered - // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED < // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED < // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED < // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED. - // UNSPECIFIED will be returned if and only if the server's maximum wait - // time was reached before the Update reached the stage specified in the - // request WaitPolicy, and before the context deadline expired; clients may - // may then retry the call as needed. + // If the server's maximum wait time was reached before the stage requested by the client, then + // the returned stage may be less than the requested stage. Clients may then retry the call as + // needed. temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage stage = 3; } @@ -1535,14 +1532,12 @@ message PollWorkflowExecutionUpdateResponse { temporal.api.update.v1.Outcome outcome = 1; // The most advanced lifecycle stage that the Update is known to have // reached, where lifecycle stages are ordered - // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED < // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED < // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED < // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED. - // UNSPECIFIED will be returned if and only if the server's maximum wait - // time was reached before the Update reached the stage specified in the - // request WaitPolicy, and before the context deadline expired; clients may - // may then retry the call as needed. + // If the server's maximum wait time was reached before the stage requested by the client, then + // the returned stage may be less than the requested stage. Clients may then retry the call as + // needed. temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage stage = 2; // Sufficient information to address this update. temporal.api.update.v1.UpdateRef update_ref = 3; From 25e39a4ceef69d5919db79c3c95ad5dfccd701a1 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Mon, 20 May 2024 12:03:34 -0400 Subject: [PATCH 2/2] Update update API docs --- openapi/openapiv2.json | 6 +++--- openapi/openapiv3.yaml | 4 ++-- temporal/api/update/v1/message.proto | 2 +- temporal/api/workflowservice/v1/request_response.proto | 5 ++--- 4 files changed, 8 insertions(+), 9 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 0fd91f3c..5acf6968 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -3457,7 +3457,7 @@ }, "waitPolicy": { "$ref": "#/definitions/v1WaitPolicy", - "description": "How long to wait before returning control to the caller." + "description": "When this request should return." }, "request": { "type": "object", @@ -8907,7 +8907,7 @@ }, "waitPolicy": { "$ref": "#/definitions/v1WaitPolicy", - "description": "How long to wait before returning control to the caller." + "description": "When this request should return." }, "request": { "$ref": "#/definitions/apiupdatev1Request", @@ -8987,7 +8987,7 @@ "description": "The update stage that this request should attempt to wait for." } }, - "description": "How long the client wants an update-related RPC call to wait before returning control to the caller." + "description": "Specifies when an update-related request should return." }, "v1WorkerVersionCapabilities": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index ac5c72cb..6dc45faf 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -6648,7 +6648,7 @@ components: waitPolicy: allOf: - $ref: '#/components/schemas/WaitPolicy' - description: How long to wait before returning control to the caller. + description: When this request should return. request: allOf: - $ref: '#/components/schemas/Request' @@ -6726,7 +6726,7 @@ components: type: string description: The update stage that this request should attempt to wait for. format: enum - description: How long the client wants an update-related RPC call to wait before returning control to the caller. + description: Specifies when an update-related request should return. WorkerVersionCapabilities: type: object properties: diff --git a/temporal/api/update/v1/message.proto b/temporal/api/update/v1/message.proto index 1cb907e3..bd111d3c 100644 --- a/temporal/api/update/v1/message.proto +++ b/temporal/api/update/v1/message.proto @@ -35,7 +35,7 @@ import "temporal/api/common/v1/message.proto"; import "temporal/api/enums/v1/update.proto"; import "temporal/api/failure/v1/message.proto"; -// How long the client wants an update-related RPC call to wait before returning control to the caller. +// Specifies when an update-related request should return. message WaitPolicy { // The update stage that this request should attempt to wait for. temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage lifecycle_stage = 1; diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 61cd8285..df3ed767 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -1389,7 +1389,7 @@ message UpdateWorkflowExecutionRequest { // part of the same execution chain as this id. string first_execution_run_id = 3; - // How long to wait before returning control to the caller. + // When this request should return. temporal.api.update.v1.WaitPolicy wait_policy = 4; // The request information that will be delivered all the way down to the @@ -1518,8 +1518,7 @@ message PollWorkflowExecutionUpdateRequest { temporal.api.update.v1.UpdateRef update_ref = 2; // The identity of the worker/client who is polling this update outcome string identity = 3; - // Describes when this poll request should return a response. - // Omit to request a non-blocking poll. + // When this request should return. Omit to request a non-blocking poll. temporal.api.update.v1.WaitPolicy wait_policy = 4; }