From ed6e413814ae8e477e0b9258da90e646b418fec6 Mon Sep 17 00:00:00 2001 From: Tudor Voicu Date: Fri, 19 Nov 2021 23:08:01 +0100 Subject: [PATCH 01/12] Updated Ledger API services protobuf definitions CHANGELOG_BEGIN CHANGELOG_END --- .../v1/admin/config_management_service.proto | 8 ++--- .../v1/admin/package_management_service.proto | 3 -- .../admin/participant_pruning_service.proto | 11 ++---- .../v1/admin/party_management_service.proto | 4 +-- .../api/v1/command_completion_service.proto | 5 +-- .../daml/ledger/api/v1/command_service.proto | 36 ++++++++++++------- .../api/v1/command_submission_service.proto | 9 +++-- .../ledger/api/v1/transaction_service.proto | 10 +++--- 8 files changed, 45 insertions(+), 41 deletions(-) diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/config_management_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/config_management_service.proto index 0cff08350193..88acb0ba75e3 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/config_management_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/config_management_service.proto @@ -12,10 +12,7 @@ option csharp_namespace = "Com.Daml.Ledger.Api.V1.Admin"; import "google/protobuf/duration.proto"; import "google/protobuf/timestamp.proto"; -// Status: experimental interface, will change before it is deemed production -// ready -// -// Ledger configuration management service provides methods for the ledger administrator +// The ledger configuration management service provides methods for the ledger administrator // to change the current ledger configuration. The services provides methods to modify // different aspects of the configuration. service ConfigManagementService { @@ -34,9 +31,10 @@ service ConfigManagementService { // does not match the current active configuration generation. The caller is expected // to retry by again fetching current time model using 'GetTimeModel', applying changes // and resubmitting. - // - ``ABORTED``: if the request is rejected or times out. Note that a timed out request may + // - ``DEADLINE_EXCEEDED``: if the request times out. Note that a timed out request may // have still been committed to the ledger. Application should re-query the current // time model before retrying. + // - ``FAILED_PRECONDITION``: if the request is rejected. // - ``UNIMPLEMENTED``: if this method is not supported by the backing ledger. rpc SetTimeModel (SetTimeModelRequest) returns (SetTimeModelResponse); } diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/package_management_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/package_management_service.proto index f7833628928f..4563429e84c7 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/package_management_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/package_management_service.proto @@ -11,9 +11,6 @@ option java_outer_classname = "PackageManagementServiceOuterClass"; option java_package = "com.daml.ledger.api.v1.admin"; option csharp_namespace = "Com.Daml.Ledger.Api.V1.Admin"; -// Status: experimental interface, will change before it is deemed production -// ready -// // Query the Daml-LF packages supported by the ledger participant and upload // DAR files. We use 'backing participant' to refer to this specific participant // in the methods of this API. diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/participant_pruning_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/participant_pruning_service.proto index dd68c183f8c3..02f751cc8d5a 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/participant_pruning_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/participant_pruning_service.proto @@ -9,9 +9,6 @@ option java_outer_classname = "ParticipantPruningServiceOuterClass"; option java_package = "com.daml.ledger.api.v1.admin"; option csharp_namespace = "Com.Daml.Ledger.Api.V1.Admin"; -// Status: experimental interface, will change before it is deemed production -// ready - // Prunes/truncates the "oldest" transactions from the participant (the participant Ledger Api Server plus any other // participant-local state) by removing a portion of the ledger in such a way that the set of future, allowed // commands are not affected. @@ -28,12 +25,10 @@ service ParticipantPruningService { // - ``INTERNAL``: if the participant has encountered a failure and has potentially applied pruning partially. Such cases // warrant verifying the participant health before retrying the prune with the same (or a larger, valid) offset. // Successful retries after such errors ensure that different components reach a consistent pruning state. - // - // Other GRPC errors can be returned depending on the type of condition preventing a prune: - // - ``OUT_OF_RANGE``: if the participant is not yet able to prune at the specified offset, but without user intervention + // - ``FAILED_PRECONDITION``: if the participant is not yet able to prune at the specified offset, but without user intervention // the offset will eventually be usable for pruning. - // - ``FAILED_PRECONDITION`` if some sort of user intervention is required before pruning can proceed at the specified - // offset. + // Other GRPC errors can be returned depending on the type of condition preventing a prune: + // rpc Prune (PruneRequest) returns (PruneResponse); } diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/party_management_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/party_management_service.proto index bb84b54f1a73..6dd4d2ca7101 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/party_management_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/party_management_service.proto @@ -10,9 +10,6 @@ option java_outer_classname = "PartyManagementServiceOuterClass"; option java_package = "com.daml.ledger.api.v1.admin"; option csharp_namespace = "Com.Daml.Ledger.Api.V1.Admin"; -// Status: experimental interface, will change before it is deemed production -// ready -// // Inspect the party management state of a ledger participant and modify the // parts that are modifiable. We use 'backing participant' to refer to this // specific participant in the methods of this API. @@ -54,6 +51,7 @@ service PartyManagementService { // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation // - ``UNIMPLEMENTED``: if synchronous party allocation is not supported by the backing participant + // - ``DEADLINE_EXCEEDED``: if the request times out // - ``INVALID_ARGUMENT``: if the provided hint and/or display name is invalid on the given ledger (see below). // daml-on-sql: suggestion's uniqueness is checked and call rejected if the identifier is already present // daml-on-kv-ledger: suggestion's uniqueness is checked by the validators in diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_completion_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_completion_service.proto index 8e9407613310..b647a5212ef6 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_completion_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_completion_service.proto @@ -33,9 +33,10 @@ service CommandCompletionService { // Errors: // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation - // - ``NOT_FOUND``: if the request does not include a valid ledger id or if the ledger has been pruned before ``begin`` + // - ``NOT_FOUND``: if the request does not include a valid ledger id + // - ``FAILED_PRECONDITION``: if the ledger has been pruned after the subscription start offset // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields - // - ``OUT_OF_RANGE``: if the absolute offset is not before the end of the ledger + // - ``OUT_OF_RANGE``: if the absolute offset is after the end of the ledger rpc CompletionStream (CompletionStreamRequest) returns (stream CompletionStreamResponse); // Returns the offset after the latest completion. diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_service.proto index bb5f95c463ac..dab7487bd125 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_service.proto @@ -24,11 +24,14 @@ service CommandService { // Errors: // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation - // - ``NOT_FOUND``: if the request does not include a valid ledger id + // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a contract key is missing + // due to for example contention on resources + // - ``ALREADY_EXISTS`` if a contract key is duplicated // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields - // - ``RESOURCE_EXHAUSTED``: if the number of in-flight commands reached the maximum (if a limit is configured) + // - ``ABORTED``: if the number of in-flight commands reached the maximum (if a limit is configured) + // - ``FAILED_PRECONDITION``: on consistency errors (e.g. the contract key has changed since the submission) + // or if an interpretation error occurred // - ``UNAVAILABLE``: if the participant is not yet ready to submit commands or if the service has been shut down. - // - ``ABORTED``: if a contract key is missing or duplicated due to for example contention on resources rpc SubmitAndWait (SubmitAndWaitRequest) returns (google.protobuf.Empty); // Submits a single composite command, waits for its result, and returns the transaction id. @@ -36,11 +39,14 @@ service CommandService { // Errors: // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation - // - ``NOT_FOUND``: if the request does not include a valid ledger id + // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a contract key is missing + // due to for example contention on resources + // - ``ALREADY_EXISTS`` if a contract key is duplicated // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields - // - ``RESOURCE_EXHAUSTED``: if the number of in-flight commands reached the maximum (if a limit is configured) + // - ``ABORTED``: if the number of in-flight commands reached the maximum (if a limit is configured) + // - ``FAILED_PRECONDITION``: on consistency errors (e.g. the contract key has changed since the submission) + // or if an interpretation error occurred // - ``UNAVAILABLE``: if the participant is not yet ready to submit commands or if the service has been shut down. - // - ``ABORTED``: if a contract key is missing or duplicated due to for example contention on resources rpc SubmitAndWaitForTransactionId (SubmitAndWaitRequest) returns (SubmitAndWaitForTransactionIdResponse); // Submits a single composite command, waits for its result, and returns the transaction. @@ -48,11 +54,14 @@ service CommandService { // Errors: // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation - // - ``NOT_FOUND``: if the request does not include a valid ledger id + // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a contract key is missing + // due to for example contention on resources + // - ``ALREADY_EXISTS`` if a contract key is duplicated // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields - // - ``RESOURCE_EXHAUSTED``: if the number of in-flight commands reached the maximum (if a limit is configured) + // - ``ABORTED``: if the number of in-flight commands reached the maximum (if a limit is configured) + // - ``FAILED_PRECONDITION``: on consistency errors (e.g. the contract key has changed since the submission) + // or if an interpretation error occurred // - ``UNAVAILABLE``: if the participant is not yet ready to submit commands or if the service has been shut down. - // - ``ABORTED``: if a contract key is missing or duplicated due to for example contention on resources rpc SubmitAndWaitForTransaction (SubmitAndWaitRequest) returns (SubmitAndWaitForTransactionResponse); // Submits a single composite command, waits for its result, and returns the transaction tree. @@ -60,11 +69,14 @@ service CommandService { // Errors: // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation - // - ``NOT_FOUND``: if the request does not include a valid ledger id + // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a contract key is missing + // due to for example contention on resources + // - ``ALREADY_EXISTS`` if a contract key is duplicated // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields - // - ``RESOURCE_EXHAUSTED``: if the number of in-flight commands reached the maximum (if a limit is configured) + // - ``ABORTED``: if the number of in-flight commands reached the maximum (if a limit is configured) + // - ``FAILED_PRECONDITION``: on consistency errors (e.g. the contract key has changed since the submission) + // or if an interpretation error occurred // - ``UNAVAILABLE``: if the participant is not yet ready to submit commands or if the service has been shut down. - // - ``ABORTED``: if a contract key is missing or duplicated due to for example contention on resources rpc SubmitAndWaitForTransactionTree (SubmitAndWaitRequest) returns (SubmitAndWaitForTransactionTreeResponse); } diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_submission_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_submission_service.proto index 202d4d63b7be..47664bae0140 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_submission_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_submission_service.proto @@ -32,11 +32,14 @@ service CommandSubmissionService { // Errors: // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation - // - ``NOT_FOUND``: if the request does not include a valid ledger id + // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a contract key is missing + // due to for example contention on resources + // - ``ALREADY_EXISTS`` if a contract key is duplicated // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields + // - ``ABORTED``: if the number of in-flight commands reached the maximum (if a limit is configured) + // - ``FAILED_PRECONDITION``: on consistency errors (e.g. the contract key has changed since the submission) + // or if an interpretation error occurred // - ``UNAVAILABLE``: if the participant is not yet ready to submit commands or if the service has been shut down. - // - ``RESOURCE_EXHAUSTED``: if the participant or the ledger is overloaded. Clients should back off exponentially and retry. - // - ``ABORTED``: if a contract key is missing or duplicated due to for example contention on resources rpc Submit (SubmitRequest) returns (google.protobuf.Empty); } diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/transaction_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/transaction_service.proto index 7885445f68d4..2f6208c09a55 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/transaction_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/transaction_service.proto @@ -22,8 +22,8 @@ service TransactionService { // Errors: // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation - // - ``NOT_FOUND``: if the request does not include a valid ledger id or if the ledger has been pruned before ``begin`` - // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields (e.g. if ``before`` is not before ``end``) + // - ``NOT_FOUND``: if the request does not include a valid ledger id + // - ``FAILED_PRECONDITION``: if the ledger has been pruned after the subscription start offset // - ``OUT_OF_RANGE``: if the ``begin`` parameter value is not before the end of the ledger rpc GetTransactions (GetTransactionsRequest) returns (stream GetTransactionsResponse); @@ -32,8 +32,8 @@ service TransactionService { // Errors: // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation - // - ``NOT_FOUND``: if the request does not include a valid ledger id or if the ledger has been pruned before ``begin`` - // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields (e.g. if ``before`` is not before ``end``) + // - ``NOT_FOUND``: if the request does not include a valid ledger id + // - ``FAILED_PRECONDITION``: if the ledger has been pruned after the subscription start offset // - ``OUT_OF_RANGE``: if the ``begin`` parameter value is not before the end of the ledger rpc GetTransactionTrees (GetTransactionsRequest) returns (stream GetTransactionTreesResponse); @@ -76,7 +76,7 @@ service TransactionService { // Errors: // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation - // - ``NOT_FOUND``: if the request does not include a valid ledger id or no such transaction exists + // - ``NOT_FOUND``: if the request does not include a valid ledger id rpc GetLedgerEnd (GetLedgerEndRequest) returns (GetLedgerEndResponse); } From 3baf37c6fd2312814b1faf6f186ee38a53018f78 Mon Sep 17 00:00:00 2001 From: Tudor Voicu Date: Fri, 19 Nov 2021 23:50:55 +0100 Subject: [PATCH 02/12] Adapted Building Applications / Ledger API / gRPC section --- docs/source/app-dev/grpc/index.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/source/app-dev/grpc/index.rst b/docs/source/app-dev/grpc/index.rst index fa6235531c5a..089d5d18407c 100644 --- a/docs/source/app-dev/grpc/index.rst +++ b/docs/source/app-dev/grpc/index.rst @@ -66,14 +66,16 @@ For information on how Daml types and contracts are represented by the Ledger AP Error handling ************** -For the standard error codes that the server or the client might return, see the `gRPC documentation `__ . +The Ledger API generally uses the gRPC standard error codes for signaling response failures to client applications. -For submitted commands, there are these response codes: +For more details on the gRPC standard error codes, see the `gRPC documentation `__ . + +Generically, on submitted commands the ledger API responds with the following gRPC status codes: ABORTED The platform failed to record the result of the command due to a transient server-side error or a time constraint violation. You can retry the submission. In case of a time constraint violation, please refer to the section :ref:`Dealing with time ` on how to handle commands with long processing times. ALREADY_EXISTS - The command was rejected because it was sent within the deduplication period of a previous command with the same change ID. + The command was rejected because the resource already exists or because it was sent within the deduplication period of a previous command with the same change ID. INVALID_ARGUMENT The submission failed because of a client error. The platform will definitely reject resubmissions of the same command. OK, INTERNAL, UNKNOWN (when returned by the Command Submission Service) @@ -82,3 +84,7 @@ OK (when returned by the Command Service) You can be sure that the command was successful. INTERNAL, UNKNOWN (when returned by the Command Service) Resubmit the command with the same command_id. + +Aside from the standard gRPC status codes, the failures returned by the Ledger API are enriched with details meant to help the application +or the application developer to handle the error autonomously (e.g. by retrying on a retryable error). +For more details on the rich error details see the :doc:`/error-codes/self-service/index` From ec2d4909ea2bb5daca271261bb58feed4decdd45 Mon Sep 17 00:00:00 2001 From: Tudor Voicu Date: Sat, 20 Nov 2021 00:15:45 +0100 Subject: [PATCH 03/12] Moved Error Codes under Building Applications / Ledger API / gRPC --- .../index.rst => app-dev/grpc/error-codes.rst} | 5 ++--- docs/source/app-dev/grpc/index.rst | 9 ++++++--- docs/source/index.rst | 1 - 3 files changed, 8 insertions(+), 7 deletions(-) rename docs/source/{error-codes/self-service/index.rst => app-dev/grpc/error-codes.rst} (99%) diff --git a/docs/source/error-codes/self-service/index.rst b/docs/source/app-dev/grpc/error-codes.rst similarity index 99% rename from docs/source/error-codes/self-service/index.rst rename to docs/source/app-dev/grpc/error-codes.rst index fb3c8cdf1374..0b895e927bb4 100644 --- a/docs/source/error-codes/self-service/index.rst +++ b/docs/source/app-dev/grpc/error-codes.rst @@ -1,12 +1,11 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 +.. _error-codes: + Error Codes ########### -.. toctree:: - :hidden: - Overview ********* diff --git a/docs/source/app-dev/grpc/index.rst b/docs/source/app-dev/grpc/index.rst index 089d5d18407c..04832d4229fb 100644 --- a/docs/source/app-dev/grpc/index.rst +++ b/docs/source/app-dev/grpc/index.rst @@ -1,11 +1,14 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -.. _grpc: - gRPC #### +.. toctree:: + :hidden: + + error-codes + If you want to write an application for the ledger API in other languages, you'll need to use `gRPC `__ directly. If you're not familiar with gRPC and protobuf, we strongly recommend following the `gRPC quickstart `__ and `gRPC tutorials `__. This documentation is written assuming you already have an understanding of gRPC. @@ -87,4 +90,4 @@ INTERNAL, UNKNOWN (when returned by the Command Service) Aside from the standard gRPC status codes, the failures returned by the Ledger API are enriched with details meant to help the application or the application developer to handle the error autonomously (e.g. by retrying on a retryable error). -For more details on the rich error details see the :doc:`/error-codes/self-service/index` +For more details on the rich error details see the :doc:`error-codes` diff --git a/docs/source/index.rst b/docs/source/index.rst index c416512745c8..fca852cb5c5b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -52,7 +52,6 @@ Daml Documentation triggers/index tools/trigger-service/index tools/auth-middleware/index - error-codes/self-service/index .. toctree:: :titlesonly: From b3ceb8d8684e73d88a7710f4b76051d8e8f75149 Mon Sep 17 00:00:00 2001 From: Tudor Voicu Date: Sat, 20 Nov 2021 00:21:17 +0100 Subject: [PATCH 04/12] Small rewording Error codes page --- docs/source/app-dev/grpc/error-codes.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/app-dev/grpc/error-codes.rst b/docs/source/app-dev/grpc/error-codes.rst index 0b895e927bb4..f186b5bc7a7f 100644 --- a/docs/source/app-dev/grpc/error-codes.rst +++ b/docs/source/app-dev/grpc/error-codes.rst @@ -12,15 +12,15 @@ Overview .. _gRPC status codes: https://grpc.github.io/grpc/core/md_doc_statuscodes.html .. _gRPC status code: https://grpc.github.io/grpc/core/md_doc_statuscodes.html -.. _StatusRuntimeException: https://grpc.github.io/grpc-java/javadoc/io/grpc/StatusRuntimeException.html .. _rich gRPC error model: https://cloud.google.com/apis/design/errors#error_details .. _standard gRPC description: https://grpc.github.io/grpc-java/javadoc/io/grpc/Status.html#getDescription-- The majority of the errors are a result of some request processing. -They are logged and returned to the user as a failed gRPC request -using the standard StatusRuntimeException_. -As such this approach remains unchanged in principle while we aim at +They are logged and returned to the user as a failed gRPC response +containing the status code, an optional status message and optional metadata. + +This approach remains unchanged in principle while we aim at enhancing it by providing: - improved consistency of the returned errors across API endpoints, From 2054f847e22e4674cdfb92857a78e5c45a1195a2 Mon Sep 17 00:00:00 2001 From: Tudor Voicu Date: Sat, 20 Nov 2021 00:31:06 +0100 Subject: [PATCH 05/12] Updated outdated LedgerAPI / gRPC page --- docs/source/app-dev/grpc/error-codes.rst | 3 +-- docs/source/app-dev/grpc/index.rst | 20 ++++++++++++++----- .../admin/participant_pruning_service.proto | 4 +--- .../daml/ledger/api/v1/command_service.proto | 20 +++++++++++-------- .../api/v1/command_submission_service.proto | 4 ++-- 5 files changed, 31 insertions(+), 20 deletions(-) diff --git a/docs/source/app-dev/grpc/error-codes.rst b/docs/source/app-dev/grpc/error-codes.rst index f186b5bc7a7f..71ac31dd2ef6 100644 --- a/docs/source/app-dev/grpc/error-codes.rst +++ b/docs/source/app-dev/grpc/error-codes.rst @@ -291,8 +291,7 @@ Anatomy of an Error --------------------------- -Errors returned to users are represented as instances of standard StatusRuntimeException_. -As such they contain a `gRPC status code`_, a description and additional machine readable information +Errors returned to users contain a `gRPC status code`_, a description and additional machine readable information represented in the `rich gRPC error model`_. diff --git a/docs/source/app-dev/grpc/index.rst b/docs/source/app-dev/grpc/index.rst index 04832d4229fb..2663d5ff75b2 100644 --- a/docs/source/app-dev/grpc/index.rst +++ b/docs/source/app-dev/grpc/index.rst @@ -1,9 +1,13 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 +.. _grpc: + gRPC #### + + .. toctree:: :hidden: @@ -73,20 +77,26 @@ The Ledger API generally uses the gRPC standard error codes for signaling respon For more details on the gRPC standard error codes, see the `gRPC documentation `__ . -Generically, on submitted commands the ledger API responds with the following gRPC status codes: +Generically, on submitted commands the Ledger API responds with the following gRPC status codes: ABORTED The platform failed to record the result of the command due to a transient server-side error or a time constraint violation. You can retry the submission. In case of a time constraint violation, please refer to the section :ref:`Dealing with time ` on how to handle commands with long processing times. +DEADLINE_EXCEEDED (when returned by the Command Service) + The request might not have been processed, as its deadline expired before its completion was signalled. ALREADY_EXISTS - The command was rejected because the resource already exists or because it was sent within the deduplication period of a previous command with the same change ID. + The command was rejected because the resource (e.g. contract key) already exists or because it was sent within the deduplication period of a previous command with the same change ID. +NOT_FOUND + The command was rejected due to a missing resources (e.g. contract key not found). INVALID_ARGUMENT The submission failed because of a client error. The platform will definitely reject resubmissions of the same command. -OK, INTERNAL, UNKNOWN (when returned by the Command Submission Service) - Assume that the command was accepted, and wait for the resulting completion or a timeout from the Command Completion Service. +FAILED_PRECONDITION + The command was rejected due to an interpretation error or due to a consistency error due to races. +OK (when returned by the Command Submission Service) + Assume that the command was accepted and wait for the resulting completion or a timeout from the Command Completion Service. OK (when returned by the Command Service) You can be sure that the command was successful. INTERNAL, UNKNOWN (when returned by the Command Service) - Resubmit the command with the same command_id. + An internal system fault occurred. Contact the participant operator for the resolution. Aside from the standard gRPC status codes, the failures returned by the Ledger API are enriched with details meant to help the application or the application developer to handle the error autonomously (e.g. by retrying on a retryable error). diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/participant_pruning_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/participant_pruning_service.proto index 02f751cc8d5a..27836b908d5b 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/participant_pruning_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/participant_pruning_service.proto @@ -25,9 +25,7 @@ service ParticipantPruningService { // - ``INTERNAL``: if the participant has encountered a failure and has potentially applied pruning partially. Such cases // warrant verifying the participant health before retrying the prune with the same (or a larger, valid) offset. // Successful retries after such errors ensure that different components reach a consistent pruning state. - // - ``FAILED_PRECONDITION``: if the participant is not yet able to prune at the specified offset, but without user intervention - // the offset will eventually be usable for pruning. - // Other GRPC errors can be returned depending on the type of condition preventing a prune: + // - ``FAILED_PRECONDITION``: if the participant is not yet able to prune at the specified offset. // rpc Prune (PruneRequest) returns (PruneResponse); diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_service.proto index dab7487bd125..302f277b1461 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_service.proto @@ -24,14 +24,15 @@ service CommandService { // Errors: // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation - // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a contract key is missing + // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a resource is missing (e.g. contract key) // due to for example contention on resources - // - ``ALREADY_EXISTS`` if a contract key is duplicated + // - ``ALREADY_EXISTS`` if a resource is duplicated (e.g. contract key) // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields // - ``ABORTED``: if the number of in-flight commands reached the maximum (if a limit is configured) // - ``FAILED_PRECONDITION``: on consistency errors (e.g. the contract key has changed since the submission) // or if an interpretation error occurred // - ``UNAVAILABLE``: if the participant is not yet ready to submit commands or if the service has been shut down. + // - ``DEADLINE_EXCEEDED``: if the request failed to receive its completion within the predefined timeout. rpc SubmitAndWait (SubmitAndWaitRequest) returns (google.protobuf.Empty); // Submits a single composite command, waits for its result, and returns the transaction id. @@ -39,14 +40,15 @@ service CommandService { // Errors: // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation - // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a contract key is missing + // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a resource is missing (e.g. contract key) // due to for example contention on resources - // - ``ALREADY_EXISTS`` if a contract key is duplicated + // - ``ALREADY_EXISTS`` if a resource is duplicated (e.g. contract key) // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields // - ``ABORTED``: if the number of in-flight commands reached the maximum (if a limit is configured) // - ``FAILED_PRECONDITION``: on consistency errors (e.g. the contract key has changed since the submission) // or if an interpretation error occurred // - ``UNAVAILABLE``: if the participant is not yet ready to submit commands or if the service has been shut down. + // - ``DEADLINE_EXCEEDED``: if the request failed to receive its completion within the predefined timeout. rpc SubmitAndWaitForTransactionId (SubmitAndWaitRequest) returns (SubmitAndWaitForTransactionIdResponse); // Submits a single composite command, waits for its result, and returns the transaction. @@ -54,14 +56,15 @@ service CommandService { // Errors: // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation - // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a contract key is missing + // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a resource is missing (e.g. contract key) // due to for example contention on resources - // - ``ALREADY_EXISTS`` if a contract key is duplicated + // - ``ALREADY_EXISTS`` if a resource is duplicated (e.g. contract key) // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields // - ``ABORTED``: if the number of in-flight commands reached the maximum (if a limit is configured) // - ``FAILED_PRECONDITION``: on consistency errors (e.g. the contract key has changed since the submission) // or if an interpretation error occurred // - ``UNAVAILABLE``: if the participant is not yet ready to submit commands or if the service has been shut down. + // - ``DEADLINE_EXCEEDED``: if the request failed to receive its completion within the predefined timeout. rpc SubmitAndWaitForTransaction (SubmitAndWaitRequest) returns (SubmitAndWaitForTransactionResponse); // Submits a single composite command, waits for its result, and returns the transaction tree. @@ -69,14 +72,15 @@ service CommandService { // Errors: // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation - // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a contract key is missing + // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a resource is missing (e.g. contract key) // due to for example contention on resources - // - ``ALREADY_EXISTS`` if a contract key is duplicated + // - ``ALREADY_EXISTS`` if a resource is duplicated (e.g. contract key) // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields // - ``ABORTED``: if the number of in-flight commands reached the maximum (if a limit is configured) // - ``FAILED_PRECONDITION``: on consistency errors (e.g. the contract key has changed since the submission) // or if an interpretation error occurred // - ``UNAVAILABLE``: if the participant is not yet ready to submit commands or if the service has been shut down. + // - ``DEADLINE_EXCEEDED``: if the request failed to receive its completion within the predefined timeout. rpc SubmitAndWaitForTransactionTree (SubmitAndWaitRequest) returns (SubmitAndWaitForTransactionTreeResponse); } diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_submission_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_submission_service.proto index 47664bae0140..4f04a3a4b679 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_submission_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/command_submission_service.proto @@ -32,9 +32,9 @@ service CommandSubmissionService { // Errors: // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation - // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a contract key is missing + // - ``NOT_FOUND``: if the request does not include a valid ledger id or if a resource is missing (e.g. contract key) // due to for example contention on resources - // - ``ALREADY_EXISTS`` if a contract key is duplicated + // - ``ALREADY_EXISTS`` if a resource is duplicated (e.g. contract key) // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields // - ``ABORTED``: if the number of in-flight commands reached the maximum (if a limit is configured) // - ``FAILED_PRECONDITION``: on consistency errors (e.g. the contract key has changed since the submission) From cf1efed8114e2c108e6aa92b688f0230f58ce968 Mon Sep 17 00:00:00 2001 From: tudor-da Date: Mon, 22 Nov 2021 13:39:19 +0100 Subject: [PATCH 06/12] Apply suggestions from code review Co-authored-by: pbatko-da --- docs/source/app-dev/grpc/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/app-dev/grpc/index.rst b/docs/source/app-dev/grpc/index.rst index 2663d5ff75b2..27b313eba40c 100644 --- a/docs/source/app-dev/grpc/index.rst +++ b/docs/source/app-dev/grpc/index.rst @@ -73,9 +73,9 @@ For information on how Daml types and contracts are represented by the Ledger AP Error handling ************** -The Ledger API generally uses the gRPC standard error codes for signaling response failures to client applications. +The Ledger API generally uses the gRPC standard status codes for signaling response failures to client applications. -For more details on the gRPC standard error codes, see the `gRPC documentation `__ . +For more details on the gRPC standard status codes, see the `gRPC documentation `__ . Generically, on submitted commands the Ledger API responds with the following gRPC status codes: From 9d2909a3eef52a72cb1fd546f7b225cb41c20d81 Mon Sep 17 00:00:00 2001 From: Tudor Voicu Date: Sat, 20 Nov 2021 00:15:45 +0100 Subject: [PATCH 07/12] Moved Error Codes under Building Applications / Ledger API / gRPC --- docs/source/app-dev/grpc/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/app-dev/grpc/index.rst b/docs/source/app-dev/grpc/index.rst index 27b313eba40c..982266245455 100644 --- a/docs/source/app-dev/grpc/index.rst +++ b/docs/source/app-dev/grpc/index.rst @@ -7,7 +7,6 @@ gRPC #### - .. toctree:: :hidden: From 042d4893f6c7dec859354b9c631a8bc88c4a112c Mon Sep 17 00:00:00 2001 From: Tudor Voicu Date: Sat, 20 Nov 2021 00:31:06 +0100 Subject: [PATCH 08/12] Updated outdated LedgerAPI / gRPC page --- docs/source/app-dev/grpc/index.rst | 2 +- docs/source/ops/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/app-dev/grpc/index.rst b/docs/source/app-dev/grpc/index.rst index 982266245455..5163e89bdee6 100644 --- a/docs/source/app-dev/grpc/index.rst +++ b/docs/source/app-dev/grpc/index.rst @@ -79,7 +79,7 @@ For more details on the gRPC standard status codes, see the `gRPC documentation Generically, on submitted commands the Ledger API responds with the following gRPC status codes: ABORTED - The platform failed to record the result of the command due to a transient server-side error or a time constraint violation. You can retry the submission. In case of a time constraint violation, please refer to the section :ref:`Dealing with time ` on how to handle commands with long processing times. + The platform failed to record the result of the command due to a transient server-side error (e.g. backpressure due to high load) or a time constraint violation. You can retry the submission. In case of a time constraint violation, please refer to the section :ref:`Dealing with time ` on how to handle commands with long processing times. DEADLINE_EXCEEDED (when returned by the Command Service) The request might not have been processed, as its deadline expired before its completion was signalled. ALREADY_EXISTS diff --git a/docs/source/ops/index.rst b/docs/source/ops/index.rst index 17967c903af5..9ce2d9517837 100644 --- a/docs/source/ops/index.rst +++ b/docs/source/ops/index.rst @@ -40,7 +40,7 @@ How the Daml Ledger API is affected ----------------------------------- - Active data streams from the Daml Participant may abort and need to be re-established by the Daml application from a later offset than pruned, even if they are already streaming past it. -- Requesting information at offsets that predate pruning, including from the ledger's start, will result in a ``NOT_FOUND`` gRPC error. +- Requesting information at offsets that predate pruning, including from the ledger's start, will result in a ``FAILED_PRECONDITION`` gRPC error. - As a consequence, after pruning, a Daml application must bootstrap from the Active Contract Service and a recent offset [3]_. Submission validation and Daml Ledger API endpoints that write to the ledger are generally not affected by pruning; an exception is that in-progress calls could abort while awaiting completion. From 7109cdc447591e2e2ad481da89b70ef5644c355b Mon Sep 17 00:00:00 2001 From: Tudor Voicu Date: Mon, 22 Nov 2021 13:46:02 +0100 Subject: [PATCH 09/12] Addressed review comments --- .../daml/ledger/api/v1/admin/config_management_service.proto | 3 +++ .../daml/ledger/api/v1/admin/package_management_service.proto | 3 +++ .../daml/ledger/api/v1/admin/participant_pruning_service.proto | 3 +++ .../daml/ledger/api/v1/admin/party_management_service.proto | 3 +++ 4 files changed, 12 insertions(+) diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/config_management_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/config_management_service.proto index 88acb0ba75e3..564e8bc1565a 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/config_management_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/config_management_service.proto @@ -12,6 +12,9 @@ option csharp_namespace = "Com.Daml.Ledger.Api.V1.Admin"; import "google/protobuf/duration.proto"; import "google/protobuf/timestamp.proto"; +// Status: experimental interface, will change before it is deemed production +// ready +// // The ledger configuration management service provides methods for the ledger administrator // to change the current ledger configuration. The services provides methods to modify // different aspects of the configuration. diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/package_management_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/package_management_service.proto index 4563429e84c7..f7833628928f 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/package_management_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/package_management_service.proto @@ -11,6 +11,9 @@ option java_outer_classname = "PackageManagementServiceOuterClass"; option java_package = "com.daml.ledger.api.v1.admin"; option csharp_namespace = "Com.Daml.Ledger.Api.V1.Admin"; +// Status: experimental interface, will change before it is deemed production +// ready +// // Query the Daml-LF packages supported by the ledger participant and upload // DAR files. We use 'backing participant' to refer to this specific participant // in the methods of this API. diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/participant_pruning_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/participant_pruning_service.proto index 27836b908d5b..44d7261e9dfa 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/participant_pruning_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/participant_pruning_service.proto @@ -9,6 +9,9 @@ option java_outer_classname = "ParticipantPruningServiceOuterClass"; option java_package = "com.daml.ledger.api.v1.admin"; option csharp_namespace = "Com.Daml.Ledger.Api.V1.Admin"; +// Status: experimental interface, will change before it is deemed production +// ready + // Prunes/truncates the "oldest" transactions from the participant (the participant Ledger Api Server plus any other // participant-local state) by removing a portion of the ledger in such a way that the set of future, allowed // commands are not affected. diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/party_management_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/party_management_service.proto index 6dd4d2ca7101..2b5744da35e7 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/party_management_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/party_management_service.proto @@ -10,6 +10,9 @@ option java_outer_classname = "PartyManagementServiceOuterClass"; option java_package = "com.daml.ledger.api.v1.admin"; option csharp_namespace = "Com.Daml.Ledger.Api.V1.Admin"; +// Status: experimental interface, will change before it is deemed production +// ready +// // Inspect the party management state of a ledger participant and modify the // parts that are modifiable. We use 'backing participant' to refer to this // specific participant in the methods of this API. From 175d3554e4b8f0c1e9b1d1843b238d322262d0d2 Mon Sep 17 00:00:00 2001 From: Tudor Voicu Date: Mon, 22 Nov 2021 15:08:01 +0100 Subject: [PATCH 10/12] Addressed review comments --- .../com/daml/ledger/api/v1/transaction_service.proto | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/transaction_service.proto b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/transaction_service.proto index 2f6208c09a55..2fd77b308828 100644 --- a/ledger-api/grpc-definitions/com/daml/ledger/api/v1/transaction_service.proto +++ b/ledger-api/grpc-definitions/com/daml/ledger/api/v1/transaction_service.proto @@ -23,6 +23,7 @@ service TransactionService { // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation // - ``NOT_FOUND``: if the request does not include a valid ledger id + // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields (e.g. if ``before`` is not before ``end``) // - ``FAILED_PRECONDITION``: if the ledger has been pruned after the subscription start offset // - ``OUT_OF_RANGE``: if the ``begin`` parameter value is not before the end of the ledger rpc GetTransactions (GetTransactionsRequest) returns (stream GetTransactionsResponse); @@ -33,6 +34,7 @@ service TransactionService { // - ``UNAUTHENTICATED``: if the request does not include a valid access token // - ``PERMISSION_DENIED``: if the claims in the token are insufficient to perform a given operation // - ``NOT_FOUND``: if the request does not include a valid ledger id + // - ``INVALID_ARGUMENT``: if the payload is malformed or is missing required fields (e.g. if ``before`` is not before ``end``) // - ``FAILED_PRECONDITION``: if the ledger has been pruned after the subscription start offset // - ``OUT_OF_RANGE``: if the ``begin`` parameter value is not before the end of the ledger rpc GetTransactionTrees (GetTransactionsRequest) returns (stream GetTransactionTreesResponse); From a572486259f88f15fc5eed55429ff476e099ebfd Mon Sep 17 00:00:00 2001 From: Tudor Voicu Date: Mon, 22 Nov 2021 15:19:35 +0100 Subject: [PATCH 11/12] Remove unnecessary link to error-codes --- docs/source/app-dev/grpc/error-codes.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/source/app-dev/grpc/error-codes.rst b/docs/source/app-dev/grpc/error-codes.rst index 71ac31dd2ef6..1cd5331a1ac4 100644 --- a/docs/source/app-dev/grpc/error-codes.rst +++ b/docs/source/app-dev/grpc/error-codes.rst @@ -1,8 +1,6 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -.. _error-codes: - Error Codes ########### From bb87f4ab19ec8755aafaf8261c34367afbf4d367 Mon Sep 17 00:00:00 2001 From: Tudor Voicu Date: Mon, 22 Nov 2021 15:59:56 +0100 Subject: [PATCH 12/12] `Ledger API` changed to `Common Ledger API change` --- docs/source/app-dev/grpc/error-codes.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/app-dev/grpc/error-codes.rst b/docs/source/app-dev/grpc/error-codes.rst index 1cd5331a1ac4..38c2d548f888 100644 --- a/docs/source/app-dev/grpc/error-codes.rst +++ b/docs/source/app-dev/grpc/error-codes.rst @@ -365,8 +365,8 @@ compatibility with previous releases for some service Ledger API endpoints. The table below outlines all the cases and error conditions when a Ledger API service endpoint returns a different gRPC status code in comparison to the pre-1.18 releases. -Ledger API -^^^^^^^^^^ +Common Ledger API changes +^^^^^^^^^^^^^^^^^^^^^^^^^ The table below outlines generic gRPC status code changes pertaining to the Ledger API and apply to all ledger backends. For changes specific to a ledger backend, check the next subsections.