defmodule Vela.Backend do
  @moduledoc """
  Behaviour for cache backends.
  """
  alias Vela.Cache.Entry

  @doc "Initialize the backend. Called once when the cache starts."
  @callback init(config :: Vela.Cache.Config.t()) ::
              {:ok, state :: term()} | {:error, reason :: term()}

  @doc "Fetch a single entry by key."
  @callback get(state :: term(), key :: term()) ::
              {:ok, Entry.t()} | {:error, :not_found}

  @doc "Store a single entry."
  @callback put(state :: term(), entry :: Entry.t()) ::
              {:ok, state :: term()} | {:error, reason :: term()}

  @doc "Delete a single entry by key."
  @callback delete(state :: term(), key :: term()) ::
              {:ok, state :: term()}

  @doc "Fetch multiple entries at once."
  @callback get_many(state :: term(), keys :: [term()]) ::
              {:ok, %{term() => Entry.t()}}

  @doc "Store multiple entries at once."
  @callback put_many(state :: term(), entries :: [Entry.t()]) ::
              {:ok, state :: term()} | {:error, term()}

  @doc "Delete all entries."
  @callback flush(state :: term()) ::
              {:ok, state :: term()}

  @doc "Delete all entries that have expired."
  @callback flush_expired(state :: term(), now :: integer()) ::
              {:ok, count :: integer(), state :: term()}

  @doc "Return the number of entries."
  @callback size(state :: term()) :: integer()

  @doc "Delete all entries that have the given tag. Returns count of deleted entries."
  @callback delete_by_tag(state :: term(), tag :: atom()) ::
              {:ok, count :: integer(), state :: term()}
end