Ferricstore.NamespaceConfig (ferricstore v0.3.1)

Copy Markdown View Source

GenServer managing per-namespace (prefix) runtime configuration.

Stores namespace-specific overrides for commit window timing and durability mode in an ETS table (:ferricstore_ns_config). Prefixes that have no explicit override fall back to sensible defaults (1 ms window, :quorum durability).

ETS schema

Each entry is a tuple:

{prefix, window_ms, durability, changed_at, changed_by}

Where:

  • prefix -- binary namespace prefix (e.g. "rate", "session")
  • window_ms -- commit window in milliseconds (positive integer)
  • durability -- :quorum or :async
  • changed_at -- Unix timestamp (seconds) of the last change, or 0 for defaults
  • changed_by -- identifier of the client that made the change (empty string for defaults)

Default values

When no override exists for a prefix, the effective configuration is:

  • window_ms -- 1
  • durability -- :quorum

Usage

Ferricstore.NamespaceConfig.set("rate", "window_ms", 10)
#=> :ok

Ferricstore.NamespaceConfig.get("rate")
#=> {:ok, %{prefix: "rate", window_ms: 10, durability: :quorum, changed_at: 1711111111, changed_by: ""}}

Ferricstore.NamespaceConfig.window_for("rate")
#=> 10

Ferricstore.NamespaceConfig.durability_for("rate")
#=> :quorum

Ferricstore.NamespaceConfig.reset("rate")
#=> :ok

Summary

Types

field()

Valid field names for set/3.

ns_entry()

A namespace configuration entry.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

default_durability()

Returns the default durability mode.

default_window_ms()

Returns the default window_ms value.

durability_for(prefix)

Returns the effective durability mode for a namespace prefix.

get(prefix)

Returns the configuration for a single namespace prefix.

get_all()

Returns configuration entries for all namespaces that have explicit overrides.

reset(prefix)

Resets the configuration for a single namespace prefix back to defaults.

reset_all()

Resets all namespace configurations back to defaults.

set(prefix, field, value)

Sets a configuration field for the given namespace prefix.

set(prefix, field, value, changed_by)

Sets a configuration field for the given namespace prefix with caller identity.

start_link(opts \\ [])

Starts the NamespaceConfig GenServer and creates the backing ETS table.

window_for(prefix)

Returns the effective window_ms for a namespace prefix.

Types

field()

@type field() :: :window_ms | :durability

Valid field names for set/3.

ns_entry()

@type ns_entry() :: %{
  prefix: binary(),
  window_ms: non_neg_integer(),
  durability: :quorum | :async,
  changed_at: non_neg_integer(),
  changed_by: binary()
}

A namespace configuration entry.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

default_durability()

Returns the default durability mode.

default_window_ms()

@spec default_window_ms() :: pos_integer()

Returns the default window_ms value.

durability_for(prefix)

@spec durability_for(binary()) :: :quorum | :async

Returns the effective durability mode for a namespace prefix.

Falls back to the default (:quorum) when no override exists.

Parameters

  • prefix -- namespace prefix string

Returns

:quorum or :async.

get(prefix)

@spec get(binary()) :: {:ok, ns_entry()}

Returns the configuration for a single namespace prefix.

If the prefix has no explicit override, returns the default configuration.

Parameters

  • prefix -- namespace prefix string

Returns

  • {:ok, ns_entry()} -- always succeeds; returns defaults for unconfigured prefixes

Examples

iex> Ferricstore.NamespaceConfig.get("rate")
{:ok, %{prefix: "rate", window_ms: 1, durability: :quorum, changed_at: 0, changed_by: ""}}

get_all()

@spec get_all() :: [ns_entry()]

Returns configuration entries for all namespaces that have explicit overrides.

Returns an empty list when no overrides have been set.

Returns

A list of ns_entry() maps, sorted by prefix.

reset(prefix)

@spec reset(binary()) :: :ok

Resets the configuration for a single namespace prefix back to defaults.

Deletes the explicit override from ETS. Subsequent calls to get/1, window_for/1, and durability_for/1 will return default values.

Parameters

  • prefix -- namespace prefix string

Returns

  • :ok -- always succeeds (no-op if the prefix had no override)

reset_all()

@spec reset_all() :: :ok

Resets all namespace configurations back to defaults.

Deletes all explicit overrides from ETS.

Returns

  • :ok

set(prefix, field, value)

@spec set(binary(), binary(), binary()) :: :ok | {:error, binary()}

Sets a configuration field for the given namespace prefix.

Parameters

  • prefix -- namespace prefix string (e.g. "rate")
  • field -- field name string: "window_ms" or "durability"
  • value -- field value string: a positive integer for window_ms, or "quorum" / "async" for durability

Returns

  • :ok on success
  • {:error, reason} when the field name or value is invalid

Examples

iex> Ferricstore.NamespaceConfig.set("rate", "window_ms", "10")
:ok

iex> Ferricstore.NamespaceConfig.set("ts", "durability", "async")
:ok

set(prefix, field, value, changed_by)

@spec set(binary(), binary(), binary(), binary()) :: :ok | {:error, binary()}

Sets a configuration field for the given namespace prefix with caller identity.

Behaves identically to set/3 but also records changed_by for audit trail purposes.

Parameters

  • prefix -- namespace prefix string
  • field -- field name string: "window_ms" or "durability"
  • value -- field value string
  • changed_by -- identity of the caller making the change

Returns

  • :ok on success
  • {:error, reason} when the field name or value is invalid

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the NamespaceConfig GenServer and creates the backing ETS table.

window_for(prefix)

@spec window_for(binary()) :: pos_integer()

Returns the effective window_ms for a namespace prefix.

Falls back to the default (1) when no override exists.

Parameters

  • prefix -- namespace prefix string

Returns

A positive integer representing the commit window in milliseconds.