Skip to content

Commit

Permalink
Improve docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@whatyouhide
whatyouhide committed Jan 29, 2025
1 parent ced253f commit c194947
Showing 1 changed file with 61 additions and 50 deletions.
111 changes: 61 additions & 50 deletions lib/plug/cowboy.ex
View file
Original file line number Diff line number Diff line change
@@ -1,43 +1,46 @@
defmodule Plug.Cowboy do
@moduledoc """
Adapter interface to the Cowboy2 webserver.
Adapter interface to the [Cowboy webserver](https://github.com/ninenines/cowboy).
## Options
* `:net` - If using `:inet` (IPv4 only - the default) or `:inet6` (IPv6)
* `:net` - if using `:inet` (IPv4 only, the default) or `:inet6` (IPv6).
* `:ip` - the IP to bind the server to. Must be one of:
* a tuple in the format `{a, b, c, d}` with each value in `0..255` for IPv4,
* a tuple in the format `{a, b, c, d, e, f, g, h}` with each value in `0..65_535` for IPv6,
* or a tuple in the format `{:local, path}` for a Unix socket at the given `path`.
* `: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`.
If you set an IPv6, the `:net` option will be automatically set to `:inet6`.
If both `:net` and `:ip` options are given, make sure they are compatible
(i.e. give a IPv4 for `:inet` and IPv6 for `:inet6`).
Also, see "Loopback vs Public IP Addresses".
(that is, give a IPv4 for `:inet` and IPv6 for `:inet6`).
Also, see the [*Loopback vs Public IP Addresses*
section](#module-loopback-vs-public-ip-addresses).
* `:port` - the port to run the server.
Defaults to 4000 (http) and 4040 (https).
Must be 0 when `:ip` is a `{:local, path}` tuple.
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.
Defaults to `plug.HTTP` (HTTP) and `plug.HTTPS` (HTTPS).
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.
For example, `ref: MyPlug_HTTP_4000`, `ref: MyPlug_HTTP_4001`, and so on.
This is the value that needs to be given on shutdown.
* `:compress` - Cowboy will attempt to compress the response body.
Defaults to false.
* `:compress` - if `true`, Cowboy will attempt to compress the response body.
Defaults to `false`.
* `:stream_handlers` - List of Cowboy `stream_handlers`,
see [Cowboy docs](https://ninenines.eu/docs/en/cowboy/2.12/manual/cowboy_http/).
* `:protocol_options` - Specifies remaining protocol options,
see [Cowboy docs](https://ninenines.eu/docs/en/cowboy/2.12/manual/cowboy_http/).
see the [Cowboy docs](https://ninenines.eu/docs/en/cowboy/2.12/manual/cowboy_http/).
* `:transport_options` - A keyword list specifying transport options,
see [Ranch docs](https://ninenines.eu/docs/en/ranch/1.7/manual/ranch/).
Expand All @@ -58,16 +61,16 @@ defmodule Plug.Cowboy do
When using a Unix socket, OTP 21+ is required for `Plug.Static` and
`Plug.Conn.send_file/3` to behave correctly.
## Safety limits
## Safety Limits
Cowboy sets different limits on URL size, header length, number of
headers and so on to protect your application from attacks. For example,
headers, and so on to protect your application from attacks. For example,
the request line length defaults to 10k, which means Cowboy will return
414 if a larger URL is given. You can change this under `:protocol_options`:
`414` if a larger URL is given. You can change this under `:protocol_options`:
protocol_options: [max_request_line_length: 50_000]
Keep in mind though increasing those limits can pose a security risk.
Keep in mind that increasing those limits can pose a security risk.
Other times, browsers and proxies along the way may have equally strict
limits, which means the request will still fail or the URL will be
pruned. You can [consult all limits here](https://ninenines.eu/docs/en/cowboy/2.12/manual/cowboy_http/).
Expand All @@ -82,21 +85,22 @@ defmodule Plug.Cowboy do
Loopback addresses are only reachable from the same host (`localhost` is
usually configured to resolve to a loopback address). You may wish to use one if:
- Your app is running in a development environment (such as your laptop) and
you don't want others on the same network to access it.
- Your app is running in production, but behind a reverse proxy. For example,
you might have Nginx bound to a public address and serving HTTPS, but
forwarding the traffic to your application running on the same host. In that
case, having your app bind to the loopback address means that Nginx can reach
it, but outside traffic can only reach it via Nginx.
* Your app is running in a development environment (such as your laptop) and
you don't want others on the same network to access it.
* Your app is running in production, but behind a reverse proxy. For
example, you might have [nginx](https://nginx.org/en/) bound to a public
address and serving HTTPS, but forwarding the traffic to your application
running on the same host. In that case, having your app bind to the
loopback address means that nginx can reach it, but outside traffic can
only reach it via nginx.
Public addresses are reachable from other hosts. You may wish to use one if:
- Your app is running in a container. In this case, its loopback address is
reachable only from within the container; to be accessible from outside the
container, it needs to bind to a public IP address.
- Your app is running in production without a reverse proxy, using Cowboy's
SSL support.
* Your app is running in a container. In this case, its loopback address is
reachable only from within the container; to be accessible from outside the
container, it needs to bind to a public IP address.
* Your app is running in production without a reverse proxy, using Cowboy's
SSL support.
## Logging
Expand All @@ -109,7 +113,7 @@ defmodule Plug.Cowboy do
log_exceptions_with_status_code: [400..599]
By default, `Plug.Cowboy` includes the entire `conn` to the log metadata for exceptions.
However, this metadata may contain sensitive information such as security headers or
However, this metadata may contain sensitive information such as security headers or
cookies, which may be logged in plain text by certain logging backends. To prevent this,
you can configure the `:conn_in_exception_metadata` option to not include the `conn` in the metadata.
Expand All @@ -118,8 +122,8 @@ defmodule Plug.Cowboy do
## Instrumentation
Plug.Cowboy uses the `:telemetry` library for instrumentation. The following
span events are published during each request:
`Plug.Cowboy` uses the [`telemetry` library](https://github.com/beam-telemetry/telemetry)
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
Expand All @@ -129,14 +133,16 @@ defmodule Plug.Cowboy do
* `[: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.
for more details on the events and their measurements and metadata.
To opt-out of this default instrumentation, you can manually configure
cowboy with the option `stream_handlers: [:cowboy_stream_h]`.
Cowboy with the option:
stream_handlers: [:cowboy_stream_h]
## WebSocket support
Plug.Cowboy supports upgrading HTTP requests to WebSocket connections via
`Plug.Cowboy` supports upgrading HTTP requests to WebSocket connections via
the use of the `Plug.Conn.upgrade_adapter/3` function, called with `:websocket` as the second
argument. Applications should validate that the connection represents a valid WebSocket request
before calling this function (Cowboy will validate the connection as part of the upgrade
Expand Down Expand Up @@ -177,15 +183,15 @@ defmodule Plug.Cowboy do
end

@doc """
Runs cowboy under http.
Runs cowboy under HTTP.
## Example
# Starts a new interface
Plug.Cowboy.http MyPlug, [], port: 80
# Starts a new interface:
Plug.Cowboy.http(MyPlug, [], port: 80)
# The interface above can be shutdown with
Plug.Cowboy.shutdown MyPlug.HTTP
# The interface above can be shut down with:
Plug.Cowboy.shutdown(MyPlug.HTTP)
"""
@spec http(module(), Keyword.t(), Keyword.t()) ::
Expand All @@ -195,25 +201,28 @@ defmodule Plug.Cowboy do
end

@doc """
Runs cowboy under https.
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/1`.
## Example
# Starts a new interface
Plug.Cowboy.https MyPlug, [],
# 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
# The interface above can be shut down with:
Plug.Cowboy.shutdown(MyPlug.HTTPS)
"""
@spec https(module(), Keyword.t(), Keyword.t()) ::
Expand All @@ -226,12 +235,13 @@ defmodule Plug.Cowboy do
@doc """
Shutdowns the given reference.
"""
@spec shutdown(:ranch.ref()) :: :ok | {:error, :not_found}
def shutdown(ref) do
:cowboy.stop_listener(ref)
end

@doc """
A function for starting a Cowboy2 server under Elixir v1.5+ supervisors.
Returns a supervisor child spec to start Cowboy under a supervisor.
It supports all options as specified in the module documentation plus it
requires the following two options:
Expand All @@ -251,6 +261,7 @@ defmodule Plug.Cowboy do
Supervisor.start_link(children, strategy: :one_for_one)
"""
@spec child_spec(keyword()) :: Supervisor.child_spec()
def child_spec(opts) do
scheme = Keyword.fetch!(opts, :scheme)

Expand Down

0 comments on commit c194947

Please sign in to comment.