From 40c7ce79d1a8b167257e1beade6ce9902181b63a Mon Sep 17 00:00:00 2001 From: Ryan Tan Date: Wed, 3 Jul 2024 16:09:21 +0100 Subject: [PATCH 1/2] Docs: add docs for max-age http cache header --- docs/paris/consensus.rst | 2 ++ docs/user/node-configuration.rst | 19 +++++++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/docs/paris/consensus.rst b/docs/paris/consensus.rst index 956ca75c28b4..c419117d2fb9 100644 --- a/docs/paris/consensus.rst +++ b/docs/paris/consensus.rst @@ -126,6 +126,8 @@ Consequently, to agree on a block, that is, on both the payload and the header, confirmation, and thus guarantees **block finality after 2 confirmations**. +.. _time_between_blocks: + Time between blocks ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/user/node-configuration.rst b/docs/user/node-configuration.rst index 703b79cd5a3a..fe6e4ea281ff 100644 --- a/docs/user/node-configuration.rst +++ b/docs/user/node-configuration.rst @@ -279,6 +279,25 @@ actually listening on): .. literalinclude:: default-acl.json :language: json +HTTP Caching Headers +~~~~~~~~~~~~~~~~~~~~ + +It is possible to enable http caching headers in the RPC responses with the +``--enable-http-cache-headers`` option. This feature is disabled by default. + +When enabled, the RPC server will include ``Cache-control: public, max-age: `` in the response +headers of head related queries (``/chains/main/blocks/head*``) for responses that are considered fresh and can +be cached. This also works on paths that are relative to ``head`` such as ``head-n`` and ``head~n``. A response is +considered fresh if it was processed by the RPC server during the head block's consensus round. The calculated +```` value will be the remaining time until the :ref:`estimated end time` of the +consensus round. If an RPC response cannot be cached, the RPC server will not include any cache control headers. + +This feature is useful when running the RPC server behind a reverse proxy that supports automatic +content caching (eg. `NGINX's proxy_cache setting `_). Beware that +enabling this feature adds a non-negligible performance overhead (up to 10-15% slower) to every head related query +as the RPC server needs to calculate the ```` value. Consequently, it is advised to enable thie feature +only when operating the RPC server behind appropriate caching infrastructure. + .. _configure_p2p: P2P parameters -- GitLab From 67230a239a87f06bfb494225075d30ccbc95ff66 Mon Sep 17 00:00:00 2001 From: Ryan Tan Date: Thu, 11 Jul 2024 18:11:14 +0100 Subject: [PATCH 2/2] Docs: add docs for if-none-match http cache header --- docs/user/node-configuration.rst | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/user/node-configuration.rst b/docs/user/node-configuration.rst index fe6e4ea281ff..6c898d8526d5 100644 --- a/docs/user/node-configuration.rst +++ b/docs/user/node-configuration.rst @@ -285,17 +285,22 @@ HTTP Caching Headers It is possible to enable http caching headers in the RPC responses with the ``--enable-http-cache-headers`` option. This feature is disabled by default. -When enabled, the RPC server will include ``Cache-control: public, max-age: `` in the response -headers of head related queries (``/chains/main/blocks/head*``) for responses that are considered fresh and can -be cached. This also works on paths that are relative to ``head`` such as ``head-n`` and ``head~n``. A response is -considered fresh if it was processed by the RPC server during the head block's consensus round. The calculated -```` value will be the remaining time until the :ref:`estimated end time` of the -consensus round. If an RPC response cannot be cached, the RPC server will not include any cache control headers. +When enabled, the RPC server will support `max-age `_ +header. The header ``Cache-control: public, max-age: `` will be included in the response headers of head related +queries (``/chains/main/blocks/head*``) for responses that are cacheable. This also works on paths +that are relative to ``head`` such as ``head-n`` and ``head~n``. The response is cacheable throughout the ```` +of the head block's consensus round where ```` is the remaining time until the :ref:`estimated end time` +of the consensus round. If a response should not be cached, the RPC server will not include any cache control headers. + +The RPC server will also support the conditional request header `If-None-Match `_ +and include the ``ETag`` field in every head related query. The value of the ``ETag`` will be set to the block hash that the query +is related to. If the client sends a request with ``If-None-Match: `` header and the block hash +is included in the list of etag values, the RPC server will respond with a ``304 Not Modified`` status code with an empty body. This feature is useful when running the RPC server behind a reverse proxy that supports automatic content caching (eg. `NGINX's proxy_cache setting `_). Beware that enabling this feature adds a non-negligible performance overhead (up to 10-15% slower) to every head related query -as the RPC server needs to calculate the ```` value. Consequently, it is advised to enable thie feature +as the RPC server needs to perform additional checks and calculations. Consequently, it is advised to enable thie feature only when operating the RPC server behind appropriate caching infrastructure. .. _configure_p2p: -- GitLab