Proxy server¶
This page describes the proxy server, a readonly frontend to tezos-node
which is designed to lower the load of full nodes. It can be run separately from
a node and will handle some RPC requests by itself. It is named after two
things:
The proxy mode of the client on which it builds upon.
Regular HTTP proxies, as proxy servers are meant to be deployed in front of a node, to lower the node’s load.
While the proxy server can only serve a subset of the RPCs a full node can serve (detailed below), one can transparently use a proxy server as a replacement for a full node, in the manner described below: it will use HTTP redirects to redirect clients to the node when it cannot handle a certain request.
Launching a proxy server¶
The minimal arguments to launch a proxy server are --endpoint
and --rpc-addr
:
--endpoint
specifies the URL of the RPC server of the node to do requests to obtain data (RPCs of the form/chains/<chain_id>/blocks/<block_id>/context/raw/bytes
).--rpc-addr
specifies the URL that the proxy server should serve.
Another important argument is --data-dir
:
--data-dir
specifies the directory of the node from which to obtain data. This argument can only be used when the proxy server has actual access to the specified data directory. In this case, this option will reduce the number of RPC calls to the node, thereby reducing its IO consumption.
The full list of arguments is detailed below.
Example with the sandbox¶
In this section, we show examples of usage of a proxy server when using
the sandboxed node. For convenience we repeat
instructions for the sandboxed mode here, but refer the reader to the
sandboxed mode page for further details. First, edit
src/proto_alpha/parameters/sandbox-parameters.json
to set the first value of time_between_blocks
to 15
seconds (it’s
the time between two blocks in the chain, we set it to 15
seconds,
so that the scenario below is easier to understand):
{ ...,
"time_between_blocks": [ "15", "0" ],
...
}
In a terminal, start a sandboxed node:
$ ./src/bin_node/tezos-sandboxed-node.sh 1 --connections 1
April 21 11:05:32.789 - node.config.validation: the node configuration has been successfully validated.
Created /tmp/tezos-node.Uzq5aGAN/config.json for network: sandbox.
...
Leave that terminal running. In a second terminal, prepare the appropriate environment for using a proxy server:
$ eval `./src/bin_client/tezos-init-sandboxed-client.sh 1`
Then upgrade the node to protocol alpha:
$ tezos-activate-alpha
$ tezos-client bake for bootstrap1
To avoid warnings being printed in upcoming commands (optional):
$ export TEZOS_CLIENT_UNSAFE_DISABLE_DISCLAIMER=y
You’re now ready to use a proxy server. Open a third terminal, and
launch a proxy server as shown below. We specify debug variables
in TEZOS_LOG
to have debug output showing what the proxy server
is doing (see the proxy mode page for more details).
$ export TEZOS_LOG="proxy_rpc_ctxt->debug; alpha.proxy_rpc->debug; proxy_server_run->debug; proxy_getter->debug; proxy_services->debug"
$ ./tezos-proxy-server --endpoint http://127.0.0.1:18731 --rpc-addr http://127.0.0.1:18732
protocol of proxy unspecified, using the node's protocol: ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK
Apr 21 11:09:22.092 - proxy_server_run: starting proxy RPC server on 127.0.0.1:18732
Now, start a fourth terminal, and make a client request data from the proxy server:
$ export TEZOS_CLIENT_UNSAFE_DISABLE_DISCLAIMER=y
$ ./tezos-client --endpoint http://127.0.0.1:18732 rpc get /chains/main/blocks/head/context/contracts
[ "tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN",
"tz1ddb9NMYHZi5UzPdzTZMYQQZoMub195zgv",
"tz1faswCTDciRzE4oJ9jn2Vm2dvjeyA9fUzU",
"tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx",
"tz1b7tUupMgCNw2cCLpKTkSD1NZzB5TkP2sv" ]
In the proxy server’s terminal, you should see this output (tree sizes may vary):
Apr 21 11:10:07.474 - alpha.proxy_rpc: chains/<main>/blocks/<head>/header
Apr 21 11:10:07.474 - alpha.proxy_rpc: proxy cache created for chain main and block head
Apr 21 11:10:07.476 - proxy_getter: Cache miss: (v1/constants)
Apr 21 11:10:07.476 - proxy_getter: split_key heuristic triggers, getting v1 instead of v1/constants
Apr 21 11:10:07.476 - alpha.proxy_rpc: /chains/<main>/blocks/<head>/context/raw/bytes/v1
Apr 21 11:10:07.477 - alpha.proxy_rpc: received tree of size 2
Apr 21 11:10:07.477 - proxy_getter: Cache hit: (v1/cycle_eras)
Apr 21 11:10:07.477 - proxy_getter: Cache miss: (pending_migration_balance_updates)
Apr 21 11:10:07.477 - alpha.proxy_rpc: /chains/<main>/blocks/<head>/context/raw/bytes/pending_migration_balance_updates
Apr 21 11:10:07.477 - proxy_getter: Cache miss: (pending_migration_operation_results)
Apr 21 11:10:07.477 - alpha.proxy_rpc: /chains/<main>/blocks/<head>/context/raw/bytes/pending_migration_operation_results
Apr 21 11:10:07.478 - proxy_getter: Cache miss: (contracts/index)
Apr 21 11:10:07.478 - alpha.proxy_rpc: /chains/<main>/blocks/<head>/context/raw/bytes/contracts/index
Apr 21 11:10:07.479 - alpha.proxy_rpc: received tree of size 115
Lines of the form alpha.proxy_rpc: /chains/<main>/blocks/<head>/context/raw/bytes/...
show requests that the proxy server does to the node to obtain data.
15
seconds after the previous command, the proxy server should clear
the data it obtained, because time_between_blocks
was set to 15
seconds at the beginning of this scenario:
Apr 21 11:10:22.478 - proxy_services: clearing data for chain main and block head
Now, in the fourth terminal, retrieve the contracts again, but twice in a row:
$ ./tezos-client --endpoint http://127.0.0.1:18732 rpc get /chains/main/blocks/head/context/contracts
[ "tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN",
"tz1ddb9NMYHZi5UzPdzTZMYQQZoMub195zgv",
"tz1faswCTDciRzE4oJ9jn2Vm2dvjeyA9fUzU",
"tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx",
"tz1b7tUupMgCNw2cCLpKTkSD1NZzB5TkP2sv" ]
$ ./tezos-client --endpoint http://127.0.0.1:18732 rpc get /chains/main/blocks/head/context/contracts
# ... same output ...
In the meantime, in the proxy server’s terminal, you should see:
Apr 21 11:14:04.262 - alpha.proxy_rpc: chains/<main>/blocks/<head>/header
Apr 21 11:14:04.263 - alpha.proxy_rpc: proxy cache created for chain main and block head
Apr 21 11:14:04.266 - proxy_getter: Cache miss: (v1/constants)
Apr 21 11:14:04.266 - proxy_getter: split_key heuristic triggers, getting v1 instead of v1/constants
Apr 21 11:14:04.266 - alpha.proxy_rpc: /chains/<main>/blocks/<head>/context/raw/bytes/v1
Apr 21 11:14:04.266 - alpha.proxy_rpc: received tree of size 2
Apr 21 11:14:04.267 - proxy_getter: Cache hit: (v1/cycle_eras)
Apr 21 11:14:04.267 - proxy_getter: Cache miss: (pending_migration_balance_updates)
Apr 21 11:14:04.267 - alpha.proxy_rpc: /chains/<main>/blocks/<head>/context/raw/bytes/pending_migration_balance_updates
Apr 21 11:14:04.267 - proxy_getter: Cache miss: (pending_migration_operation_results)
Apr 21 11:14:04.267 - alpha.proxy_rpc: /chains/<main>/blocks/<head>/context/raw/bytes/pending_migration_operation_results
Apr 21 11:14:04.267 - proxy_getter: Cache miss: (contracts/index)
Apr 21 11:14:04.268 - alpha.proxy_rpc: /chains/<main>/blocks/<head>/context/raw/bytes/contracts/index
Apr 21 11:14:04.269 - alpha.proxy_rpc: received tree of size 115
Apr 21 11:14:06.511 - proxy_getter: Cache hit: (v1/constants)
Apr 21 11:14:06.512 - proxy_getter: Cache hit: (v1/cycle_eras)
Apr 21 11:14:06.512 - proxy_getter: Cache hit: (pending_migration_balance_updates)
Apr 21 11:14:06.512 - proxy_getter: Cache hit: (pending_migration_operation_results)
Apr 21 11:14:06.512 - proxy_getter: Cache hit: (contracts/index)
The last four lines show that the proxy server is answering the request
without delegating anything to the node: there is no alpha.proxy_rpc
line.
The proxy server is reusing the data it obtained for <head>
from
the first request, because less than time_between_block
(15
seconds)
have passed.
Reducing RPC calls: --data-dir
¶
To make the proxy server read the node’s data-dir instead of doing
/chains/<main>/blocks/<head>/context/raw/bytes
RPC calls, kill
the proxy server you have launched above),
and restart it as follows:
$ ./tezos-proxy-server --endpoint http://127.0.0.1:18731 --rpc-addr http://127.0.0.1:18732 --data-dir /tmp/tezos-node.Uzq5aGAN
protocol of proxy unspecified, using the node's protocol: ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK
Apr 21 11:09:22.092 - proxy_server_run: starting proxy RPC server on 127.0.0.1:18732
The value of the --data-dir
argument was obtained by looking at the
output of the terminal where tezos-node
was launched
(see above).
Now, in the fourth terminal (the client’s terminal), redo the request to retrieve contracts:
$ ./tezos-client --endpoint http://127.0.0.1:18732 rpc get /chains/main/blocks/head/context/contracts
# ... same output as above ...
Now the output in the proxy server terminal should be:
Apr 21 11:22:44.359 - alpha.proxy_rpc: chains/<main>/blocks/<head>/header
Apr 21 11:22:44.360 - alpha.proxy_rpc: proxy cache created for chain main and block head
Apr 21 11:22:59.362 - proxy_services: clearing data for chain main and block head
There are far fewer alpha.proxy_rpc
lines! That is because the proxy
server obtained its data by reading the node’s data-dir, instead of performing RPC calls.
Additional arguments¶
We describe the entire list of arguments of the proxy server. This
documentation is also available with ./tezos-proxy-server --help
.
Here is the list of possible arguments:
-c
and--config
specify the JSON file to use an input for the configuration. This JSON file is an object like this:{"endpoint": "http://127.0.0.1:18731", "rpc_addr": "http://127.0.0.1:18732", "sym_block_caching_time": 60}
. This file can specify all command line arguments except-l
/--log-requests
. If an argument if specified both in the configuration file and on the command line, the command line takes precedence.-d
and--data-dir
specify the path of the data directory of the node. If specified, the proxy server obtains data by reading the disk instead of performing the/chains/<chain_id>/blocks/<block_id>/context/raw/bytes
RPC. If possible (i.e. if the proxy server can access the node’s disk), this option should be used, because it reduces IO consumption of the node.Note that this argument doesn’t make
--endpoint
optional, because the proxy server still needs to do RPC calls to obtain block headers. Further work removing all RPC calls is described in issue 2502.-E
and--endpoint
specify the URL of the RPC server of the node to do requests to obtain data (RPCs of the form/chains/<chain_id>/blocks/<block_id>/context/raw/bytes
).-l
and--log-requests
specify to print the requests that are delegated to the node, in a verbose manner.--rpc-addr
specifies the URL that the proxy server should serve.--rpc-tls
specifies that the proxy server must use TLS. It should be a string of the formcrt_file,key_file
wherecrt_file
is the path to the TLS certificate to use andkey_file
is the path to the key to use.--sym-block-caching-time
specifies the duration during which data for a symbolic block identifier (likehead
,head~1
) is kept. Smaller values increase the endpoint’s load but yield more up-to-date to clients. Higher values decrease the endpoint’s load but make clients observe slightly deprecated values. If omitted, the value is defaulted totime_between_blocks
. Astime_between_blocks
is hence regularly requested from the node, this incurs a higher load of the node.
All arguments are optional as they can either be specified in the configuration file or on the command line. However, the union of the configuration file and the command line should specify the endpoint to use and the RPC address to serve.
What the proxy server serves¶
The proxy server itself serves protocol-specific RPCs, which are listed
here for protocol Alpha,
but not all of them: since the proxy server is a readonly frontend for the
underlying node, it only serves the readonly requests (GET
requests, as
well as a subset of the POST
requests).
Because computations done by the proxy server are protocol dependent, the proxy server
does not support all protocols. However, it is expected than, at any
given time, the proxy server supports Alpha
and the three protocols
before that. In doubt, execute
tezos-client list proxy protocols
to see the supported protocols.
Unsupported RPCs¶
Requests that are not readonly can only be handled by a full node. However, it
is possible to send any RPC to the proxy server: if the RPC is not supported
by the proxy server, it will redirect clients to the appropriate endpoint on the
underlying node using an HTTP redirect (301 Moved Permanently
), and the node
will then handle the request.
This can be easily demonstrated with a simple test: start a proxy server, and
make a request to it with curl -vL <proxy server endpoint>/<any node-only RPC>
.
(For example, /chains/main/blocks/head/header
is one such RPC.) The output
from curl
will show that the proxy server asks curl to follow a redirect to
the node’s endpoint, which it will do because of the -L
flag, and
then it is finally responded to by the node. Any RPC that can be handled by the
proxy server itself will of course not show this behaviour.
Clearly, making such requests to the proxy server does not decrease the load of the node. (To be precise, it in fact also adds a slight delay to the HTTP request if the redirect is not cached by the client.) However, it does allow the use of a single endpoint for all RPC requests, which may be more convenient for certain use-cases.
Deployment¶
As a proxy server is a readonly frontend to a node, you can spawn multiple proxy servers in front of a single node.
Because the proxy server is protocol-dependent, if the node it talks to changes protocol; the proxy server will start failing for RPCs concerning blocks of the new protocol. We hereby recommend to automatically restart proxy servers that have a high ratio of failures. Restarting a proxy server is always fine, they can be thrown away at any moment.
Heuristics¶
The proxy server has heuristics. For example there is an heuristic
to make big map queries faster, when many queries to siblings keys of a given
big map are done in burst. The list of heuristics is
visible for protocol Alpha in
proxy.ml.
The heuristic is implemented in function split_key
. For example,
any request of the form rolls/owner/snapshot/i/j/tail
is transformed
into a request of the form rolls/owner/snapshot/i/j
to obtain data for all
possible values of tail
at once.
For the moment the heuristics cannot be specified on the command line. However,
it would be possible to do so. Please contact us for requesting such a change,
see the Support section.
Support¶
The proxy server is a project led by evertedsphere. To contact us:
We are on the Tezos-dev slack, or
create an issue on Tezos’ Gitlab and assign it to us.