PlugCowboy v1.0.0 Plug.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.
:log_error_on_incomplete_requests - An error is logged when the response status code is 400 and no headers are set in the request. Defaults to true.
:protocol_options - Specifies remaining protocol options, see Cowboy protocol docs.

All other options are given to the underlying transport. When running on HTTPS, any SSL configuration should be given directly to the adapter. See https/3 for an example and read Plug.SSL.configure/1 to understand about our SSL defaults.

Link to this section Summary

Functions

child_spec(opts)

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

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

Runs cowboy under http

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

Runs 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

Assuming your Plug module is named MyApp you can add it to your supervision tree by using this function:

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

Supervisor.start_link(children, strategy: :one_for_one)

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

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

Runs cowboy under http.

Example

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

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

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

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

Runs cowboy under https.

Besides the options described in the module documentation, this modules sets defaults and accepts all options defined in Plug.SSL.configure/2.

Example

# Starts a new interface
Plug.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.Cowboy.shutdown MyPlug.HTTPS

shutdown(ref)

Shutdowns the given reference.