defmodule GenRetry do
  @moduledoc ~s"""
  GenRetry provides utilities for retrying Elixir functions,
  with configurable delay and backoff characteristics.

  ## Summary

  Given a 0-arity function which raises an exception upon failure, `retry/2`
  and `retry_link/2` repeatedly executes the function until success is
  reached or the maximum number of retries has occurred.

  `GenRetry.Task.async/2` and `GenRetry.Task.Supervisor.async/3`
  provide drop-in replacements for `Task.async/1` and
  `Task.Supervisor.async/2`, respectively, adding retry capability.
  They return plain `%Task{}` structs, usable with any other function in
  the `Task` module.


  ## Examples

      my_background_function = fn ->
        :ok = try_to_send_tps_reports()
      end
      GenRetry.retry(my_background_function, retries: 10, delay: 10_000)

      my_future_function = fn ->
        {:ok, val} = get_val_from_flaky_network_service()
        val
      end
      t = GenRetry.Task.async(my_future_function, retries: 3)
      my_val = Task.await(t)  # may raise exception


  ## Installation

  1. Add GenRetry to your list of dependencies in `mix.exs`:

          def deps do
            [{:gen_retry, "~> #{GenRetry.Mixfile.project()[:version]}"}]
          end

  2. Ensure GenRetry is started before your application:

          def application do
            [applications: [:gen_retry]]
          end

  3. (Optional) Specify a custom logging module in your config.exs

          config :gen_retry, GenRetry.Logger, logger: MyApp.CustomLogger

      where MyApp.CustomLogger implements the GenRetry.Logger behavior.
      The default module is GenRetry.Utils if none is specified in a config.

  ## Options

  * `:retries`, integer (default 1):
    Number of times to retry upon failure.  Set to
    0 to try exactly once; set to `:infinity` to retry forever.

  * `:delay`, integer (default 1000):
    Number of milliseconds to wait between first failure and first retry.
    Subsequent retries use this value as a starting point for exponential
    backoff.

  * `:jitter`, number (default 0):
    Proportion of current retry delay to randomly add to delay time.
    For example, given options `delay: 1000, jitter: 0.1`, the first delay
    will be a random time between 1000 and 1100 milliseconds.  Values
    under 0 will remove time rather than add it; beware of values under -1,
    which may result in nonsensical "negative time delays".

  * `:exp_base`, number (default 2):
    The base to use for exponentiation during exponential backoff.
    Set to `1` to disable backoff.  Values less than 1 are not very useful.

  * `:respond_to`, pid (ignored by `GenRetry.Task.*`):
    The process ID to which a message should be sent upon completion.
    Successful exits send `{:success, return_value, final_retry_state}`;
    unsuccessful exits send `{:failure, error, stacktrace, final_retry_state}`.

  * `:on_success`, `fn {result, final_retry_state} -> nil end` (default no-op):
    A function to run on success. The argument is a tuple containing the result and the final retry state.

  * `:on_failure`, `fn {exception, stacktrace, final_retry_state} -> nil end` (default no-op):
    A function to run on failure. The argument is a tuple containing the exception, stacktrace, and final retry state.

  """

  use Application

  @doc false
  def start(_type, _args) do
    import Supervisor.Spec, warn: false

    children = [
      worker(GenRetry.Launcher, [[], [name: :gen_retry_launcher]])
    ]

    opts = [strategy: :one_for_one, name: GenRetry.Supervisor]
    Supervisor.start_link(children, opts)
  end

  defmodule State do
    @moduledoc ~S"""
    Used to represent the state of a GenRetry invocation.
    This struct is part of the success or failure message to be
    optionally sent to another process, specified by `opts[:respond_to]`,
    upon completion.

    * `:function` and `:opts` are the invocation arguments supplied by the user.
    * `:tries` is the total number of attempts made before sending this message.
    * `:retry_at` is either the timestamp of the last attempt, or 0
      (if `opts[:retries] == 0`).
    """

    # the function to retry
    defstruct function: nil,
              # %GenRetry.Options{} from caller
              opts: nil,
              # number of tries performed so far
              tries: 0,
              # :erlang.system_time(:milli_seconds)
              retry_at: 0,
              # a function for logging
              logger: nil

    @type t :: %__MODULE__{
            function: GenRetry.retryable_fun(),
            opts: GenRetry.Options.t(),
            tries: non_neg_integer,
            retry_at: non_neg_integer
          }
  end

  defmodule Options do
    @moduledoc false
    defstruct retries: 1,
              delay: 1000,
              jitter: 0,
              exp_base: 2,
              respond_to: nil,
              on_success: nil,
              on_failure: nil

    @type t :: %__MODULE__{
            retries: :infinity | non_neg_integer,
            delay: non_neg_integer,
            jitter: number,
            exp_base: number,
            respond_to: pid | nil,
            on_success: GenRetry.on_success(),
            on_failure: GenRetry.on_failure()
          }

    use ExConstructor
  end

  @type option ::
          {:retries, :infinity | non_neg_integer}
          | {:delay, non_neg_integer}
          | {:jitter, number}
          | {:exp_base, number}
          | {:respond_to, pid}
          | {:on_success, on_success()}
          | {:on_failure, on_failure()}

  @type options :: [option]

  @type retryable_fun :: (() -> any | no_return)

  @type success_msg :: {:success, any, GenRetry.State.t()}

  @type failure_msg ::
          {:failure, Exception.t(), [:erlang.stack_item()], GenRetry.State.t()}

  @type on_success ::
          ({result :: any(), final_retry_state :: GenRetry.State.t()} -> any())

  @type on_failure ::
          ({exception :: any(), stacktrace :: list(),
            final_retry_state :: GenRetry.State.t()} ->
             any())

  @doc ~S"""
  Starts a retryable process linked to `GenRetry.Supervisor`, and returns its
  pid.  `fun` should be a function that raises an exception upon failure;
  any other return value is treated as success.
  """
  @spec retry(retryable_fun, options) :: pid
  def retry(fun, opts \\ []) do
    GenRetry.Launcher.launch(fun, opts)
  end

  @doc ~S"""
  Starts a retryable process linked to the current process, and returns its
  pid.  `fun` should be a function that raises an exception upon failure;
  any other return value is treated as success.
  """
  @spec retry_link(retryable_fun, options) :: pid
  def retry_link(fun, opts \\ []) do
    {:ok, pid} =
      GenServer.start_link(
        GenRetry.Worker,
        {fun, Options.new(opts)},
        timeout: :infinity
      )

    pid
  end
end
