PlugCowboy

v2.1.0

PlugCowboy v2.1.0 Plug.Cowboy View Source

Adapter interface to the Cowboy2 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, or a tuple in the format {:local, path} for a unix socket at the given path.

  • :port - the port to run the server. Defaults to 4000 (http) and 4040 (https). Must be 0 when :ip is a {:local, path} tuple.

  • :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.

  • :protocol_options - Specifies remaining protocol options, see Cowboy docs.

  • :transport_options - A keyword list specifying transport options, see ranch docs. By default :num_acceptors will be set to 100 and :max_connections to 16_384.

All other options are given as :socket_opts 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. When using a unix socket, OTP 21+ is required for Plug.Static and Plug.Conn.send_file/3 to behave correctly.

Link to this section Summary

Functions

child_spec(opts)

A function for starting a Cowboy2 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

Link to this function

child_spec(opts) View Source

A function for starting a Cowboy2 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)
Link to this function

http(plug, opts, cowboy_options \\ []) View Source 
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
Link to this function

https(plug, opts, cowboy_options \\ []) View Source 
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
Link to this function

shutdown(ref) View Source

Shutdowns the given reference.