Standalone Nexus Operations (#685)

**What changed?**

- Added the full API scope for standalone nexus operations.

**Server PR**

temporalio/temporal#9869

---------

Co-authored-by: Stephan Behnke <stephanos@users.noreply.github.com>

Author: bergundy

openapi/openapiv2.json

@@ -247,10 +247,18 @@ message Link {
         string run_id = 3;
     }
 
+    // A link to a standalone Nexus operation.
+    message NexusOperation {
+        string namespace = 1;
+        string operation_id = 2;
+        string run_id = 3;
+    }
+
     oneof variant {
         WorkflowEvent workflow_event = 1;
         BatchJob batch_job = 2;
         Activity activity = 3;
+        NexusOperation nexus_operation = 4;
     }
 }
 

openapi/openapiv3.yaml

@@ -20,3 +20,63 @@ enum NexusHandlerErrorRetryBehavior {
     NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE = 2;
 }
 
+// Status of a standalone Nexus operation execution.
+// The status is updated once, when the operation is originally scheduled, and again when the
+// operation reaches a terminal status.
+// (-- api-linter: core::0216::synonyms=disabled
+//     aip.dev/not-precedent: Named consistently with WorkflowExecutionStatus. --)
+enum NexusOperationExecutionStatus {
+    NEXUS_OPERATION_EXECUTION_STATUS_UNSPECIFIED = 0;
+    // The operation is not in a terminal status. The operation may be attempting to start,
+    // backing off between attempts, or already started.
+    NEXUS_OPERATION_EXECUTION_STATUS_RUNNING = 1;
+    // The operation completed successfully.
+    NEXUS_OPERATION_EXECUTION_STATUS_COMPLETED = 2;
+    // The operation completed with failure.
+    NEXUS_OPERATION_EXECUTION_STATUS_FAILED = 3;
+    // The operation completed as canceled.
+    // Requesting to cancel an operation does not automatically transition the operation to canceled status, depending
+    // on the current operation status and the cancelation type used.
+    NEXUS_OPERATION_EXECUTION_STATUS_CANCELED = 4;
+    // The operation was terminated. Termination happens immediately without notifying the handler.
+    NEXUS_OPERATION_EXECUTION_STATUS_TERMINATED = 5;
+    // The operation has timed out by reaching one of the specified timeouts.
+    NEXUS_OPERATION_EXECUTION_STATUS_TIMED_OUT = 6;
+}
+
+// Stage that can be specified when waiting on a nexus operation.
+enum NexusOperationWaitStage {
+    NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED = 0;
+    // Wait for the operation to be started.
+    NEXUS_OPERATION_WAIT_STAGE_STARTED = 1;
+    // Wait for the operation to be in a terminal state, either successful or unsuccessful.
+    NEXUS_OPERATION_WAIT_STAGE_CLOSED = 2;
+}
+
+// Defines whether to allow re-using an operation ID from a previously *closed* Nexus operation.
+// If the request is denied, the server returns a `NexusOperationAlreadyStarted` error.
+//
+// See `NexusOperationIdConflictPolicy` for handling ID duplication with a *running* operation.
+enum NexusOperationIdReusePolicy {
+    NEXUS_OPERATION_ID_REUSE_POLICY_UNSPECIFIED = 0;
+    // Always allow starting an operation using the same operation ID.
+    NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE = 1;
+    // Allow starting an operation using the same ID only when the last operation's final state is one
+    // of {failed, canceled, terminated, timed out}.
+    NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY = 2;
+    // Do not permit re-use of the ID for this operation. Future start requests could potentially change the policy,
+    // allowing re-use of the ID.
+    NEXUS_OPERATION_ID_REUSE_POLICY_REJECT_DUPLICATE = 3;
+}
+
+// Defines what to do when trying to start a Nexus operation with the same ID as a *running* operation.
+// Note that it is *never* valid to have two running instances of the same operation ID.
+//
+// See `NexusOperationIdReusePolicy` for handling operation ID duplication with a *closed* operation.
+enum NexusOperationIdConflictPolicy {
+    NEXUS_OPERATION_ID_CONFLICT_POLICY_UNSPECIFIED = 0;
+    // Don't start a new operation; instead return `NexusOperationAlreadyStarted` error.
+    NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL = 1;
+    // Don't start a new operation; instead return a handle for the running operation.
+    NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING = 2;
+}

temporal/api/common/v1/message.proto

