Add standalone activity APIs

Missing API support for:

- [ ] PauseActivity
- [ ] UnpauseActivity
- [ ] ResetActivity
- [ ] UpdateActivityOptions

Author: bergundy

openapi/openapiv2.json

@@ -9,10 +9,36 @@ 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";
+// Identifies a specific activity within a namespace. Practically speaking, because run_id is a
+// uuid, a workflow execution is globally unique. Note that many commands allow specifying an empty
+// run id as a way of saying "target the latest run of the activity".
+// TODO: Make this a generic EntityExecution?
+message ActivityExecution {
+    string activity_id = 1;
+    string run_id = 2;
+}
+
+// When StartActivityExecution uses the ID_CONFLICT_POLICY_USE_EXISTING and there is already an existing running
+// activity, OnConflictOptions defines actions to be taken on the existing running activity, updating its state.
+message OnConflictOptions {
+    // Attaches the request ID to the running workflow.
+    bool attach_request_id = 1;
+    // Attaches the completion callbacks to the running workflow.
+    bool attach_completion_callbacks = 2;
+    // Attaches the links to the WorkflowExecutionOptionsUpdatedEvent history event.
+    bool attach_links = 3;
+}
 
 message ActivityOptions {
     temporal.api.taskqueue.v1.TaskQueue task_queue = 1;
@@ -40,6 +66,135 @@ 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;
-}
+}
+
+// Info for a standalone activity.
+message ActivityExecutionInfo {
+    // Unique identifier of this activity within its namespace.
+    ActivityExecution activity_execution = 1;
+
+    // The type of the activity, a string that maps to a registered activity on a worker.
+    temporal.api.common.v1.ActivityType activity_type = 2;
+    // 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 = 3;
+    // More detailed breakdown of ACTIVITY_EXECUTION_STATUS_RUNNING.
+    temporal.api.enums.v1.PendingActivityState run_state = 4;
+    // Details provided in the last recorded activity heartbeat.
+    temporal.api.common.v1.Payloads heartbeat_details = 5;
+    // Time the last heartbeat was recorded.
+    google.protobuf.Timestamp last_heartbeat_time = 6;
+    // Time the last attempt was started.
+    google.protobuf.Timestamp last_started_time = 7;
+    // The attempt this activity is currently on.
+    // Incremented each time a new attempt is started.
+    // TODO: Confirm if this is on scheduled or started.
+    int32 attempt = 8;
+    int32 maximum_attempts = 9;
+    // Time the activity was originally scheduled via a StartActivityExecution request.
+    google.protobuf.Timestamp scheduled_time = 10;
+    // Scheduled time + schedule to close timeout.
+    google.protobuf.Timestamp expiration_time = 11;
+    // Failure details from the last failed attempt.
+    temporal.api.failure.v1.Failure last_failure = 12;
+    string last_worker_identity = 13;
+
+    // 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 = 14;
+
+    // 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 = 15;
+
+    // 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 = 16;
+
+    // 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 = 17;
+
+    // Priority metadata.
+    temporal.api.common.v1.Priority priority = 18;
+
+    // TODO: Move this to a common package?
+    message PauseInfo {
+        // The time when the activity was paused.
+        google.protobuf.Timestamp pause_time = 1;
+
+        message Manual {
+            // The identity of the actor that paused the activity.
+            string identity = 1;
+            // Reason for pausing the activity.
+            string reason = 2;
+        }
+
+        oneof paused_by {
+            // The activity was paused by direct API invocation.
+            Manual manual = 2;
+        }
+    }
+
+    PauseInfo pause_info = 19;
+
+    // Current activity options. May be different from the one used to start the activity.
+    temporal.api.activity.v1.ActivityOptions activity_options = 20;
+
+    // Serialized activity input, passed as arguments to the activity function.
+    temporal.api.common.v1.Payloads input = 21;
+
+    // Incremented each time the activity's state is mutated in persistence.
+    int64 state_transition_count = 22;
+
+    temporal.api.common.v1.SearchAttributes search_attributes = 23;
+    temporal.api.common.v1.Header header = 24;
+    // Whether the activity was started with a request_eager_execution flag set to `true`, indicating that the first
+    // task was delivered inline in the start response, bypassing matching.
+    bool eager_execution_requested = 25;
+
+    // Callbacks to be called by the server when this activity reaches a terminal status.
+    // Callback addresses must be whitelisted in the server's dynamic configuration.
+    repeated temporal.api.common.v1.Callback completion_callbacks = 26;
+    // 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 = 27;
+    // Links to be associated with the activity.
+    repeated temporal.api.common.v1.Link links = 28;
+
+    // Set if activity cancelation was requested.
+    string canceled_reason = 31;
+}
+
+// Limited activity information returned in the list response.
+message ActivityListInfo {
+    // Unique identifier of this activity within its namespace.
+    ActivityExecution activity_execution = 1;
+    // The type of the activity, a string that maps to a registered activity on a worker.
+    temporal.api.common.v1.ActivityType activity_type = 2;
+    // Time the activity was originally scheduled via a StartActivityExecution request.
+    // TODO: Workflows call this schedule_time but it's scheduled_time in PendingActivityInfo, what should we choose for
+    // consistency?
+    google.protobuf.Timestamp scheduled_time = 3;
+    // If the activity is in a terminal status, this field represents the time the activity transitioned to that status.
+    google.protobuf.Timestamp close_time = 4;
+    // 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 = 5;
+
+    // Search attributes from the start request.
+    temporal.api.common.v1.SearchAttributes search_attributes = 6;
+
+    // The task queue this activity was scheduled on when it was originally started, updated on activity options update.
+    string task_queue = 7;
+    // Updated on terminal status.
+    int64 state_transition_count = 8;
+    // Updated once on scheduled and once on terminal status.
+    int64 state_size_bytes = 9;
+    // The difference between close time and scheduled time.
+    // This field is only populated if the activity is closed.
+    google.protobuf.Duration execution_duration = 10;
+}

