Standalone Activity (#688)

Standalone Activity API

---------

Co-authored-by: Roey Berman <[email protected]>
Co-authored-by: Fred Tzeng <[email protected]>

Author: 3 people

openapi/openapiv2.json

@@ -9,10 +9,26 @@ option java_outer_classname = "MessageProto";
 option ruby_package = "Temporalio::Api::Activity::V1";
 option csharp_namespace = "Temporalio.Api.Activity.V1";
 
+import "google/protobuf/duration.proto";
+import "google/protobuf/timestamp.proto";
+
 import "temporal/api/common/v1/message.proto";
+import "temporal/api/deployment/v1/message.proto";
+import "temporal/api/enums/v1/activity.proto";
+import "temporal/api/enums/v1/workflow.proto";
+import "temporal/api/failure/v1/message.proto";
 import "temporal/api/taskqueue/v1/message.proto";
+import "temporal/api/sdk/v1/user_metadata.proto";
 
-import "google/protobuf/duration.proto";
+// The outcome of a completed activity execution: either a successful result or a failure.
+message ActivityExecutionOutcome {
+    oneof value {
+        // The result if the activity completed successfully.
+        temporal.api.common.v1.Payloads result = 1;
+        // The failure if the activity completed unsuccessfully.
+        temporal.api.failure.v1.Failure failure = 2;
+    }
+}
 
 message ActivityOptions {
     temporal.api.taskqueue.v1.TaskQueue task_queue = 1;
@@ -40,10 +56,142 @@ message ActivityOptions {
     google.protobuf.Duration start_to_close_timeout = 4;
     // Maximum permitted time between successful worker heartbeats.
     google.protobuf.Duration heartbeat_timeout = 5;
-
+    // The retry policy for the activity. Will never exceed `schedule_to_close_timeout`.
     temporal.api.common.v1.RetryPolicy retry_policy = 6;
 
     // Priority metadata. If this message is not present, or any fields are not
     // present, they inherit the values from the workflow.
     temporal.api.common.v1.Priority priority = 7;
-}
+}
+
+// Information about a standalone activity.
+message ActivityExecutionInfo {
+    // Unique identifier of this activity within its namespace along with run ID (below).
+    string activity_id = 1;
+    string run_id = 2;
+
+    // The type of the activity, a string that maps to a registered activity on a worker.
+    temporal.api.common.v1.ActivityType activity_type = 3;
+    // A general status for this activity, indicates whether it is currently running or in one of the terminal statuses.
+    temporal.api.enums.v1.ActivityExecutionStatus status = 4;
+    // More detailed breakdown of ACTIVITY_EXECUTION_STATUS_RUNNING.
+    temporal.api.enums.v1.PendingActivityState run_state = 5;
+
+    string task_queue = 6;
+
+    // Indicates how long the caller is willing to wait for an activity completion. Limits how long
+    // retries will be attempted.
+    //
+    // (-- api-linter: core::0140::prepositions=disabled
+    //     aip.dev/not-precedent: "to" is used to indicate interval. --)
+    google.protobuf.Duration schedule_to_close_timeout = 7;
+    // Limits time an activity task can stay in a task queue before a worker picks it up. This
+    // timeout is always non retryable, as all a retry would achieve is to put it back into the same
+    // queue. Defaults to `schedule_to_close_timeout`.
+    //
+    // (-- api-linter: core::0140::prepositions=disabled
+    //     aip.dev/not-precedent: "to" is used to indicate interval. --)
+    google.protobuf.Duration schedule_to_start_timeout = 8;
+    // Maximum time a single activity attempt is allowed to execute after being picked up by a worker. This
+    // timeout is always retryable.
+    //
+    // (-- api-linter: core::0140::prepositions=disabled
+    //     aip.dev/not-precedent: "to" is used to indicate interval. --)
+    google.protobuf.Duration start_to_close_timeout = 9;
+
+    // Maximum permitted time between successful worker heartbeats.
+    google.protobuf.Duration heartbeat_timeout = 10;
+
+    // The retry policy for the activity. Will never exceed `schedule_to_close_timeout`.
+    temporal.api.common.v1.RetryPolicy retry_policy = 11;
+
+    // Details provided in the last recorded activity heartbeat.
+    temporal.api.common.v1.Payloads heartbeat_details = 12;
+    // Time the last heartbeat was recorded.
+    google.protobuf.Timestamp last_heartbeat_time = 13;
+    // Time the last attempt was started.
+    google.protobuf.Timestamp last_started_time = 14;
+    // The attempt this activity is currently on. Incremented each time a new attempt is scheduled.
+    int32 attempt = 15;
+    // How long this activity has been running for, including all attempts and backoff between attempts.
+    google.protobuf.Duration execution_duration = 16;
+    // Time the activity was originally scheduled via a StartActivityExecution request.
+    google.protobuf.Timestamp schedule_time = 17;
+    // Scheduled time + schedule to close timeout.
+    google.protobuf.Timestamp expiration_time = 18;
+    // Time when the activity transitioned to a closed state.
+    google.protobuf.Timestamp close_time = 19;
+
+    // Failure details from the last failed attempt.
+    temporal.api.failure.v1.Failure last_failure = 20;
+    string last_worker_identity = 21;
+
+    // Time from the last attempt failure to the next activity retry.
+    // If the activity is currently running, this represents the next retry interval in case the attempt fails.
+    // If activity is currently backing off between attempt, this represents the current retry interval.
+    // If there is no next retry allowed, this field will be null.
+    // This interval is typically calculated from the specified retry policy, but may be modified if an activity fails
+    // with a retryable application failure specifying a retry delay.
+    google.protobuf.Duration current_retry_interval = 22;
+
+    // The time when the last activity attempt completed. If activity has not been completed yet, it will be null.
+    google.protobuf.Timestamp last_attempt_complete_time = 23;
+
+    // The time when the next activity attempt will be scheduled.
+    // If activity is currently scheduled or started, this field will be null.
+    google.protobuf.Timestamp next_attempt_schedule_time = 24;
+
+    // The Worker Deployment Version this activity was dispatched to most recently.
+    // If nil, the activity has not yet been dispatched or was last dispatched to an unversioned worker.
+    temporal.api.deployment.v1.WorkerDeploymentVersion last_deployment_version = 25;
+
+    // Priority metadata.
+    temporal.api.common.v1.Priority priority = 26;
+
+    // Incremented each time the activity's state is mutated in persistence.
+    int64 state_transition_count = 27;
+
+    // Updated once on scheduled and once on terminal status.
+    int64 state_size_bytes = 28;
+
+    temporal.api.common.v1.SearchAttributes search_attributes = 29;
+    temporal.api.common.v1.Header header = 30;
+    // Metadata for use by user interfaces to display the fixed as-of-start summary and details of the activity.
+    temporal.api.sdk.v1.UserMetadata user_metadata = 31;
+
+    // Set if activity cancelation was requested.
+    string canceled_reason = 32;
+}
+
+// Limited activity information returned in the list response.
+// When adding fields here, ensure that it is also present in ActivityExecutionInfo (note that it
+// may already be present in ActivityExecutionInfo but not at the top-level).
+message ActivityExecutionListInfo {
+    // A unique identifier of this activity within its namespace along with run ID (below).
+    string activity_id = 1;
+    // The run ID of the standalone activity.
+    string run_id = 2;
+
+    // The type of the activity, a string that maps to a registered activity on a worker.
+    temporal.api.common.v1.ActivityType activity_type = 3;
+    // Time the activity was originally scheduled via a StartActivityExecution request.
+    google.protobuf.Timestamp schedule_time = 4;
+    // If the activity is in a terminal status, this field represents the time the activity transitioned to that status.
+    google.protobuf.Timestamp close_time = 5;
+    // Only scheduled and terminal statuses appear here. More detailed information in PendingActivityInfo but not
+    // available in the list response.
+    temporal.api.enums.v1.ActivityExecutionStatus status = 6;
+
+    // Search attributes from the start request.
+    temporal.api.common.v1.SearchAttributes search_attributes = 7;
+
+    // The task queue this activity was scheduled on when it was originally started, updated on activity options update.
+    string task_queue = 8;
+    // Updated on terminal status.
+    int64 state_transition_count = 9;
+    // Updated once on scheduled and once on terminal status.
+    int64 state_size_bytes = 10;
+    // The difference between close time and scheduled time.
+    // This field is only populated if the activity is closed.
+    google.protobuf.Duration execution_duration = 11;
+}

openapi/openapiv3.yaml

@@ -346,4 +346,3 @@ message WorkerSelector {
         string worker_instance_key = 1;
     }
 }