@@ -129,3 +129,11 @@ message ActivityExecutionAlreadyStartedFailure {
     string start_request_id = 1;
     string run_id = 2;
 }
+
+// An error indicating that a Nexus operation failed to start. Returned when there is an existing operation with the
+// given operation ID, and the given ID reuse and conflict policies do not permit starting a new one or attaching to an
+// existing one.
+message NexusOperationExecutionAlreadyStartedFailure {
+    string start_request_id = 1;
+    string run_id = 2;
+}

temporal/api/enums/v1/nexus.proto

@@ -9,10 +9,13 @@ option java_outer_classname = "MessageProto";
 option ruby_package = "Temporalio::Api::Nexus::V1";
 option csharp_namespace = "Temporalio.Api.Nexus.V1";
 
+import "google/protobuf/duration.proto";
 import "google/protobuf/timestamp.proto";
 import "temporal/api/common/v1/message.proto";
+import "temporal/api/enums/v1/common.proto";
 import "temporal/api/enums/v1/nexus.proto";
 import "temporal/api/failure/v1/message.proto";
+import "temporal/api/sdk/v1/user_metadata.proto";
 
 // A general purpose failure message.
 // See: https://github.com/nexus-rpc/api/blob/main/SPEC.md#failure
@@ -199,7 +202,7 @@ message EndpointTarget {
         // Nexus task queue to route requests to.
         string task_queue = 2;
     }
-  
+
     // Target an external server by URL.
     // At a later point, this will support providing credentials, in the meantime, an http.RoundTripper can be injected
     // into the server to modify the request.
@@ -213,3 +216,150 @@ message EndpointTarget {
         External external = 2;
     }
 }
