defmodule Apical do
  @moduledoc """
  Generates a web router from an OpenAPI document.

  Building an OpenAPI-compliant Phoenix router can be as simple as:

  ```elixir
  defmodule MyRouter do
    require Apical

    Apical.router_from_file(
      "path/to/openapi.yaml",
      controller: MyProjectWeb.ApiController
    )
  end
  ```

  See https://spec.openapis.org/oas/v3.1.0 for details on how to compose an OpenAPI
  schema.

  Using the macros `router_from_string/2` or `router_from_file/2` you may generate a
  `Phoenix.Router` that corresponds to OpenAPI document.

  > ### Tip {: .tip }
  >
  > In general, using `router_from_file/2` is should be preferred, especially if you
  > must maintain multiple versions of the schema, though you may find it easier to
  > iterate using `router_from_string/2` during early development.  In that case, it
  > is possible to switch to `router_from_file/2` when you are ready to finalize your
  > API design or start versioning

  > ### Plug routers {: .info }
  >
  > `Plug`-only routers, which do not require `Phoenix`, are planned for a future release.

  The following activities are performed by the router generated by the macros:

  - Tagging inbound requests with API version
  - Constructing route and http verb matches in the router
  - Parameter operations
    - Supports:
      - Cookie parameters
      - Header parameters
      - Path parameters
      - Query parameters
    - Features:
      - Style decoding based on parameter styles (see https://spec.openapis.org/oas/v3.1.0#style-values)
      - Custom style decoding
      - Parameter marshalling (converting strings to types)
      - Parameter validation
  - Request body validation
    - content-length and content-type validation
    - matching content-type with request body plugs
    - Automatic json and `form-encoded` request body parsing
    - Parameter marshalling for `form-encoded` requests

  ### Options

  The following options are common to `router_from_string/2` and `router_from_file/2`.

  #### Global options
  - `encoding`: mimetype which describes how the schema is encoded.

    required in `router_from_string/2`, deduced from filename in `router_from_file/2`.

  - `decoders`:  A proplist of mimetype to decoders.

    If you use an encoding that isn't `application/json` or `application/yaml` you
    should provide this proplist, which, at a minimum, contains
    `[{encoding_mimetype, {module, function}}]`.  The call `module.function(string)`
    should return a map representing the OpenAPI schema, and should raise in the
    case that the content is not decodable.

  - `root`: the root path for the router.

    Defaults to `/v{major}` where `major` is the major version of the API, as declared
    under `info.version` in the schema.

  - `dump`: (For debugging), sends formatted code of the router to stdout.

    Defaults to `false`.  If set to `:all`, will also pass `dump: true` to Exonerate.

  #### Scopable options

  The following options are *scopable*.  They may be placed as top-level options
  or under the scopes (see below)

  - `controller`:  Plug module which contains code implementing the API.

    It is recommended to `use Phoenix.Controller` in this plug module, or the
    functions may or may not be targetted as expected.

    Controller modules should implement public functions corresponding to the
    `operationId` of each operation in the schema.  These functions must be
    cased in the same fashion as the `operationId`, and like all Phoenix Controller
    functions, take two arguments:

    - `conn`: the `Plug.Conn` for the request
    - `params`: a map containing the parameters for the operation.  This is
      identical to `conn.params`.

    > ### Important {: .warning }
    >
    > Unlike standard Phoenix controller functions, parameters declared in the
    > `parameters` list of the operation are made avaliable in the `params`
    > argument as well as in `conn.params`.  These parameters will overwrite
    > any fields present in body parameters that happen to have the same name.

    A single router may have its routes target more than one controller.

  - `extra_plugs`: a list of plugs to execute after the route has matched
    but before the parameter and body pipeline has been executed.

    These plugs are  defined using `{atom, [args...]}` where `args` is
    a list of plug options to be applied to the plug, or `atom` which
    is equivalent to `{atom, []}`.  These may be either a function plug
    or a module plug.

    > ### Route-level Security Plugs {: .tip }
    >
    > Route-level security checks should be performed in plugs declared in
    > `extra_plugs`, until `Apical` provides direct support for security
    > schemes.

    > ### Global plugs {: .tip }
    >
    > if you need plugs to be executed for all routes, declare those plugs
    > in the router module before the macro `Exonerate.router_from_*`.

    > ### Post-pipeline plugs {: .tip }
    >
    > if you need plugs to be executed after the parameter and body pipeline,
    > for example, for row-level security checks, declare those plugs in the
    > controller module.  Note that these plugs should be able to match on
    > the `operationId` atom using `conn.private.operation_id`.

  - `styles`: a proplist of custom styles and their corresponding parsers.

      Each parser is represented as `{module, function, [args...]}` or
      `{module, function}` which is equivalent too `{module, function []}`.

      The parsers are functions that are called as
      `module.function(string, args...)`,  and return `{:ok, value}` or
      `{:error, message}`.  The message should be a string describing the
      error.

      The following styles are supported by default and do not need to be
      included in the styles proplist:

      - `"matrix"`
      - `"label"`
      - `"simple"`
      - `"form"`
      - `"space_delimited"`
      - `"pipe_delimited"`
      - `"deep_object"`

      see https://spec.openapis.org/oas/v3.1.0#style-values for description
      of these styles.

      > ### Custom styles {: .warning }
      >
      > If you need to support a custom style, you *must* add it to the
      > `styles` proplist.

      > ### Form-exploded objects {: .error }
      >
      > Form-exploded style parameters with type `object` in their schema are
      > not supported due to ambiguity in their definition per the OpenAPI
      > specification.

  - `content_sources`: A proplist of media-types (as **string** keys) and
    functions to act as the source for request body.  These should be
    defined as `{media_type, {module, [opts...]}}`.  These opts will be
    passed into the `c:Apical.Plugs.RequestBody.Source.fetch/3`.

  - `nest_all_json`: Analogous to the option in `Plug.Parsers.JSON`, this
    option will nest all json request body payloads under the `"_json"` key.
    if this is not true, objects payloads will be merged into `conn.params`.

  #### Available scopes

  The scopes have the following precedence:

  operation_ids > tags > parameters > global

  - `operation_ids`: A keywordlist of `operationId`s (as atom keys) and options
    to target to these operations.

    The keys must be cased in the same fashion as the `operationId` in the
    schema.

  - `tags`: A keywordlist of tags (as atom keys) and options to target to those
    tags.

    The tag keys must be cased in the same fashion as their tags in the schema.

  - `parameters`: A keywordlist of parameters (as atom keys) and options to
    target to those parameters.

    The parameter keys must be cased in the same fashion (including kebab-case)
    Note that this scope may be further nested inside of `tag` and
    `operation_ids` scopes.
  """

  alias Apical.Tools

  @spec router_from_string(String.t(), Keyword.t()) :: any()
  @doc """
  Generates a web router from a String containing an OpenAPI document.

  ### Example:

  ```elixir
  defmodule MyRouter do
    require Apical

    Apical.router_from_string(
      \"""
      openapi: 3.1.0
      info:
        title: My API
        version: 1.0.0
      paths:
        "/":
          get:
            operationId: getOperation
            responses:
              "200":
                description: OK
      \""",
      controller: MyProjectWeb.ApiController,
      encoding: "application/yaml"
    )
  end
  ```

  For options see `Apical` module docs.
  """
  defmacro router_from_string(string, opts) do
    opts = Macro.expand_literals(opts, __CALLER__)

    router(string, opts)
  end

  @spec router_from_file(Path.t(), Keyword.t()) :: any()
  @doc """
  Generates a web router from a String containing an OpenAPI document.

  ### Example:

  ```elixir
  defmodule MyRouter do
    require Apical

    Apical.router_from_file(
      "path/to/openapi.yaml",
      controller: MyProjectWeb.ApiController
    )
  end
  ```

  For options see `Apical` module docs.
  """
  defmacro router_from_file(file, opts) do
    opts =
      opts
      |> Macro.expand_literals(__CALLER__)
      |> Keyword.merge(file: file)
      |> Keyword.put_new_lazy(:encoding, fn -> find_encoding(file, opts) end)

    file
    |> Macro.expand(__CALLER__)
    |> File.read!()
    |> router(opts)
  end

  defp router(string, opts) do
    string
    |> Tools.decode(opts)
    |> Apical.Phoenix.router(string, opts)
    |> Tools.maybe_dump(opts)
  end

  defp find_encoding(filename, _opts) do
    case Path.extname(filename) do
      ".json" -> "application/json"
      ".yaml" -> "application/yaml"
      _ -> raise "unsupported file extension"
    end
  end
end