Phoenix.Endpoint

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 where requests are sent through;

  • to host web specific configuration for your application.

Endpoints

An endpoint is simply a module defined with the help of Phoenix.Endpoint. If you have used the mix phoenix.new generator, an endpoint was automatically generated as part of your application:

defmodule YourApp.Endpoint do
  use Phoenix.Endpoint, otp_app: :your_app

  # plug ...
  # plug ...

  plug YourApp.Router
end

Before being used, an endpoint must be explicitly started as part of your application supervision tree too (which is again done by default in generated applications):

supervisor(YourApp.Endpoint, [])

Endpoint configuration

All endpoints are configured in your application environment. For example:

config :your_app, YourApp.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 and instrumentation.

Runtime configuration, instead, is accessed during or after your application is started and can be read and written through the config/2 function:

YourApp.Endpoint.config(:port)
YourApp.Endpoint.config(:some_config, :default_value)

Compile-time configuration

  • :code_reloader - when true, enables code reloading functionality

  • :debug_errors - when true, uses Plug.Debugger functionality for debugging failures in the application. Recommended to be set to true only in development as it allows listing of the application source code during debugging. Defaults to false.

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

    [view: MyApp.ErrorView, accepts: ~w(html)]

    The default format is used when none is set in the connection.

  • :instrumenters - a list of instrumenters modules whose callbacks will be fired on instrumentation events. Read more on instrumentation in the “Instrumentation” section below.

Runtime configuration

  • :root - the root of your application for running external commands. This is only required if the watchers or code reloading functionality are enabled.

  • :cache_static_lookup - when true, static file lookup in the filesystem via the static_path function are cached. Defaults to true.

  • :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/manifest.json” which is the file automatically generated by mix phoenix.digest.

  • :check_origin - configure transports to check origins or not. May be false, true or a list of hosts that are allowed.

  • :http - the configuration for the HTTP server. Currently uses cowboy and accepts all options as defined by Plug.Adapters.Cowboy. Defaults to false.

  • :https - the configuration for the HTTPS server. Currently uses cowboy and accepts all options as defined by Plug.Adapters.Cowboy. Defaults to false.

  • :force_ssl - ensures no data is ever sent via http, always redirecting to https. It expects a list of options which are forwarded to Plug.SSL. By default, it redirects http requests and sets the “strict-transport-security” header for https ones.

  • :secret_key_base - a secret key used as a base to generate secrets to encode cookies, session and friends. Defaults to nil as it must be set per application.

  • :server - when true, starts the web server when the endpoint supervision tree starts. Defaults to false. The mix phoenix.server task automatically sets this to true.

  • :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, string, or {:system, "ENV_VAR"}. When given a tuple like {:system, "PORT"}, the port will be referenced from System.get_env("PORT") at runtime as a workaround for releases where environment specific information is loaded only at compile-time.

  • :static_url - configuration for generating URLs for static files. It will fallback to url if no option is provided. Accepts the same options as url.

  • :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. For example, the watcher below will run the “watch” mode of the brunch build tool when the server starts. You can configure it to whatever build tool or command you want:

    [node: ["node_modules/brunch/bin/brunch", "watch"]]
  • :live_reload - configuration for the live reload option. Configuration requires a :paths option which should be a list of files to watch. When these files change, it will trigger a reload. If you are using a tool like pow in development, you may need to set the :url option appropriately.

    [url: "ws://localhost:4000",
     paths: [Path.expand("priv/static/js/phoenix.js")]]
  • :pubsub - configuration for this endpoint’s pubsub adapter. Configuration either requires a :name of the registered pubsub server or a :name and :adapter pair. The given adapter and name pair will be started as part of the supervision tree. if no adapter is specified, the pubsub system will work by sending events and subscribing to the given name. Defaults to:

    [adapter: Phoenix.PubSub.PG2, name: MyApp.PubSub]

    It also supports custom adpater configuration:

    [name: :my_pubsub, adapter: Phoenix.PubSub.Redis,
     host: "192.168.100.1"]

Endpoint API

In the previous section, we have used the config/2 function which is automatically generated in your endpoint. Here is a summary of all the functions that are automatically defined in your endpoint.

Paths and URLs

  • url() - generates the endpoint base URL without any path information
  • static_url() - generates the static URL without any path information

  • struct_url() - generates the endpoint base URL but as a URI struct

  • path(path) - generates the path information when routing to this endpoint
  • static_path(path) - generates a route to a static file in priv/static

