package temporal.api.nexus.v1

Get desktop application:
View/edit binary Protocol Buffers messages

A request to cancel an operation.

Used in: Request

• string service = 1

  Service name.

• string operation = 2

  Type of operation to cancel.

• string operation_id = 3

  Operation ID as originally generated by a Handler. Deprecated. Renamed to operation_token.

• string operation_token = 4

  Operation token as originally generated by a Handler.

Response variant for CancelOperationRequest.

Used in: Response

(message has no fields)

A cluster-global binding from an endpoint ID to a target for dispatching incoming Nexus requests.

Used in: operatorservice.v1.CreateNexusEndpointResponse, operatorservice.v1.GetNexusEndpointResponse, operatorservice.v1.ListNexusEndpointsResponse, operatorservice.v1.UpdateNexusEndpointResponse

• int64 version = 1

  Data version for this endpoint, incremented for every update issued via the UpdateNexusEndpoint API.

• string id = 2

  Unique server-generated endpoint ID.

• optional EndpointSpec spec = 3

  Spec for the endpoint.

• optional google.protobuf.Timestamp created_time = 4

  The date and time when the endpoint was created. (-- api-linter: core::0142::time-field-names=disabled aip.dev/not-precedent: Not following linter rules. --)

• optional google.protobuf.Timestamp last_modified_time = 5

  The date and time when the endpoint was last modified. Will not be set if the endpoint has never been modified. (-- api-linter: core::0142::time-field-names=disabled aip.dev/not-precedent: Not following linter rules. --)

• string url_prefix = 6

  Server exposed URL prefix for invocation of operations on this endpoint. This doesn't include the protocol, hostname or port as the server does not know how it should be accessed publicly. The URL is stable in the face of endpoint renames.

Contains mutable fields for an Endpoint.

Used in: Endpoint, operatorservice.v1.CreateNexusEndpointRequest, operatorservice.v1.UpdateNexusEndpointRequest

• string name = 1

  Endpoint name, unique for this cluster. Must match `[a-zA-Z_][a-zA-Z0-9_]*`. Renaming an endpoint breaks all workflow callers that reference this endpoint, causing operations to fail.

• optional common.v1.Payload description = 2

  Markdown description serialized as a single JSON string. If the Payload is encrypted, the UI and CLI may decrypt with the configured codec server endpoint. By default, the server enforces a limit of 20,000 bytes for this entire payload.

• optional EndpointTarget target = 3

  Target to route requests to.

Target to route requests to.

Used in: EndpointSpec

• oneof variant

  • EndpointTarget.Worker worker = 1

  • EndpointTarget.External external = 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.

Used in: EndpointTarget

• string url = 1

  URL to call.

Target a worker polling on a Nexus task queue in a specific namespace.

Used in: EndpointTarget

• string namespace = 1

  Namespace to route requests to.

• string task_queue = 2

  Nexus task queue to route requests to.

A general purpose failure message. See: https://github.com/nexus-rpc/api/blob/main/SPEC.md#failure

Used in: HandlerError, UnsuccessfulOperationError

• string message = 1

• string stack_trace = 4

• map<string, string> metadata = 2

• bytes details = 3

  UTF-8 encoded JSON serializable details.

• optional Failure cause = 5

Used in: workflowservice.v1.RespondNexusTaskFailedRequest

• string error_type = 1

  See https://github.com/nexus-rpc/api/blob/main/SPEC.md#predefined-handler-errors.

• optional Failure failure = 2

• enums.v1.NexusHandlerErrorRetryBehavior retry_behavior = 3

  Retry behavior, defaults to the retry behavior of the error type as defined in the spec.

Used in: StartOperationRequest, StartOperationResponse.Async, StartOperationResponse.Sync

• string url = 1

  See https://github.com/nexus-rpc/api/blob/main/SPEC.md#links.

• string type = 2

NexusOperationExecutionCancellationInfo contains the state of a Nexus operation cancellation.

Used in: NexusOperationExecutionInfo

• optional google.protobuf.Timestamp requested_time = 1

  The time when cancellation was requested.

• enums.v1.NexusOperationCancellationState state = 2

• int32 attempt = 3

  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.

• optional google.protobuf.Timestamp last_attempt_complete_time = 4

  The time when the last attempt completed.

• optional failure.v1.Failure last_attempt_failure = 5

  The last attempt's failure, if any.

• optional google.protobuf.Timestamp next_attempt_schedule_time = 6

  The time when the next attempt is scheduled.

• string blocked_reason = 7

  If the state is BLOCKED, blocked reason provides additional information.

• string reason = 8

  A reason that may be specified in the CancelNexusOperationRequest.

Full current state of a standalone Nexus operation, as of the time of the request.

Used in: workflowservice.v1.DescribeNexusOperationExecutionResponse

• string operation_id = 1

  Unique identifier of this Nexus operation within its namespace along with run ID (below).

• string run_id = 2

• string endpoint = 3

  Endpoint name, resolved to a URL via the cluster's endpoint registry.

• string service = 4

  Service name.

• string operation = 5

  Operation name.

• enums.v1.NexusOperationExecutionStatus status = 6

  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.

• enums.v1.PendingNexusOperationState state = 7

  More detailed breakdown of NEXUS_OPERATION_EXECUTION_STATUS_RUNNING.

• optional google.protobuf.Duration schedule_to_close_timeout = 8

  Schedule-to-close timeout for this operation. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --)

• optional google.protobuf.Duration schedule_to_start_timeout = 9

  Schedule-to-start timeout for this operation. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --)

• optional google.protobuf.Duration start_to_close_timeout = 10

  Start-to-close timeout for this operation. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --)

