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 in0..255for IPv4, or a tuple in the format{a, b, c, d, e, f, g, h}with each value in0..65535for IPv6, or a tuple in the format{:local, path}for a unix socket at the givenpath.:port- the port to run the server. Defaults to 4000 (http) and 4040 (https). Must be 0 when:ipis 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 toplug.HTTP(http) andplug.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:refaccordingly, 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 Cowboystream_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_acceptorswill be set to100and:max_connectionsto16_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:httpor:https:plug- such asMyPlugor{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)Specs
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.HTTPSpecs
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.HTTPSShutdowns the given reference.