tezos-rpc

Tezos: library of auto-documented RPCs (service and hierarchy descriptions)
Library tezos-rpc
Module Tezos_rpc . RPC_directory
include module type of struct include Resto_directory.Make(RPC_encoding) end
type step = Resto_directory.Make(Tezos_rpc.RPC_encoding).step =
| Static of string(*

A literal chunk

*)
| Dynamic of Resto.Arg.descr(*

A chunk which describes a argument to a service

*)
| DynamicTail of Resto.Arg.descr(*

The remainder of the chunks are to be interpreted as a list of arguments

*)

The different chunks of a path

E.g., /archive/<year>/<months>/ has a Static "archive" step followed by a Dynamic _ step followed by a Dynamic _ step. Each Dynamic _ step has an Resto.Arg payload describing the chunk.

type conflict = Resto_directory.Make(Tezos_rpc.RPC_encoding).conflict =
| CService of Resto.meth
| CDir
| CBuilder
| CTail
| CTypes of Resto.Arg.descr * Resto.Arg.descr
| CType of Resto.Arg.descr * string list

Possible error while registring services.

type ('query, 'input, 'output, 'error) types = ( 'query, 'input, 'output, 'error ) Resto_directory.Make(Tezos_rpc.RPC_encoding).types = {
query : 'query Resto.Query.t;
input : 'input Service.input;
output : 'output Tezos_rpc.RPC_encoding.t;
error : 'error Tezos_rpc.RPC_encoding.t;
}
type registered_service = Resto_directory.Make(Tezos_rpc.RPC_encoding).registered_service =
| Service : {
types : ( 'q, 'i, 'o, 'e ) types;
handler : 'q -> 'i -> ( 'o, 'e ) Resto_directory.Answer.t Lwt.t;
} -> registered_service

Dispatch tree

