highperfocused/bitcoin
1
0
Fork 0
mirror of https://github.com/bitcoin/bitcoin.git synced 2026-09-12 05:32:22 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge bitcoin/bitcoin#34794: rest: add Cache-Control headers to REST responses

Browse Source 
75f5851927 doc: add release note for REST cache-control headers (w0xlt)
bbe21ac29f doc: document REST cache-control defaults (w0xlt)
862a179556 http: add no-store to dispatcher-generated error responses (w0xlt)
acf45c44c0 rest: add Cache-Control headers to REST responses (w0xlt)

Pull request description:

  This PR adds explicit Cache-Control headers to REST responses.

  The policy is:

  - Immutable data gets: `Cache-Control: public, immutable, max-age=86400`
  - Mutable, node-local, and error responses get: `Cache-Control: no-store`

  Important details:

  - `/block` and `/block/notxdetails` bin/hex, `/blockpart`, `/blockfilter`, `/spenttxouts`, and `/deploymentinfo/<blockhash>.json` are treated as immutable.
  - `/block` and `/block/notxdetails` JSON, all `/tx` formats, `/headers`, `/blockfilterheaders`, `/blockhashbyheight`, `/chaininfo`, `/mempool`, `/getutxos`, and `/deploymentinfo.json` are no-store.
  - REST errors and HTTP dispatcher-generated errors are no-store.
  - Unmatched `/rest` 404s also return no-store, including paths like `/rest/tx`, `/rest/does-not-exist`, and `/rest?x=1`.

  Tests were added in `interface_rest.py` to cover successful responses, behavior across a newly mined block, REST errors, and unmatched REST 404s.

  Docs were added to `REST-interface.md`, including guidance for overriding the defaults in a reverse proxy or CDN.

  Closes #33809

ACKs for top commit:
  stickies-v:
    re-ACK 75f5851927
  pinheadmz:
    ACK 75f5851927
  sedited:
    ACK 75f5851927

Tree-SHA512: 292ccd06ddfc9272c17fa720ce1ea8bb05462337af6460488f70003d3daf31fcf262e68c264522a911bba65ae2b25fc88a1fd422e5664583daf64070231cb062
This commit is contained in:
merge-script
2026-08-10 10:21:55 +01:00
parent 128456b62d 75f5851927
commit b6bd573eb9
5 changed files with 202 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
doc/REST-interface.md
View File

@@ -12,6 +12,25 @@ REST Interface consistency guarantees
The [same guarantees as for the RPC Interface](/doc/JSON-RPC-interface.md#rpc-consistency-guarantees)
apply.
Default HTTP caching
--------------------
REST responses include `Cache-Control` headers by default:
* `public, immutable, max-age=86400` for `/block` and `/block/notxdetails`
binary and hex responses, `/blockpart`, `/blockfilter` and `/spenttxouts` in
all formats, and `/deploymentinfo/<BLOCKHASH>.json`. The TTL is deliberately
short so caches do not hold older response shapes across software upgrades.
* `no-store` for `/block` and `/block/notxdetails` JSON, `/tx`, `/headers`,
`/blockfilterheaders`, `/blockhashbyheight`, `/chaininfo`, `/mempool`,
`/getutxos`, `/deploymentinfo.json`, and all error responses. These responses
can change with active chain or node state and do not currently provide cache
validators such as `ETag` or `Last-Modified`.
If you front `bitcoind` with a reverse proxy or CDN such as Caddy or nginx with
the headers-more module, you can override these defaults there. Keep overrides
scoped to responses you know are safe to cache more aggressively.
Limitations
-----------

8
doc/release-notes-34794.md Normal file
View File

@@ -0,0 +1,8 @@
REST API
--------
- REST responses now include `Cache-Control` headers to guide intermediary
caches. Immutable responses such as block binary and hex data, block parts,
block filters, spent transaction outputs, and block-specific deployment info
are marked cacheable for one day. Responses that can change with active chain
or node state, as well as errors, are marked `no-store`. (#34794)