-

temporal/api/activity/v1/message.proto

@@ -0,0 +1,81 @@
+syntax = "proto3";
+
+package temporal.api.enums.v1;
+
+option go_package = "go.temporal.io/api/enums/v1;enums";
+option java_package = "io.temporal.api.enums.v1";
+option java_multiple_files = true;
+option java_outer_classname = "ActivityProto";
+option ruby_package = "Temporalio::Api::Enums::V1";
+option csharp_namespace = "Temporalio.Api.Enums.V1";
+
+// Status of a standalone activity.
+// The status is updated once, when the activity is originally scheduled, and again when the activity reaches a terminal
+// status.
+// (-- api-linter: core::0216::synonyms=disabled
+//     aip.dev/not-precedent: Named consistently with WorkflowExecutionStatus. --)
+enum ActivityExecutionStatus {
+    ACTIVITY_EXECUTION_STATUS_UNSPECIFIED = 0;
+
+    // The activity has not reached a terminal status. See PendingActivityState for the run state
+    // (SCHEDULED, STARTED, or CANCEL_REQUESTED).
+    ACTIVITY_EXECUTION_STATUS_RUNNING = 1;
+
+    // The activity completed successfully. An activity can complete even after cancellation is
+    // requested if the worker calls RespondActivityTaskCompleted before acknowledging cancellation.
+    ACTIVITY_EXECUTION_STATUS_COMPLETED = 2;
+
+    // The activity failed. Causes:
+    // - Worker returned a non-retryable failure
+    // - RetryPolicy.maximum_attempts exhausted
+    // - Attempt failed after cancellation was requested (retries blocked)
+    ACTIVITY_EXECUTION_STATUS_FAILED = 3;
+
+    // The activity was canceled. Reached when:
+    // - Cancellation requested while SCHEDULED (immediate), or
+    // - Cancellation requested while STARTED and worker called RespondActivityTaskCanceled.
+    //
+    // Workers discover cancellation requests via heartbeat responses (cancel_requested=true).
+    // Activities that do not heartbeat will not learn of cancellation and may complete, fail, or
+    // time out normally. CANCELED requires explicit worker acknowledgment or immediate cancellation
+    // of a SCHEDULED activity.
+    ACTIVITY_EXECUTION_STATUS_CANCELED = 4;
+
+    // The activity was terminated. Immediate; does not wait for worker acknowledgment.
+    ACTIVITY_EXECUTION_STATUS_TERMINATED = 5;
+
+    // The activity timed out. See TimeoutType for the specific timeout.
+    // - SCHEDULE_TO_START and SCHEDULE_TO_CLOSE timeouts always result in TIMED_OUT.
+    // - START_TO_CLOSE and HEARTBEAT may retry if RetryPolicy permits; TIMED_OUT is
+    //   reached when retry is blocked (RetryPolicy.maximum_attempts exhausted,
+    //   SCHEDULE_TO_CLOSE would be exceeded, or cancellation has been requested).
+    ACTIVITY_EXECUTION_STATUS_TIMED_OUT = 6;
+}
+
+// Defines whether to allow re-using an activity ID from a previously *closed* activity.
+// If the request is denied, the server returns an `ActivityExecutionAlreadyStarted` error.
+//
+// See `ActivityIdConflictPolicy` for handling ID duplication with a *running* activity.
+enum ActivityIdReusePolicy {
+    ACTIVITY_ID_REUSE_POLICY_UNSPECIFIED = 0;
+    // Always allow starting an activity using the same activity ID.
+    ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE = 1;
+    // Allow starting an activity using the same ID only when the last activity's final state is one
+    // of {failed, canceled, terminated, timed out}.
+    ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY = 2;
+    // Do not permit re-use of the ID for this activity. Future start requests could potentially change the policy,
+    // allowing re-use of the ID.
+    ACTIVITY_ID_REUSE_POLICY_REJECT_DUPLICATE = 3;
+}
+
+// Defines what to do when trying to start an activity with the same ID as a *running* activity.
+// Note that it is *never* valid to have two running instances of the same activity ID.
+//
+// See `ActivityIdReusePolicy` for handling activity ID duplication with a *closed* activity.
+enum ActivityIdConflictPolicy {
+    ACTIVITY_ID_CONFLICT_POLICY_UNSPECIFIED = 0;
+    // Don't start a new activity; instead return `ActivityExecutionAlreadyStarted` error.
+    ACTIVITY_ID_CONFLICT_POLICY_FAIL = 1;
+    // Don't start a new activity; instead return a handle for the running activity.
+    ACTIVITY_ID_CONFLICT_POLICY_USE_EXISTING = 2;
+}

temporal/api/common/v1/message.proto

@@ -121,3 +121,11 @@ message MultiOperationExecutionFailure {
         repeated google.protobuf.Any details = 3;
     }
 }
+
+// An error indicating that an activity execution failed to start. Returned when there is an existing activity with the
+// given activity ID, and the given ID reuse and conflict policies do not permit starting a new one or attaching to an
+// existing one.
+message ActivityExecutionAlreadyStartedFailure {
+    string start_request_id = 1;
+    string run_id = 2;
+}