+
+// NexusOperationExecutionCancellationInfo contains the state of a Nexus operation cancellation.
+message NexusOperationExecutionCancellationInfo {
+    // The time when cancellation was requested.
+    google.protobuf.Timestamp requested_time = 1;
+
+    temporal.api.enums.v1.NexusOperationCancellationState state = 2;
+
+    // The number of attempts made to deliver the cancel operation request.
+    // This number represents a minimum bound since the attempt is incremented after the request completes.
+    int32 attempt = 3;
+
+    // The time when the last attempt completed.
+    google.protobuf.Timestamp last_attempt_complete_time = 4;
+    // The last attempt's failure, if any.
+    temporal.api.failure.v1.Failure last_attempt_failure = 5;
+    // The time when the next attempt is scheduled.
+    google.protobuf.Timestamp next_attempt_schedule_time = 6;
+
+    // If the state is BLOCKED, blocked reason provides additional information.
+    string blocked_reason = 7;
+
+    // A reason that may be specified in the CancelNexusOperationRequest.
+    string reason = 8;
+}
+
+// Full current state of a standalone Nexus operation, as of the time of the request.
+message NexusOperationExecutionInfo {
+    // Unique identifier of this Nexus operation within its namespace along with run ID (below).
+    string operation_id = 1;
+    string run_id = 2;
+
+    // Endpoint name, resolved to a URL via the cluster's endpoint registry.
+    string endpoint = 3;
+    // Service name.
+    string service = 4;
+    // Operation name.
+    string operation = 5;
+
+    // A general status for this operation, indicates whether it is currently running or in one of the terminal statuses.
+    // Updated once when the operation is originally scheduled, and again when it reaches a terminal status.
+    temporal.api.enums.v1.NexusOperationExecutionStatus status = 6;
+    // More detailed breakdown of NEXUS_OPERATION_EXECUTION_STATUS_RUNNING.
+    temporal.api.enums.v1.PendingNexusOperationState state = 7;
+
+    // Schedule-to-close timeout for this operation.
+    // (-- api-linter: core::0140::prepositions=disabled
+    //     aip.dev/not-precedent: "to" is used to indicate interval. --)
+    google.protobuf.Duration schedule_to_close_timeout = 8;
+
+    // Schedule-to-start timeout for this operation.
+    // (-- api-linter: core::0140::prepositions=disabled
+    //     aip.dev/not-precedent: "to" is used to indicate interval. --)
+    google.protobuf.Duration schedule_to_start_timeout = 9;
+
+    // Start-to-close timeout for this operation.
+    // (-- api-linter: core::0140::prepositions=disabled
+    //     aip.dev/not-precedent: "to" is used to indicate interval. --)
+    google.protobuf.Duration start_to_close_timeout = 10;
+
+    // The number of attempts made to deliver the start operation request.
+    // This number is approximate, it is incremented when a task is added to the history queue.
+    // In practice, there could be more attempts if a task is executed but fails to commit, or less attempts if a task
+    // was never executed.
+    int32 attempt = 11;
+
+    // Time the operation was originally scheduled via a StartNexusOperation request.
+    google.protobuf.Timestamp schedule_time = 12;
+    // Scheduled time + schedule to close timeout.
+    google.protobuf.Timestamp expiration_time = 13;
+    // Time when the operation transitioned to a closed state.
+    google.protobuf.Timestamp close_time = 14;
+
+    // The time when the last attempt completed.
+    google.protobuf.Timestamp last_attempt_complete_time = 15;
+    // The last attempt's failure, if any.
+    temporal.api.failure.v1.Failure last_attempt_failure = 16;
+    // The time when the next attempt is scheduled.
+    google.protobuf.Timestamp next_attempt_schedule_time = 17;
+
+    // Elapsed time from schedule_time to now for running operations or to close_time for closed
+    // operations, including all attempts and backoff between attempts.
+    google.protobuf.Duration execution_duration = 18;
+
+    NexusOperationExecutionCancellationInfo cancellation_info = 19;
+
+    // If the state is BLOCKED, blocked reason provides additional information.
+    string blocked_reason = 20;
+
+    // Server-generated request ID used as an idempotency token when submitting start requests to
+    // the handler. Distinct from the request_id in StartNexusOperationRequest, which is the
+    // caller-side idempotency key for the StartNexusOperation RPC itself.
+    string request_id = 21;
+
+    // Operation token. Only set for asynchronous operations after a successful StartOperation call.
+    string operation_token = 22;
+
+    // Incremented each time the operation's state is mutated in persistence.
+    int64 state_transition_count = 23;
+
+    temporal.api.common.v1.SearchAttributes search_attributes = 24;
+
+    // Header for context propagation and tracing purposes.
+    map<string, string> nexus_header = 25;
+
+    // Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation.
+    temporal.api.sdk.v1.UserMetadata user_metadata = 26;
+
+    // Links attached by the handler of this operation on start or completion.
+    repeated temporal.api.common.v1.Link links = 27;
+
+    // The identity of the client who started this operation.
+    string identity = 28;
+}
+
+// Limited Nexus operation information returned in the list response.
+// When adding fields here, ensure that it is also present in NexusOperationExecutionInfo (note that it may already be present in
+// NexusOperationExecutionInfo but not at the top-level).
+message NexusOperationExecutionListInfo {
+    // A unique identifier of this operation within its namespace along with run ID (below).
+    string operation_id = 1;
+    // The run ID of the standalone Nexus operation.
+    string run_id = 2;
+
+    // Endpoint name.
+    string endpoint = 3;
+    // Service name.
+    string service = 4;
+    // Operation name.
+    string operation = 5;
+
+    // Time the operation was originally scheduled via a StartNexusOperation request.
+    google.protobuf.Timestamp schedule_time = 6;
+    // If the operation is in a terminal status, this field represents the time the operation transitioned to that status.
+    google.protobuf.Timestamp close_time = 7;
+    // The status is updated once, when the operation is originally scheduled, and again when the operation reaches a terminal status.
+    temporal.api.enums.v1.NexusOperationExecutionStatus status = 8;
+
+    // Search attributes from the start request.
+    temporal.api.common.v1.SearchAttributes search_attributes = 9;
+
+    // Updated on terminal status.
+    int64 state_transition_count = 10;
+    // The difference between close time and scheduled time.
+    // This field is only populated if the operation is closed.
+    google.protobuf.Duration execution_duration = 11;
+}

temporal/api/errordetails/v1/message.proto

@@ -515,7 +515,9 @@ message PendingNexusOperationInfo {
     temporal.api.enums.v1.PendingNexusOperationState state = 7;
 
     // The number of attempts made to deliver the start operation request.
-    // This number represents a minimum bound since the attempt is incremented after the request completes.
+    // This number is approximate, it is incremented when a task is added to the history queue.
+    // In practice, there could be more attempts if a task is executed but fails to commit, or less attempts if a task
+    // was never executed.
     int32 attempt = 8;
 
     // The time when the last attempt completed.
@@ -753,4 +755,3 @@ message WorkflowExecutionPauseInfo {
     // The reason for pausing the workflow execution.
     string reason = 3;
 }
-