# TeslaHTTPCache
HTTP caching middleware for Tesla
## Installation
```elixir
def deps do
[
{:http_cache, "~> 0.3.1"}
{:tesla_http_cache, "~> 0.3.0"}
]
end
```
Responses have to be stored in a separate store backend (this library does not come with one), such
as:
- [`http_cache_store_memory`](https://github.com/tanguilp/http_cache_store_memory): responses are
stored in memory (ETS)
- [`http_cache_store_disk`](https://github.com/tanguilp/http_cache_store_disk): responses are
stored on disk. An application using the `sendfile` system call (such as
[`plug_http_cache`](https://github.com/tanguilp/plug_http_cache)) may benefit from the kernel's
memory caching automatically
Both are cluster-aware.
## Configuration
Options of this middleware are options of the [http_cache](https://hexdocs.pm/http_cache)
library, By default, the following options are set:
- `:type`: `:private`
- `:auto_accept_encoding`: `true`
- `:auto_compress`: `true`
The `:store` option must be set when configuring the middleware.
## Examples
Notice the `age` response header after the first request.
```elixir
iex> client = Tesla.client([{TeslaHTTPCache, %{store: :http_cache_store_process}}])
%Tesla.Client{
fun: nil,
pre: [{TeslaHTTPCache, :call, [%{store: :http_cache_store_process}]}],
post: [],
adapter: nil
}
iex> Tesla.get!(client, "http://perdu.com")
%Tesla.Env{
method: :get,
url: "http://perdu.com",
query: [],
headers: [
{"cache-control", "max-age=600"},
{"date", "Sat, 22 Apr 2023 14:15:11 GMT"},
{"etag", "W/\"cc-5344555136fe9-gzip\""},
{"server", "cloudflare"},
{"vary", "Accept-Encoding,User-Agent"},
{"content-type", "text/html"},
{"expires", "Sat, 22 Apr 2023 14:25:11 GMT"},
{"last-modified", "Thu, 02 Jun 2016 06:01:08 GMT"},
{"cf-cache-status", "DYNAMIC"},
{"report-to",
"{\"endpoints\":[{\"url\":\"https:\\/\\/a.nel.cloudflare.com\\/report\\/v3?s=OW%2BJhOzTmxq4FGquM7w7bvkDLoryGQY9elB6ajNGx6Wgw0%2BjJechCF9vurIyh1V8rJ%2F0O6KL%2B36xUILE8SICSy1o0O1%2FrR2lx0XHgsN0ZWhBXsWf81OnlHM6ITw%3D\"}],\"group\":\"cf-nel\",\"max_age\":604800}"},
{"nel",
"{\"success_fraction\":0,\"report_to\":\"cf-nel\",\"max_age\":604800}"},
{"cf-ray", "7bbe7a35ea419bc2-FRA"},
{"alt-svc", "h3=\":443\"; ma=86400, h3-29=\":443\"; ma=86400"},
{"content-length", "204"}
],
body: "<html><head><title>Vous Etes Perdu ?</title></head><body><h1>Perdu sur l'Internet ?</h1><h2>Pas de panique, on va vous aider</h2><strong><pre> * <----- vous êtes ici</pre></strong></body></html>\n",
status: 200,
opts: [],
__module__: Tesla,
__client__: %Tesla.Client{
fun: nil,
pre: [{TeslaHTTPCache, :call, [%{store: :http_cache_store_process}]}],
post: [],
adapter: nil
}
}
iex> Tesla.get!(client, "http://perdu.com")
%Tesla.Env{
method: :get,
url: "http://perdu.com",
query: [],
headers: [
{"cache-control", "max-age=600"},
{"date", "Sat, 22 Apr 2023 14:15:11 GMT"},
{"etag", "W/\"cc-5344555136fe9-gzip\""},
{"server", "cloudflare"},
{"vary", "Accept-Encoding,User-Agent"},
{"content-type", "text/html"},
{"expires", "Sat, 22 Apr 2023 14:25:11 GMT"},
{"last-modified", "Thu, 02 Jun 2016 06:01:08 GMT"},
{"cf-cache-status", "DYNAMIC"},
{"report-to",
"{\"endpoints\":[{\"url\":\"https:\\/\\/a.nel.cloudflare.com\\/report\\/v3?s=OW%2BJhOzTmxq4FGquM7w7bvkDLoryGQY9elB6ajNGx6Wgw0%2BjJechCF9vurIyh1V8rJ%2F0O6KL%2B36xUILE8SICSy1o0O1%2FrR2lx0XHgsN0ZWhBXsWf81OnlHM6ITw%3D\"}],\"group\":\"cf-nel\",\"max_age\":604800}"},
{"nel",
"{\"success_fraction\":0,\"report_to\":\"cf-nel\",\"max_age\":604800}"},
{"cf-ray", "7bbe7a35ea419bc2-FRA"},
{"alt-svc", "h3=\":443\"; ma=86400, h3-29=\":443\"; ma=86400"},
{"content-length", "204"},
{"age", "8"}
],
body: "<html><head><title>Vous Etes Perdu ?</title></head><body><h1>Perdu sur l'Internet ?</h1><h2>Pas de panique, on va vous aider</h2><strong><pre> * <----- vous êtes ici</pre></strong></body></html>\n",
status: 200,
opts: [],
__module__: Tesla,
__client__: %Tesla.Client{
fun: nil,
pre: [{TeslaHTTPCache, :call, [%{store: :http_cache_store_process}]}],
post: [],
adapter: nil
}
}
iex> Tesla.get!(client, "http://perdu.com", headers: [{"range", "bytes=12-43"}])
%Tesla.Env{
method: :get,
url: "http://perdu.com",
query: [],
headers: [
{"cache-control", "max-age=600"},
{"date", "Sat, 22 Apr 2023 14:15:11 GMT"},
{"etag", "W/\"cc-5344555136fe9-gzip\""},
{"server", "cloudflare"},
{"vary", "Accept-Encoding,User-Agent"},
{"content-type", "text/html"},
{"expires", "Sat, 22 Apr 2023 14:25:11 GMT"},
{"last-modified", "Thu, 02 Jun 2016 06:01:08 GMT"},
{"cf-cache-status", "DYNAMIC"},
{"report-to",
"{\"endpoints\":[{\"url\":\"https:\\/\\/a.nel.cloudflare.com\\/report\\/v3?s=OW%2BJhOzTmxq4FGquM7w7bvkDLoryGQY9elB6ajNGx6Wgw0%2BjJechCF9vurIyh1V8rJ%2F0O6KL%2B36xUILE8SICSy1o0O1%2FrR2lx0XHgsN0ZWhBXsWf81OnlHM6ITw%3D\"}],\"group\":\"cf-nel\",\"max_age\":604800}"},
{"nel",
"{\"success_fraction\":0,\"report_to\":\"cf-nel\",\"max_age\":604800}"},
{"cf-ray", "7bbe7a35ea419bc2-FRA"},
{"alt-svc", "h3=\":443\"; ma=86400, h3-29=\":443\"; ma=86400"},
{"content-range", "bytes 12-43/204"},
{"content-length", "32"},
{"age", "22"}
],
body: "<title>Vous Etes Perdu ?</title>",
status: 206,
opts: [],
__module__: Tesla,
__client__: %Tesla.Client{
fun: nil,
pre: [{TeslaHTTPCache, :call, [%{store: :http_cache_store_process}]}],
post: [],
adapter: nil
}
}
iex> Tesla.get!(client, "http://perdu.com", headers: [{"cache-control", "no-cache"}])
%Tesla.Env{
method: :get,
url: "http://perdu.com",
query: [],
headers: [
{"cache-control", "max-age=600"},
{"date", "Sat, 22 Apr 2023 14:15:46 GMT"},
{"etag", "W/\"cc-5344555136fe9-gzip\""},
{"server", "cloudflare"},
{"vary", "Accept-Encoding,User-Agent"},
{"content-type", "text/html"},
{"expires", "Sat, 22 Apr 2023 14:25:46 GMT"},
{"last-modified", "Thu, 02 Jun 2016 06:01:08 GMT"},
{"cf-cache-status", "DYNAMIC"},
{"report-to",
"{\"endpoints\":[{\"url\":\"https:\\/\\/a.nel.cloudflare.com\\/report\\/v3?s=3gbcT%2Bp7OxvokGPjTitRoTA9KyQOcbn6z1EG5jp2%2Frvg%2FqA%2Bi0CZgDK0O7VNSB6c5UIPsilr%2BMysTPCgi8ocxYYCsMhc82q4e7EP4nAI5zYYuJhmMGFXTeSjWMI%3D\"}],\"group\":\"cf-nel\",\"max_age\":604800}"},
{"nel",
"{\"success_fraction\":0,\"report_to\":\"cf-nel\",\"max_age\":604800}"},
{"cf-ray", "7bbe7b10f8619bc2-FRA"},
{"alt-svc", "h3=\":443\"; ma=86400, h3-29=\":443\"; ma=86400"},
{"content-length", "204"}
],
body: "<html><head><title>Vous Etes Perdu ?</title></head><body><h1>Perdu sur l'Internet ?</h1><h2>Pas de panique, on va vous aider</h2><strong><pre> * <----- vous êtes ici</pre></strong></body></html>\n",
status: 200,
opts: [],
__module__: Tesla,
__client__: %Tesla.Client{
fun: nil,
pre: [{TeslaHTTPCache, :call, [%{store: :http_cache_store_process}]}],
post: [],
adapter: nil
}
}
```
## Middleware order
`http_cache` only caches iodata bodies. As a consequence, beware of not decoding the body before
caching. For instance, do not:
```elixir
defp client(token) do
Tesla.client([
Tesla.Middleware.Logger,
{Tesla.Middleware.BearerAuth, token: token},
{TeslaHTTPCache, %{store: :http_cache_store_memory}},
Tesla.Middleware.JSON # <- WRONG!!!
])
end
```
as the JSON will be decoded before caching, and the body wil be a map (not cacheable). Instead do:
```elixir
defp client(token) do
Tesla.client([
Tesla.Middleware.Logger,
{Tesla.Middleware.BearerAuth, token: token},
Tesla.Middleware.JSON,
{TeslaHTTPCache, %{store: :http_cache_store_memory}}
])
end
```
Response will be cached first then decoded.
## Telemetry events
The following events are emitted:
- `[:tesla_http_cache, :hit]` when a response is returned from the cache
- measurements: none
- metadata:
- `:freshness`: one of
- `:fresh`: a fresh response was returned
- `:stale`: a stale response was returned
- `:revalidated`: the response was successfully revalidated and returned
- `[:tesla_http_cache, :miss]` in case of cache miss
- measurements: none
- metadata: none
