View Source Phoenix.Endpoint behaviour (Phoenix v1.7.0-rc.3)
Defines a Phoenix endpoint.
The endpoint is the boundary where all requests to your web application start. It is also the interface your application provides to the underlying web servers.
Overall, an endpoint has three responsibilities:
to provide a wrapper for starting and stopping the endpoint as part of a supervision tree
to define an initial plug pipeline for requests to pass through
to host web specific configuration for your application
endpoints
Endpoints
An endpoint is simply a module defined with the help
of Phoenix.Endpoint
. If you have used the mix phx.new
generator, an endpoint was automatically generated as
part of your application:
defmodule YourAppWeb.Endpoint do
use Phoenix.Endpoint, otp_app: :your_app
# plug ...
# plug ...
plug YourApp.Router
end
Endpoints must be explicitly started as part of your application supervision tree. Endpoints are added by default to the supervision tree in generated applications. Endpoints can be added to the supervision tree as follows:
children = [
YourAppWeb.Endpoint
]
endpoint-configuration
Endpoint configuration
All endpoints are configured in your application environment. For example:
config :your_app, YourAppWeb.Endpoint,
secret_key_base: "kjoy3o1zeidquwy1398juxzldjlksahdk3"
Endpoint configuration is split into two categories. Compile-time configuration means the configuration is read during compilation and changing it at runtime has no effect. The compile-time configuration is mostly related to error handling.
Runtime configuration, instead, is accessed during or
after your application is started and can be read through the
config/2
function:
YourAppWeb.Endpoint.config(:port)
YourAppWeb.Endpoint.config(:some_config, :default_value)
dynamic-configuration
Dynamic configuration
For dynamically configuring the endpoint, such as loading data
from environment variables or configuration files, Phoenix invokes
the init/2
callback on the endpoint, passing the atom :supervisor
as the first argument and the endpoint configuration as second.
All of Phoenix configuration, except the Compile-time configuration
below can be set dynamically from the init/2
callback.
compile-time-configuration
Compile-time configuration
:code_reloader
- whentrue
, enables code reloading functionality. For the list of code reloader configuration options seePhoenix.CodeReloader.reload/1
. Keep in mind code reloading is based on the file-system, therefore it is not possible to run two instances of the same app at the same time with code reloading in development, as they will race each other and only one will effectively recompile the files. In such cases, tweak your config files so code reloading is enabled in only one of the apps or set the MIX_BUILD environment variable to give them distinct build directories:debug_errors
- whentrue
, usesPlug.Debugger
functionality for debugging failures in the application. Recommended to be set totrue
only in development as it allows listing of the application source code during debugging. Defaults tofalse
:force_ssl
- ensures no data is ever sent via HTTP, always redirecting to HTTPS. It expects a list of options which are forwarded toPlug.SSL
. By default it sets the "strict-transport-security" header in HTTPS requests, forcing browsers to always use HTTPS. If an unsafe request (HTTP) is sent, it redirects to the HTTPS version using the:host
specified in the:url
configuration. To dynamically redirect to thehost
of the current request, set:host
in the:force_ssl
configuration tonil
runtime-configuration
Runtime configuration
:adapter
- which webserver adapter to use for serving web requests. See the "Adapter configuration" section below:cache_static_manifest
- a path to a json manifest file that contains static files and their digested version. This is typically set to "priv/static/cache_manifest.json" which is the file automatically generated bymix phx.digest
. It can be either: a string containing a file system path or a tuple containing the application name and the path within that application.:cache_static_manifest_latest
- a map of the static files pointing to their digest version. This is automatically loaded fromcache_static_manifest
on boot. However, if you have your own static handling mechanism, you may want to set this value explicitly. This is used by projects such asLiveView
to detect if the client is running on the latest version of all assets.:cache_manifest_skip_vsn
- when true, skips the appended query string "?vsn=d" when generating paths to static assets. This query string is used byPlug.Static
to set long expiry dates, therefore, you should set this option to true only if you are not usingPlug.Static
to serve assets, for example, if you are using a CDN. If you are setting this option, you should also consider passing--no-vsn
tomix phx.digest
. Defaults tofalse
.:check_origin
- configure the default:check_origin
setting for transports. Seesocket/3
for options. Defaults totrue
.:secret_key_base
- a secret key used as a base to generate secrets for encrypting and signing data. For example, cookies and tokens are signed by default, but they may also be encrypted if desired. Defaults tonil
as it must be set per application:server
- whentrue
, starts the web server when the endpoint supervision tree starts. Defaults tofalse
. Themix phx.server
task automatically sets this totrue
:url
- configuration for generating URLs throughout the app. Accepts the:host
,:scheme
,:path
and:port
options. All keys except:path
can be changed at runtime. Defaults to:[host: "localhost", path: "/"]
The
:port
option requires either an integer or string. The:host
option requires a string.The
:scheme
option accepts"http"
and"https"
values. Default value is inferred from top level:http
or:https
option. It is useful when hosting Phoenix behind a load balancer or reverse proxy and terminating SSL there.The
:path
option can be used to override root path. Useful when hosting Phoenix behind a reverse proxy with URL rewrite rules:static_url
- configuration for generating URLs for static files. It will fallback tourl
if no option is provided. Accepts the same options asurl
:watchers
- a set of watchers to run alongside your server. It expects a list of tuples containing the executable and its arguments. Watchers are guaranteed to run in the application directory, but only when the server is enabled (unless:force_watchers
configuration is set totrue
). For example, the watcher below will run the "watch" mode of the webpack build tool when the server starts. You can configure it to whatever build tool or command you want:[ node: [ "node_modules/webpack/bin/webpack.js", "--mode", "development", "--watch", "--watch-options-stdin" ] ]
The
:cd
and:env
options can be given at the end of the list to customize the watcher:[node: [..., cd: "assets", env: [{"TAILWIND_MODE", "watch"}]]]
A watcher can also be a module-function-args tuple that will be invoked accordingly:
[another: {Mod, :fun, [arg1, arg2]}]
:force_watchers
- whentrue
, forces your watchers to start even when the:server
option is set tofalse
.:live_reload
- configuration for the live reload option. Configuration requires a:patterns
option which should be a list of file patterns to watch. When these files change, it will trigger a reload.live_reload: [ url: "ws://localhost:4000", patterns: [ ~r"priv/static/.*(js|css|png|jpeg|jpg|gif|svg)$", ~r"lib/app_web/(live|views)/.*(ex)$", ~r"lib/app_web/templates/.*(eex)$" ] ]
:pubsub_server
- the name of the pubsub server to use in channels and via the Endpoint broadcast functions. The PubSub server is typically started in your supervision tree.:render_errors
- responsible for rendering templates whenever there is a failure in the application. For example, if the application crashes with a 500 error during a HTML request,render("500.html", assigns)
will be called in the view given to:render_errors
. A:formats
list can be provided to specify a module per format to handle error rendering. Example:[formats: [html: MyApp.ErrorHTML], layout: false, log: :debug]
:log_access_url
- log the access url once the server boots
adapter-configuration
Adapter configuration
Phoenix allows you to choose which webserver adapter to use. The default
is Phoenix.Endpoint.Cowboy2Adapter
which can be configured via the
following top-level options.
:http
- the configuration for the HTTP server. It accepts all options as defined byPlug.Cowboy
. Defaults tofalse
:https
- the configuration for the HTTPS server. It accepts all options as defined byPlug.Cowboy
. Defaults tofalse
:drainer
- a drainer process that triggers when your application is shutting down to wait for any on-going request to finish. It accepts all options as defined byPlug.Cowboy.Drainer
. Defaults to[]
, which will start a drainer process for each configured endpoint, but can be disabled by setting it tofalse
.
endpoint-api
Endpoint API
In the previous section, we have used the config/2
function that is
automatically generated in your endpoint. Here's a list of all the functions
that are automatically defined in your endpoint:
for handling paths and URLs:
struct_url/0
,url/0
,path/1
,static_url/0
,static_path/1
, andstatic_integrity/1
for broadcasting to channels:
broadcast/3
,broadcast!/3
,broadcast_from/4
,broadcast_from!/4
,local_broadcast/3
, andlocal_broadcast_from/4
for configuration:
start_link/1
,config/2
, andconfig_change/2
as required by the
Plug
behaviour:Plug.init/1
andPlug.call/2
Link to this section Summary
Callbacks
Broadcasts a msg
as event
in the given topic
to all nodes.
Broadcasts a msg
as event
in the given topic
to all nodes.
Broadcasts a msg
from the given from
as event
in the given topic
to all nodes.
Broadcasts a msg
from the given from
as event
in the given topic
to all nodes.
Access the endpoint configuration given by key.
Reload the endpoint configuration on application upgrades.
Returns the host from the :url configuration.
Initialize the endpoint configuration.
Broadcasts a msg
as event
in the given topic
within the current node.
Broadcasts a msg
from the given from
as event
in the given topic
within the current node.
Generates the path information when routing to this endpoint.
Returns the script name from the :url configuration.
Starts the endpoint supervision tree.
Generates an integrity hash to a static file in priv/static
.
Generates a two item tuple containing the static_path
and static_integrity
.
Generates a route to a static file in priv/static
.
Generates the static URL without any path information.
Generates the endpoint base URL, but as a URI
struct.
Subscribes the caller to the given topic.
Unsubscribes the caller from the given topic.
Generates the endpoint base URL without any path information.
Functions
Checks if Endpoint's web server has been configured to start.
Defines a websocket/longpoll mount-point for a socket.
Link to this section Types
Link to this section Callbacks
Broadcasts a msg
as event
in the given topic
to all nodes.
Broadcasts a msg
as event
in the given topic
to all nodes.
Raises in case of failures.
Broadcasts a msg
from the given from
as event
in the given topic
to all nodes.
Broadcasts a msg
from the given from
as event
in the given topic
to all nodes.
Raises in case of failures.
Access the endpoint configuration given by key.
Reload the endpoint configuration on application upgrades.
@callback host() :: String.t()
Returns the host from the :url configuration.
Initialize the endpoint configuration.
Invoked when the endpoint supervisor starts, allows dynamically configuring the endpoint from system environment or other runtime sources.
Broadcasts a msg
as event
in the given topic
within the current node.
Broadcasts a msg
from the given from
as event
in the given topic
within the current node.
Generates the path information when routing to this endpoint.
@callback script_name() :: [String.t()]
Returns the script name from the :url configuration.
@callback start_link(keyword()) :: Supervisor.on_start()
Starts the endpoint supervision tree.
Starts endpoint's configuration cache and possibly the servers for handling requests.
Generates an integrity hash to a static file in priv/static
.
Generates a two item tuple containing the static_path
and static_integrity
.
Generates a route to a static file in priv/static
.
@callback static_url() :: String.t()
Generates the static URL without any path information.
@callback struct_url() :: URI.t()
Generates the endpoint base URL, but as a URI
struct.
Subscribes the caller to the given topic.
See Phoenix.PubSub.subscribe/3
for options.
Unsubscribes the caller from the given topic.
@callback url() :: String.t()
Generates the endpoint base URL without any path information.
Link to this section Functions
Checks if Endpoint's web server has been configured to start.
otp_app
- The OTP app running the endpoint, for example:my_app
endpoint
- The endpoint module, for exampleMyAppWeb.Endpoint
examples
Examples
iex> Phoenix.Endpoint.server?(:my_app, MyAppWeb.Endpoint)
true
Defines a websocket/longpoll mount-point for a socket.
options
Options
:websocket
- controls the websocket configuration. Defaults totrue
. May be false or a keyword list of options. See "Common configuration" and "WebSocket configuration" for the whole list:longpoll
- controls the longpoll configuration. Defaults tofalse
. May be true or a keyword list of options. See "Common configuration" and "Longpoll configuration" for the whole list
If your socket is implemented using Phoenix.Socket
,
you can also pass to each transport above all options
accepted on use Phoenix.Socket
. An option given here
will override the value in use Phoenix.Socket
.
examples
Examples
socket "/ws", MyApp.UserSocket
socket "/ws/admin", MyApp.AdminUserSocket,
longpoll: true,
websocket: [compress: true]
path-params
Path params
It is possible to include variables in the path, these will be
available in the params
that are passed to the socket.
socket "/ws/:user_id", MyApp.UserSocket,
websocket: [path: "/project/:project_id"]
common-configuration
Common configuration
The configuration below can be given to both :websocket
and
:longpoll
keys:
:path
- the path to use for the transport. Will default to the transport name ("/websocket" or "/longpoll"):serializer
- a list of serializers for messages. SeePhoenix.Socket
for more information:transport_log
- if the transport layer itself should log and, if so, the level:check_origin
- if the transport should check the origin of requests when theorigin
header is present. May betrue
,false
, a list of hosts that are allowed, or a function provided as MFA tuple. Defaults to:check_origin
setting at endpoint configuration.If
true
, the header is checked against:host
inYourAppWeb.Endpoint.config(:url)[:host]
.If
false
, your app is vulnerable to Cross-Site WebSocket Hijacking (CSWSH) attacks. Only use in development, when the host is truly unknown or when serving clients that do not send theorigin
header, such as mobile apps.You can also specify a list of explicitly allowed origins. Wildcards are supported.
check_origin: [ "https://example.com", "//another.com:888", "//*.other.com" ]
Or to accept any origin matching the request connection's host, port, and scheme:
check_origin: :conn
Or a custom MFA function:
check_origin: {MyAppWeb.Auth, :my_check_origin?, []}
The MFA is invoked with the request
%URI{}
as the first argument, followed by arguments in the MFA list, and must return a boolean.:code_reloader
- enable or disable the code reloader. Defaults to your endpoint configuration:connect_info
- a list of keys that represent data to be copied from the transport to be made available in the user socketconnect/3
callbackThe valid keys are:
:peer_data
- the result ofPlug.Conn.get_peer_data/1
:trace_context_headers
- a list of all trace context headers. Supported headers are defined by the W3C Trace Context Specification. These headers are necessary for libraries such as OpenTelemetry to extract trace propagation information to know this request is part of a larger trace in progress.:x_headers
- all request headers that have an "x-" prefix:uri
- a%URI{}
with information from the conn:user_agent
- the value of the "user-agent" request header{:session, session_config}
- the session information fromPlug.Conn
. Thesession_config
is an exact copy of the arguments given toPlug.Session
. This requires the "_csrf_token" to be given as request parameter with the value ofURI.encode_www_form(Plug.CSRFProtection.get_csrf_token())
when connecting to the socket. It can also be a MFA to allow loading config in runtime{MyAppWeb.Auth, :get_session_config, []}
. Otherwise the session will benil
.
Arbitrary keywords may also appear following the above valid keys, which is useful for passing custom connection information to the socket.
For example:
socket "/socket", AppWeb.UserSocket, websocket: [ connect_info: [:peer_data, :trace_context_headers, :x_headers, :uri, session: [store: :cookie]] ]
With arbitrary keywords:
socket "/socket", AppWeb.UserSocket, websocket: [ connect_info: [:uri, custom_value: "abcdef"] ]
websocket-configuration
Websocket configuration
The following configuration applies only to :websocket
.
:timeout
- the timeout for keeping websocket connections open after it last received data, defaults to 60_000ms:max_frame_size
- the maximum allowed frame size in bytes, defaults to "infinity":fullsweep_after
- the maximum number of garbage collections before forcing a fullsweep for the socket process. You can set it to0
to force more frequent cleanups of your websocket transport processes. Setting this option requires Erlang/OTP 24:compress
- whether to enable per message compression on all data frames, defaults to false:subprotocols
- a list of supported websocket subprotocols. Used for handshakeSec-WebSocket-Protocol
response header, defaults to nil.For example:
subprotocols: ["sip", "mqtt"]
:error_handler
- custom error handler for connection errors. IfPhoenix.Socket.connect/3
returns an{:error, reason}
tuple, the error handler will be called with the error reason. For WebSockets, the error handler must be a MFA tuple that receives aPlug.Conn
, the error reason, and returns aPlug.Conn
with a response. For example:socket "/socket", MySocket, websocket: [ error_handler: {MySocket, :handle_error, []} ]
and a
{:error, :rate_limit}
return may be handled onMySocket
as:def handle_error(conn, :rate_limit), do: Plug.Conn.send_resp(conn, 429, "Too many requests")
longpoll-configuration
Longpoll configuration
The following configuration applies only to :longpoll
:
:window_ms
- how long the client can wait for new messages in its poll request in milliseconds (ms). Defaults to10_000
.:pubsub_timeout_ms
- how long a request can wait for the pubsub layer to respond in milliseconds (ms). Defaults to2000
.:crypto
- options for verifying and signing the token, accepted byPhoenix.Token
. By default tokens are valid for 2 weeks