combo

defmodule Combo.Endpoint do
  @moduledoc ~S"""
  Defines an endpoint.

  The endpoint is the boundary where all requests to a web application start.
  It is also the interface of the underlying web servers.

  Overall, an endpoint has three responsibilities:

    * to define an initial plug pipeline for requests to pass through

    * to provide a wrapper for starting and stopping the endpoint as part
      of a supervision tree

    * to host configuration for your web application

  ## Endpoints

  An endpoint is a module defined with the help of `Combo.Endpoint`.

      defmodule Demo.Web.Endpoint do
        use Combo.Endpoint, otp_app: :your_app

        # plug ...
        # plug ...

        plug Demo.Web.Router
      end

  Endpoints can be added to the supervision tree as following:

      children = [
        Demo.Web.Endpoint
      ]

  ## Endpoint configuration

  Endpoints are configured in your application environment. For example:

      config :demo, Demo.Web.Endpoint,
        secret_key_base: "kjoy3o1zeidquwy1398juxzldjlksahdk3"

  Endpoint configuration is split into two categories:

    * Compile-time configuration
    * Runtime configuretion

  Compile-time configuration means the configuration is read during
  compilation and changing it at runtime has no effect.

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

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

  ### Compile-time configuration

  The configuration below may be set on `config/dev.exs`, `config/prod.exs`
  and so on, but has no effect on `config/runtime.exs`.

    * `:code_reloader` - when `true`, enables code reloading functionality.
      For the list of code reloader configuration options see
      `Combo.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 configuration so code reloading is enabled in
      only one of the apps or set the `MIX_BUILD_PATH` system environment
      variable to give them distinct build directories.

    * `:live_reloader` - the configuration of `Combo.LiveReloader`.

    * `:process_limit` - limits the number of processes. It can be a
      `pos_integer()` or `:infinity`. Default to `:infinity`.
      This configuration will be used for settings:

        * the number of acceptors spawned for web server.
        * the number of supervisors spawned for `socket/3`.

      It would be useful when inspecting the hierarchical structure of
      processes. In order to ensure optimal performance, Combo dynamically
      adjusts the number of processes according to the hardware specifications.
      This is good. However, in development, this can be troublesome. For
      example, when using `:observer` on a powerful machine, you may see a large
      number of processes, making it difficult to get an overall view of the
      hierarchical structure of processes. This configuration helps address
      above troublesome.

    * `: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`.

    * `: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 sets the "strict-transport-security" header in HTTPS
      requests, forcing browsers to always use HTTPS. If an unsafe HTTP request
      is sent, it redirects to the HTTPS version using the `:host` specified in
      the `:url` configuration. To dynamically redirect to the `host` of the
      current request, set `:host` in the `:force_ssl` configuration to `nil`.

  ### Runtime configuration

  The configuration below may be set on `config/dev.exs`, `config/prod.exs`
  and so on, as well as on `config/runtime.exs`.

  Typically, if you need to configure them with system environment variables,
  you set them in `config/runtime.exs`. These options may also be set when
  starting the endpoint in your supervision tree, such as
  `{Demo.Web.Endpoint, opts}`.

    * `:adapter` - which web server 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 generated by
      `mix combo.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 from the file
      specified by the `:cache_static_manifest` option on boot. However, if you
      have your own static handling mechanism, you may want to set this value
      explicitly.

    * `:cache_static_manifest_skip_vsn` - when `true`, skips the appended query
      string "?vsn=d" when generating paths to static assets. This query string
      is used by `Plug.Static` to set long expiry dates, therefore, you should
      set this option to `true` only if you are not using `Plug.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` to `mix combo.digest`.
      Defaults to `false`.

    * `:check_origin` - configure the `:check_origin` option for transports.
      See `socket/3` for options. Defaults to `true`.

    * `: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 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 combo.serve` task
      automatically sets this to `true`.

    * `:url` - a keyword list for generating URLs. Accepts the `:scheme`,
      `:host`, `:path` and `:port` options. All option except `:path` can be
      changed at runtime. Defaults to:

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

      The `:scheme` option accepts `"http"` and `"https"` values. Default value
      is inferred from top level `:http` or `:https` option. It is useful when
      hosting your web application behind a load balancer or reverse proxy and
      terminating SSL there.

      The `:host` option requires a string.

      The `:port` option requires either an integer or a string.

      The `:path` option requires a string. It can be used to override root
      path. It's useful when hosting your web application behind a reverse
      proxy with URL rewrite rules.

    * `:static_url` - a keyword list for generating URLs for static files.
      It will fallback to `:url` option if not set. Accepts the same value
      as `:url` option.

    * `:watchers` - a set of watchers to run alongside the server. It expects
      a list of tuples containing the executable and its arguments.
      Only when the server is enabled, or `mix combo.serve` runs, watchers
      will run. For example, the watcher below will run the "watch" mode of
      the webpack when the server starts. You can configure it to whatever
      build tool or command you want:

          [
            npx: [
              "webpack",
              "--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: [{"BUILD_MODE", "debug"}]]]

      A watcher can also be an MFA that will be invoked accordingly:

          [another: {Mod, :fun, [arg1, arg2]}]

      When `false`, watchers can be disabled.

    * `: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/(?!uploads/).*(js|css|png|jpeg|jpg|gif|svg)$",
              ~r"lib/demo/web/.*(ex)$",
              ~r"lib/demo/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 your application. For example, if your 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. For example:

          [
            formats: [html: Demo.Web.ErrorHTML, json: Demo.Web.ErrorJSON],
            layout: false,
            log: :debug
          ]

    * `:log_access_url` - log the access url once the server boots.

  Note that you can also store your own configurations in the `Combo.Endpoint`.

  ### Adapter configuration

  Combo allows you to choose which web server adapter to use.

  Applications generated via `combo_new` uses `Combo.Endpoint.BanditAdapter`.
  If not otherwise specified via the `:adapter` option, Combo will fall back
  to use `Combo.Endpoint.Cowboy2Adapter`.

  Both adapters can be configured in a similar manner using the following two
  top-level options:

    * `:http` - the configuration for the HTTP server. It accepts all options
      as defined by either [`Bandit`](https://hexdocs.pm/bandit/Bandit.html#t:options/0)
      or [`Plug.Cowboy`](https://hexdocs.pm/plug_cowboy/) depending on your
      choice of adapter. Defaults to `false`.

    * `:https` - the configuration for the HTTPS server. It accepts all options
      as defined by either [`Bandit`](https://hexdocs.pm/bandit/Bandit.html#t:options/0)
      or [`Plug.Cowboy`](https://hexdocs.pm/plug_cowboy/) depending on your
      choice of adapter. Defaults to `false`.

  In addition, the connection draining can be configured for the Cowboy web
  server via the following top-level option (this is not required for Bandit
  as it has connection draining built-in):

    * `:drainer` - a drainer process waits for any on-going request to finish
      during application shutdown. It accepts the `:shutdown` and
      `:check_interval` options as defined by `Plug.Cowboy.Drainer`.
      Note the draining does not terminate any existing connection, it simply
      waits for them to finish. Socket connections run their own drainer
      before this one is invoked. That's because sockets are stateful and
      can be gracefully notified, which allows us to stagger them over a
      longer period of time. See the documentation for `socket/3` for more
      information

  ## Endpoint API

  Here's a list of all the functions that are generated in your endpoint:

    * for configuration: `c:start_link/1`, `c:config/2`, and `c:config_change/2`

    * for handling paths and URLs: `c:struct_url/0`, `c:url/0`, `c:path/1`,
      `c:static_url/0`,`c:static_path/1`, and `c:static_integrity/1`

    * for gathering runtime information about the address and port the
      endpoint is running on: `c:server_info/1`

    * for broadcasting to channels: `c:broadcast/3`, `c:broadcast!/3`,
      `c:broadcast_from/4`, `c:broadcast_from!/4`, `c:local_broadcast/3`,
      and `c:local_broadcast_from/4`

    * as required by the `Plug` behaviour: `c:Plug.init/1` and `c:Plug.call/2`

  """

  @type topic :: String.t()
  @type event :: String.t()
  @type msg :: map | {:binary, binary}

  require Logger

  # Configuration

  @doc """
  Starts the endpoint supervision tree.

  Starts endpoint's configuration cache and possibly the servers for handling
  requests.
  """
  @callback start_link(opts :: keyword()) :: Supervisor.on_start()

  @doc """
  Access the endpoint configuration given by key.
  """
  @callback config(key :: atom(), default :: term()) :: term()

  @doc """
  Reload the endpoint configuration on application upgrades.
  """
  @callback config_change(changed :: term(), removed :: term()) :: term()

  # Paths and URLs

  @doc """
  Generates the endpoint base URL, but as a `URI` struct.
  """
  @callback struct_url() :: URI.t()

  @doc """
  Generates the endpoint base URL without any path information.
  """
  @callback url() :: String.t()

  @doc """
  Generates the path information when routing to this endpoint.
  """
  @callback path(path :: String.t()) :: String.t()

  @doc """
  Generates the static URL without any path information.
  """
  @callback static_url() :: String.t()

  @doc """
  Generates a route to a static file in `priv/static`.
  """
  @callback static_path(path :: String.t()) :: String.t()

  @doc """
  Generates an integrity hash to a static file in `priv/static`.
  """
  @callback static_integrity(path :: String.t()) :: String.t() | nil

  @doc """
  Generates a two item tuple containing the `static_path` and `static_integrity`.
  """
  @callback static_lookup(path :: String.t()) :: {String.t(), String.t()} | {String.t(), nil}

  @doc """
  Returns the script name from the :url configuration.
  """
  @callback script_name() :: [String.t()]

  @doc """
  Returns the host from the :url configuration.
  """
  @callback host() :: String.t()

  # Server information

  @doc """
  Returns the address and port that the server is running on
  """
  @callback server_info(Plug.Conn.scheme()) ::
              {:ok, {:inet.ip_address(), :inet.port_number()} | :inet.returned_non_ip_address()}
              | {:error, term()}

  # Channels

  @doc """
  Subscribes the caller to the given topic.

  See `Phoenix.PubSub.subscribe/3` for options.
  """
  @callback subscribe(topic, opts :: keyword()) :: :ok | {:error, term()}

  @doc """
  Unsubscribes the caller from the given topic.
  """
  @callback unsubscribe(topic) :: :ok | {:error, term()}

  @doc """
  Broadcasts a `msg` as `event` in the given `topic` to all nodes.
  """
  @callback broadcast(topic, event, msg) :: :ok | {:error, term()}

  @doc """
  Broadcasts a `msg` as `event` in the given `topic` to all nodes.

  Raises in case of failures.
  """
  @callback broadcast!(topic, event, msg) :: :ok

  @doc """
  Broadcasts a `msg` from the given `from` as `event` in the given `topic` to all nodes.
  """
  @callback broadcast_from(from :: pid(), topic, event, msg) :: :ok | {:error, term()}

  @doc """
  Broadcasts a `msg` from the given `from` as `event` in the given `topic` to all nodes.

  Raises in case of failures.
  """
  @callback broadcast_from!(from :: pid(), topic, event, msg) :: :ok

  @doc """
  Broadcasts a `msg` as `event` in the given `topic` within the current node.
  """
  @callback local_broadcast(topic, event, msg) :: :ok

  @doc """
  Broadcasts a `msg` from the given `from` as `event` in the given `topic` within the current node.
  """
  @callback local_broadcast_from(from :: pid(), topic, event, msg) :: :ok

  @doc false
  defmacro __using__(opts) do
    quote do
      @behaviour Combo.Endpoint

      unquote(config(opts))
      unquote(pubsub())
      unquote(plug())
      unquote(server())
    end
  end

  defp config(opts) do
    quote do
      @otp_app unquote(opts)[:otp_app] || raise("endpoint expects :otp_app to be given")

      # Compile-time configuration checking
      # This ensures that, if a compile-time configuration is overwritten at runtime,
      # the application won't boot.
      var!(live_reloading?) = !!Application.compile_env(@otp_app, [__MODULE__, :live_reloader])
      var!(code_reloading?) = !!Application.compile_env(@otp_app, [__MODULE__, :code_reloader])

      process_limit = Application.compile_env(@otp_app, [__MODULE__, :process_limit], :infinity)
      var!(process_limiting?) = process_limit != :infinity

      var!(debug_errors?) = Application.compile_env(@otp_app, [__MODULE__, :debug_errors], false)
      var!(force_ssl) = Application.compile_env(@otp_app, [__MODULE__, :force_ssl])

      # Configurations exposed as module attributes
      Module.put_attribute(__MODULE__, :combo_process_limit, process_limit)

      # Avoid unused variable warnings
      _ = var!(live_reloading?)
      _ = var!(code_reloading?)
      _ = var!(process_limiting?)
      _ = var!(force_ssl)
    end
  end

  defp pubsub() do
    quote do
      def subscribe(topic, opts \\ []) when is_binary(topic) do
        Phoenix.PubSub.subscribe(pubsub_server!(), topic, opts)
      end

      def unsubscribe(topic) do
        Phoenix.PubSub.unsubscribe(pubsub_server!(), topic)
      end

      def broadcast_from(from, topic, event, msg) do
        Combo.Channel.Server.broadcast_from(pubsub_server!(), from, topic, event, msg)
      end

      def broadcast_from!(from, topic, event, msg) do
        Combo.Channel.Server.broadcast_from!(pubsub_server!(), from, topic, event, msg)
      end

      def broadcast(topic, event, msg) do
        Combo.Channel.Server.broadcast(pubsub_server!(), topic, event, msg)
      end

      def broadcast!(topic, event, msg) do
        Combo.Channel.Server.broadcast!(pubsub_server!(), topic, event, msg)
      end

      def local_broadcast(topic, event, msg) do
        Combo.Channel.Server.local_broadcast(pubsub_server!(), topic, event, msg)
      end

      def local_broadcast_from(from, topic, event, msg) do
        Combo.Channel.Server.local_broadcast_from(pubsub_server!(), from, topic, event, msg)
      end

      defp pubsub_server! do
        config(:pubsub_server) ||
          raise ArgumentError, "no :pubsub_server configured for #{inspect(__MODULE__)}"
      end
    end
  end

  defp plug() do
    quote location: :keep do
      use Plug.Builder, init_mode: Combo.plug_init_mode()
      import Combo.Endpoint

      Module.register_attribute(__MODULE__, :combo_sockets, accumulate: true)

      if force_ssl = Combo.Endpoint.__force_ssl__(__MODULE__, var!(force_ssl)) do
        plug Plug.SSL, force_ssl
      end

      if var!(debug_errors?) do
        use Plug.Debugger,
          otp_app: @otp_app,
          banner: {Combo.Endpoint.RenderErrors, :__debugger_banner__, []},
          style: [
            primary: "#D00000",
            logo: nil,
            dark: [
              primary: "#FF5F59",
              logo: nil
            ]
          ]
      end

      plug :socket_dispatch

      # Compile after the debugger so we properly wrap it.
      @before_compile Combo.Endpoint
    end
  end

  defp server() do
    quote location: :keep, unquote: false do
      @doc """
      Returns the child specification to start the endpoint
      under a supervision tree.
      """
      def child_spec(opts) do
        %{
          id: __MODULE__,
          start: {__MODULE__, :start_link, [opts]},
          type: :supervisor
        }
      end

      @doc """
      Starts the endpoint supervision tree.

      All other options are merged into the endpoint configuration.
      """
      def start_link(opts \\ []) do
        Combo.Endpoint.Supervisor.start_link(@otp_app, __MODULE__, opts)
      end

      @doc """
      Returns the endpoint configuration for `key`.

      Returns `default` if the key does not exist.
      """
      def config(key, default \\ nil) do
        case :ets.lookup(__MODULE__, key) do
          [{^key, val}] -> val
          [] -> default
        end
      end

      @doc """
      Reloads the configuration given the application environment changes.
      """
      def config_change(changed, removed) do
        Combo.Endpoint.Supervisor.config_change(__MODULE__, changed, removed)
      end

      defp persistent!() do
        :persistent_term.get({Combo.Endpoint, __MODULE__}, nil) ||
          raise "could not find persistent term for endpoint #{inspect(__MODULE__)}. Make sure your endpoint is started and note you cannot access endpoint functions at compile-time"
      end

      @doc """
      Generates the endpoint base URL without any path information.

      It uses the configuration under `:url` to generate such.
      """
      def url, do: persistent!().url

      @doc """
      Generates the static URL without any path information.

      It uses the configuration under `:static_url` to generate
      such. It falls back to `:url` if `:static_url` is not set.
      """
      def static_url, do: persistent!().static_url

      @doc """
      Generates the endpoint base URL but as a `URI` struct.

      It uses the configuration under `:url` to generate such.
      Useful for manipulating the URL data and passing it to
      URL helpers.
      """
      def struct_url, do: persistent!().struct_url

      @doc """
      Returns the host for the given endpoint.
      """
      def host, do: persistent!().host

      @doc """
      Generates the path information when routing to this endpoint.
      """
      def path(path), do: persistent!().path <> path

      @doc """
      Generates the script name.
      """
      def script_name, do: persistent!().script_name

      @doc """
      Generates a route to a static file in `priv/static`.
      """
      def static_path(path) do
        prefix = persistent!().static_path

        case :binary.split(path, "#") do
          [path, fragment] -> prefix <> elem(static_lookup(path), 0) <> "#" <> fragment
          [path] -> prefix <> elem(static_lookup(path), 0)
        end
      end

      @doc """
      Generates a base64-encoded cryptographic hash (sha512) to a static file
      in `priv/static`. Meant to be used for Subresource Integrity with CDNs.
      """
      def static_integrity(path), do: elem(static_lookup(path), 1)

      @doc """
      Returns a two item tuple with the first item being the `static_path`
      and the second item being the `static_integrity`.
      """
      def static_lookup(path) do
        Combo.Config.cache(
          __MODULE__,
          {:__combo_static__, path},
          &Combo.Endpoint.Supervisor.static_lookup(&1, path)
        )
      end

      @doc """
      Returns the address and port that the server is running on.
      """
      def server_info(scheme), do: config(:adapter).server_info(__MODULE__, scheme)
    end
  end

  @doc false
  def __force_ssl__(module, force_ssl) do
    if force_ssl do
      Keyword.put_new(force_ssl, :host, {module, :host, []})
    end
  end

  @doc false
  defmacro __before_compile__(%{module: module}) do
    sockets = Module.get_attribute(module, :combo_sockets)
    process_limit = Module.get_attribute(module, :combo_process_limit)

    sockets =
      for {path, socket, socket_opts} <- sockets do
        socket_opts = put_socket_process_limit_opts(socket_opts, process_limit)
        {path, socket, socket_opts}
      end

    dispatches =
      for {path, socket, socket_opts} <- sockets,
          {path, plug, conn_ast, plug_opts} <- socket_paths(module, path, socket, socket_opts) do
        quote do
          defp do_socket_dispatch(unquote(path), conn) do
            halt(unquote(plug).call(unquote(conn_ast), unquote(Macro.escape(plug_opts))))
          end
        end
      end

    quote do
      defoverridable call: 2

      # Inline render errors so we set the endpoint before calling it.
      def call(conn, opts) do
        conn = %{conn | script_name: script_name(), secret_key_base: config(:secret_key_base)}
        conn = Plug.Conn.put_private(conn, :combo_endpoint, __MODULE__)

        try do
          super(conn, opts)
        rescue
          e in Plug.Conn.WrapperError ->
            %{conn: conn, kind: kind, reason: reason, stack: stack} = e

            Combo.Endpoint.RenderErrors.__catch__(
              conn,
              kind,
              reason,
              stack,
              config(:render_errors)
            )
        catch
          kind, reason ->
            stack = __STACKTRACE__

            Combo.Endpoint.RenderErrors.__catch__(
              conn,
              kind,
              reason,
              stack,
              config(:render_errors)
            )
        end
      end

      @doc false
      def __sockets__, do: unquote(Macro.escape(sockets))

      @doc false
      def socket_dispatch(%{path_info: path} = conn, _opts), do: do_socket_dispatch(path, conn)
      unquote(dispatches)
      defp do_socket_dispatch(_path, conn), do: conn
    end
  end

  defp put_socket_process_limit_opts(opts, :infinity), do: opts

  defp put_socket_process_limit_opts(opts, limit) do
    if Keyword.has_key?(opts, :partitions),
      do: opts,
      else: Keyword.put(opts, :partitions, limit)
  end

  defp socket_paths(endpoint, path, socket, opts) do
    paths = []

    common_config = [
      :path,
      :serializer,
      :transport_log,
      :check_origin,
      :check_csrf,
      :code_reloader,
      :connect_info,
      :auth_token,
      :log
    ]

    websocket =
      opts
      |> Keyword.get(:websocket, true)
      |> maybe_validate_keys(
        common_config ++
          [
            :timeout,
            :max_frame_size,
            :fullsweep_after,
            :compress,
            :subprotocols,
            :error_handler
          ]
      )

    longpoll =
      opts
      |> Keyword.get(:longpoll, true)
      |> maybe_validate_keys(
        common_config ++
          [
            :window_ms,
            :pubsub_timeout_ms,
            :crypto
          ]
      )

    paths =
      if websocket do
        websocket = put_auth_token(websocket, opts[:auth_token])
        config = Combo.Socket.Transport.load_config(websocket, Combo.Transports.WebSocket)
        plug_init = {endpoint, socket, config}
        {conn_ast, match_path} = socket_path(path, config)
        [{match_path, Combo.Transports.WebSocket, conn_ast, plug_init} | paths]
      else
        paths
      end

    paths =
      if longpoll do
        longpoll = put_auth_token(longpoll, opts[:auth_token])
        config = Combo.Socket.Transport.load_config(longpoll, Combo.Transports.LongPoll)
        plug_init = {endpoint, socket, config}
        {conn_ast, match_path} = socket_path(path, config)
        [{match_path, Combo.Transports.LongPoll, conn_ast, plug_init} | paths]
      else
        paths
      end

    paths
  end

  defp put_auth_token(true, enabled), do: [auth_token: enabled]
  defp put_auth_token(opts, enabled), do: Keyword.put(opts, :auth_token, enabled)

  defp socket_path(path, config) do
    end_path_fragment = Keyword.fetch!(config, :path)

    {vars, path} =
      String.split(path <> "/" <> end_path_fragment, "/", trim: true)
      |> Enum.join("/")
      |> Plug.Router.Utils.build_path_match()

    conn_ast =
      if vars == [] do
        quote do
          conn
        end
      else
        params =
          for var <- vars,
              param = Atom.to_string(var),
              not match?("_" <> _, param),
              do: {param, Macro.var(var, nil)}

        quote do
          params = %{unquote_splicing(params)}
          %{conn | path_params: params, params: params}
        end
      end

    {conn_ast, path}
  end

  defp maybe_validate_keys(opts, keys) when is_list(opts), do: Keyword.validate!(opts, keys)
  defp maybe_validate_keys(other, _), do: other

  ## API

  @doc """
  Defines a websocket/longpoll mount-point for a `socket`.

  It expects a `path`, a `socket` module, and a set of options.
  The socket module is typically defined with `Combo.Socket`.

  Both websocket and longpolling connections are supported out of the box.

  ## Options

    * `:websocket` - controls the websocket configuration.
      May be a boolean or a keyword list of options.
      See ["Common configuration"](#socket/3-common-configuration)
      and ["WebSocket configuration"](#socket/3-websocket-configuration)
      for the whole list.
      Defaults to `true`.

    * `:longpoll` - controls the longpoll configuration.
      May be a boolean or a keyword list of options.
      of options. See ["Common configuration"](#socket/3-common-configuration)
      and ["Longpoll configuration"](#socket/3-longpoll-configuration)
      for the whole list.
      Defaults to `false`.

    * `:drainer` - a keyword list or an MFA function returning a keyword list.
      For example, `{Demo.Web.Socket, :drainer_configuration, []}` configuring
      how to drain sockets on application shutdown. The goal is to notify all
      channels clients to reconnect. The supported options are:

      * `:batch_size` - the amount of clients to notify at once in a given
        batch. Defaults to `10000`.
      * `:batch_interval` - the amount of time in milliseconds given for a
        batch to terminate. Defaults to `2000`ms.
      * `:shutdown` - the maximum amount of time in milliseconds allowed to
        drain all batches. Defaults to `30000`ms.
      * `:log` - the log level for drain actions. Defaults the `:log` option
        passed to `use Combo.Socket` or `:info`. Set it to `false` to disable
        logging.

      For example, if you have 150k connections, the default values will split
      them into 15 batches of 10k connections. Each batch takes 2000ms before
      the next batch starts. In this case, we will do everything right under
      the maximum shutdown time of 30000ms. Therefore, as you increase the
      number of connections, remember to adjust the shutdown accordingly.
      Finally, after the socket drainer runs, the lower level HTTP/HTTPS
      connection drainer will still run, and apply to all connections.
      Set it to `false` to disable draining.

    * `:auth_token` - a boolean that enables the use of the channels client's
      `auth_token` option. The exact token exchange mechanism depends on the
      transport:

        * the websocket transport, this enables a token to be passed through
          the `Sec-WebSocket-Protocol` header.
        * the longpoll transport, this allows the token to be passed through
          the `Authorization` header.

      The token is available in the `connect_info` as `:auth_token`.

      Custom transports might implement their own mechanism.

  You can also pass the options below on `use Combo.Socket`.
  The values specified here override the value in `use Combo.Socket`.

  ## Examples

      socket "/ws", Demo.Web.UserSocket

      socket "/ws/admin", Demo.Web.AdminUserSocket,
        longpoll: true,
        websocket: [compress: true]

  ## 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", Demo.Web.UserSocket,
        websocket: [path: "/project/:project_id"]

  ## Common configuration

  The configuration below can be given to both `:websocket` and `:longpoll`
  options:

    * `:path` - the path to use for the transport. Default to the transport
      name (`"/websocket"` or `"/longpoll"`).

    * `:serializer` - a list of serializers for messages. See `Combo.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 the `origin` header is present. May be a boolean, a list of URIs
      that are allowed, or a function provided as an MFA.
      Defaults to `:check_origin` setting at endpoint configuration.

      If `true`, the header is checked against `:host` in
      `Demo.Web.Endpoint.config(:url)[:host]`.

      If `false` and you do not validate the session in your socket, 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 the `origin` header, such as mobile apps.

      You can also specify a list of explicitly allowed origins. Each origin may include
      scheme, host, and port. 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 function provided as an MFA:

          check_origin: {Demo.Web.Auth, :check_origin?, []}

      The MFA is invoked with the request `%URI{}` as the first argument,
      followed by arguments in the MFA, and must return a boolean.

    * `:check_csrf` - if the transport should perform CSRF check. To avoid
      "Cross-Site WebSocket Hijacking", you must have at least one of
      `check_origin` and `check_csrf` enabled. If you set both to `false`,
      Combo will raise, but it is still possible to disable both by passing
      an MFA to `check_origin`. In such cases, it is your responsibility to
      ensure at least one of them is enabled. Defaults to `true`.

    * `: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 socket `connect/3` callback.
      See the "Connect info" subsection for valid keys.

  ### Connect info

  The valid keys are:

    * `:peer_data` - the result of `Plug.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](https://www.w3.org/TR/trace-context-1/).
      These headers are necessary for libraries such as [OpenTelemetry](https://opentelemetry.io/)
      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 from `Plug.Conn`.
      The `session_config` is typically an exact copy of the arguments given
      to `Plug.Session`. In order to validate the session, the "_csrf_token"
      must be given as request parameter when connecting the socket with the
      value of `URI.encode_www_form(Plug.CSRFProtection.get_csrf_token())`.
      The CSRF token request parameter can be modified via the `:csrf_token_key`
      option.

      Additionally, `session_config` may be an MFA, such as
      `{Demo.Web.Auth, :get_session_config, []}`, to allow loading config in
      runtime.

  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", Demo.Web.UserSocket,
        websocket: [
          connect_info: [:peer_data, :trace_context_headers, :x_headers, :uri, session: [store: :cookie]]
        ]

  With arbitrary keywords:

      socket "/socket", Demo.Web.UserSocket,
        websocket: [
          connect_info: [:uri, custom_value: "abcdef"]
        ]

  > #### Where are my headers? {: .tip}
  >
  > Combo only gives you limited access to the connection headers for security
  > reasons. WebSockets are cross-domain, which means that, when a user "John Doe"
  > visits a malicious website, the malicious website can open up a WebSocket
  > connection to your application, and the browser will gladly submit John Doe's
  > authentication/cookie information. If you were to accept this information as is,
  > the malicious website would have full control of a WebSocket connection to your
  > application, authenticated on John Doe's behalf.
  >
  > To safe-guard your application, Combo limits and validates the connection
  > information your socket can access. This means your application is safe from
  > these attacks, but you can't access cookies and other headers in your socket.
  > You may access the session stored in the connection via the `:connect_info`
  > option, provided you also pass a csrf token when connecting over WebSocket.

  ## 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_000`ms.

    * `: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 to `0` 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 handshake `Sec-WebSocket-Protocol` response header.
      Defaults to `nil`.

      For example:

          subprotocols: ["sip", "mqtt"]

    * `:error_handler` - custom error handler for connection errors.
      If `c:Combo.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 an MFA tuple that receives a `Plug.Conn`, the
      error reason, and returns a `Plug.Conn` with a response. For example:

          socket "/socket", Demo.Web.Socket,
            websocket: [
              error_handler: {Demo.Web.Socket, :handle_error, []}
            ]

      and a `{:error, :rate_limit}` return may be handled on `Demo.Web.Socket` as:

          def handle_error(conn, :rate_limit),
            do: Plug.Conn.send_resp(conn, 429, "Too many requests")

  ## 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 to `10_000`.

    * `:pubsub_timeout_ms` - how long a request can wait for the
      pubsub layer to respond in milliseconds (ms). Defaults to `2000`.

    * `:crypto` - options for verifying and signing the token, accepted
      by `Combo.Token`. By default tokens are valid for 2 weeks.

  """
  defmacro socket(path, module, opts \\ []) do
    module = Macro.expand(module, %{__CALLER__ | function: {:socket_dispatch, 2}})

    quote do
      @combo_sockets {unquote(path), unquote(module), unquote(opts)}
    end
  end

  @doc """
  Checks if Endpoint's web server has been configured to start.

    * `otp_app` - The OTP app running the endpoint, such as `:my_app`.
    * `endpoint` - The endpoint module, such as `MyAppWeb.Endpoint`.

  ## Examples

      iex> Combo.Endpoint.server?(:demo, Demo.Web.Endpoint)
      true

  """
  def server?(otp_app, endpoint) when is_atom(otp_app) and is_atom(endpoint) do
    Combo.Endpoint.Supervisor.server?(otp_app, endpoint)
  end
end