phoenix

1.3.1

1.8.9 1.8.8 1.8.7 1.8.6 1.8.5 1.8.4 1.8.3 1.8.2 1.8.1 1.8.0 1.8.0-rc.4 1.8.0-rc.3 1.8.0-rc.2 1.8.0-rc.1 1.8.0-rc.0 1.7.24 1.7.23 1.7.22 1.7.21 1.7.20 1.7.19 1.7.18 1.7.17 1.7.16 1.7.15 1.7.14 1.7.13 1.7.12 1.7.11 1.7.10 1.7.9 1.7.8 1.7.7 1.7.6 1.7.5 1.7.4 1.7.3 1.7.2 1.7.1 1.7.0 1.7.0-rc.3 1.7.0-rc.2 1.7.0-rc.1 1.7.0-rc.0 1.6.17 1.6.16 1.6.15 1.6.14 1.6.13 1.6.12 1.6.11 1.6.10 1.6.9 1.6.8 1.6.7 1.6.6 1.6.5 1.6.4 1.6.3 1.6.2 1.6.1 1.6.0 1.6.0-rc.1 1.6.0-rc.0 1.5.15 1.5.14 1.5.13 1.5.12 1.5.11 1.5.10 1.5.9 1.5.8 1.5.7 1.5.6 1.5.5 1.5.4 1.5.3 1.5.2 1.5.1 1.5.0 1.5.0-rc.0 1.4.18 1.4.17 1.4.16 1.4.15 1.4.14 1.4.13 1.4.12 1.4.11 1.4.10 1.4.9 1.4.8 1.4.7 1.4.6 1.4.5 1.4.4 1.4.3 1.4.2 1.4.1 1.4.0 1.4.0-rc.3 1.4.0-rc.2 1.4.0-rc.1 1.4.0-rc.0 1.3.5 1.3.4 1.3.3 1.3.2 1.3.1 1.3.0 1.3.0-rc.3 1.3.0-rc.2 1.3.0-rc.1 1.3.0-rc.0 1.2.5 1.2.4 1.2.3 1.2.2 1.2.1 1.2.0 1.2.0-rc.1 1.2.0-rc.0 1.1.9 1.1.8 1.1.7 1.1.6 1.1.5 1.1.4 1.1.3 1.1.2 1.1.1 1.1.0 1.0.6 1.0.5 1.0.4 1.0.3 1.0.2 1.0.1 1.0.0 0.17.1 0.17.0 0.16.1 0.16.0 0.15.0 0.14.0 0.13.1 0.13.0 0.12.0 0.11.0 0.10.0 0.9.0 0.8.0 0.7.2 0.7.1 0.7.0 0.6.2 0.6.1 0.6.0 0.5.0 0.4.1 0.4.0 0.3.1 0.3.0 0.2.11 0.2.10 0.2.9 0.2.8 0.2.7 0.2.6 0.2.5 0.2.4 0.2.3 0.2.2 0.2.1 0.2.0 0.1.0

Productive. Reliable. Fast. A productive web framework that does not compromise speed or maintainability.

Security advisory: This version has known vulnerabilities. View advisories

HexDocs

Current section

Files

Jump to

Readme 176 Versions 4 Dependencies Dependants 5 Advisories Files Activity

phoenix lib phoenix router route.ex

Raw

lib/phoenix/router/route.ex

