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 :router, 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.

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, format: "html"]

  The format is the default format when one was not set in the connection.

Runtime configuration

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

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

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

• :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 the :path one can be changed at runtime. Defaults to:

  [host: "localhost", path: "/"]

  The :port options 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.

• :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, :adapter, and options which starts the adapter in the endpoint’s supervision tree. If no name is provided, the name is inflected from the endpoint module. Defaults to:

  [adapter: Phoenix.PubSub.PG2]

  with advanced adapter configuration:

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

• :transports - configuration for the channel transport. Check the transport modules for transport specific options. A list of allowed origins can be specified in the :origins key to restrict clients based on the given Origin header.

  [origins: ["//example.com", "http://example.com",
             "https://example.com:8080"]]

  If no such header is sent no verification will be performed. If the Origin header does not match the list of allowed origins a 403 Forbidden response will be sent to the client.

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(path) - returns the URL for this endpoint with the given path
• static_path(path) - returns the static path for a given asset

Channels

• broadcast_from(from, topic, event, msg) - proxy to Phoenix.Channel.broadcast_from/4 using this endpoint’s configured pubsub server
• broadcast_from!(from, topic, event, msg) - proxies to Phoenix.Channel.broadcast_from!/4 using this endpoint’s configured pubsub server
• broadcast(topic, event, msg) - proxies to Phoenix.Channel.broadcast/3 using this endpoint’s configured pubsub server
• broadcast!(topic, event, msg) - proxies to Phoenix.Channel.broadcast!/3 using this endpoint’s configured pubsub server

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)