package tezos-rpc-http-server

  1. Overview
  2. Docs
package tezos-rpc-http-server
Legend:
Library
Module
Module type
Parameter
Class
Class type
include module type of Resto_acl.Acl
type chunk_matcher =
  1. | Literal of string
  2. | Wildcard

path_matcher is the type of values that describe a path or a set of paths. Specifically,

  • Literal s matches path chunks that are identical to s,
  • Wildcard matches any single path chunk,
  • Exact chunks matches any path the chunks of which match chunks one-by-one,
  • FollowedByAnySuffix chunks matches any path that is a suffix of a path matched by Exact chunks.

E.g., Exact [Literal "users"; Wildcard; Literal "display-name"] matches the path "/users/Alice/display-name" and "/users/Bob/display-name", but not "/users/foo/preferences/", nor "/users/Bar/display-name/normalised".

E.g., FollowedByAnySuffix [Literal "admin"; Literal "keys"] matches the path "/admin/keys" and "admin/keys/gpg".

It is recommended that you use FollowedByAnySuffix in order to match a whole directory attached to a given prefix, or a whole set of services that are register under a common prefix.

It is recommended that you use Wildcard to match path-parameters (such as with the path "/users/<user-id>/".

It is _NOT_ recommended that you use Literal _ to match on the specific value of a parameter.

type path_matcher =
  1. | Exact of chunk_matcher list
  2. | FollowedByAnySuffix of chunk_matcher list
type meth_matcher =
  1. | Exact of Resto.meth
  2. | Any

meth_matcher is the type of values that describe a method or a set of methods. Exact m matches m whilst Any matches any method.

type matcher = {
  1. meth : meth_matcher;
  2. path : path_matcher;
}
val parse : string -> matcher

parse s parses the string s as a matcher. It raises Invalid_argument if the argument s is not in line with the following format.

A string representation of a matcher has the following components one after the other.

1. An optional method. If the method is absent, then Any is the method matcher. If the method is present it must be one of "GET"; "POST"; "DELETE"; "PUT"; "PATCH". 2. Any number (including none (0)) of spaces ( ). 3. A path which must start with a slash (/) and be followed by a sequence of chunks separated by slashes (/). Each chunk is either a single asterisk (*) (for Wildcard) or a non-empty sequence of characters (for Literal _). Special characters (see below) must be percentage-encoded. 4. An optional suffix slash-star-star ("/**") indicates FollowedByAnySuffix and it's absence is for Exact.

E.g., "/**" is a matcher for any method and any path. E.g., " /**" is the same matcher with extra (ignored) space (for alignment). E.g., "GET /**" is a matcher for the GET method and any path. E.g., "POST /admin/**" is a matcher for the POST method on any suffix of "/admin". E.g., "PATCH/*" is a matcher for the PATCH method on any single-chunk path. E.g., "/users/*/display-name" is a matcher for any method on paths that fit in the "/users/<user-id>/display-name" pattern.

Chunks cannot contain the following special characters. These characters must be represented percent-encoded. (Note that chunks are percent-decoded and the character percent (%) should appear percent-encoded (%25).

  • slash (/, represented by %2F)
  • asterisk (*, represented by %2A)
  • question mark (?, represented by %3F)
  • ampersand (&, represented by %26)
  • hash (#, represented by %23)
  • equal (=, represented by %3D)

Also note that each chunk is percent-decoded.

E.g., "GET /entries/by/year/2020/*/*" is a matcher for the GET method on paths that fit in the "/entries/by/year/2020/<month>/<day>" pattern. E.g., "GET /entries/by/year/20*/*/*" is not a valid matcher. The character asterisk (*) is not allowed within literal chunks. To match on the specific string "20*" use the percent-encoding 20%2A. You cannot match on regular expressions nor glob expansions using this Acl module.

  • raises {!Invalid_argument}

    if the path does not follow the format described above.

type t =
  1. | Allow_all of {
    1. except : matcher list;
    }
    (*

    Allow all by default but deny requests matched by the exception list.

    *)
  2. | Deny_all of {
    1. except : matcher list;
    }
    (*

    Deny all by default but allow requests matched by the exception list.

    *)

access policy

val allowed : t -> meth:Resto.meth -> path:string list -> bool
type policy

A policy for the whole RPC server is a set of access control lists for the different addresses that the RPC server listens to. It is represented as an association list mapping listening addresses (in string literal forms) to deny/access access policies.

val secure : t

Default ACL policy in case none is defined in configuration. It only exposes such endpoints that are necessary for the node to allow clients to make use of their Tez. It applies to all listening addresses except for localhost (see allow_all for this address).

val allow_all : t

An allow-all policy, which is the default for the localhost listening address.

val default : Tezos_base.P2p_addr.t -> t

Selects default ACL based on listening address. Selects allow_all for loopback addresses and secure for everything else.

Add an ACL for given address into the policy. Overrides previously existing policy for that address if any.

val empty_policy : policy

Empty ACL policy allows access to all endpoints. Currently it's the same as default below, but that will likely change in the future, therefore it's better to use default rather than this value. It's mainly intended for testing.

val policy_encoding : policy Data_encoding.t
val policy_to_string : policy -> string

Returns the JSON representation of the policy.

val find_policy : policy -> (string * int option) -> t option

find_policy policy address looks for the address within the policy and returns corresponding access control list.

An ACL is considered matching if its corresponding IP part matches the IP part of the address and either:

  • its corresponding port also matches address's port OR
  • its corresponding address does not mention any port at all.

The first ACL whose corresponding address matches these criteria is returned.

val matcher_to_string : matcher -> string

Returns string representation of a given matcher. Useful for testing.

val acl_type : t -> [ `Whitelist | `Blacklist ]

Returns the ACL type, either `Whitelist or `Blacklist.

Replace domain-name addresses in the policy with the IP addresses they resolve to.

resolve_domain_names p returns a policy equivalent to p but with all domain-name addresses resolved to IPs. This is useful to make it easier to match them with listening addresses given to the server.

val resolve_domain_names : policy -> policy Lwt.t
module Internal_for_test : sig ... end