defmodule Phoenix.Router.Route do
  # This module defines the Route struct that is used
  # throughout Phoenix's router. This struct is private
  # as it contains internal routing information.
  @moduledoc false

  alias Phoenix.Router.Route

  @doc """
  The `Phoenix.Router.Route` struct. It stores:

    * :verb - the HTTP verb as an upcased string
    * :line - the line the route was defined
    * :kind - the kind of route, one of `:match`, `:forward`
    * :path - the normalized path as string
    * :host - the request host or host prefix
    * :plug - the plug module
    * :opts - the plug options
    * :helper - the name of the helper as a string (may be nil)
    * :private - the private route info
    * :assigns - the route info
    * :pipe_through - the pipeline names as a list of atoms

  """

  defstruct [:verb, :line, :kind, :path, :host, :plug, :opts,
             :helper, :private, :pipe_through, :assigns]

  @type t :: %Route{}

  @doc """
  Receives the verb, path, plug, options and helper
  and returns a `Phoenix.Router.Route` struct.
  """
  @spec build(non_neg_integer, :match | :forward, String.t, String.t, String.t | nil, atom, atom, atom | nil, atom, %{}, %{}) :: t
  def build(line, kind, verb, path, host, plug, opts, helper, pipe_through, private, assigns)
      when is_atom(verb) and (is_binary(host) or is_nil(host)) and
           is_atom(plug) and (is_binary(helper) or is_nil(helper)) and
           is_list(pipe_through) and is_map(private) and is_map(assigns)
           and kind in [:match, :forward] do

    %Route{kind: kind, verb: verb, path: path, host: host, private: private,
           plug: plug, opts: opts, helper: helper,
           pipe_through: pipe_through, assigns: assigns, line: line}
  end

  @doc """
  Builds the expressions used by the route.
  """
  def exprs(route) do
    {path, binding} = build_path_and_binding(route)

    %{path: path,
      host: build_host(route.host),
      verb_match: verb_match(route.verb),
      binding: binding,
      route_match: build_route_match(route, binding)}
  end

  defp verb_match(:*), do: Macro.var(:_verb, nil)
  defp verb_match(verb), do: verb |> to_string() |> String.upcase()

  defp build_path_and_binding(%Route{path: path} = route) do
    {params, segments} = case route.kind do
      :forward -> Plug.Router.Utils.build_path_match(path <> "/*_forward_path_info")
      :match   -> Plug.Router.Utils.build_path_match(path)
    end

    binding = for var <- params, var != :_forward_path_info do
      {Atom.to_string(var), Macro.var(var, nil)}
    end

    {segments, binding}
  end

  defp build_host(host) do
    cond do
      is_nil(host)             -> quote do: _
      String.last(host) == "." -> quote do: unquote(host) <> _
      true                     -> host
    end
  end

  defp build_route_match(route, binding) do
    dispatch_block = build_dispatch(route)
    pipes_block = build_pipes(route)
    exprs =
      [build_params(binding),
       maybe_merge(:private, route.private),
       maybe_merge(:assigns, route.assigns)]

    conn_block = {:__block__, [], Enum.filter(exprs, & &1 != nil)}

    {conn_block, pipes_block, dispatch_block}
  end

  defp build_dispatch(%Route{kind: :forward} = route) do
    {_params, fwd_segments} = Plug.Router.Utils.build_path_match(route.path)
    opts = route.opts |> route.plug.init() |> Macro.escape()

    quote do
      fn conn ->
        Phoenix.Router.Route.forward(conn, unquote(fwd_segments), unquote(route.plug), unquote(opts))
      end
    end
  end
  defp build_dispatch(%Route{} = route) do
    quote do
      fn conn ->
        # We need to store this in a variable so the compiler
        # does not see a call and then suddenly start tracking
        # changes in the controller.
        plug = unquote(route.plug)
        opts = plug.init(unquote(route.opts))
        plug.call(conn, opts)
      end
    end
  end

  defp maybe_merge(key, data) do
    if map_size(data) > 0 do
      quote do
        var!(conn) =
          update_in var!(conn).unquote(key), &Map.merge(&1, unquote(Macro.escape(data)))
      end
    end
  end

  defp build_params([]), do: nil
  defp build_params(binding) do
    quote do
      path_binding = unquote({:%{}, [], binding})
      var!(conn) =
        %Plug.Conn{var!(conn) |
                   params: Map.merge(var!(conn).params, path_binding),
                   path_params: path_binding}
    end
  end

  defp build_pipes(%Route{pipe_through: []}) do
    quote do: fn conn -> conn end
  end
  defp build_pipes(%Route{pipe_through: pipe_through}) do
    plugs = pipe_through |> Enum.reverse |> Enum.map(&{&1, [], true})
    {conn, body} = Plug.Builder.compile(__ENV__, plugs, [])

    quote do
      fn unquote(conn) ->
        unquote(conn) = Plug.Conn.put_private(unquote(conn), :phoenix_pipelines, unquote(pipe_through))
        unquote(body)
      end
    end
  end


  @doc """
  Forwards requests to another Plug at a new path.
  """
  def forward(%Plug.Conn{path_info: path, script_name: script} = conn, fwd_segments, target, opts) do
    new_path = path -- fwd_segments
    {base, ^new_path} = Enum.split(path, length(path) - length(new_path))

    conn = %Plug.Conn{conn | path_info: new_path, script_name: script ++ base} |> target.call(opts)
    %Plug.Conn{conn | path_info: path, script_name: script}
  end

  @doc """
  Validates and returns the list of forward path segments.

  Raises RuntimeError plug is already forwarded or path contains
  a dynamic segment.
  """
  def forward_path_segments(path, plug, phoenix_forwards) do
    case Plug.Router.Utils.build_path_match(path) do
      {[], path_segments} ->
        if phoenix_forwards[plug] do
          raise ArgumentError, "`#{inspect plug}` has already been forwarded to. A module can only be forwarded a single time."
        end
        path_segments
      _ ->
        raise ArgumentError, "Dynamic segment `\"#{path}\"` not allowed when forwarding. Use a static path instead."
    end
  end
end

Operator	Description	Example
name:	Match package name. Supports * wildcards and repo/package form	name:phx* or name:hexpm/phoenix
description:	Full-text search of package descriptions	description:auth
depends:	Packages depending on a given package. Supports repo:package form	depends:ecto or depends:hexpm:ecto
build_tool:	Filter by build tool	build_tool:mix
updated_after:	Packages updated after an ISO8601 datetime	updated_after:2025-01-01T00:00:00Z
extra:	Match custom metadata (key,value). Nested keys are separated by commas	extra:license,MIT