Plug.Cowboy (PlugCowboy v2.4.0) 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). Note, the default reference name does not contain the port so in order to serve the same plug on multiple ports you need to set the :ref accordingly, e.g.: ref: MyPlug_HTTP_4000, ref: MyPlug_HTTP_4001, etc. This is the value that needs to be given on shutdown.

  • :compress - Cowboy will attempt to compress the response body. Defaults to false.

  • :stream_handlers - List of Cowboy stream_handlers, see Cowboy docs.

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

Instrumentation

PlugCowboy uses the :telemetry library for instrumentation. The following span events are published during each request:

  • [:cowboy, :request, :start] - dispatched at the beginning of the request
  • [:cowboy, :request, :stop] - dispatched at the end of the request
  • [:cowboy, :request, :exception] - dispatched at the end of a request that exits

A single event is published when the request ends with an early error:

  • [:cowboy, :request, :early_error] - dispatched for requests terminated early by Cowboy

See (cowboy_telemetry)[https://github.com/beam-telemetry/cowboy_telemetry#telemetry-events] for more details on the events.

To opt-out of this default instrumentation, you can manually configure cowboy with the option stream_handlers: [:cowboy_stream_h].

Link to this section Summary

Functions

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

Runs cowboy under http.

Runs cowboy under https.

Shutdowns the given reference.

Link to this section Functions

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

It supports all options as specified in the module documentation plus it requires the follow two options:

  • :scheme - either :http or :https
  • :plug - such as MyPlug or {MyPlug, plug_opts}

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

handle_event(arg1, _, arg3, _)

View Source
Link to this function

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

View Source

Specs

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

Specs

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 function 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

Shutdowns the given reference.