GameServer.KV (game_server_sdk v1.0.15)

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. If you want per-lobby values, pass lobby_id: ... to the same functions. You can also pass both to scope a key to a user within a lobby.

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

Note: This is an SDK stub. Calling these functions will raise an error. The actual implementation runs on the GameServer.

Summary

Types

attrs()

list_opts()

metadata()

payload()

value()

Functions

count_entries()

Count the number of entries that match the optional filter.

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/lobby_id, value, metadata). Returns {:ok, entry} or {:error, changeset}.

delete(key)

Delete the entry at key.

delete(key, opts)

Delete the entry at key.

delete_entry(id)

Delete an entry by its id.

get(key)

Retrieve the value and metadata stored for key.

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()

List key/value entries with optional pagination and filtering.

list_entries(opts)

List key/value entries with optional pagination and filtering.

put(key, value)

Store value with optional metadata at key.

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(),
  optional(:lobby_id) => pos_integer(),
  :value => value(),
  optional(:metadata) => metadata()
}

list_opts()

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

metadata()

@type metadata() :: map()

payload()

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

value()

@type value() :: map()

Functions

count_entries()

@spec count_entries() :: 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.

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/lobby_id, value, metadata). Returns {:ok, entry} or {:error, changeset}.

delete(key)

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

Delete the entry at key.

Pass user_id: id or lobby_id: id in opts to delete a scoped key. Returns :ok.

delete(key, opts)

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

Delete the entry at key.

Pass user_id: id or lobby_id: id in opts to delete a scoped 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)

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

Retrieve the value and metadata stored for key.

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

get(key, opts)

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

Retrieve the value and metadata stored for key.

Pass user_id: id or lobby_id: id in opts to scope the lookup. 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()

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

List key/value entries with optional pagination and filtering.

Supported options: :page, :page_size, :user_id, :lobby_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.

list_entries(opts)

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

List key/value entries with optional pagination and filtering.

put(key, value)

@spec put(String.t(), value()) ::
  {: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 or lobby_id: id to scope the entry. Returns {:ok, entry} on success or {:error, changeset} on validation failure.

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 or lobby_id: id to scope the entry. 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.