Module Tezos_rpc.Path

The type for service's paths

A (p, a) path is a path in which some segments encode a value of type a.

Typically a (_, unit) path is a static path. Also typically, a dynamic path has type (_, ((unit * a) * b) * ..) path where different segments encode the different components of the tuple (a, b, etc.). For example the path /entries-by-date/<year>/<month>/<day> may be described as a (_, ((unit * int) * int) * int) path.

root is the basis to build paths upon. It is the "Nil" of path construction.

add_suffix p s is a path in which s has been appended to the sequence of segments described by p.

(/) is an infix operator for add_suffix.

add_arg p a is a path in which a segment representing a value of type a has been appended to the sequence of segments described by p.

This is intended for use by services. Specifically, a service that is parameterized over a value of type ty is attached to a path that includes an argument for a value of type ty. When the service is called, Resto decodes the argument and passes its value to the service.

(/:) is an infix operator for add_arg.

add_final_args p a is a path in which an arbitrary sequence of segments representing values of type a has been appended to the sequence of segments described by p.

A similar use to the add_arg is intended, but for a list of values rather than a single value.

Note that, as the name suggests, add_final_args is final: you cannot add further suffixes or arguments to the resulting path. Attempting to do so raises Invalid_arg. Similarly, using the resulting path as a prefix (see below) raises the same exception. This is because paths built with add_final_args consume all the suffix as an unterminated list of arguments, there cannot be further suffixes or arguments.

( /:* ) is an infix operator for add_final_args.

prefix p q is a path in which the sequence of segments of p is followed by the sequence of segments of q.

subst0 p is a path akin to p but with a different type for the prefix parameter. This is useful when declaring a service in a part of the code where the type of the prefix parameters are not available.

The typical use-case is with protocol services. A service is declared with some dummy prefix parameters.

Later, the shell instantiates the protocol. The shell obtains this service declaration from the instantiated protocol. The shell maintains a protocol state (so called context), which is associated to a given chain (main, testnet, etc.).

The shell registers the service by substituting the shell-side prefix parameters.

For example, below is a commented excerpt from src/lib_shell/block_directory.ml.

  (* new directory with concrete prefix parameters *)
  let dir :
      (Store.chain_store * Block_hash.t * Block_header.t) Tezos_rpc.Directory.t
      ref =
    ref Tezos_rpc.Directory.empty
  in
  (* function to add a service to the new directory
     note the call to [subst0] which substitutes the dummy prefix parameters of
     [s] to the concrete ones *)
  let register0 s f =
    dir :=
      Tezos_rpc.Directory.register
        !dir
        (Tezos_rpc.Service.subst0 s) (* apply [subst0] to the path of [s] *)
        (fun block p q -> f block p q)
  in
  (* get the service declarations from the [Proto]col *)
  let module Block_services = Block_services.Make (Proto) (Proto) in
  let module S = Block_services.S in
  register0
    S.hash (* service declared in the protocol used a dummy unit instead of
              [(chain, hash, header)] *)
    (fun (_, hash, _) () () -> return hash) ;
  (* more registration with subst0 threaded in …*)

See subst0 for rationale.

See subst0 for rationale.

See subst0 for rationale.

to_segments path evaluates in the list of the different elements that constitute the given path.

to_string path evaluates in a string representation of the given path.