Add activiy APIs - pause, reset, resume, describe #456

ychebotarev · 2024-10-01T18:29:30Z

Add definitions for DescribeActivity, PauseActivity, ResumeActivity and ResetActivity API

Part of Activity API work.

No.

cretz · 2024-10-01T18:52:12Z

temporal/api/workflowservice/v1/request_response.proto

+    // Activity options after an update
+    temporal.api.activity.v1.ActivityOptions activity_options = 1;
+
+    // Activity state
+    temporal.api.enums.v1.ActivityState activity_state = 2;


I wonder if there is value in temporal.api.activity.v1.ActivityDescription that encompasses these and maybe more in the future. Arguably this API and pending activity API have a lot of model overlap.

This does has a lot of in common with PendingActivityInfo. And I wish I can just use PendingActivityInfo. But - PendingActivityInfo is more "internal". It has lots of fields that are at best "situational", etc.
I though it will be cleaner if we have a separate structure.

Ignoring the pending activity info part, I still wonder if a combination of these things (and potentially more in the future) deserves an encompassing ActivityDescription message.

Just like "DescribeWorkflowExecutionResponse", I think this structure is the one to have all potential fields, and wrapping those fields into ActivityDescription message doesn't add much. It is an extra level of indirection.

temporal/api/workflowservice/v1/service.proto

cretz

This looks good to me.

The only reason I am hesitant to approve is I would like to see if we can get implementation (mostly) done before merging just in case we learn things during implementation. But otherwise, effectively "approved" from my POV.

temporal/api/enums/v1/activity.proto

bergundy · 2024-10-02T19:17:41Z

temporal/api/workflowservice/v1/service.proto

@@ -871,5 +870,71 @@ service WorkflowService {
        };
    }

-}
+    // DescribeActivityById is called by the client to get current activity options and state.


Does this only return pending activities? Otherwise, how does this handle when two activities with the same ID (yes, that's supported as long as they're not both pending).

I'm asking because DescribeWorkflowExecution only returns pending activities as those are stored in mutable state. If you want to return finished activities, you'll need to load history.

only pending activities

Put this in the docstring.

bergundy · 2024-10-02T19:19:29Z

temporal/api/workflowservice/v1/request_response.proto

+    // If activity was paused, it will be kept paused after reset
+    bool keep_paused = 7;


Should we support reset and pause in the same request?

It sounds like we're still not aligned here, as I still am worried about unpausing being the default.
To give us time to collect more opinions, can we leave it out for this PR and consider adding it later after consultation with folks like Roey/Max/Chad?

Should we support reset and pause in the same request?

I think they are different operations entirely. Whether we want to combine operations or not in general I don't have a strong opinion, but I don't think these two are special.

To give us time to collect more opinions, can we leave it out for this PR

Can you clarify which part to leave out of the PR? Pausing? Reset? If both are still in, we need to define some behavior for resetting a paused activity and a default. Whether that default is unpause or remain paused I have no opinion on.

This is after long discussions with Drew. Basically if user paused and then reset - in some cases he may want to keep paused activities to stay paused. We right now discussing what should be "by default" - keep paused and specify a flag to resume, or resume and specify a flag to keep paused.

bergundy · 2024-10-02T19:20:22Z

temporal/api/workflowservice/v1/request_response.proto

@@ -1695,3 +1696,92 @@ message UpdateActivityOptionsByIdResponse {
    // Activity options after an update
    temporal.api.activity.v1.ActivityOptions activity_options = 1;
 }
