[DO NOT MERGE] Add standalone activity APIs

temporal/api/activity/v1/message.proto

@@ -9,10 +9,16 @@ 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 "google/protobuf/duration.proto";
+import "temporal/api/sdk/v1/user_metadata.proto";
 
 message ActivityOptions {
  temporal.api.taskqueue.v1.TaskQueue task_queue = 1;
@@ -40,10 +46,147 @@ 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;
+
+ temporal.api.taskqueue.v1.TaskQueue 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 started.
+ // TODO(dandavison): Confirm if this is on scheduled or started.
+ int32 attempt = 15;
+ int32 maximum_attempts = 16;
+ // Time the activity was originally scheduled via a StartActivityExecution request.
+ google.protobuf.Timestamp scheduled_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;
+
+ // Current activity options. May be different from the one used to start the activity.
+ temporal.api.activity.v1.ActivityOptions activity_options = 27;
+
+ // Incremented each time the activity's state is mutated in persistence.
+ int64 state_transition_count = 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 {
+ // For standalone activity - a unique identifier of this activity within its namespace along with run ID (below).
+ string activity_id = 1;
+ // The run ID of the workflow or standalone activity.
+ string run_id = 2;
+ // Workflow that contains this activity - only present for workflow activity.
+ string workflow_id = 3;
+
+ // The type of the activity, a string that maps to a registered activity on a worker.
+ temporal.api.common.v1.ActivityType activity_type = 4;
+ // 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 = 5;
+ // If the activity is in a terminal status, this field represents the time the activity transitioned to that status.
+ google.protobuf.Timestamp close_time = 6;
+ // 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 = 7;
+
+ // Search attributes from the start request.
+ temporal.api.common.v1.SearchAttributes search_attributes = 8;
+
+ // The task queue this activity was scheduled on when it was originally started, updated on activity options update.
+ string task_queue = 9;
+ // Updated on terminal status.
+ int64 state_transition_count = 10;
+ // Updated once on scheduled and once on terminal status.
+ int64 state_size_bytes = 11;
+ // The difference between close time and scheduled time.
+ // This field is only populated if the activity is closed.
+ google.protobuf.Duration execution_duration = 12;
+}

temporal/api/common/v1/message.proto

@@ -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;
  }
 }
 
@@ -338,4 +346,3 @@ message WorkerSelector {
  string worker_instance_key = 1;
  }
 }
-

temporal/api/enums/v1/activity.proto

@@ -0,0 +1,68 @@
+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;
+}
+
+// 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/errordetails/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;
+}