@spec append(FerricStore.Instance.t(), binary(), binary()) :: {:ok, non_neg_integer()}

Atomically appends suffix to the value of key.

If the key does not exist, it is created with value suffix. Returns {:ok, new_byte_length}.

@spec batch_get_with_file_refs(
  FerricStore.Instance.t(),
  [binary()],
  non_neg_integer()
) :: [
  binary() | nil | {:file_ref, binary(), non_neg_integer(), non_neg_integer()}
]

Batch GET variant for TCP large-value streaming.

It performs the same single ETS pass as batch_get/2, but cold entries whose value size is at least min_file_ref_size are returned as validated {:file_ref, path, value_offset, size} tuples instead of being materialized into BEAM binaries. Stale or invalid refs fall back to the normal batched cold pread path.

@spec batch_put(FerricStore.Instance.t(), [{binary(), binary()}]) ::
  :ok | {:error, binary()}

Batch PUT API with :ok | {:error, _} result shape.

The default application instance submits through quorum. Embedded/custom instances write locally because the Raft batchers are owned by the default application instance.

@spec batch_quorum_put(FerricStore.Instance.t(), [{binary(), binary()}]) :: [
  :ok | {:error, binary() | {:timeout, :unknown_outcome}}
]

Batch quorum PUT for pipelined SET commands.

Groups commands by shard, submits each group as a single batch to its Batcher with ONE reply ref per shard, then waits for all shard replies. Returns a list of results in input order.

Uses one ref per shard (not per command) so the connection process's selective receive scans at most shard_count refs instead of N*pipeline refs — critical for high concurrency where TCP messages flood the mailbox.

@spec dbsize(FerricStore.Instance.t()) :: non_neg_integer()

Returns the count of all live keys across every shard.

@spec delete(FerricStore.Instance.t(), binary()) :: :ok

Deletes key. Returns :ok whether or not the key existed.

@spec exists?(FerricStore.Instance.t(), binary()) :: boolean()

Returns true if key exists and is not expired.

Uses direct ETS lookup (no GenServer roundtrip) for hot and cold keys. A key is considered existing if it is in the keydir and not expired, regardless of whether its value is hot (in ETS) or cold (on disk only).

@spec exists_fast?(FerricStore.Instance.t(), binary()) :: boolean()

Fast ETS-direct existence check for a key.

Returns true if the key exists in ETS and is not expired, false otherwise. This bypasses the GenServer entirely, saving ~1-3us per call. Used in the hot write path (check_keydir_full/2) where we only need a boolean answer and can tolerate the fact that cold keys (value=nil but still in keydir) are correctly detected as existing.

@spec expire_at_ms(FerricStore.Instance.t(), binary()) :: non_neg_integer() | nil

Returns the expiry timestamp for a live plain key without reading its value.

This is used by expiry-time commands so cold large values do not pay a Bitcask pread just to report TTL metadata.

@spec extract_hash_tag(binary()) :: binary() | nil

Extracts the hash tag from a key, following Redis hash tag semantics.

If the key contains a substring enclosed in {...} where the content between the first { and the next } is non-empty, that substring is used for hashing instead of the full key. This allows related keys to be routed to the same shard.

Examples

iex> Ferricstore.Store.Router.extract_hash_tag("{user:42}:session")
"user:42"

iex> Ferricstore.Store.Router.extract_hash_tag("no_tag")
nil

iex> Ferricstore.Store.Router.extract_hash_tag("{}empty")
nil

@spec get(FerricStore.Instance.t(), binary()) :: binary() | nil

Retrieves the value for key, or nil if the key does not exist or is expired.

Hot path: reads directly from ETS (no GenServer roundtrip for cached keys). Falls back to a GenServer call for cache misses or when the ETS table is temporarily unavailable (e.g. during a shard restart).

Each successful read is recorded as either hot (ETS hit) or cold (Bitcask fallback) in Ferricstore.Stats for the FERRICSTORE.HOTNESS command and the INFO stats hot/cold fields.

