From 0f7b467baa05f9af5fd7858b4985e05944501860 Mon Sep 17 00:00:00 2001 From: Jwahir Sundai Date: Wed, 4 Sep 2024 07:35:24 -0500 Subject: [PATCH 1/6] first add --- docs/references/commands.mdx | 18 ++++- docs/references/errors.mdx | 22 +++++- docs/references/failures.mdx | 135 +++++++++++++++++++++++++++++++++-- 3 files changed, 168 insertions(+), 7 deletions(-) diff --git a/docs/references/commands.mdx b/docs/references/commands.mdx index 7d1a7a2f0a..9c17075c93 100644 --- a/docs/references/commands.mdx +++ b/docs/references/commands.mdx @@ -119,7 +119,23 @@ This Command is triggered by a call to "upsert" Workflow [Search Attributes](/vi ### ProtocolMessageCommand -This Command helps guarantee ordering constraints for features such as Updates +This Command helps guarantee ordering constraints for features such as Updates. This Command points at the message from which the Event is created. Therefore, just from the Command, you can't predict the resulting Event type. + +### ScheduleNexusOperation + +This Command is triggered by a call to execute an Nexus Operation in the caller Workflow. + +Awaitable: Yes, a Workflow Execution can await on the action resulting from this Command.\ +Corresponding Event: NexusOperationScheduled + +By default, you cannot schedule more than 30 Nexus Operations concurrently (or in total during public preview since completed operations are not yet deleted), see [Limits](/#workflow-execution-nexus-operation-limits) for details. + +### CancelNexusOperation + +This Command is triggered by a call to request the cancellation of a Nexus Operation. + +Awaitable: No, a Workflow Execution can not await on the action resulting from this Command.\ +Corresponding Event: NexusOperationCancelRequested diff --git a/docs/references/errors.mdx b/docs/references/errors.mdx index f1f5e0b7c0..51026fd15b 100644 --- a/docs/references/errors.mdx +++ b/docs/references/errors.mdx @@ -64,7 +64,7 @@ Restart the [Worker](/workers) that the [Workflow](/workflows) and [Activity](/a This error indicates that the [Workflow Task](/workers#workflow-task) failed to validate attributes on a property in the Upsert Memo or in a payload. These attributes are either unset or exceeding size limits. -Reset any unset and empty atrributes. +Reset any unset and empty attributes. Adjust the size of the [Memo](/workflows#memo) or payload to fit within the system's limits. ## Bad Record Marker Attributes {#bad-record-marker-attributes} @@ -100,6 +100,12 @@ This error indicates unset or invalid attributes for [`ScheduleActivityTask`](/r Reset any unset or empty attributes. Adjust the size of the received payload to stay within the given size limit. +## Bad Schedule Nexus Operation Attributes + +This error indicates unset or invalid attributes for ScheduleNexusOperation, for example if the Nexus Endpoint name used in the caller Workflow does not exist. + +Reset any unset or empty attributes. Adjust the size of the received payload to stay within the given size limit. + ## Bad Search Attributes {#bad-search-attributes} This error indicates that the [Workflow Task](/workers#workflow-task) has unset or invalid [Search Attributes](/visibility#search-attribute). @@ -208,6 +214,20 @@ Therefore, the [Workflow Task](/workers#workflow-task) was failed to prevent add Wait for the system to finish any currently running Child Workflows before redeploying this Task. +## Pending Nexus Operations Limit Exceeded {#pending-nexus-operations-limit-exceeded} + +The Workflow has reached capacity for pending Nexus Operations. Therefore, the Workflow Task was failed to prevent the creation of another Nexus Operation. + +:::note + +In Public Preview Nexus Operations are not yet deleted from mutable state when they complete, so the limit is for the total count of Nexus Operations in a given workflow. + +::: + +Let the Workflow complete any current Nexus Operation before retrying the Task. + +See [Per Workflow Nexus Operation Limits](#per-workflow-nexus-operation-limits) for details. + ## Pending Request Cancel Limit Exceeded {#pending-request-cancel-limit-exceeded} This error indicates that the [Workflow Task](/workers#workflow-task) failed after attempting to add more cancel requests. diff --git a/docs/references/failures.mdx b/docs/references/failures.mdx index 6449534a0b..9bb8e9bccc 100644 --- a/docs/references/failures.mdx +++ b/docs/references/failures.mdx @@ -36,8 +36,8 @@ The base [Failure proto message](https://api-docs.temporal.io/#temporal.api.fail ## Application Failure -Workflow and Activity code use Application Failures to communicate application-specific failures that happen. -This is the only type of Failure created and thrown by user code. +Workflow, and Activity, and Nexus Operation code use Application Failures to communicate application-specific failures that happen. +This is the only type of Temporal Failure created and thrown by user code. - TypeScript: [ApplicationFailure](https://typescript.temporal.io/api/classes/common.ApplicationFailure) - Java: [ApplicationFailure](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/failure/ApplicationFailure.html) @@ -82,26 +82,130 @@ During conversion, the following Application Failure fields are set: When an [Activity Execution](/activities#activity-execution) fails, the Application Failure from the last Activity Task is the `cause` field of the [ActivityFailure](#activity-failure) thrown in the Workflow. +### Errors in Nexus Operations + +An error in a Nexus Operation can cause either a Nexus Operation Task Failure (the Task will be retried) or a Nexus Operation Execution Failure (the Nexus Operation is marked as failed). + +#### Nexus Operation Task Failures + +A Nexus Operation Task Failure is an unexpected situation failing to process a Nexus Operation Task in a handler. +This could be triggered by throwing an unknown error in your Nexus handler code. These types of failures will cause the Nexus Operation Task to be retried. + +#### Nexus Operation Execution Failures + +A non-retryable Application Failure can be thrown by a Nexus Operation handler to fail the overall Nexus Operation Execution. +Nexus Operation Execution Failures put the Nexus Operation Execution into the "Failed" state and no more attempts will be made to complete the Nexus Operation. + +#### Propagation of Workflow errors + +Application Errors thrown from a Workflow created by a Nexus NewWorkflowRunOperation handler, will be automatically propagated to the caller as a non-retryable error and result in a Nexus Operation Execution Failure. + +#### Using Failures in a Nexus hander + +In a Nexus Operation handler, you can throw an Application Failure, a Nexus Error or another Error to fail the individual Nexus Operation Task or fail the overall Nexus Operation Execution. + +Unknown errors are converted to a retryable Application Failure. During conversion, the following fields are set on the Application Failure: + +- non\_retryable is set to false. +- type is set to the error's type name. +- message is set to the error message. + +#### Retryable failures + +Retryable Nexus Operation Task failures, like an unknown error, are automatically retried with a built-in retry policy. +When a Nexus Task fails, the caller workflow records an event attempt failure on the pending Nexus Operation and sets the following fields: + +- state is set to the new state, for example BackingOff +- attempt is set to an incremented count +- next\_attempt\_schedule\_time is set when the Nexus Task will be retried +- last\_attempt\_failure is set with the following fields: + - message is set to the error message. + - failure\_info is set to the Application Failure + +For example, an unknown error thrown in a Nexus handler will surface as: + +``` +temporal workflow describe -w my-workflow-id +... +Pending Nexus Operations: 1 + + Endpoint myendpoint + Service my-hello-service + Operation echo + OperationID + State BackingOff + Attempt 6 + ScheduleToCloseTimeout 0s + NextAttemptScheduleTime 20 seconds from now + LastAttemptCompleteTime 11 seconds ago + LastAttemptFailure {"message":"unexpected response status: \"500 Internal Server Error\": internal error","applicationFailureInfo":{}} +``` + ### Non-retryable When an Activity or Workflow throws an Application Failure, the Failure's `type` field is matched against a Retry Policy's list of [non-retryable errors](/encyclopedia/retry-policies#non-retryable-errors) to determine whether to retry the Activity or Workflow. Activities and Workflow can also avoid retrying by setting an Application Failure's `non_retryable` flag to `true`. +When a Nexus Operation handler throws an Application Failure, it is retried by default using a built-in Retry Policy that cannot be customized. +Nexus Operation handlers can avoid retrying by setting an Application Failure's non\_retryable flag to true. When a [non-retryable error](/#nexus-errors) is returned from a Nexus handler, the overall Nexus Operation Execution is failed and the error is returned to the caller’s Workflow Execution as a **Nexus Operation Failure.** + ### Setting the Next Retry Delay {#next-retry-delay} -By setting the Next Retry Delay for a given Application Failure, you can tell the server to wait that amount of time before trying the Activity or Workflow again. This will override whatever the Retry Policy would have computed for your specific exception. +Activities and Workflows can set the Next Retry Delay for a given Application Failure, to tell the server to wait that amount of time before trying the Activity or Workflow again. +This will override whatever the Retry Policy would have computed for your specific exception. + +Nexus Operations do not currently allow the handler to customize the Next Retry Delay for a given Application Failure. Java: [NextRetryDelay](/develop/java/failure-detection#next-retry-delay) +### Nexus errors {#nexus-errors} + +#### Default mapping + +By default, Application Failures thrown from a Nexus Operation handler will be mapped to the following underlying Nexus Failures, based on what non\_retryable is set to: + +| non\_retryable | Nexus error | HTTP status code | +| :-------------- | :------------------------- | :------------------------ | +| false (default) | HandlerErrorTypeInternal | 500 Internal Server Error | +| true | UnsuccessfulOperationError | 424 Failed Dependency | + +#### Use Nexus Errors directly + +For improved semantics and mapping to HTTP status codes for external Nexus callers (when supported), we recommend that Nexus Operation handlers throw a Nexus Error directly, which includes the list below with associated retry semantics. + +For example the Nexus Go SDK provides + +- `nexus.HandlerErrorf(nexus.HandlerErrorType, msg)` +- `nexus.UnsuccessfulOperationError{state, failure}` + +#### Retryable Nexus errors + +| Nexus error type | non\_retryable | +| :-------------------------------- | :------------- | +| HandlerErrorTypeResourceExhausted | false | +| HandlerErrorTypeInternal | false | +| HandlerErrorTypeNotImplemented | false | +| HandlerErrorTypeUnavailable | false | + +#### Non-retryable Nexus errors + +| Nexus error type | non\_retryable | +| :------------------------------ | :------------- | +| HandlerErrorTypeBadRequest | true | +| HandlerErrorTypeUnauthenticated | true | +| HandlerErrorTypeUnauthorized | true | +| HandlerErrorTypeNotFound | true | +| UnsuccessfulOperationError | true | + ## Cancelled Failure -When [Cancellation](/activities#cancellation) of a Workflow or Activity is requested, SDKs represent the cancellation to the user in language-specific ways. +When [Cancellation](/activities#cancellation) of a Workflow, Activity or Nexus Operation is requested, SDKs represent the cancellation to the user in language-specific ways. For example, in TypeScript, in some cases a Cancelled Failure is thrown directly by a Workflow API function, and in other cases the Cancelled Failure is wrapped in a different Failure. To check both types of cases, TypeScript has the [isCancellation](https://typescript.temporal.io/api/namespaces/workflow#iscancellation) helper. {/* TODO also link to Workflow Cancellation concept */} -When a Workflow or Activity is successfully Cancelled, a Cancelled Failure is the `cause` field of the Activity Failure or "Workflow failed" error. +When a Workflow, Activity or Nexus Operation is successfully Cancelled, a Cancelled Failure is the `cause` field of the Activity Failure, Nexus Operation Failure or "Workflow failed" error. - TypeScript: [CancelledFailure](https://typescript.temporal.io/api/classes/common.CancelledFailure) - Java: [CanceledFailure](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/failure/CanceledFailure.html) @@ -122,6 +226,27 @@ For example, if an Activity Execution times out, the `cause` is a [Timeout Failu - Python: [ActivityError](https://python.temporal.io/temporalio.exceptions.ActivityError.html) - Proto: [ActivityFailureInfo](https://api-docs.temporal.io/#temporal.api.failure.v1.ActivityFailureInfo) and [Failure](https://api-docs.temporal.io/#temporal.api.failure.v1.Failure) +## Nexus Operation Failure + +A Nexus Operation Failure is delivered to the Workflow Execution when a Nexus Operation fails. It contains information about the failure and the Nexus Operation Execution; for example, the Nexus Operation name and Nexus Operation Id. The reason for the failure is in the message and cause (typically an Application Error or a Canceled Error). + +Go: NexusOperationError\ +Proto: NexusOperationFailureInfo + +A **Nexus Operation Failure** includes the following fields: + +- endpoint is set to the name of the endpoint +- service is set to the name of the service +- operation is set to the name of the operation +- operation_id is set to the id of the operation, if this is an async operation +- scheduled_event_id is set to the caller’s event id that scheduled the operation +- message is set to a generic unsuccessful error message +- cause is set to the underlying Application Failure with the following fields: + - non-retryable is set to true + - type is set to the error's type name. + - message is set to the error message. +- nexus_error_code is set the the underlying Nexus error code + ## Child Workflow Failure A Child Workflow Failure is delivered to the Workflow Execution when a Child Workflow Execution fails. From 433a07584bfd578a4b79e309c792eab6860b5758 Mon Sep 17 00:00:00 2001 From: Jwahir Sundai Date: Fri, 11 Oct 2024 09:44:12 -0500 Subject: [PATCH 2/6] fixing formatting on commands pg --- docs/references/commands.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/references/commands.mdx b/docs/references/commands.mdx index 9c17075c93..3f7c96543a 100644 --- a/docs/references/commands.mdx +++ b/docs/references/commands.mdx @@ -128,14 +128,14 @@ Therefore, just from the Command, you can't predict the resulting Event type. This Command is triggered by a call to execute an Nexus Operation in the caller Workflow. -Awaitable: Yes, a Workflow Execution can await on the action resulting from this Command.\ -Corresponding Event: NexusOperationScheduled +- Awaitable: Yes, a Workflow Execution can await on the action resulting from this Command. +- Corresponding Event: NexusOperationScheduled -By default, you cannot schedule more than 30 Nexus Operations concurrently (or in total during public preview since completed operations are not yet deleted), see [Limits](/#workflow-execution-nexus-operation-limits) for details. +By default, you can't schedule more than 30 Nexus Operations concurrently (or in total during Public Preview since completed operations are not yet deleted), see [Limits](/#workflow-execution-nexus-operation-limits) for details. ### CancelNexusOperation This Command is triggered by a call to request the cancellation of a Nexus Operation. -Awaitable: No, a Workflow Execution can not await on the action resulting from this Command.\ -Corresponding Event: NexusOperationCancelRequested +- Awaitable: No, a Workflow Execution can not await on the action resulting from this Command. +- Corresponding Event: NexusOperationCancelRequested From 57ab05938b99f6a6f2b89fa5f5c8fbc30807e0a6 Mon Sep 17 00:00:00 2001 From: Jwahir Sundai Date: Fri, 11 Oct 2024 09:52:52 -0500 Subject: [PATCH 3/6] edits --- docs/references/errors.mdx | 6 +++--- docs/references/failures.mdx | 36 +++++++++++++++++------------------- 2 files changed, 20 insertions(+), 22 deletions(-) diff --git a/docs/references/errors.mdx b/docs/references/errors.mdx index 51026fd15b..3716ce9b7f 100644 --- a/docs/references/errors.mdx +++ b/docs/references/errors.mdx @@ -102,9 +102,9 @@ Adjust the size of the received payload to stay within the given size limit. ## Bad Schedule Nexus Operation Attributes -This error indicates unset or invalid attributes for ScheduleNexusOperation, for example if the Nexus Endpoint name used in the caller Workflow does not exist. +This error indicates unset or invalid attributes for ScheduleNexusOperation, for example if the Nexus Endpoint name used in the caller Workflow doesn't exist. -Reset any unset or empty attributes. Adjust the size of the received payload to stay within the given size limit. +Reset any unset or empty attributes and adjust the size of the received payload to stay within the given size limit. ## Bad Search Attributes {#bad-search-attributes} @@ -220,7 +220,7 @@ The Workflow has reached capacity for pending Nexus Operations. Therefore, the W :::note -In Public Preview Nexus Operations are not yet deleted from mutable state when they complete, so the limit is for the total count of Nexus Operations in a given workflow. +In Public Preview, Nexus Operations are not yet deleted from mutable state when they complete, so the limit is for the total count of Nexus Operations in a given Workflow. ::: diff --git a/docs/references/failures.mdx b/docs/references/failures.mdx index 9bb8e9bccc..4af558ef1c 100644 --- a/docs/references/failures.mdx +++ b/docs/references/failures.mdx @@ -106,21 +106,21 @@ In a Nexus Operation handler, you can throw an Application Failure, a Nexus Erro Unknown errors are converted to a retryable Application Failure. During conversion, the following fields are set on the Application Failure: -- non\_retryable is set to false. -- type is set to the error's type name. -- message is set to the error message. +- Non_retryable is set to false. +- Type is set to the error's type name. +- Message is set to the error message. #### Retryable failures Retryable Nexus Operation Task failures, like an unknown error, are automatically retried with a built-in retry policy. When a Nexus Task fails, the caller workflow records an event attempt failure on the pending Nexus Operation and sets the following fields: -- state is set to the new state, for example BackingOff -- attempt is set to an incremented count -- next\_attempt\_schedule\_time is set when the Nexus Task will be retried -- last\_attempt\_failure is set with the following fields: - - message is set to the error message. - - failure\_info is set to the Application Failure +- State is set to the new state, for example BackingOff +- Attempt is set to an incremented count +- Next_attempt_schedule_time is set when the Nexus Task will be retried +- Last_attempt_failure is set with the following fields: + - Message is set to the error message. + - Failure_info is set to the Application Failure For example, an unknown error thrown in a Nexus handler will surface as: @@ -138,7 +138,7 @@ Pending Nexus Operations: 1 ScheduleToCloseTimeout 0s NextAttemptScheduleTime 20 seconds from now LastAttemptCompleteTime 11 seconds ago - LastAttemptFailure {"message":"unexpected response status: \"500 Internal Server Error\": internal error","applicationFailureInfo":{}} + LastAttemptFailure {"message":"unexpected response status: "500 Internal Server Error": internal error","applicationFailureInfo":{}} ``` ### Non-retryable @@ -147,7 +147,7 @@ When an Activity or Workflow throws an Application Failure, the Failure's `type` Activities and Workflow can also avoid retrying by setting an Application Failure's `non_retryable` flag to `true`. When a Nexus Operation handler throws an Application Failure, it is retried by default using a built-in Retry Policy that cannot be customized. -Nexus Operation handlers can avoid retrying by setting an Application Failure's non\_retryable flag to true. When a [non-retryable error](/#nexus-errors) is returned from a Nexus handler, the overall Nexus Operation Execution is failed and the error is returned to the caller’s Workflow Execution as a **Nexus Operation Failure.** +Nexus Operation handlers can avoid retrying by setting an Application Failure's non_retryable flag to true. When a [non-retryable error](/#nexus-errors) is returned from a Nexus handler, the overall Nexus Operation Execution is failed and the error is returned to the caller’s Workflow Execution as a **Nexus Operation Failure.** ### Setting the Next Retry Delay {#next-retry-delay} @@ -162,9 +162,9 @@ Java: [NextRetryDelay](/develop/java/failure-detection#next-retry-delay) #### Default mapping -By default, Application Failures thrown from a Nexus Operation handler will be mapped to the following underlying Nexus Failures, based on what non\_retryable is set to: +By default, Application Failures thrown from a Nexus Operation handler will be mapped to the following underlying Nexus Failures, based on what non_retryable is set to: -| non\_retryable | Nexus error | HTTP status code | +| non_retryable | Nexus error | HTTP status code | | :-------------- | :------------------------- | :------------------------ | | false (default) | HandlerErrorTypeInternal | 500 Internal Server Error | | true | UnsuccessfulOperationError | 424 Failed Dependency | @@ -175,12 +175,12 @@ For improved semantics and mapping to HTTP status codes for external Nexus calle For example the Nexus Go SDK provides -- `nexus.HandlerErrorf(nexus.HandlerErrorType, msg)` +- `nexus.HandlerError(nexus.HandlerErrorType, msg)` - `nexus.UnsuccessfulOperationError{state, failure}` #### Retryable Nexus errors -| Nexus error type | non\_retryable | +| Nexus error type | non_retryable | | :-------------------------------- | :------------- | | HandlerErrorTypeResourceExhausted | false | | HandlerErrorTypeInternal | false | @@ -189,7 +189,7 @@ For example the Nexus Go SDK provides #### Non-retryable Nexus errors -| Nexus error type | non\_retryable | +| Nexus error type | non_retryable | | :------------------------------ | :------------- | | HandlerErrorTypeBadRequest | true | | HandlerErrorTypeUnauthenticated | true | @@ -203,8 +203,6 @@ When [Cancellation](/activities#cancellation) of a Workflow, Activity or Nexus O For example, in TypeScript, in some cases a Cancelled Failure is thrown directly by a Workflow API function, and in other cases the Cancelled Failure is wrapped in a different Failure. To check both types of cases, TypeScript has the [isCancellation](https://typescript.temporal.io/api/namespaces/workflow#iscancellation) helper. -{/* TODO also link to Workflow Cancellation concept */} - When a Workflow, Activity or Nexus Operation is successfully Cancelled, a Cancelled Failure is the `cause` field of the Activity Failure, Nexus Operation Failure or "Workflow failed" error. - TypeScript: [CancelledFailure](https://typescript.temporal.io/api/classes/common.CancelledFailure) @@ -230,7 +228,7 @@ For example, if an Activity Execution times out, the `cause` is a [Timeout Failu A Nexus Operation Failure is delivered to the Workflow Execution when a Nexus Operation fails. It contains information about the failure and the Nexus Operation Execution; for example, the Nexus Operation name and Nexus Operation Id. The reason for the failure is in the message and cause (typically an Application Error or a Canceled Error). -Go: NexusOperationError\ +Go: NexusOperationError Proto: NexusOperationFailureInfo A **Nexus Operation Failure** includes the following fields: From 1fac9ff6102afa3fc353c0c949a45ddba3eeda5f Mon Sep 17 00:00:00 2001 From: Jwahir Sundai Date: Fri, 11 Oct 2024 11:43:07 -0500 Subject: [PATCH 4/6] edits and adding link to create preview --- docs/references/commands.mdx | 2 +- docs/references/errors.mdx | 2 +- docs/references/failures.mdx | 3 ++- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/references/commands.mdx b/docs/references/commands.mdx index 3f7c96543a..df2f456220 100644 --- a/docs/references/commands.mdx +++ b/docs/references/commands.mdx @@ -131,7 +131,7 @@ This Command is triggered by a call to execute an Nexus Operation in the caller - Awaitable: Yes, a Workflow Execution can await on the action resulting from this Command. - Corresponding Event: NexusOperationScheduled -By default, you can't schedule more than 30 Nexus Operations concurrently (or in total during Public Preview since completed operations are not yet deleted), see [Limits](/#workflow-execution-nexus-operation-limits) for details. +By default, you can't schedule more than 30 Nexus Operations concurrently (or in total during Public Preview since completed operations are not yet deleted), see [Limits](/workflows#workflow-execution-nexus-operation-limits) for details. ### CancelNexusOperation diff --git a/docs/references/errors.mdx b/docs/references/errors.mdx index 3716ce9b7f..f786c8476a 100644 --- a/docs/references/errors.mdx +++ b/docs/references/errors.mdx @@ -226,7 +226,7 @@ In Public Preview, Nexus Operations are not yet deleted from mutable state when Let the Workflow complete any current Nexus Operation before retrying the Task. -See [Per Workflow Nexus Operation Limits](#per-workflow-nexus-operation-limits) for details. +See [Per Workflow Nexus Operation Limits](/cloud/limits#per-workflow-nexus-operation-limits) for details. ## Pending Request Cancel Limit Exceeded {#pending-request-cancel-limit-exceeded} diff --git a/docs/references/failures.mdx b/docs/references/failures.mdx index 4af558ef1c..09b487d1b9 100644 --- a/docs/references/failures.mdx +++ b/docs/references/failures.mdx @@ -147,7 +147,8 @@ When an Activity or Workflow throws an Application Failure, the Failure's `type` Activities and Workflow can also avoid retrying by setting an Application Failure's `non_retryable` flag to `true`. When a Nexus Operation handler throws an Application Failure, it is retried by default using a built-in Retry Policy that cannot be customized. -Nexus Operation handlers can avoid retrying by setting an Application Failure's non_retryable flag to true. When a [non-retryable error](/#nexus-errors) is returned from a Nexus handler, the overall Nexus Operation Execution is failed and the error is returned to the caller’s Workflow Execution as a **Nexus Operation Failure.** +Nexus Operation handlers can avoid retrying by setting an Application Failure's non_retryable flag to true. +When a non-retryable error is returned from a Nexus handler, the overall Nexus Operation Execution is failed and the error is returned to the caller’s Workflow Execution as a **Nexus Operation Failure.** ### Setting the Next Retry Delay {#next-retry-delay} From ded37c3b726a8f896441fc807e1e341bfdf0ab6a Mon Sep 17 00:00:00 2001 From: Jwahir Sundai Date: Fri, 11 Oct 2024 12:36:45 -0500 Subject: [PATCH 5/6] formatting file --- docs/references/failures.mdx | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/references/failures.mdx b/docs/references/failures.mdx index 09b487d1b9..e64d641992 100644 --- a/docs/references/failures.mdx +++ b/docs/references/failures.mdx @@ -147,7 +147,7 @@ When an Activity or Workflow throws an Application Failure, the Failure's `type` Activities and Workflow can also avoid retrying by setting an Application Failure's `non_retryable` flag to `true`. When a Nexus Operation handler throws an Application Failure, it is retried by default using a built-in Retry Policy that cannot be customized. -Nexus Operation handlers can avoid retrying by setting an Application Failure's non_retryable flag to true. +Nexus Operation handlers can avoid retrying by setting an Application Failure's non_retryable flag to true. When a non-retryable error is returned from a Nexus handler, the overall Nexus Operation Execution is failed and the error is returned to the caller’s Workflow Execution as a **Nexus Operation Failure.** ### Setting the Next Retry Delay {#next-retry-delay} @@ -165,7 +165,7 @@ Java: [NextRetryDelay](/develop/java/failure-detection#next-retry-delay) By default, Application Failures thrown from a Nexus Operation handler will be mapped to the following underlying Nexus Failures, based on what non_retryable is set to: -| non_retryable | Nexus error | HTTP status code | +| non_retryable | Nexus error | HTTP status code | | :-------------- | :------------------------- | :------------------------ | | false (default) | HandlerErrorTypeInternal | 500 Internal Server Error | | true | UnsuccessfulOperationError | 424 Failed Dependency | @@ -182,21 +182,21 @@ For example the Nexus Go SDK provides #### Retryable Nexus errors | Nexus error type | non_retryable | -| :-------------------------------- | :------------- | -| HandlerErrorTypeResourceExhausted | false | -| HandlerErrorTypeInternal | false | -| HandlerErrorTypeNotImplemented | false | -| HandlerErrorTypeUnavailable | false | +| :-------------------------------- | :------------ | +| HandlerErrorTypeResourceExhausted | false | +| HandlerErrorTypeInternal | false | +| HandlerErrorTypeNotImplemented | false | +| HandlerErrorTypeUnavailable | false | #### Non-retryable Nexus errors | Nexus error type | non_retryable | -| :------------------------------ | :------------- | -| HandlerErrorTypeBadRequest | true | -| HandlerErrorTypeUnauthenticated | true | -| HandlerErrorTypeUnauthorized | true | -| HandlerErrorTypeNotFound | true | -| UnsuccessfulOperationError | true | +| :------------------------------ | :------------ | +| HandlerErrorTypeBadRequest | true | +| HandlerErrorTypeUnauthenticated | true | +| HandlerErrorTypeUnauthorized | true | +| HandlerErrorTypeNotFound | true | +| UnsuccessfulOperationError | true | ## Cancelled Failure From 6fbd8d875349b0e3fd40c5aa114006836eaa628f Mon Sep 17 00:00:00 2001 From: Jwahir Sundai Date: Fri, 11 Oct 2024 13:15:11 -0500 Subject: [PATCH 6/6] editing failure --- docs/references/failures.mdx | 51 +++++++++++++++++++----------------- 1 file changed, 27 insertions(+), 24 deletions(-) diff --git a/docs/references/failures.mdx b/docs/references/failures.mdx index e64d641992..97081aad0d 100644 --- a/docs/references/failures.mdx +++ b/docs/references/failures.mdx @@ -89,7 +89,8 @@ An error in a Nexus Operation can cause either a Nexus Operation Task Failure (t #### Nexus Operation Task Failures A Nexus Operation Task Failure is an unexpected situation failing to process a Nexus Operation Task in a handler. -This could be triggered by throwing an unknown error in your Nexus handler code. These types of failures will cause the Nexus Operation Task to be retried. +This could be triggered by throwing an unknown error in your Nexus handler code. +These types of failures will cause the Nexus Operation Task to be retried. #### Nexus Operation Execution Failures @@ -100,7 +101,7 @@ Nexus Operation Execution Failures put the Nexus Operation Execution into the "F Application Errors thrown from a Workflow created by a Nexus NewWorkflowRunOperation handler, will be automatically propagated to the caller as a non-retryable error and result in a Nexus Operation Execution Failure. -#### Using Failures in a Nexus hander +#### Using Failures in a Nexus handler In a Nexus Operation handler, you can throw an Application Failure, a Nexus Error or another Error to fail the individual Nexus Operation Task or fail the overall Nexus Operation Execution. @@ -112,15 +113,15 @@ Unknown errors are converted to a retryable Application Failure. During conversi #### Retryable failures -Retryable Nexus Operation Task failures, like an unknown error, are automatically retried with a built-in retry policy. -When a Nexus Task fails, the caller workflow records an event attempt failure on the pending Nexus Operation and sets the following fields: +Retryable Nexus Operation Task failures, like an unknown error, are automatically retried with a built-in Retry Policy. +When a Nexus Task fails, the caller Workflow records an event attempt failure on the pending Nexus Operation and sets the following fields: -- State is set to the new state, for example BackingOff -- Attempt is set to an incremented count -- Next_attempt_schedule_time is set when the Nexus Task will be retried +- State is set to the new state, for example BackingOff. +- Attempt is set to an incremented count. +- Next_attempt_schedule_time is set when the Nexus Task will be retried. - Last_attempt_failure is set with the following fields: - Message is set to the error message. - - Failure_info is set to the Application Failure + - Failure_info is set to the Application Failure. For example, an unknown error thrown in a Nexus handler will surface as: @@ -148,7 +149,7 @@ Activities and Workflow can also avoid retrying by setting an Application Failur When a Nexus Operation handler throws an Application Failure, it is retried by default using a built-in Retry Policy that cannot be customized. Nexus Operation handlers can avoid retrying by setting an Application Failure's non_retryable flag to true. -When a non-retryable error is returned from a Nexus handler, the overall Nexus Operation Execution is failed and the error is returned to the caller’s Workflow Execution as a **Nexus Operation Failure.** +When a non-retryable error is returned from a Nexus handler, the overall Nexus Operation Execution is failed and the error is returned to the caller’s Workflow Execution as a Nexus Operation Failure. ### Setting the Next Retry Delay {#next-retry-delay} @@ -227,24 +228,26 @@ For example, if an Activity Execution times out, the `cause` is a [Timeout Failu ## Nexus Operation Failure -A Nexus Operation Failure is delivered to the Workflow Execution when a Nexus Operation fails. It contains information about the failure and the Nexus Operation Execution; for example, the Nexus Operation name and Nexus Operation Id. The reason for the failure is in the message and cause (typically an Application Error or a Canceled Error). +A Nexus Operation Failure is delivered to the Workflow Execution when a Nexus Operation fails. +It contains information about the failure and the Nexus Operation Execution; for example, the Nexus Operation name and Nexus Operation ID. +The reason for the failure is in the message and cause (typically an Application Error or a Canceled Error). -Go: NexusOperationError -Proto: NexusOperationFailureInfo +- Go: NexusOperationError +- Proto: NexusOperationFailureInfo -A **Nexus Operation Failure** includes the following fields: +A Nexus Operation Failure includes the following fields: -- endpoint is set to the name of the endpoint -- service is set to the name of the service -- operation is set to the name of the operation -- operation_id is set to the id of the operation, if this is an async operation -- scheduled_event_id is set to the caller’s event id that scheduled the operation -- message is set to a generic unsuccessful error message -- cause is set to the underlying Application Failure with the following fields: - - non-retryable is set to true - - type is set to the error's type name. - - message is set to the error message. -- nexus_error_code is set the the underlying Nexus error code +- Endpoint is set to the name of the endpoint. +- Service is set to the name of the service. +- Operation is set to the name of the operation. +- Operation_id is set to the id of the operation, if this is an async operation. +- Scheduled_event_id is set to the caller’s event id that scheduled the operation. +- Message is set to a generic unsuccessful error message. +- Cause is set to the underlying Application Failure with the following fields: + - Non-retryable is set to true. + - Type is set to the error's type name. + - Message is set to the error message. +- Nexus_error_code is set the the underlying Nexus error code. ## Child Workflow Failure