openapi/openapiv3.yaml

@@ -232,9 +232,17 @@ message Link {
         string job_id = 1;
     }
 
+    // A link to an activity.
+    message Activity {
+        string namespace = 1;
+        string activity_id = 2;
+        string run_id = 3;
+    }
+
     oneof variant {
         WorkflowEvent workflow_event = 1;
         BatchJob batch_job = 2;
+        Activity activity = 3;
     }
 }
 

temporal/api/activity/v1/message.proto

@@ -0,0 +1,40 @@
+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.
+// TODO: Should this be a common execution status? Seems like the other archetypes will share this status.
+// (-- api-linter: core::0216::synonyms=disabled
+//     aip.dev/not-precedent: Named consistently with WorkflowExecutionStatus. --)
+enum ActivityExecutionStatus {
+    ACTIVITY_EXECUTION_STATUS_UNSPECIFIED = 0;
+    // The activity is not in a terminal status. This does not necessarily mean that there is a currently running
+    // attempt. The activity may be backing off between attempts or waiting for a worker to pick it up.
+    ACTIVITY_EXECUTION_STATUS_RUNNING = 1;
+    // The activity completed successfully.
+    ACTIVITY_EXECUTION_STATUS_COMPLETED = 2;
+    // The activity completed with failure.
+    ACTIVITY_EXECUTION_STATUS_FAILED = 3;
+    // The activity completed as canceled.
+    // Requesting to cancel an activity does not automatically transition the activity to canceled status. If the
+    // activity has a currently running attempt, the activity will only transition to canceled status if the current
+    // attempt is unsuccessful.
+    // TODO: Clarify what happens if there are no more allowed retries after the current attempt.
+    ACTIVITY_EXECUTION_STATUS_CANCELED = 4;
+    // The activity was terminated. Termination does not reach the worker and the activity code cannot react to it.
+    // A terminated activity may have a running attempt and will be requested to be canceled by the server when it
+    // heartbeats.
+    ACTIVITY_EXECUTION_STATUS_TERMINATED = 5;
+    // The activity has timed out by reaching the specified shedule-to-start or schedule-to-close timeouts.
+    // TODO: Clarify if there are other conditions where the activity can end up in timed out status.
+    ACTIVITY_EXECUTION_STATUS_TIMED_OUT = 6;
+}

temporal/api/common/v1/message.proto

@@ -0,0 +1,40 @@
+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 = "IdProto";
+option ruby_package = "Temporalio::Api::Enums::V1";
+option csharp_namespace = "Temporalio.Api.Enums.V1";
+
+// Defines whether to allow re-using an ID from a previously *closed* execution.
+// If the request is denied, the server returns an `ExecutionAlreadyStarted` error.
+//
+// See `IdConflictPolicy` for handling ID duplication with a *running* execution.
+enum IdReusePolicy {
+    ID_REUSE_POLICY_UNSPECIFIED = 0;
+    // Always allow starting an execution using the same entity ID.
+    ID_REUSE_POLICY_ALLOW_DUPLICATE = 1;
+    // Allow starting an execution using the same ID, only when the last execution's final state is one of [terminated,
+    // cancelled, timed out, failed].
+    ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY = 2;
+    // Do not permit re-use of the ID for this execution. Future start requests could potentially change the policy,
+    // allowing re-use of the ID.
+    ID_REUSE_POLICY_REJECT_DUPLICATE = 3;
+}
+
+// Defines what to do when trying to start an execution with the same ID as a *running* execution.
+// Note that it is *never* valid to have two actively running instances of the same execution ID.
+//
+// See `IdReusePolicy` for handling execution ID duplication with a *closed* execution.
+enum IdConflictPolicy {
+    ID_CONFLICT_POLICY_UNSPECIFIED = 0;
+    // Don't start a new execution; instead return `ExecutionAlreadyStarted` error.
+    ID_CONFLICT_POLICY_FAIL = 1;
+    // Don't start a new execution; instead return a handle for the running execution.
+    ID_CONFLICT_POLICY_USE_EXISTING = 2;
+    // Terminate the running execution before starting a new one.
+    ID_CONFLICT_POLICY_TERMINATE_EXISTING = 3;
+}