tarrsalah / phoenix_etag

ETag support for phoenix

PhoenixETag

Conditional request (ETag & modified-since) support for Phoenix.

Based heavily on code from hex_web.

Usage

The library provides a replacement function for Phoenix.Controller.render/1-4 called PhoenixETag.render_if_stale/1-4 accepting exactly the same arguments. When called the function expects the view to implement an additional callback: stale_checks/2 similar to render/2 that is responsible for returning the etag value and/or last modified value for the current resource.

Additional helper PhoenixETag.schema_etag/1 is provided for generating etag values of a single or multiple schema structs.

# controller

def show(conn, %{"id" => id}) do
  data = MyApp.load_data(id)
  PhoenixETag.render_if_stale(conn, :show, data: data)
end

# view

def stale_checks("show." <> _format, %{data: data}) do
  [etag: PhoenixETag.schema_etag(data), 
   last_modified: PhoenixETag.schema_last_modified(data)]
end

Both the etag and last_modified values are optional. The first one will add an etag header to the response and perform a stale check against the if-none-match header. The second one will add a last-modified header to the response and perform a stale check against the if-modified-since header. If the headers indicate cache is fresh a 304 Not Modified response is triggered, and rendering of the response is aborted. If headers indicate cache is stale, render proceeds as normal, except the extra headers are added to the response.

Installation

If available in Hex, the package can be installed by adding phoenix_etag to your list of dependencies in mix.exs:

def deps do
  [{:phoenix_etag, "~> 0.1"}]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/phoenix_etag.