type 'prefix directory = 'prefix t
type lookup_error = [
| `Not_found
| `Method_not_allowed of Resto.meth list
| `Cannot_parse_path of string list * Resto.Arg.descr * string
]
val lookup : 'prefix directory -> 'prefix -> Resto.meth -> string list -> ( registered_service, [> lookup_error ] ) result Lwt.t

lookup d m p is Ok (Service _) if there is a service s registered in d and both the method of s is m and the path of s matches p. It is Error _ otherwise.

If it is Ok (Service _) then the returned value corresponds to the registered service.

val lookup_uri_desc : 'prefix directory -> 'prefix -> Resto.meth -> string list -> ( string, [> lookup_error ] ) result Lwt.t

lookup_uri_desc d p is Ok u where u is a formated URI description, if there is a service s registered in d and the path of s matches p. It is Error _ otherwise.

For instance, given the following path p: "/entries-by-date/2022/01/10" where "2022", "01", and "10" are expected to be paramaters in the path of s, the function will evaluate in "/entries-by-date/<year>/<month>/<day>".

val allowed_methods : 'prefix directory -> 'prefix -> string list -> ( Resto.meth list, [> lookup_error ] ) result Lwt.t

allowed_methods d p is the set of methods m such that lookup d m p is Ok _. In other words, it is the set of methods m such that a service has been registered in d for a path that matches p.

val transparent_lookup : 'prefix directory -> ( 'meth, 'prefix, 'params, 'query, 'input, 'output, 'error ) Service.t -> 'params -> 'query -> 'input -> [> ( 'output, 'error ) Resto_directory.Answer.t ] Lwt.t
val empty : 'prefix directory

Empty tree

val map : ( 'a -> 'b Lwt.t ) -> 'b directory -> 'a directory
val prefix : ( 'pr, 'p ) Resto.Path.path -> 'p directory -> 'pr directory

prefix p d is a directory of services which includes a service registered on the path p / q for each service registered on the path q in d.

  • raises [Invalid_argument]

    if p is a dynamic path.

val merge : 'a directory -> 'a directory -> 'a directory

merge d1 d2 is a directory which includes all the services of d1 and d2.

  • raises [Conflict]

    if one or more service from d1 conflicts with one or more service from d2.

exception Conflict of step list * conflict
val register_dynamic_directory : ?descr:string -> 'prefix directory -> ( 'prefix, 'a ) Resto.Path.path -> ( 'a -> 'a directory Lwt.t ) -> 'prefix directory

Registring dynamic subtree.

val register_dynamic_directory1 : ?descr:string -> 'prefix directory -> ( 'prefix, unit * 'a ) Resto.Path.path -> ( 'a -> (unit * 'a) directory Lwt.t ) -> 'prefix directory

Registring dynamic subtree. (Curryfied variant)

val register_dynamic_directory2 : ?descr:string -> 'prefix directory -> ( 'prefix, (unit * 'a) * 'b ) Resto.Path.path -> ( 'a -> 'b -> ((unit * 'a) * 'b) directory Lwt.t ) -> 'prefix directory
val register_dynamic_directory3 : ?descr:string -> 'prefix directory -> ( 'prefix, ((unit * 'a) * 'b) * 'c ) Resto.Path.path -> ( 'a -> 'b -> 'c -> (((unit * 'a) * 'b) * 'c) directory Lwt.t ) -> 'prefix directory
val register_describe_directory_service : 'prefix directory -> ( 'prefix, 'prefix, 'error ) Service.description_service -> 'prefix directory

Registring a description service.

val describe_directory : recurse:bool -> ?arg:'a -> 'a directory -> Tezos_rpc.RPC_encoding.schema Resto.Description.directory Lwt.t
val register : 'prefix directory -> ( [< Resto.meth ], 'prefix, 'p, 'q, 'i, 'o ) RPC_service.t -> ( 'p -> 'q -> 'i -> 'o Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> 'prefix directory

Registering handler in service tree.

val register_chunked : 'prefix directory -> ( [< Resto.meth ], 'prefix, 'p, 'q, 'i, 'o ) RPC_service.t -> ( 'p -> 'q -> 'i -> 'o Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> 'prefix directory
val opt_register : 'prefix directory -> ( [< Resto.meth ], 'prefix, 'p, 'q, 'i, 'o ) RPC_service.t -> ( 'p -> 'q -> 'i -> 'o option Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> 'prefix directory
val gen_register : 'prefix directory -> ( 'meth, 'prefix, 'params, 'query, 'input, 'output ) RPC_service.t -> ( 'params -> 'query -> 'input -> [< 'output RPC_answer.t ] Lwt.t ) -> 'prefix directory
val lwt_register : 'prefix directory -> ( [< Resto.meth ], 'prefix, 'p, 'q, 'i, 'o ) RPC_service.t -> ( 'p -> 'q -> 'i -> 'o Lwt.t ) -> 'prefix directory

Registering handler in service tree. Curryfied variant.

val register0 : unit directory -> ( 'm, unit, unit, 'q, 'i, 'o ) RPC_service.t -> ( 'q -> 'i -> 'o Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> unit directory
val register0_chunked : unit directory -> ( 'm, unit, unit, 'q, 'i, 'o ) RPC_service.t -> ( 'q -> 'i -> 'o Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> unit directory
val register1 : 'prefix directory -> ( 'm, 'prefix, unit * 'a, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'q -> 'i -> 'o Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> 'prefix directory
val register2 : 'prefix directory -> ( 'm, 'prefix, (unit * 'a) * 'b, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'q -> 'i -> 'o Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> 'prefix directory
val register3 : 'prefix directory -> ( 'm, 'prefix, ((unit * 'a) * 'b) * 'c, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'c -> 'q -> 'i -> 'o Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> 'prefix directory
val register4 : 'prefix directory -> ( 'm, 'prefix, (((unit * 'a) * 'b) * 'c) * 'd, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'c -> 'd -> 'q -> 'i -> 'o Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> 'prefix directory
val register5 : 'prefix directory -> ( 'm, 'prefix, ((((unit * 'a) * 'b) * 'c) * 'd) * 'e, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'c -> 'd -> 'e -> 'q -> 'i -> 'o Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> 'prefix directory
val opt_register0 : unit directory -> ( 'm, unit, unit, 'q, 'i, 'o ) RPC_service.t -> ( 'q -> 'i -> 'o option Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> unit directory
val opt_register1 : 'prefix directory -> ( 'm, 'prefix, unit * 'a, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'q -> 'i -> 'o option Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> 'prefix directory
val opt_register2 : 'prefix directory -> ( 'm, 'prefix, (unit * 'a) * 'b, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'q -> 'i -> 'o option Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> 'prefix directory
val opt_register3 : 'prefix directory -> ( 'm, 'prefix, ((unit * 'a) * 'b) * 'c, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'c -> 'q -> 'i -> 'o option Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> 'prefix directory
val opt_register4 : 'prefix directory -> ( 'm, 'prefix, (((unit * 'a) * 'b) * 'c) * 'd, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'c -> 'd -> 'q -> 'i -> 'o option Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> 'prefix directory
val opt_register5 : 'prefix directory -> ( 'm, 'prefix, ((((unit * 'a) * 'b) * 'c) * 'd) * 'e, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'c -> 'd -> 'e -> 'q -> 'i -> 'o option Tezos_error_monad.Error_monad.tzresult Lwt.t ) -> 'prefix directory
val gen_register0 : unit directory -> ( 'm, unit, unit, 'q, 'i, 'o ) RPC_service.t -> ( 'q -> 'i -> [< 'o RPC_answer.t ] Lwt.t ) -> unit directory
val gen_register1 : 'prefix directory -> ( 'm, 'prefix, unit * 'a, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'q -> 'i -> [< 'o RPC_answer.t ] Lwt.t ) -> 'prefix directory
val gen_register2 : 'prefix directory -> ( 'm, 'prefix, (unit * 'a) * 'b, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'q -> 'i -> [< 'o RPC_answer.t ] Lwt.t ) -> 'prefix directory
val gen_register3 : 'prefix directory -> ( 'm, 'prefix, ((unit * 'a) * 'b) * 'c, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'c -> 'q -> 'i -> [< 'o RPC_answer.t ] Lwt.t ) -> 'prefix directory
val gen_register4 : 'prefix directory -> ( 'm, 'prefix, (((unit * 'a) * 'b) * 'c) * 'd, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'c -> 'd -> 'q -> 'i -> [< 'o RPC_answer.t ] Lwt.t ) -> 'prefix directory
val gen_register5 : 'prefix directory -> ( 'm, 'prefix, ((((unit * 'a) * 'b) * 'c) * 'd) * 'e, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'c -> 'd -> 'e -> 'q -> 'i -> [< 'o RPC_answer.t ] Lwt.t ) -> 'prefix directory
val lwt_register0 : unit directory -> ( 'm, unit, unit, 'q, 'i, 'o ) RPC_service.t -> ( 'q -> 'i -> 'o Lwt.t ) -> unit directory
val lwt_register1 : 'prefix directory -> ( 'm, 'prefix, unit * 'a, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'q -> 'i -> 'o Lwt.t ) -> 'prefix directory
val lwt_register2 : 'prefix directory -> ( 'm, 'prefix, (unit * 'a) * 'b, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'q -> 'i -> 'o Lwt.t ) -> 'prefix directory
val lwt_register3 : 'prefix directory -> ( 'm, 'prefix, ((unit * 'a) * 'b) * 'c, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'c -> 'q -> 'i -> 'o Lwt.t ) -> 'prefix directory
val lwt_register4 : 'prefix directory -> ( 'm, 'prefix, (((unit * 'a) * 'b) * 'c) * 'd, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'c -> 'd -> 'q -> 'i -> 'o Lwt.t ) -> 'prefix directory
val lwt_register5 : 'prefix directory -> ( 'm, 'prefix, ((((unit * 'a) * 'b) * 'c) * 'd) * 'e, 'q, 'i, 'o ) RPC_service.t -> ( 'a -> 'b -> 'c -> 'd -> 'e -> 'q -> 'i -> 'o Lwt.t ) -> 'prefix directory