Plug v1.4.0 Plug.Adapters.Cowboy View Source

Adapter interface to the Cowboy webserver.

Options

:ip - the ip to bind the server to. Must be either a tuple in the format {a, b, c, d} with each value in 0..255 for IPv4 or a tuple in the format {a, b, c, d, e, f, g, h} with each value in 0..65535 for IPv6.
:port - the port to run the server. Defaults to 4000 (http) and 4040 (https).
:acceptors - the number of acceptors for the listener. Defaults to 100.
:max_connections - max number of connections supported. Defaults to 16_384.
:dispatch - manually configure Cowboy’s dispatch. If this option is used, the given plug won’t be initialized nor dispatched to (and doing so becomes the user’s responsibility).
:ref - the reference name to be used. Defaults to plug.HTTP (http) and plug.HTTPS (https). This is the value that needs to be given on shutdown.
:compress - Cowboy will attempt to compress the response body. Defaults to false.
:timeout - Time in ms with no requests before Cowboy closes the connection. Defaults to 5000ms.
:protocol_options - Specifies remaining protocol options, see Cowboy protocol docs.

All other options are given to the underlying transport.

Link to this section Summary

Functions

child_spec(opts)

A function for starting a Cowboy server under Elixir v1.5 supervisors

child_spec(scheme, plug, opts, cowboy_options \\ [])

Returns a child spec to be supervised by your application

http(plug, opts, cowboy_options \\ [])

Run cowboy under http

https(plug, opts, cowboy_options \\ [])

Run cowboy under https

shutdown(ref)

Shutdowns the given reference

Link to this section Functions

child_spec(opts)

A function for starting a Cowboy server under Elixir v1.5 supervisors.

It expects three options:

:scheme - either :http or :https
:plug - such as MyPlug or {MyPlug, plug_opts}
:options - the server options as specified in the module documentation

Examples

children = [
  {Plug.Adapters.Cowboy, scheme: :http, plug: MyApp, options: [port: 4040]}
]

Supervisor.start_link(children, strategy: :one_for_one)

child_spec(scheme, plug, opts, cowboy_options \\ [])

Returns a child spec to be supervised by your application.

This function returns the old child specs used by early OTP and Elixir versions. See child_spec/1 for the Elixir v1.5 based child specifications.

Example

Presuming your Plug module is named MyRouter you can add it to your supervision tree like so using this function:

defmodule MyApp do
  use Application

  def start(_type, _args) do
    import Supervisor.Spec

    children = [
      Plug.Adapters.Cowboy.child_spec(:http, MyRouter, [], [port: 4001])
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

http(plug, opts, cowboy_options \\ [])

http(module, Keyword.t, Keyword.t) ::
  {:ok, pid} |
  {:error, :eaddrinuse} |
  {:error, term}

Run cowboy under http.

Example

# Starts a new interface
Plug.Adapters.Cowboy.http MyPlug, [], port: 80

# The interface above can be shutdown with
Plug.Adapters.Cowboy.shutdown MyPlug.HTTP

https(plug, opts, cowboy_options \\ [])

https(module, Keyword.t, Keyword.t) ::
  {:ok, pid} |
  {:error, :eaddrinuse} |
  {:error, term}

Run cowboy under https.

Besides the options described in the module documentation, this module also accepts all options defined in [the ssl erlang module] (http://www.erlang.org/doc/man/ssl.html), like keyfile, certfile, cacertfile, dhfile and others.

The certificate files can be given as a relative path. For such, the :otp_app option must also be given and certificates will be looked from the priv directory of the given application.

Example

# Starts a new interface
Plug.Adapters.Cowboy.https MyPlug, [],
  port: 443,
  password: "SECRET",
  otp_app: :my_app,
  keyfile: "priv/ssl/key.pem",
  certfile: "priv/ssl/cert.pem",
  dhfile: "priv/ssl/dhparam.pem"

# The interface above can be shutdown with
Plug.Adapters.Cowboy.shutdown MyPlug.HTTPS

shutdown(ref)

Shutdowns the given reference.