+
+message DescribeActivityByIdRequest {
+    // Namespace of the workflow which scheduled this activity


Please put . at the end of sentences to be consistent with the rest of the docstrings in this file.

Skipping UpdateActivityOptionsByIdRequest (which doesn't have dots for the same reason), scrolling above XXXNexus request/responses:

PollWorkflowExecutionUpdateResponse - no dots
PollWorkflowExecutionUpdateRequest - no dots
ListBatchOperationsResponse - no dots
ListBatchOperationsRequest - no dots
DescribeBatchOperationResponse - no dots
StopBatchOperationRequest - no dots

activity related:
PollActivityTaskQueueResponse - no dots
RecordActivityTaskHeartbeatRequest - no dots
RecordActivityTaskHeartbeatByIdRequest- no dots

from what I see not having . at the end is more consistent with the rest of the docstrings in this file.

I do also see some with dots, but seems they are minority.
Though if we go top-to-bottom - first few have dots...
Hm, also it looks like this is a subject of some heated discussions online. And Google proto style guidelines don't have recommendations.

Let's have periods in our doc strings. I think the majority do.

temporal/api/enums/v1/activity.proto

bergundy · 2024-10-02T19:25:16Z

temporal/api/enums/v1/activity.proto

+  ACTIVITY_STATE_UNSPECIFIED = 0;
+  ACTIVITY_STATE_SCHEDULED = 1;
+  ACTIVITY_STATE_STARTED = 2;
+  ACTIVITY_STATE_PAUSED = 3;


I'm not loving PAUSED as a separate state, I prefer to model pause as a separate dimension to be able to express things like "started and paused", which is a valid state.

If you do think that PAUSED is a valid state, please update PendingActivityState to reflect this as well.

I will add PAUSED and BACKING_OFF to PendingActivityState

bergundy · 2024-10-02T19:27:05Z

This looks good to me.

The only reason I am hesitant to approve is I would like to see if we can get implementation (mostly) done before merging just in case we learn things during implementation. But otherwise, effectively "approved" from my POV.

+1 to this, please use a feature branch until the implementation solidifies and you're confident in the API.

drewhoskins-temporal · 2024-10-02T22:26:21Z

openapi/openapiv3.yaml

+          required: true
+          schema:
+            type: string
+        - name: workflowId


Should this be required? If not, can comments explain the requirements ?

This is auto-generated code for the HTTP API and is unrelated to whether something is required from the gRPC side. The generator only marks things as required that are present in the URL path and we had decided in the past that activity RPC URLs are not sub-URLs of the workflow. We may be able to change that though if we want (or add additional bindings). We may also be able to look in to validation annotations to be more specific about which fields are required in proto, but that is a general/separate topic and not specific to this PR.

drewhoskins-temporal · 2024-10-02T22:29:28Z

temporal/api/workflowservice/v1/request_response.proto

+    // Id of the activity we're updating
+    string activity_id = 4;
+
+    // The identity of the client who initiated this request


What's this for?
Is this a freeform user-specified field, or otherwise, how does somebody obtain one?

The "client identity" is present in almost all actionable RPCs and is a unique client identifier sent by the SDK. It allows you to uniquely identify a client that did something (we often store this on events and other places). This is a settable option in every SDK and usually defaults to a string with process ID and hostname.

drewhoskins-temporal · 2024-10-02T22:34:07Z

temporal/api/workflowservice/v1/request_response.proto

+    // If activity was paused, it will be kept paused after reset
+    bool keep_paused = 7;


It sounds like we're still not aligned here, as I still am worried about unpausing being the default.
To give us time to collect more opinions, can we leave it out for this PR and consider adding it later after consultation with folks like Roey/Max/Chad?

Add activiy APSs - pause, reset, resume, descrive

9d88e12

ychebotarev requested review from a team as code owners October 1, 2024 18:29

cretz reviewed Oct 1, 2024

View reviewed changes

ychebotarev added 3 commits October 1, 2024 14:56

work on comments

488b9fa

linter

e3ce8ad

regenerate openapi files

e4c0cfb

cretz reviewed Oct 2, 2024

View reviewed changes

temporal/api/workflowservice/v1/service.proto Outdated Show resolved Hide resolved

add more comments

b0c0ac9

cretz reviewed Oct 2, 2024

View reviewed changes

bergundy reviewed Oct 2, 2024

View reviewed changes

temporal/api/enums/v1/activity.proto Show resolved Hide resolved

bergundy reviewed Oct 2, 2024

View reviewed changes

temporal/api/enums/v1/activity.proto Show resolved Hide resolved

bergundy reviewed Oct 2, 2024

View reviewed changes

drewhoskins-temporal changed the title ~~Add activiy APSs - pause, reset, resume, descrive~~ Add activiy APIs - pause, reset, resume, describe Oct 2, 2024

drewhoskins-temporal reviewed Oct 2, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add activiy APIs - pause, reset, resume, describe #456

Add activiy APIs - pause, reset, resume, describe #456

ychebotarev commented Oct 1, 2024 •

edited

Loading

cretz Oct 1, 2024

ychebotarev Oct 1, 2024

cretz Oct 2, 2024

ychebotarev Oct 2, 2024

cretz left a comment •

edited

Loading

bergundy Oct 2, 2024

bergundy Oct 2, 2024

ychebotarev Oct 4, 2024

bergundy Oct 4, 2024

bergundy Oct 2, 2024

drewhoskins-temporal Oct 2, 2024

cretz Oct 3, 2024

ychebotarev Oct 3, 2024

bergundy Oct 2, 2024

ychebotarev Oct 4, 2024

bergundy Oct 4, 2024

bergundy Oct 2, 2024

bergundy Oct 2, 2024

ychebotarev Oct 4, 2024

bergundy commented Oct 2, 2024

drewhoskins-temporal Oct 2, 2024

cretz Oct 3, 2024

drewhoskins-temporal Oct 2, 2024

cretz Oct 3, 2024 •

edited

Loading

drewhoskins-temporal Oct 2, 2024

		// If activity was paused, it will be kept paused after reset
		bool keep_paused = 7;

Add activiy APIs - pause, reset, resume, describe #456

Are you sure you want to change the base?

Add activiy APIs - pause, reset, resume, describe #456

Conversation

ychebotarev commented Oct 1, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cretz left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bergundy commented Oct 2, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cretz Oct 3, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ychebotarev commented Oct 1, 2024 •

edited

Loading

cretz left a comment •

edited

Loading

cretz Oct 3, 2024 •

edited

Loading