GameServer.KV (GameServer v1.0.509)

Generic key/value storage.

This is intentionally minimal and un-opinionated.

If you want namespacing, encode it in key (e.g. "polyglot_pirates:key1"). If you want per-user values, pass user_id: ... to get/2, put/4, and delete/2.

This module uses the app cache (GameServer.Cache) as a best-effort read cache. Writes update the cache and deletes evict it.

Summary

Types

attrs()

Attributes used when creating or updating entries.

list_opts()

Options accepted by list_entries/1 and count_entries/1.

metadata()

Metadata stored alongside a value. Typically a small map with auxiliary fields.

payload()

Payload returned by get/1 and get/2.

value()

Value stored for a key. This is an arbitrary map and should contain JSON-serializable data.

Functions

count_entries(opts \\ [])

Count the number of entries that match the optional filter.

create_entry(attrs)

Create a new Entry from attrs (expecting key, optional user_id, value, metadata). Returns {:ok, entry} or {:error, changeset}.

delete(key, opts \\ [])

Delete the entry at key.

delete_entry(id)

Delete an entry by its id.

get(key, opts \\ [])

Retrieve the value and metadata stored for key.

get_entry(id)

Fetch an Entry by its numeric id. Returns the Entry struct or nil if not found.

list_entries(opts \\ [])

List key/value entries with optional pagination and filtering.

put(key, value, metadata \\ %{})
put(key, value, metadata, opts)

Store value with optional metadata at key.

update_entry(id, attrs)

Update an existing entry by id with attrs. Returns {:ok, entry}, {:error, :not_found} if missing, or {:error, changeset} on validation error.

Types

attrs()

@type attrs() :: %{
  :key => String.t(),
  optional(:user_id) => pos_integer(),
  :value => value(),
  optional(:metadata) => metadata()
}

Attributes used when creating or updating entries.

Expected keys (atom keys recommended):

  • :key — the entry key (String.t())
  • :user_id — optional user id (pos_integer())
  • :value — the stored value (value())
  • :metadata — optional metadata (metadata())

list_opts()

@type list_opts() :: [
  page: pos_integer(),
  page_size: pos_integer(),
  user_id: pos_integer(),
  global_only: boolean(),
  key: String.t()
]

Options accepted by list_entries/1 and count_entries/1.

Keys (all optional):

  • :page — page number (pos_integer(), defaults to 1)
  • :page_size — page size (pos_integer(), defaults to 50)
  • :user_id — filter by user id (pos_integer())
  • :global_only — when true, only return global entries (where user_id is nil) (boolean())
  • :key — substring filter (String.t())

metadata()

@type metadata() :: map()

Metadata stored alongside a value. Typically a small map with auxiliary fields.

payload()

@type payload() :: %{value: value(), metadata: metadata()}

Payload returned by get/1 and get/2.

value()

@type value() :: map()

Value stored for a key. This is an arbitrary map and should contain JSON-serializable data.

Functions

count_entries(opts \\ [])

@spec count_entries(list_opts()) :: non_neg_integer()

Count the number of entries that match the optional filter.

Accepts the same options as list_entries/1 (see list_opts/0). Returns a non-negative integer.

create_entry(attrs)

@spec create_entry(attrs()) ::
  {:ok, GameServer.KV.Entry.t()} | {:error, Ecto.Changeset.t()}

Create a new Entry from attrs (expecting key, optional user_id, value, metadata). Returns {:ok, entry} or {:error, changeset}.

delete(key, opts \\ [])

@spec delete(
  String.t(),
  keyword()
) :: :ok

Delete the entry at key.

Pass user_id: id in opts to delete a per-user key. Returns :ok.

delete_entry(id)

@spec delete_entry(pos_integer()) :: :ok

Delete an entry by its id.

Returns :ok whether or not the entry existed.

get(key, opts \\ [])

@spec get(
  String.t(),
  keyword()
) :: {:ok, payload()} | :error

Retrieve the value and metadata stored for key.

Pass user_id: id in opts to scope the lookup to a specific user. Returns {:ok, %{value: map(), metadata: map()}} when found, or :error when not present.

get_entry(id)

@spec get_entry(pos_integer()) :: GameServer.KV.Entry.t() | nil

Fetch an Entry by its numeric id. Returns the Entry struct or nil if not found.

list_entries(opts \\ [])

@spec list_entries(list_opts()) :: [GameServer.KV.Entry.t()]

List key/value entries with optional pagination and filtering.

Supported options: :page, :page_size, :user_id, :global_only, and :key (substring filter). See list_opts/0 for the expected option types. Returns a list of Entry structs ordered by most recently updated.

put(key, value, metadata \\ %{})

@spec put(String.t(), value(), metadata()) ::
  {:ok, GameServer.KV.Entry.t()} | {:error, Ecto.Changeset.t()}

put(key, value, metadata, opts)

@spec put(String.t(), value(), metadata(), list_opts()) ::
  {:ok, GameServer.KV.Entry.t()} | {:error, Ecto.Changeset.t()}

Store value with optional metadata at key.

When using the 4-arity, supported options include user_id: id to scope the entry to a user. Returns {:ok, entry} on success or {:error, changeset} on validation failure.

update_entry(id, attrs)

@spec update_entry(pos_integer(), attrs()) ::
  {:ok, GameServer.KV.Entry.t()}
  | {:error, :not_found}
  | {:error, Ecto.Changeset.t()}

Update an existing entry by id with attrs. Returns {:ok, entry}, {:error, :not_found} if missing, or {:error, changeset} on validation error.