defmodule GitHub.Webhook do
  @moduledoc """
  Helpers for validating and handling webhooks dispatched by GitHub

  This module is made for Plug / Phoenix applications that wish to accept webhook requests that
  are sent from the GitHub API. Receiving these requests requires setting up a webhook or GitHub
  App, which is out of scope for this documentation.

  ## Configuration

  In order to validate that incoming webhooks are, in fact, from GitHub, it is **strongly
  advised** to set a webhook secret. This is a secret value that you generate and supply to GitHub
  in the webhook or GitHub App settings. If you are using Phoenix, an easy way to generate this
  value is by running `mix phx.gen.secret`.

  Then, supply this value to the library at runtime using the following configuration:

      config :oapi_github,
        webhook_secret: "my secret"

  It is common to use `System.fetch_env!/1` or a similar function to load this type of secret
  from environment variables. Alternatively, the webhook secret can be supplied directly to
  `verify_github_signature/2` at compile time.

  ## Usage

  If the optional dependencies `Plug` and `Plug.Crypto` are installed, this module provides
  several helpers to simplify the process of handling webhook requests. A typical webhook
  controller might look like this:

      defmodule MyAppWeb.GitHubController do
        use MyAppWeb, :controller
        import GitHub.Webhook

        plug :verify_github_event
        plug :verify_github_signature

        def webhook(conn, params) do
          # Handle the webhook...
        end
      end

  In order to perform verification of the signature, it is necessary to store the original request
  body in an assign `:raw_body` or `:body`. This usually requires implementing a custom
  `Plug.Parser` for webhook requests.

  See `verify_github_event/2` and `verify_github_signature/2` for more information.
  """

  @doc """
  Construct the value of the `:body_reader` option for `Plug.Parsers` for caching request bodies

  This function, called at compile time, creates a valid value for the `:body_reader` option in
  a call to the `Plug.Parsers` plug. Usually called in a Phoenix Endpoint, the code looks like:

      plug Plug.Parsers,
        parsers: [:json, ...],
        json_decoder: Jason,
        # ...
        body_reader: GitHub.Webhook.body_reader()

  It sets up `cache_request_body/2` as the body reader, which will in turn cache the raw request
  body as an assign `:raw_body` for use during signature verification.

  ## Options

    * `:fallback`: If using the `:routes` option below, which body reader function to call for
      requests that do not match one of the specified routes. Defaults to
      `{Plug.Conn, :read_body, []}`.

    * `:routes`: Optionally restrict the caching of request bodies to specific routes, given as
      a list of strings (ex. `["/hook/github"]`). Defaults to caching request bodies for all
      requests, which can cause a significant performance impact.

  """
  @spec body_reader(keyword) :: tuple
  def body_reader(opts \\ []) do
    {GitHub.Webhook, :cache_request_body, [[fallback: opts[:fallback], routes: opts[:routes]]]}
  end

  @doc """
  Cache request body as `:raw_body` assign for chosen connections

  This function adheres to the needs of the `:body_reader` option for the `Plug.Parsers` plug. It
  saves the raw request body as a binary to the `:raw_body` assign on the `Plug.Conn`, so that it
  can be used for signature verification later.

  This function is not usually called directly. Instead, use `body_reader/1`.
  """
  @spec cache_request_body(Plug.Conn.t(), keyword, keyword) ::
          {:ok, binary, Plug.Conn.t()} | {:error, term}
  def cache_request_body(conn, parser_opts, cache_opts)

  if Code.ensure_loaded?(Plug) do
    def cache_request_body(conn, opts, cache_opts) do
      %Plug.Conn{path_info: path_info} = conn

      fallback =
        case cache_opts[:fallback] do
          {module, function, args} when is_atom(module) and is_atom(function) and is_list(args) ->
            {module, function, args}

          nil ->
            {Plug.Conn, :read_body, []}

          _else ->
            raise ArgumentError, "Invalid value for option `:fallback`"
        end

      routes =
        case cache_opts[:routes] do
          route when is_binary(route) -> [route]
          routes when is_list(routes) -> routes
          nil -> nil
          _else -> raise ArgumentError, "Invalid value for option `:routes`"
        end

      if is_list(routes) and path_info not in Enum.map(routes, &String.split(&1, "/", trim: true)) do
        {fallback_module, fallback_function, fallback_opts} = fallback
        apply(fallback_module, fallback_function, [conn, fallback_opts])
      else
        case Plug.Conn.read_body(conn, Keyword.put(opts, :length, 25_000_000)) do
          {:ok, body, conn} ->
            conn = update_in(conn.assigns[:raw_body], &[body | &1 || []])
            {:ok, body, conn}

          {:more, _, _} ->
            {:error, "Webhook payload is too large (over 25MB)"}

          {:error, _} = err ->
            err
        end
      end
    end
  else
    def cache_request_body(conn, _opts, _cache_opts) do
      raise GitHub.Error.new(
              source: conn,
              message: """
              Plug Not Installed

              Optional dependency Plug was not installed at the
              time `GitHub.Webhook` was compiled. Please ensure
              it is installed and run:

              `mix deps.compile --force oapi_github`
              """
            )
    end
  end

  @doc """
  Get and store the GitHub webhook event type

  This function looks at the `X-GitHub-Event` header to ensure the incoming request is a webhook
  event and stores the event as a `:github_event` assign on the connection. If the header is
  missing, the connection is immediately halted with a simple error message that will appear in
  GitHub's UI.
  """
  @spec verify_github_event(Plug.Conn.t(), keyword) :: Plug.Conn.t()
  def verify_github_event(conn, opts)

  if Code.ensure_loaded?(Plug) do
    def verify_github_event(conn, _opts) do
      case Plug.Conn.get_req_header(conn, "x-github-event") do
        [event | _] ->
          Plug.Conn.assign(conn, :github_event, event)

        [] ->
          conn
          |> Plug.Conn.send_resp(:bad_Request, "Missing event header")
          |> Plug.Conn.halt()
      end
    end
  else
    def verify_github_event(conn, _opts) do
      raise GitHub.Error.new(
              source: conn,
              message: """
              Plug Not Installed

              Optional dependency Plug was not installed at the
              time `GitHub.Webhook` was compiled. Please ensure
              it is installed and run:

              `mix deps.compile --force oapi_github`
              """
            )
    end
  end

  @doc """
  Check the validity of a GitHub webhook request

  This function uses the configured `:webhook_secret` or an option `:secret` to verify the
  signature of an incoming GitHub webhook. If the signature is missing or invalid, the connection
  is immediately halted with a simple error message that will appear in GitHub's UI.

  ## Configuration

    * `:webhook_secret`: Secret given to GitHub to use when signing webhook requests. If not
      supplied via configuration nor the `:secret` option, an error is raised.

  ## Options

    * `:secret`: Compile-time secret to use as the webhook secret. If not supplied at compile time
      nor via the `:webhook_secret` configuration, an error is raised.

  """
  @spec verify_github_signature(Plug.Conn.t(), keyword) :: Plug.Conn.t()
  def verify_github_signature(conn, opts)

  if Code.ensure_loaded?(Plug) do
    def verify_github_signature(conn, opts) do
      request_body = conn.assigns[:raw_body] || conn.assigns[:body]
      secret = opts[:secret] || get_secret()
      signature = Plug.Conn.get_req_header(conn, "x-hub-signature-256") |> List.first()

      unless is_binary(request_body) or is_list(request_body) do
        raise GitHub.Error.new(
                source: conn,
                message: """
                Request Body Not Present

                In order to verify the signature of a GitHub
                webhook request, a special parser must be used.
                This plug expects the raw request body to be read
                and present on the connection as a binary
                `:raw_body` or `:body` assign.

                For more information, see the documentation for
                `GitHub.Webhook`.
                """
              )
      end

      unless is_binary(secret) do
        raise GitHub.Error.new(
                source: conn,
                message: """
                Webhook Secret Not Configured

                In order to verify the signature of a GitHub
                webhook request, a webhook secret must be
                configured or passed in as an option `:secret`
                to this plug.

                For more information, see the documentation for
                `GitHub.Webhook`.
                """
              )
      end

      hash =
        "sha256=" <>
          Base.encode16(:crypto.mac(:hmac, :sha256, secret, request_body), case: :lower)

      cond do
        is_nil(signature) ->
          conn
          |> Plug.Conn.send_resp(:bad_request, "Missing signature")
          |> Plug.Conn.halt()

        Plug.Crypto.secure_compare(hash, signature) ->
          conn

        :else ->
          conn
          |> Plug.Conn.send_resp(:unauthorized, "Invalid signature")
          |> Plug.Conn.halt()
      end
    end

    @spec get_secret :: String.t() | nil
    defp get_secret, do: Application.get_env(:oapi_github, :webhook_secret)
  else
    def verify_github_signature(conn, _opts) do
      raise GitHub.Error.new(
              source: conn,
              message: """
              Plug Not Installed

              Optional dependency Plug was not installed at the
              time `GitHub.Webhook` was compiled. Please ensure
              it is installed and run:

              `mix deps.compile --force oapi_github`
              """
            )
    end
  end
end