defmodule Vela.Topology do
  @moduledoc """
  Behaviour that all topology modules must implement.

  A topology decides WHERE data lives (local node, remote node, etc.)
  and HOW reads/writes are routed. It uses a backend for the actual storage.
  """

  alias Vela.Cache.Config
  alias Vela.Cache.Entry

  @callback init(config :: Config.t()) ::
              {:ok, state :: term()} | {:error, reason :: term()}

  @callback get(state :: term(), key :: term()) ::
              {:ok, Entry.t()} | {:error, :not_found} | {:error, term()}

  @callback put(state :: term(), entry :: Entry.t()) ::
              {:ok, state :: term()} | {:error, term()}

  @callback delete(state :: term(), key :: term()) ::
              {:ok, state :: term()}

  @callback get_many(state :: term(), keys :: [term()]) ::
              {:ok, %{term() => Entry.t()}}

  @callback put_many(state :: term(), entries :: [Entry.t()]) ::
              {:ok, state :: term()} | {:error, term()}

  @callback flush(state :: term()) ::
              {:ok, state :: term()}

  @callback size(state :: term()) :: integer()

  @callback invalidate_tag(state :: term(), tag :: atom()) ::
              {:ok, count :: integer(), state :: term()}
end