package tezos-error-monad

  1. Overview
  2. Docs

The purpose of this module is to wrap a specific error monad E into a more general error monad Eg.

The user implementing such an interface is responsible to maintain the following assertions

  • The Eg error is extended locally with a specific constructor C
  • unwrapped is equal to the error type of E
  • wrap builds an Eg error value from an E error value
  • unwrap matches on Eg error cases and extracts E error value from C

As a reference implementation, see src/lib_protocol_environment/environment_V3.ml

type unwrapped = ..
include CORE with type error := unwrapped
type error_category
val string_of_category : error_category -> string
val error_encoding : unwrapped Data_encoding.t

The encoding for errors.

Note that this encoding has a few peculiarities, some of which may impact your code. These peculiarities are due to the type error being an extensible variant.

Because the error type is an extensible variant, you must register an encoding for each error constructor you add to error. This is done via register_error_kind.

Because the error type is an extensible variant, with dynamically registered errors (see peculiarity above), there are no tags associated with each error. This does not affect the JSON encoding, but it does impose restrictions on the binary encoding. The chosen workaround is to encode errors as JSON and to encode the JSON to binary form. As a result, errors can be somewhat large in binary: they include field names and such.

Because the error type is an extensible variant, with dynamically registered errors (see peculiarity above), the encoding must be recomputed when a new error is registered. This is achieved by the means of a Data_encoding.delayed combinator: the encoding is recomputed on-demand. There is a caching mechanism so that, in the case where no new errors have been registered since the last use, the last result is used.

This last peculiarity imposes a limit on the use of error_encoding itself. Specifically, it is invalid to use error_encoding inside the ~json argument of a Data_encoding.splitted. This is because splitted evaluates the delayed combinator once-and-for-all to produce a json encoding. (Note that the following data-encoding combinators use splitted internally: Data_encoding.Compact.make, Data_encoding.assoc, and Data_encoding.lazy_encoding. As a result, it is invalid to use error_encoding within the arguments of these combinators as well.)

val pp : Format.formatter -> unwrapped -> unit
val register_error_kind : error_category -> id:string -> title:string -> description:string -> ?pp:(Format.formatter -> 'err -> unit) -> 'err Data_encoding.t -> (unwrapped -> 'err option) -> ('err -> unwrapped) -> unit

The error data type is extensible. Each module can register specialized error serializers id unique name of this error. Ex.: overflow_time_counter title more readable name. Ex.: Overflow of time counter description human readable description. Ex.: The time counter overflowed while computing delta increase pp formatter used to pretty print additional arguments. Ex.: The time counter overflowed while computing delta increase. Previous value %d. Delta: %d encoder decoder data encoding for this error. If the error has no value, specify Data_encoding.empty

val classify_error : unwrapped -> Error_classification.t

Classify an error using the registered kinds

type unwrapped +=
  1. | Unclassified of string

Catch all error when 'serializing' an error.

type unwrapped +=
  1. | Unregistered_error of Data_encoding.json

Catch all error when 'deserializing' an error.

val json_of_error : unwrapped -> Data_encoding.json

An error serializer

val error_of_json : Data_encoding.json -> unwrapped

Error documentation

type error_info = {
  1. category : error_category;
  2. id : string;
  3. title : string;
  4. description : string;
  5. schema : Data_encoding.json_schema;
}

Error information

val pp_info : Format.formatter -> error_info -> unit
val find_info_of_error : unwrapped -> error_info

find_info_of_error e retrieves the `error_info` associated with the given error `e`.

  • raises Invalid_argument

    if the error is a wrapped error from another monad

  • raises Not_found

    if the error's constructor has not been registered

val get_registered_errors : unit -> error_info list

Retrieves information of registered errors

val unwrap : error -> unwrapped option

unwrap e returns Some when e matches variant constructor C and None otherwise

val wrap : unwrapped -> error

wrap e returns a general error from a specific unwrapped error e