@spec get_file_ref(FerricStore.Instance.t(), binary()) ::
  {binary(), non_neg_integer(), non_neg_integer()} | nil

Returns the on-disk file reference for a key's value, or nil.

Used by the sendfile optimisation in standalone TCP mode. Returns {file_path, value_byte_offset, value_size} for cold (on-disk) keys. Returns nil for hot keys (ETS), expired keys, or missing keys -- the caller should fall back to the normal read path.

Only cold keys benefit from sendfile: hot keys are already in BEAM memory and would need a normal get + transport.send.

@spec get_keydir_file_ref(FerricStore.Instance.t(), binary()) ::
  {:ok, {term(), non_neg_integer(), non_neg_integer()}} | :miss

Returns the keydir disk location for a key, or :miss.

Reads the {file_id, offset, value_size} fields directly from the keydir ETS table without a GenServer roundtrip. Returns {:ok, {fid, off, vsize}} for live keys, or :miss if the key is not in the keydir or is expired.

Used by sendfile zero-copy and STRLEN on cold keys.

@spec get_meta(FerricStore.Instance.t(), binary()) ::
  {binary(), non_neg_integer()} | nil

Returns {value, expire_at_ms} for a live key, or nil if the key does not exist or is expired.

Hot path: reads directly from ETS for cached keys. Each read is recorded as hot or cold in Ferricstore.Stats.

@spec get_version(FerricStore.Instance.t(), binary()) :: non_neg_integer()

Returns the current write version of the shard that owns key.

Used by the WATCH/EXEC transaction mechanism to detect concurrent modifications.

@spec get_with_file_ref(FerricStore.Instance.t(), binary()) ::
  {:hot, binary()}
  | {:cold_ref, binary(), non_neg_integer(), non_neg_integer()}
  | {:cold_value, binary()}
  | {:error, binary()}
  | :miss

Unified GET that returns everything from a single ETS lookup.

Returns:

• {:hot, value} — value is in ETS, ready to return
• {:cold_ref, path, offset, size} — value is on disk, file ref for sendfile
• {:cold_value, value} — value was on disk, GenServer fetched it
• :miss — key doesn't exist

@spec getdel(FerricStore.Instance.t(), binary()) :: binary() | nil

Atomically gets and deletes key.

Returns the value, or nil if the key did not exist.

@spec getex(FerricStore.Instance.t(), binary(), non_neg_integer()) :: binary() | nil

Atomically gets the value and updates the expiry of key.

expire_at_ms is an absolute Unix-epoch timestamp in milliseconds; pass 0 to persist (remove expiry). Returns the value, or nil if the key did not exist.

@spec getrange(FerricStore.Instance.t(), binary(), integer(), integer()) ::
  binary() | nil

Returns a byte range for a live plain key without reading the full cold value.

Hot entries slice the in-memory value. Cold entries validate the Bitcask location once, then read only the requested value bytes from the data file. Missing or expired keys return nil, matching get/2.

@spec getset(FerricStore.Instance.t(), binary(), binary()) :: binary() | nil

Atomically gets the old value and sets a new value for key.

Returns the old value, or nil if the key did not exist.

@spec hincrby(FerricStore.Instance.t(), binary(), binary(), integer()) ::
  integer() | {:error, binary()}

Atomically increments the integer value of hash field field in key by delta. Returns {:ok, new_int} or {:error, reason}. Shares ordering with the parent hash's shard (routes by the hash's redis_key).

@spec hincrbyfloat(FerricStore.Instance.t(), binary(), binary(), float()) ::
  binary() | {:error, binary()}

Atomically increments the float value of hash field field in key by delta. Returns the new value as a string, or {:error, reason}.

@spec incr(FerricStore.Instance.t(), binary(), integer()) ::
  {:ok, integer()} | {:error, binary()}

Atomically increments the integer value of key by delta.

If the key does not exist, it is set to delta. Returns {:ok, new_integer} on success or {:error, reason} if the value is not a valid integer.