Channels

  • subscribe(pid, topic, opts) - subscribes the pid to the given topic. See Phoenix.PubSub.subscribe/4 for options.

  • unsubscribe(pid, topic) - unsubscribes the pid from the given topic.

  • broadcast(topic, event, msg) - broadcasts a msg with as event in the given topic.

  • broadcast!(topic, event, msg) - broadcasts a msg with as event in the given topic. Raises in case of failures.

  • broadcast_from(from, topic, event, msg) - broadcasts a msg from the given from as event in the given topic.

  • broadcast_from!(from, topic, event, msg) - broadcasts a msg from the given from as event in the given topic. Raises in case of failures.

Endpoint configuration

  • start_link() - starts the Endpoint supervision tree, including its configuration cache and possibly the servers for handling requests
  • config(key, default) - access the endpoint configuration given by key
  • config_change(changed, removed) - reload the endpoint configuration on application upgrades

Plug API

  • init(opts) - invoked when starting the endpoint server
  • call(conn, opts) - invoked on every request (simply dispatches to the defined plug pipeline)

Instrumentation API

  • instrument(event, runtime_metadata \ nil, function) - read more about instrumentation in the “Instrumentation” section

Instrumentation

Phoenix supports instrumentation through an extensible API. Each endpoint defines an instrument/3 macro that both users and Phoenix internals can call to instrument generic events. This macro is responsible for measuring the time it takes for the event to happen and for notifying a list of interested instrumenter modules of this measurement.

You can configure this list of instrumenter modules in the compile-time configuration of your endpoint. (see the :instrumenters option above). The way these modules express their interest in events is by exporting public functions where the name of each function is the name of an event. For example, if someone instruments the :render_view event, then each instrumenter module interested in that event will have to export render_view/3.

Callbacks cycle

The way event callbacks are called is the following.

  1. The event callback is called before the event happens (in this case, before the view is rendered). The callback is called with the following arguments:

    MyInstrumenter.render_view(:start, compile_meta, runtime_meta)

    compile_meta is a map of compile-time metadata (like the file and line where the instrumentation is being done). runtime_meta is a term that is passed on by the caller of the instrumentation. The result of this call is stored and later passed to the after callback.

  2. The event happens (in this case, the view is rendered).
  3. The event callback is called again, this time with the following arguments:

    MyInstrumenter.render_view(:stop, time_diff, start_result)

    time_diff is the time in microseconds it took for the event to happen (in this case, the view rendering time). start_result is whatever the event callback returned when called with :start as the first argument: instrumenters can use this to pass “state” from the before callback to the after callback.

Using instrumentation

Each Phoenix endpoint defines its own instrument/3 macro. This macro is called like this:

require MyApp.Endpoint
MyApp.Endpoint.instrument :render_view, "index.html", fn ->
  # actual view rendering
end

All the instrumenter modules that export a render_view/3 function will be notified of the event so that they can perform their respective actions.

Summary

Functions

Checks if Endpoint’s web server has been configured to start

Macros

Instruments the given function using the instrumentation provided by the given endpoint

Stores a plug to be executed as part of the pipeline

Defines a mount-point for a Socket module to handle channel definitions

Functions

server?(otp_app, endpoint)

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 example MyApp.Endpoint

Exampes

iex> Phoenix.Endpoint.server?(:my_app, MyApp.Endpoint)
true

Macros

instrument(endpoint_or_conn_or_socket, event, runtime \\ Macro.escape(%{}), fun)

Instruments the given function using the instrumentation provided by the given endpoint.

To specify the endpoint that will provide instrumentation, the first argument can be:

  • a module name - the endpoint itself
  • a Plug.Conn struct - this macro will look for the endpoint module in the :private field of the connection; if it’s not there, fun will be executed with no instrumentation
  • a Phoenix.Socket struct - this macro will look for the endpoint module in the :endpoint field of the socket; if it’s not there, fun will be executed with no instrumentation

Usually, users should prefer to instrument events using the instrument/3 macro defined in every Phoenix endpoint. This macro should only be used for cases when the endpoint is dynamic and not known at compile time instead.

Examples

endpoint = MyApp.Endpoint
Phoenix.Endpoint.instrument endpoint, :render_view, fn -> ... end
plug(plug, opts \\ [])

Stores a plug to be executed as part of the pipeline.

socket(path, module)

Defines a mount-point for a Socket module to handle channel definitions.

Examples

socket "/ws", MyApp.UserSocket
socket "/ws/admin", MyApp.AdminUserSocket

By default, the given path is a websocket upgrade endpoint, with long-polling fallback. The transports can be configured within the Socket handler. See Phoenix.Socket for more information on defining socket handlers.