Skip to content
PlugCanonicalHost ensures that all requests are served by a single canonical host.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
test
.credo.exs
.formatter.exs
.gitignore
.travis.yml
LICENSE.md
README.md
mix.exs
mix.lock

README.md

PlugCanonicalHost

Travis Hex.pm

PlugCanonicalHost ensures that all requests are served by a single canonical host. It will redirect all requests from non-canonical hosts to the canonical one.

Installation

Add plug_canonical_host to the deps function in your project's mix.exs file:

defp deps do
  [
    …,
    {:plug_canonical_host, "~> 0.6"}
  ]
end

Then run mix do deps.get, deps.compile inside your project's directory.

Usage

PlugCanonicalHost can be used just as any other plugs. Add PlugCanonicalHost before all of the other plugs you want to happen after successful redirection to your canonical host.

The recommended way to define a canonical host is with an environment variable.

# config/config.exs
config :my_app,
  canonical_host: System.get_env("CANONICAL_HOST")

# lib/my_app/endpoint.ex
defmodule MyApp.Endpoint do
  plug(:canonical_host)

  defp canonical_host(conn, _opts) do
    :my_app
    |> Application.get_env(:canonical_host)
    |> case do
      host when is_binary(host) ->
        opts = PlugCanonicalHost.init(canonical_host: host)
        PlugCanonicalHost.call(conn, opts)

      _ ->
        conn
    end
  end
end

For example, if your application is accessible via both example.com and www.example.com, all traffic coming through example.com will be redirected (with a 301 HTTP status) to the matching www.example.com URL.

$ curl -sI "http://example.com/foo?bar=1"
#> HTTP/1.1 301 Moved Permanently
#> Location: http://www.example.com/foo?bar=1

You can also specify requests to ignore (ie. that will pass through without redirecting to the canonical host).

opts = PlugCanonicalHost.init(
  canonical_host: host,
  ignore: fn(%Conn{host: request_host}) ->
    # The argument is a `Plug.Conn` struct, which means we
    # can match on dozen of other fields (headers, query, etc.)
    #
    # Reference: https://hexdocs.pm/plug/Plug.Conn.html

    request_host in ["www.example.org"]
  end
)

Assuming example.com, www.example.com and www.example.org all point to our application:

$ curl -sI "http://example.com/foo?bar=1"
#> HTTP/1.1 301 Moved Permanently
#> Location: http://www.example.com/foo?bar=1

$ curl -sI "http://www.example.org/foo?bar=1"
#> HTTP/1.1 200 OK

License

PlugCanonicalHost is © 2016-2019 Rémi Prévost and may be freely distributed under the MIT license. See the LICENSE.md file for more information.

You can’t perform that action at this time.