nexus.proto

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 = "NexusProto";
option ruby_package = "Temporalio::Api::Enums::V1";
option csharp_namespace = "Temporalio.Api.Enums.V1";

// NexusHandlerErrorRetryBehavior allows nexus handlers to explicity set the retry behavior of a HandlerError. If not
// specified, retry behavior is determined from the error type. For example internal errors are not retryable by default
// unless specified otherwise.
enum NexusHandlerErrorRetryBehavior {
    NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_UNSPECIFIED = 0;
    // A handler error is explicitly marked as retryable.
    NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE = 1;
    // A handler error is explicitly marked as non-retryable.
    NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE = 2;
}

// Status of a standalone Nexus operation.
// 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 NexusOperationStatus {
    NEXUS_OPERATION_STATUS_UNSPECIFIED = 0;
    // The operation is not in a terminal status. The operation may attempting to start, backing off between attempts,
    // or already started.
    NEXUS_OPERATION_STATUS_RUNNING = 1;
    // The operation completed successfully.
    NEXUS_OPERATION_STATUS_COMPLETED = 2;
    // The operation completed with failure.
    NEXUS_OPERATION_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_STATUS_CANCELED = 4;
    // The operation was terminated. Termination happens immediately without notifying the handler.
    NEXUS_OPERATION_STATUS_TERMINATED = 5;
    // The operation has timed out by reaching the specified schedule-to-close timeout.
    NEXUS_OPERATION_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;
}