New polling API design

Author: dandavison

temporal/api/workflowservice/v1/request_response.proto

@@ -2674,57 +2674,59 @@ message PollActivityExecutionRequest {
     string activity_id = 2;
     // Activity run ID. If empty the request targets the latest run.
     string run_id = 3;
-    // Include the info field from the response.
-    bool include_info = 4;
     // Include the input field in the response.
-    bool include_input = 5;
-    // Include the outcome field in the response.
-    bool include_outcome = 6;
-
-    message StateChangeWaitOptions {
-        // Token from a previous PollActivityExecutionResponse used to inform the server of the
-        // last state seen by the caller. If present, run_id must also be present.
-        bytes long_poll_token = 1;
-    }
-    message CompletionWaitOptions {}
-
-    // If present, the request will be handled as a long-poll. If absent, a response will be
-    // returned immediately containing the current activity state.
-    oneof wait_policy {
-        // Wait for any change in activity state before responding. If long_poll_token is absent
-        // then the current state will be returned immediately without any wait. Otherwise the
-        // server will wait until activity state differs from that encoded in the token before
-        // returning the new state. Note that activity state may change multiple times between
-        // requests, therefore it is not guaranteed that a client making a sequence of long-poll
-        // requests will see a complete sequence of state changes.
-        StateChangeWaitOptions wait_any_state_change = 8;
-        // Wait for the activity to complete before responding.
-        // long_poll_token is currently ignored when waiting for completion
-        CompletionWaitOptions wait_completion = 9;
-    }
+    bool include_input = 4;
+    // Include the result/failure in the response if the activity has completed.
+    bool include_result = 5;
+    // Token from a previous PollActivityExecutionResponse. If present, long-poll until activity
+    // state changes from the state encoded in this token. If absent, return current state immediately.
+    // If present, run_id must also be present.
+    // Note that activity state may change multiple times between requests, therefore it is not
+    // guaranteed that a client making a sequence of long-poll requests will see a complete
+    // sequence of state changes.
+    bytes long_poll_token = 6;
 }
 
 message PollActivityExecutionResponse {
     // The run ID of the activity, useful when run_id was not specified in the request.
     string run_id = 1;
 
-    // Only set if include_info was true in the request.
+    // Information about the activity execution.
     temporal.api.activity.v1.ActivityExecutionInfo info = 2;
 
     // Serialized activity input, passed as arguments to the activity function.
+    // Only set if include_input was true in the request.
     temporal.api.common.v1.Payloads input = 3;
 
-    // Only set if the activity is completed and include_outcome was true in the request.
+    // Only set if the activity is completed and include_result was true in the request.
     oneof outcome {
         // The result if the activity completed successfully.
         temporal.api.common.v1.Payloads result = 4;
         // The failure if the activity completed unsuccessfully.
         temporal.api.failure.v1.Failure failure = 5;
     }
 
-    // Token to use for a follow-on request using wait_any_state_change.
-    // Only set if wait_policy was wait_any_state_change and the activity is not complete.
-    bytes state_change_long_poll_token = 6;
+    // Token for follow-on long-poll requests. Absent only if the activity is complete.
+    bytes long_poll_token = 6;
+}
+
+message PollActivityExecutionOutcomeRequest {
+    string namespace = 1;
+    string activity_id = 2;
+    // Activity run ID. If empty the request targets the latest run.
+    string run_id = 3;
+}
+
+message PollActivityExecutionOutcomeResponse {
+    // The run ID of the activity, useful when run_id was not specified in the request.
+    string run_id = 1;
+
+    oneof outcome {
+        // The result if the activity completed successfully.
+        temporal.api.common.v1.Payloads result = 2;
+        // The failure if the activity completed unsuccessfully.
+        temporal.api.failure.v1.Failure failure = 3;
+    }
 }
 
 

temporal/api/workflowservice/v1/service.proto

@@ -1403,11 +1403,11 @@ service WorkflowService {
         };
     }
 
-    // PollActivityExecution returns the status and/or outcome of an activity execution.
-    // Supported use cases include
+    // PollActivityExecution returns information about an activity execution.
+    // Supported use cases include:
     // - Get current activity info without waiting
-    // - Wait for next state change and return activity info
-    // - Wait for completion and return outcome
+    // - Long-poll for next state change and return new activity info
+    // Response can optionally include activity input or result (if the activity has completed)
     rpc PollActivityExecution (PollActivityExecutionRequest) returns (PollActivityExecutionResponse) {
         option (google.api.http) = {
             get: "/namespaces/{namespace}/activities/{activity_id}"
@@ -1417,6 +1417,17 @@ service WorkflowService {
         };
     }
 
+    // PollActivityExecutionOutcome long-polls for an activity execution to complete and returns
+    // the outcome (result or failure).
+    rpc PollActivityExecutionOutcome (PollActivityExecutionOutcomeRequest) returns (PollActivityExecutionOutcomeResponse) {
+        option (google.api.http) = {
+            get: "/namespaces/{namespace}/activities/{activity_id}/outcome"
+            additional_bindings {
+                get: "/api/v1/namespaces/{namespace}/activities/{activity_id}/outcome"
+            }
+        };
+    }
+
     // ListActivityExecutions is a visibility API to list activity executions in a specific namespace.
     rpc ListActivityExecutions (ListActivityExecutionsRequest) returns (ListActivityExecutionsResponse) {
         option (google.api.http) = {