• int32 attempt = 11

  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.

• optional google.protobuf.Timestamp schedule_time = 12

  Time the operation was originally scheduled via a StartNexusOperation request.

• optional google.protobuf.Timestamp expiration_time = 13

  Scheduled time + schedule to close timeout.

• optional google.protobuf.Timestamp close_time = 14

  Time when the operation transitioned to a closed state.

• optional google.protobuf.Timestamp last_attempt_complete_time = 15

  The time when the last attempt completed.

• optional failure.v1.Failure last_attempt_failure = 16

  The last attempt's failure, if any.

• optional google.protobuf.Timestamp next_attempt_schedule_time = 17

  The time when the next attempt is scheduled.

• optional google.protobuf.Duration execution_duration = 18

  Elapsed time from schedule_time to now for running operations or to close_time for closed operations, including all attempts and backoff between attempts.

• optional NexusOperationExecutionCancellationInfo cancellation_info = 19

• string blocked_reason = 20

  If the state is BLOCKED, blocked reason provides additional information.

• string request_id = 21

  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 operation_token = 22

  Operation token. Only set for asynchronous operations after a successful StartOperation call.

• int64 state_transition_count = 23

  Incremented each time the operation's state is mutated in persistence.

• optional common.v1.SearchAttributes search_attributes = 24

• map<string, string> nexus_header = 25

  Header for context propagation and tracing purposes.

• optional sdk.v1.UserMetadata user_metadata = 26

  Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation.

• repeated common.v1.Link links = 27

  Links attached by the handler of this operation on start or completion.

• string identity = 28

  The identity of the client who started this operation.

• int64 state_size_bytes = 29

  Updated once on scheduled and once on terminal status.

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).

Used in: workflowservice.v1.ListNexusOperationExecutionsResponse

• string operation_id = 1

  A unique identifier of this operation within its namespace along with run ID (below).

• string run_id = 2

  The run ID of the standalone Nexus operation.

• string endpoint = 3

  Endpoint name.

• string service = 4

  Service name.

• string operation = 5

  Operation name.

• optional google.protobuf.Timestamp schedule_time = 6

  Time the operation was originally scheduled via a StartNexusOperation request.

• optional google.protobuf.Timestamp close_time = 7

  If the operation is in a terminal status, this field represents the time the operation transitioned to that status.

• enums.v1.NexusOperationExecutionStatus status = 8

  The status is updated once, when the operation is originally scheduled, and again when the operation reaches a terminal status.

• optional common.v1.SearchAttributes search_attributes = 9

  Search attributes from the start request.

• int64 state_transition_count = 10

  Updated on terminal status.

• optional google.protobuf.Duration execution_duration = 11

  The difference between close time and scheduled time. This field is only populated if the operation is closed.

• int64 state_size_bytes = 12

  Updated once on scheduled and once on terminal status.

A Nexus request.

Used in: workflowservice.v1.PollNexusTaskQueueResponse

• map<string, string> header = 1

  Headers extracted from the original request in the Temporal frontend. When using Nexus over HTTP, this includes the request's HTTP headers ignoring multiple values.

• optional google.protobuf.Timestamp scheduled_time = 2

  The timestamp when the request was scheduled in the frontend. (-- api-linter: core::0142::time-field-names=disabled aip.dev/not-precedent: Not following linter rules. --)

• optional Request.Capabilities capabilities = 100

• oneof variant

  • StartOperationRequest start_operation = 3

  • CancelOperationRequest cancel_operation = 4

• string endpoint = 10

  The endpoint this request was addressed to before forwarding to the worker. Supported from server version 1.30.0.

Used in: Request

• bool temporal_failure_responses = 1

  If set, handlers may use temporal.api.failure.v1.Failure instances to return failures to the server. This also allows handler and operation errors to have their own messages and stack traces.

A response indicating that the handler has successfully processed a request.

Used in: workflowservice.v1.RespondNexusTaskCompletedRequest

• oneof variant

  Variant must correlate to the corresponding Request's variant.

  • StartOperationResponse start_operation = 1

  • CancelOperationResponse cancel_operation = 2

A request to start an operation.

Used in: Request

• string service = 1

  Name of service to start the operation in.

• string operation = 2

  Type of operation to start.

• string request_id = 3

  A request ID that can be used as an idempotentency key.

• string callback = 4

  Callback URL to call upon completion if the started operation is async.

• optional common.v1.Payload payload = 5

  Full request body from the incoming HTTP request.

• map<string, string> callback_header = 6

  Header that is expected to be attached to the callback request when the operation completes.

• repeated Link links = 7

  Links contain caller information and can be attached to the operations started by the handler.

Response variant for StartOperationRequest.

Used in: Response

• oneof variant

  • StartOperationResponse.Sync sync_success = 1

  • StartOperationResponse.Async async_success = 2

  • UnsuccessfulOperationError operation_error = 3

    The operation completed unsuccessfully (failed or canceled). Deprecated. Use the failure variant instead.

  • failure.v1.Failure failure = 4

    The operation completed unsuccessfully (failed or canceled). Failure object must contain an ApplicationFailureInfo or CanceledFailureInfo object.

The operation will complete asynchronously. The returned ID can be used to reference this operation.

Used in: StartOperationResponse

• string operation_id = 1

  Deprecated. Renamed to operation_token.

• repeated Link links = 2

• string operation_token = 3

An operation completed successfully.

Used in: StartOperationResponse

• optional common.v1.Payload payload = 1

• repeated Link links = 2

Used in: StartOperationResponse

• string operation_state = 1

  See https://github.com/nexus-rpc/api/blob/main/SPEC.md#operationinfo.

• optional Failure failure = 2