From 329e609ec4f974f82ac9f0ccb030a9ff0beb3bcb Mon Sep 17 00:00:00 2001 From: tudor-da Date: Tue, 23 Nov 2021 21:30:33 +0100 Subject: [PATCH] [Self-service error codes] Group explanations (#11715) * [Self-service error codes] Error group descriptions CHANGELOG_BEGIN CHANGELOG_END * Apply suggestions from code review Co-authored-by: mziolekda Co-authored-by: mziolekda --- .../daml/error/definitions/IndexErrors.scala | 1 + .../error/definitions/LedgerApiErrors.scala | 25 +++++++++++++++++++ .../LoggingPackageServiceError.scala | 4 +++ .../state/kvutils/errors/KVErrors.scala | 3 +-- 4 files changed, 31 insertions(+), 2 deletions(-) diff --git a/ledger/error/src/main/scala/com/daml/error/definitions/IndexErrors.scala b/ledger/error/src/main/scala/com/daml/error/definitions/IndexErrors.scala index 2d28f00db7aa..5ad5d5131a1f 100644 --- a/ledger/error/src/main/scala/com/daml/error/definitions/IndexErrors.scala +++ b/ledger/error/src/main/scala/com/daml/error/definitions/IndexErrors.scala @@ -8,6 +8,7 @@ import com.daml.error.definitions.ErrorGroups.ParticipantErrorGroup.IndexErrorGr import com.daml.error.utils.ErrorDetails import io.grpc.StatusRuntimeException +@Explanation("Errors raised by the Participant Index persistence layer.") object IndexErrors extends IndexErrorGroup { object DatabaseErrors extends DatabaseErrorGroup { @Explanation( diff --git a/ledger/error/src/main/scala/com/daml/error/definitions/LedgerApiErrors.scala b/ledger/error/src/main/scala/com/daml/error/definitions/LedgerApiErrors.scala index 3c77636475bb..4760133ef9cc 100644 --- a/ledger/error/src/main/scala/com/daml/error/definitions/LedgerApiErrors.scala +++ b/ledger/error/src/main/scala/com/daml/error/definitions/LedgerApiErrors.scala @@ -18,6 +18,9 @@ import org.slf4j.event.Level import java.time.{Duration, Instant} +@Explanation( + "Errors raised by or forwarded by the Ledger API." +) object LedgerApiErrors extends LedgerApiErrorGroup { @Explanation( """This error occurs when a participant rejects a command due to excessive load. @@ -58,6 +61,9 @@ object LedgerApiErrors extends LedgerApiErrorGroup { ) } + @Explanation( + "Errors raised during the command execution phase of the command submission evaluation." + ) object CommandExecution extends ErrorGroup { @Explanation( """This error occurs if the participant fails to determine the max ledger time of the used @@ -80,6 +86,7 @@ object LedgerApiErrors extends LedgerApiErrorGroup { ) } + @Explanation("Command execution errors raised due to invalid packages.") object Package extends ErrorGroup() { @Explanation( """This error indicates that the uploaded DAR is based on an unsupported language version.""" @@ -128,6 +135,9 @@ object LedgerApiErrors extends LedgerApiErrorGroup { } } + @Explanation( + "Errors raised during command conversion to the internal data representation." + ) object Preprocessing extends ErrorGroup { @Explanation("""This error occurs if a command fails during interpreter pre-processing.""") @Resolution("Inspect error details and correct your application.") @@ -146,6 +156,9 @@ object LedgerApiErrors extends LedgerApiErrorGroup { } } + @Explanation( + "Errors raised during the command interpretation phase of the command submission evaluation." + ) object Interpreter extends ErrorGroup { @Explanation("""This error occurs if a Daml transaction fails during interpretation.""") @Resolution("This error type occurs if there is an application error.") @@ -205,6 +218,7 @@ object LedgerApiErrors extends LedgerApiErrorGroup { } + @Explanation("Errors raised in lookups during the command interpretation phase.") object LookupErrors extends ErrorGroup { @Explanation( """This error occurs if the Daml engine interpreter cannot resolve a contract key to an active contract. This @@ -274,6 +288,7 @@ object LedgerApiErrors extends LedgerApiErrorGroup { ) } + @Explanation("Authentication errors.") object AuthorizationChecks extends ErrorGroup() { @Explanation( """This rejection is given if the submitted command does not contain a JWT token on a participant enforcing JWT authentication.""" @@ -326,6 +341,9 @@ object LedgerApiErrors extends LedgerApiErrorGroup { } } + @Explanation( + "Validation errors raised when evaluating requests in the Ledger API." + ) object RequestValidation extends ErrorGroup { object NotFound extends ErrorGroup() { @Explanation( @@ -606,6 +624,7 @@ object LedgerApiErrors extends LedgerApiErrorGroup { ) extends LoggingTransactionErrorImpl(cause = message, throwableO = throwableO) } + @Explanation("Errors raised by Ledger API admin services.") object AdminServices { @Explanation("This rejection is given when a new configuration is rejected.") @Resolution("Fetch newest configuration and/or retry.") @@ -636,6 +655,9 @@ object LedgerApiErrors extends LedgerApiErrorGroup { } } + @Explanation( + "Potential consistency errors raised due to race conditions during command submission or returned as submission rejections by the backing ledger." + ) object ConsistencyErrors extends ErrorGroup { @Explanation("A command with the given command id has already been successfully processed.") @Resolution( @@ -796,6 +818,9 @@ object LedgerApiErrors extends LedgerApiErrorGroup { } } + @Explanation( + "Generic submission rejection errors returned by the backing ledger's write service." + ) object WriteServiceRejections extends ErrorGroup { @Explanation("The submitting party has not been allocated.") @Resolution( diff --git a/ledger/error/src/main/scala/com/daml/error/definitions/LoggingPackageServiceError.scala b/ledger/error/src/main/scala/com/daml/error/definitions/LoggingPackageServiceError.scala index 3148f7fae4cd..0ae62767dd29 100644 --- a/ledger/error/src/main/scala/com/daml/error/definitions/LoggingPackageServiceError.scala +++ b/ledger/error/src/main/scala/com/daml/error/definitions/LoggingPackageServiceError.scala @@ -21,7 +21,11 @@ abstract class LoggingPackageServiceError( final override def logOnCreation: Boolean = true } +@Explanation( + "Errors raised by the Package Management Service on package uploads." +) object PackageServiceError extends LedgerApiErrors.PackageServiceErrorGroup { + @Explanation("Package parsing errors raised during package upload.") object Reading extends ErrorGroup { @Explanation( """This error indicates that the supplied dar file name did not meet the requirements to be stored in the persistence store.""" diff --git a/ledger/participant-state/kvutils/src/main/scala/com/daml/ledger/participant/state/kvutils/errors/KVErrors.scala b/ledger/participant-state/kvutils/src/main/scala/com/daml/ledger/participant/state/kvutils/errors/KVErrors.scala index c4bee52f2713..28204161a02b 100644 --- a/ledger/participant-state/kvutils/src/main/scala/com/daml/ledger/participant/state/kvutils/errors/KVErrors.scala +++ b/ledger/participant-state/kvutils/src/main/scala/com/daml/ledger/participant/state/kvutils/errors/KVErrors.scala @@ -17,8 +17,7 @@ import com.daml.error.{ import com.daml.ledger.participant.state.kvutils.committer.transaction.Rejection.InternallyInconsistentTransaction @Explanation( - "Errors that are specific to ledgers based on the KV architecture. " + - "Note that this section will soon cover all ledgers due to an ongoing error consolidation effort." + "Errors that are specific to ledgers based on the KV architecture: Daml Sandbox and VMBC." ) object KVErrors extends ErrorGroup()(ErrorGroups.rootErrorClass) {