@spec incr_float(FerricStore.Instance.t(), binary(), float()) ::
  {:ok, binary()} | {:error, binary()}

Atomically increments the float value of key by delta.

If the key does not exist, it is set to delta. Returns {:ok, new_float_string} on success or {:error, reason} if the value is not a valid float.

@spec keydir_name(FerricStore.Instance.t(), non_neg_integer()) :: atom() | reference()

Returns the keydir ETS table ref for the shard at index.

Uses the pre-computed tuple from the instance context for O(1) lookup.

@spec keys(FerricStore.Instance.t()) :: [binary()]

Returns all live (non-expired, non-deleted) keys across every shard.

@spec max_key_size() :: pos_integer()

Returns the maximum allowed key size in bytes.

@spec max_value_size() :: pos_integer()

Returns the maximum allowed value size in bytes.

@spec prob_write(FerricStore.Instance.t(), tuple()) :: term()

Routes a probabilistic data structure write command through Raft.

@spec put(FerricStore.Instance.t(), binary(), binary(), non_neg_integer()) ::
  :ok | {:error, binary()}

Stores key with value. expire_at_ms is an absolute Unix-epoch timestamp in milliseconds; pass 0 for no expiry.

@spec server_command(FerricStore.Instance.t(), term()) :: term()

Submits a server command through Raft for replication to all nodes.

Server commands are opaque to the library — the state machine dispatches them via the raft_apply_hook callback on the Instance struct. Routed through shard 0 for consistent ordering.

@spec set(FerricStore.Instance.t(), binary(), binary(), map()) :: term()

Atomically applies Redis SET options in Raft order.

Unlike put/4, this keeps NX/XX/GET/KEEPTTL checks inside the state machine so concurrent conditional SETs serialize correctly.

@spec setbit(FerricStore.Instance.t(), binary(), non_neg_integer(), 0 | 1) :: 0 | 1

Atomically sets the bit at offset to bit_val (0 or 1). Returns the previous bit value (0 or 1). Extends the bitmap with zero bytes if necessary. Goes through Raft so concurrent SETBITs on the same key never lose updates — the state machine is the sole mutator.

@spec setrange(FerricStore.Instance.t(), binary(), non_neg_integer(), binary()) ::
  {:ok, non_neg_integer()}

Atomically overwrites part of the string at key starting at offset.

Zero-pads if the key doesn't exist or the string is shorter than offset. Returns {:ok, new_byte_length}.

@spec shard_for(FerricStore.Instance.t(), binary()) :: non_neg_integer()

Returns the shard index (0-based) that owns key.

Routes through the 1,024-slot indirection layer: key -> SlotMap.slot_for_key/1 -> slot_map[slot] -> shard_index

Supports Redis hash tags: if the key contains {tag} (non-empty content between the first { and the next }), the tag is used for hashing instead of the full key.

@spec shard_name(FerricStore.Instance.t(), non_neg_integer()) :: atom()

Returns the registered process name for the shard at index.

Uses the pre-computed tuple from the instance context for O(1) lookup.

@spec slot_for(FerricStore.Instance.t(), binary()) :: non_neg_integer()

Returns the slot (0-1023) for a key, respecting hash tags.

@spec value_size(FerricStore.Instance.t(), binary()) :: non_neg_integer() | nil

Returns the live plain key value size without reading a cold value.

Hot entries use the in-memory value size; cold entries use the keydir value_size field populated by Bitcask append/recovery.

@spec watch_token(FerricStore.Instance.t(), binary()) :: term()

Returns a lightweight WATCH token for key.

Hot keys use the value hash plus their live Bitcask location. Cold keys use their live keydir location and expiry, avoiding a large Bitcask read just to snapshot WATCH state. Pending entries fall back to the shard write version.

@spec zincrby(FerricStore.Instance.t(), binary(), number(), binary()) ::
  binary() | {:error, binary()}

Atomically increments the score of member in the sorted set at key by increment. Returns the new score as a string.