defmodule KeenAuth.Processor do
  @moduledoc """
  Defines the processor behavior for handling authentication business logic.

  Processors are the business logic hub in KeenAuth's pipeline architecture. They receive
  normalized user data from mappers and can implement custom validation, user creation,
  role assignment, auditing, and other business-specific logic.

  ## Pipeline Stage

  The processor sits between the mapper and storage in the authentication flow:

  ```
  Strategy → Mapper → **Processor** → Storage
  ```

  ## Flexibility

  Processors can be as simple or sophisticated as needed:

  - **Simple**: Pass data through unchanged
  - **Advanced**: Database lookups, validation, user creation, role assignment, auditing

  ## Example Implementation

      defmodule MyApp.Auth.Processor do
        @behaviour KeenAuth.Processor

        def process(conn, provider, mapped_user, oauth_response) do
          with {:ok, user} <- find_or_create_user(mapped_user),
               :ok <- validate_permissions(user),
               {:ok, user} <- assign_roles(user, oauth_response) do
            {:ok, conn, user, oauth_response}
          else
            {:error, reason} ->
              conn
              |> put_flash(:error, "Authentication failed")
              |> redirect(to: "/login")
          end
        end

        def sign_out(conn, provider, params) do
          conn
          |> KeenAuth.Storage.delete()
          |> redirect(to: "/")
        end
      end

  ## Configuration

  Specify your processor in the strategy configuration:

      config :keen_auth,
        strategies: [
          azure_ad: [
            processor: MyApp.Auth.Processor,
            # ... other config
          ]
        ]
  """

  alias KeenAuth.AuthenticationController
  alias KeenAuth.Strategy

  @default_processor KeenAuth.Processor.Default

  @doc """
  Processes the authenticated user and OAuth response.

  This callback is called after the user data has been normalized by the mapper.
  It's where you implement your application's business logic for handling
  authenticated users.

  ## Parameters

  - `conn` - The Plug connection
  - `provider` - The OAuth provider atom (e.g., `:azure_ad`, `:github`)
  - `mapped_user` - User data normalized by the mapper
  - `response` - The complete OAuth response including tokens

  ## Return Values

  - `{:ok, conn, user, response}` - Success, proceed to storage
  - `conn` - Halt processing (e.g., redirect to error page)

  ## Example

      def process(conn, :azure_ad, mapped_user, oauth_response) do
        case create_or_update_user(mapped_user) do
          {:ok, user} -> {:ok, conn, user, oauth_response}
          {:error, _} -> redirect(conn, to: "/login?error=invalid_user")
        end
      end
  """
  @callback process(
              conn :: Plug.Conn.t(),
              provider :: atom(),
              mapped_user :: KeenAuth.User.t() | map(),
              response :: AuthenticationController.oauth_callback_response() | nil
            ) ::
              {:ok, Plug.Conn.t(), KeenAuth.User.t() | map(), AuthenticationController.oauth_callback_response() | nil} | Plug.Conn.t()

  @doc """
  Handles user sign out.

  This callback is called when a user signs out. It should clean up any
  user-specific data and redirect appropriately.

  ## Parameters

  - `conn` - The Plug connection
  - `provider` - The OAuth provider atom or binary
  - `params` - Request parameters (may include redirect destination)

  ## Return Value

  - `conn` - The modified connection (typically with a redirect)

  ## Example

      def sign_out(conn, _provider, params) do
        conn
        |> clear_user_session()
        |> redirect(to: params["redirect_to"] || "/")
      end
  """
  @callback sign_out(conn :: Plug.Conn.t(), provider :: binary(), params :: map()) :: Plug.Conn.t()

  defmacro __using__(_params \\ nil) do
    quote do
      @behaviour unquote(__MODULE__)

      def process(conn, provider, mapped_user, oauth_response), do: unquote(__MODULE__).process(conn, provider, mapped_user, oauth_response)
      def sign_out(conn, provider, params), do: unquote(__MODULE__).sign_out(conn, provider, params)

      defoverridable unquote(__MODULE__)
    end
  end

  @doc """
  Delegates to the configured processor for the given provider.

  This function looks up the processor configured for the specific provider
  and calls its `process/4` function.
  """
  def process(conn, provider, mapped_user, oauth_response) do
    current_processor(conn, provider).process(conn, provider, mapped_user, oauth_response)
  end

  @doc """
  Delegates to the configured processor for sign out.

  This function looks up the processor configured for the specific provider
  and calls its `sign_out/3` function.
  """
  def sign_out(conn, provider, params) do
    current_processor(conn, provider).signout(conn, provider, params)
  end

  @doc """
  Gets the processor module for the given provider.

  Fetches the configuration from the connection and returns the processor
  module configured for the provider.
  """
  def current_processor(conn, provider) do
    KeenAuth.Plug.fetch_config(conn)
    |> get_processor(provider)
  end

  @doc """
  Extracts the processor module from the configuration.

  Returns the configured processor for the provider, or the default processor
  if none is configured.
  """
  def get_processor(config, provider) do
    Strategy.get_strategy(config, provider)[:processor] || @default_processor
  end
end