Skip to content

Commit 3a34532

Browse files
gowgow
authored
[Workflow Pause] Proto changes (#653)
<!-- Describe what has changed in this PR --> Adding proto changes that are required to implement Workflow Pause/Unpause feature. Added, - `WorkflowExecutionStatus.WORKFLOW_EXECUTION_STATUS_PAUSED` enum - `EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED` & `EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED` event enums and corresponding event attributes - `PauseWorkflowExecution` & `UnpauseWorkflowExecution` gRPC along with corresponding request/responses. <!-- Tell your future self why have you made these changes --> **Why?** These changes are needed to implement workflow pause/unpause feature. <!-- Are there any breaking changes on binary or code level? --> **Breaking changes** Introduction of new status `WORKFLOW_EXECUTION_STATUS_PAUSED` may break any saved visibility queries that may have assumed `WorkflowExecutionStatus != 'Running'` returns all closed workflows.
1 parent 35aacca commit 3a34532

File tree

8 files changed

+525
-6
lines changed

8 files changed

+525
-6
lines changed

‎openapi/openapiv2.json‎

Lines changed: 217 additions & 4 deletions
Large diffs are not rendered by default.

‎openapi/openapiv3.yaml‎

Lines changed: 203 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6204,6 +6204,52 @@ paths:
62046204
application/json:
62056205
schema:
62066206
$ref: '#/components/schemas/Status'
6207+
/namespaces/{namespace}/workflows/{workflowId}/pause:
6208+
post:
6209+
tags:
6210+
- WorkflowService
6211+
description: |-
6212+
Note: This is an experimental API and the behavior may change in a future release.
6213+
PauseWorkflowExecution pauses the workflow execution specified in the request. Pausing a workflow execution results in
6214+
- The workflow execution status changes to `PAUSED` and a new WORKFLOW_EXECUTION_PAUSED event is added to the history
6215+
- No new workflow tasks or activity tasks are dispatched.
6216+
- Any workflow task currently executing on the worker will be allowed to complete.
6217+
- Any activity task currently executing will be paused.
6218+
- All server-side events will continue to be processed by the server.
6219+
- Queries & Updates on a paused workflow will be rejected.
6220+
operationId: PauseWorkflowExecution
6221+
parameters:
6222+
- name: namespace
6223+
in: path
6224+
description: Namespace of the workflow to pause.
6225+
required: true
6226+
schema:
6227+
type: string
6228+
- name: workflowId
6229+
in: path
6230+
description: ID of the workflow execution to be paused. Required.
6231+
required: true
6232+
schema:
6233+
type: string
6234+
requestBody:
6235+
content:
6236+
application/json:
6237+
schema:
6238+
$ref: '#/components/schemas/PauseWorkflowExecutionRequest'
6239+
required: true
6240+
responses:
6241+
"200":
6242+
description: OK
6243+
content:
6244+
application/json:
6245+
schema:
6246+
$ref: '#/components/schemas/PauseWorkflowExecutionResponse'
6247+
default:
6248+
description: Default error response
6249+
content:
6250+
application/json:
6251+
schema:
6252+
$ref: '#/components/schemas/Status'
62076253
/namespaces/{namespace}/workflows/{workflowId}/signal-with-start/{signalName}:
62086254
post:
62096255
tags:
@@ -6258,6 +6304,49 @@ paths:
62586304
application/json:
62596305
schema:
62606306
$ref: '#/components/schemas/Status'
6307+
/namespaces/{namespace}/workflows/{workflowId}/unpause:
6308+
post:
6309+
tags:
6310+
- WorkflowService
6311+
description: |-
6312+
Note: This is an experimental API and the behavior may change in a future release.
6313+
UnpauseWorkflowExecution unpauses a previously paused workflow execution specified in the request.
6314+
Unpausing a workflow execution results in
6315+
- The workflow execution status changes to `RUNNING` and a new WORKFLOW_EXECUTION_UNPAUSED event is added to the history
6316+
- Workflow tasks and activity tasks are resumed.
6317+
operationId: UnpauseWorkflowExecution
6318+
parameters:
6319+
- name: namespace
6320+
in: path
6321+
description: Namespace of the workflow to unpause.
6322+
required: true
6323+
schema:
6324+
type: string
6325+
- name: workflowId
6326+
in: path
6327+
description: ID of the workflow execution to be paused. Required.
6328+
required: true
6329+
schema:
6330+
type: string
6331+
requestBody:
6332+
content:
6333+
application/json:
6334+
schema:
6335+
$ref: '#/components/schemas/UnpauseWorkflowExecutionRequest'
6336+
required: true
6337+
responses:
6338+
"200":
6339+
description: OK
6340+
content:
6341+
application/json:
6342+
schema:
6343+
$ref: '#/components/schemas/UnpauseWorkflowExecutionResponse'
6344+
default:
6345+
description: Default error response
6346+
content:
6347+
application/json:
6348+
schema:
6349+
$ref: '#/components/schemas/Status'
62616350
/namespaces/{namespace}/workflows/{workflow_execution.workflow_id}/cancel:
62626351
post:
62636352
tags:
@@ -8670,6 +8759,8 @@ components:
86708759
- EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED
86718760
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_COMPLETED
86728761
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
8762+
- EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
8763+
- EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
86738764
type: string
86748765
format: enum
86758766
version:
@@ -8820,6 +8911,10 @@ components:
88208911
$ref: '#/components/schemas/NexusOperationCancelRequestCompletedEventAttributes'
88218912
nexusOperationCancelRequestFailedEventAttributes:
88228913
$ref: '#/components/schemas/NexusOperationCancelRequestFailedEventAttributes'
8914+
workflowExecutionPausedEventAttributes:
8915+
$ref: '#/components/schemas/WorkflowExecutionPausedEventAttributes'
8916+
workflowExecutionUnpausedEventAttributes:
8917+
$ref: '#/components/schemas/WorkflowExecutionUnpausedEventAttributes'
88238918
description: |-
88248919
History events are the method by which Temporal SDKs advance (or recreate) workflow state.
88258920
See the `EventType` enum for more info about what each event is for.
@@ -9664,6 +9759,32 @@ components:
96649759
reason:
96659760
type: string
96669761
description: Reason why rule was created. Populated from rule description.
9762+
PauseWorkflowExecutionRequest:
9763+
type: object
9764+
properties:
9765+
namespace:
9766+
type: string
9767+
description: Namespace of the workflow to pause.
9768+
workflowId:
9769+
type: string
9770+
description: ID of the workflow execution to be paused. Required.
9771+
runId:
9772+
type: string
9773+
description: Run ID of the workflow execution to be paused. Optional. If not provided, the current run of the workflow will be paused.
9774+
identity:
9775+
type: string
9776+
description: The identity of the client who initiated this request.
9777+
reason:
9778+
type: string
9779+
description: Reason to pause the workflow execution.
9780+
requestId:
9781+
type: string
9782+
description: A unique identifier for this pause request for idempotence. Typically UUIDv4.
9783+
description: Request to pause a workflow execution.
9784+
PauseWorkflowExecutionResponse:
9785+
type: object
9786+
properties: {}
9787+
description: Response to a successful PauseWorkflowExecution request.
96679788
Payload:
96689789
description: |-
96699790
Represents some binary (byte array) data (ex: activity input parameters or workflow result) with
@@ -10202,6 +10323,7 @@ components:
1020210323
- WORKFLOW_EXECUTION_STATUS_TERMINATED
1020310324
- WORKFLOW_EXECUTION_STATUS_CONTINUED_AS_NEW
1020410325
- WORKFLOW_EXECUTION_STATUS_TIMED_OUT
10326+
- WORKFLOW_EXECUTION_STATUS_PAUSED
1020510327
type: string
1020610328
format: enum
1020710329
QueryWorkflowRequest:
@@ -10576,6 +10698,8 @@ components:
1057610698
- EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED
1057710699
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_COMPLETED
1057810700
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
10701+
- EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
10702+
- EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
1057910703
type: string
1058010704
description: The event type of the history event generated by the request.
1058110705
format: enum
@@ -11134,6 +11258,7 @@ components:
1113411258
- WORKFLOW_EXECUTION_STATUS_TERMINATED
1113511259
- WORKFLOW_EXECUTION_STATUS_CONTINUED_AS_NEW
1113611260
- WORKFLOW_EXECUTION_STATUS_TIMED_OUT
11261+
- WORKFLOW_EXECUTION_STATUS_PAUSED
1113711262
type: string
1113811263
description: |-
1113911264
If the action was start_workflow, this field will reflect an
@@ -12213,6 +12338,7 @@ components:
1221312338
- WORKFLOW_EXECUTION_STATUS_TERMINATED
1221412339
- WORKFLOW_EXECUTION_STATUS_CONTINUED_AS_NEW
1221512340
- WORKFLOW_EXECUTION_STATUS_TIMED_OUT
12341+
- WORKFLOW_EXECUTION_STATUS_PAUSED
1221612342
type: string
1221712343
description: |-
1221812344
Current execution status of the workflow. Typically remains WORKFLOW_EXECUTION_STATUS_RUNNING
@@ -12719,6 +12845,31 @@ components:
1271912845
UnpauseActivityResponse:
1272012846
type: object
1272112847
properties: {}
12848+
UnpauseWorkflowExecutionRequest:
12849+
type: object
12850+
properties:
12851+
namespace:
12852+
type: string
12853+
description: Namespace of the workflow to unpause.
12854+
workflowId:
12855+
type: string
12856+
description: ID of the workflow execution to be paused. Required.
12857+
runId:
12858+
type: string
12859+
description: Run ID of the workflow execution to be paused. Optional. If not provided, the current run of the workflow will be paused.
12860+
identity:
12861+
type: string
12862+
description: The identity of the client who initiated this request.
12863+
reason:
12864+
type: string
12865+
description: Reason to unpause the workflow execution.
12866+
requestId:
12867+
type: string
12868+
description: A unique identifier for this unpause request for idempotence. Typically UUIDv4.
12869+
UnpauseWorkflowExecutionResponse:
12870+
type: object
12871+
properties: {}
12872+
description: Response to a successful UnpauseWorkflowExecution request.
1272212873
UpdateActivityOptionsRequest:
1272312874
type: object
1272412875
properties:
@@ -13867,6 +14018,8 @@ components:
1386714018
- EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED
1386814019
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_COMPLETED
1386914020
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
14021+
- EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
14022+
- EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
1387014023
type: string
1387114024
format: enum
1387214025
description: EventReference is a direct reference to a history event through the event ID.
@@ -13935,6 +14088,8 @@ components:
1393514088
- EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED
1393614089
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_COMPLETED
1393714090
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
14091+
- EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
14092+
- EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
1393814093
type: string
1393914094
format: enum
1394014095
description: RequestIdReference is a indirect reference to a history event through the request ID.
@@ -14152,6 +14307,7 @@ components:
1415214307
- WORKFLOW_EXECUTION_STATUS_TERMINATED
1415314308
- WORKFLOW_EXECUTION_STATUS_CONTINUED_AS_NEW
1415414309
- WORKFLOW_EXECUTION_STATUS_TIMED_OUT
14310+
- WORKFLOW_EXECUTION_STATUS_PAUSED
1415514311
type: string
1415614312
format: enum
1415714313
historyLength:
@@ -14249,6 +14405,10 @@ components:
1424914405
allOf:
1425014406
- $ref: '#/components/schemas/Priority'
1425114407
description: Priority metadata
14408+
pauseInfo:
14409+
allOf:
14410+
- $ref: '#/components/schemas/WorkflowExecutionPauseInfo'
14411+
description: Information about the workflow execution pause operation.
1425214412
description: |-
1425314413
Hold basic information about a workflow execution.
1425414414
This structure is a part of visibility, and thus contain a limited subset of information.
@@ -14284,6 +14444,33 @@ components:
1428414444
identity:
1428514445
type: string
1428614446
description: Optional. The identity of the client who initiated the request that created this event.
14447+
WorkflowExecutionPauseInfo:
14448+
type: object
14449+
properties:
14450+
identity:
14451+
type: string
14452+
description: The identity of the client who paused the workflow execution.
14453+
pausedTime:
14454+
type: string
14455+
description: The time when the workflow execution was paused.
14456+
format: date-time
14457+
reason:
14458+
type: string
14459+
description: The reason for pausing the workflow execution.
14460+
description: WorkflowExecutionPauseInfo contains the information about a workflow execution pause.
14461+
WorkflowExecutionPausedEventAttributes:
14462+
type: object
14463+
properties:
14464+
identity:
14465+
type: string
14466+
description: The identity of the client who paused the workflow execution.
14467+
reason:
14468+
type: string
14469+
description: The reason for pausing the workflow execution.
14470+
requestId:
14471+
type: string
14472+
description: The request ID of the request that paused the workflow execution.
14473+
description: Attributes for an event marking that a workflow execution was paused.
1428714474
WorkflowExecutionSignaledEventAttributes:
1428814475
type: object
1428914476
properties:
@@ -14538,6 +14725,19 @@ components:
1453814725
newExecutionRunId:
1453914726
type: string
1454014727
description: If another run is started by cron or retry, this contains the new run id.
14728+
WorkflowExecutionUnpausedEventAttributes:
14729+
type: object
14730+
properties:
14731+
identity:
14732+
type: string
14733+
description: The identity of the client who unpaused the workflow execution.
14734+
reason:
14735+
type: string
14736+
description: The reason for unpausing the workflow execution.
14737+
requestId:
14738+
type: string
14739+
description: The request ID of the request that unpaused the workflow execution.
14740+
description: Attributes for an event marking that a workflow execution was unpaused.
1454114741
WorkflowExecutionUpdateAcceptedEventAttributes:
1454214742
type: object
1454314743
properties:
@@ -15043,7 +15243,9 @@ components:
1504315243
description: The failure details
1504415244
identity:
1504515245
type: string
15046-
description: "If a worker explicitly failed this task, this field contains the worker's identity. \n When the server generates the failure internally this field is set as 'history-service'."
15246+
description: |-
15247+
If a worker explicitly failed this task, this field contains the worker's identity.
15248+
When the server generates the failure internally this field is set as 'history-service'.
1504715249
baseRunId:
1504815250
type: string
1504915251
description: The original run id of the workflow. For reset workflow.

‎temporal/api/enums/v1/event_type.proto‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,4 +169,8 @@ enum EventType {
169169
EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_COMPLETED = 56;
170170
// A cancellation request for a Nexus operation resulted in an error.
171171
EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED = 57;
172+
// An event that indicates that the workflow execution has been paused.
173+
EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED = 58;
174+
// An event that indicates that the previously paused workflow execution has been unpaused.
175+
EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED = 59;
172176
}

‎temporal/api/enums/v1/workflow.proto‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ enum WorkflowExecutionStatus {
7777
WORKFLOW_EXECUTION_STATUS_TERMINATED = 5;
7878
WORKFLOW_EXECUTION_STATUS_CONTINUED_AS_NEW = 6;
7979
WORKFLOW_EXECUTION_STATUS_TIMED_OUT = 7;
80+
WORKFLOW_EXECUTION_STATUS_PAUSED = 8;
8081
}
8182

8283
enum PendingActivityState {

‎temporal/api/history/v1/message.proto‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -320,7 +320,7 @@ message WorkflowTaskFailedEventAttributes {
320320
temporal.api.enums.v1.WorkflowTaskFailedCause cause = 3;
321321
// The failure details
322322
temporal.api.failure.v1.Failure failure = 4;
323-
// If a worker explicitly failed this task, this field contains the worker's identity.
323+
// If a worker explicitly failed this task, this field contains the worker's identity.
324324
// When the server generates the failure internally this field is set as 'history-service'.
325325
string identity = 5;
326326
// The original run id of the workflow. For reset workflow.
@@ -885,6 +885,26 @@ message WorkflowExecutionUpdateAdmittedEventAttributes {
885885
temporal.api.enums.v1.UpdateAdmittedEventOrigin origin = 2;
886886
}
887887

888+
// Attributes for an event marking that a workflow execution was paused.
889+
message WorkflowExecutionPausedEventAttributes {
890+
// The identity of the client who paused the workflow execution.
891+
string identity = 1;
892+
// The reason for pausing the workflow execution.
893+
string reason = 2;
894+
// The request ID of the request that paused the workflow execution.
895+
string request_id = 3;
896+
}
897+
898+
// Attributes for an event marking that a workflow execution was unpaused.
899+
message WorkflowExecutionUnpausedEventAttributes {
900+
// The identity of the client who unpaused the workflow execution.
901+
string identity = 1;
902+
// The reason for unpausing the workflow execution.
903+
string reason = 2;
904+
// The request ID of the request that unpaused the workflow execution.
905+
string request_id = 3;
906+
}
907+
888908
// Event marking that an operation was scheduled by a workflow via the ScheduleNexusOperation command.
889909
message NexusOperationScheduledEventAttributes {
890910
// Endpoint name, must exist in the endpoint registry.
@@ -1103,6 +1123,8 @@ message HistoryEvent {
11031123
WorkflowExecutionOptionsUpdatedEventAttributes workflow_execution_options_updated_event_attributes = 60;
11041124
NexusOperationCancelRequestCompletedEventAttributes nexus_operation_cancel_request_completed_event_attributes = 61;
11051125
NexusOperationCancelRequestFailedEventAttributes nexus_operation_cancel_request_failed_event_attributes = 62;
1126+
WorkflowExecutionPausedEventAttributes workflow_execution_paused_event_attributes = 63;
1127+
WorkflowExecutionUnpausedEventAttributes workflow_execution_unpaused_event_attributes = 64;
11061128
}
11071129
}
11081130

0 commit comments

Comments
 (0)