Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Evolve documentation of update polling parameters #406

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Evolve documentation of update polling parameters #406

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ccb8b29
Evolve documentation of update polling parameters
dandavison May 20, 2024
25e39a4
Update update API docs
dandavison May 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions openapi/openapiv2.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How long implies that this specifies a duration?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, you're right. I've now changed it to

message UpdateWorkflowExecutionRequest {
    ...
    // When this request should return.
    temporal.api.update.v1.WaitPolicy wait_policy = 4;
    ...
}

message PollWorkflowExecutionUpdateRequest {
    ...
    // When this request should return. Omit to request a non-blocking poll.
    temporal.api.update.v1.WaitPolicy wait_policy = 4;
    ...
}

},
"request": {
"type": "object",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand All @@ -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."
}
}
},
Expand Down Expand Up @@ -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",
Expand Down
20 changes: 6 additions & 14 deletions openapi/openapiv3.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
7 changes: 2 additions & 5 deletions temporal/api/update/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

Expand Down
19 changes: 7 additions & 12 deletions temporal/api/workflowservice/v1/request_response.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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;
}

Expand Down Expand Up @@ -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;
Expand Down
Loading