Ferricstore.Commands.Extension behaviour (ferricstore v0.10.0)

Behaviour and registry helpers for optional command providers.

A provider is configured with:

config :ferricstore, :command_extensions, [MyApp.Commands]

Providers declare command metadata with commands/0 and execute commands with handle/3. The core dispatcher uses this metadata for routing and key ACL extraction, while leaving command semantics in the provider module. access describes the command's key footprint. acl_categories independently controls category grants and defaults to READ or WRITE for the matching access mode.

Summary

Types

access()

acl_category()

command_entry()

prepared()

Callbacks

commands()

handle(binary, list, map)

keys(binary, list)

Functions

command?(command)

Returns true when a configured provider owns the command.

command_access_type(command)

Returns the key access type for a configured command.

command_names_upper()

Returns configured command names in uppercase form.

commands()

Returns normalized command metadata from all configured providers.

handle(command, args, store)

Dispatches a configured command to its provider module.

keys(command, args)

Extracts key arguments for a configured command.

lookup(command)

Looks up configured command metadata by command name.

lookup_upper(command)

Looks up configured command metadata by an already-uppercase command name.

modules()

Returns intrinsic OSS and configured provider modules.

non_shadowing_command_access_type(command)

Returns the access type for a non-shadowing configured command.

non_shadowing_command_names_in_acl_category(category)

Returns non-shadowing command names assigned to an ACL category.

non_shadowing_command_names_upper()

Returns uppercase configured command names excluding built-in shadows.

non_shadowing_commands()

Returns configured command metadata excluding names already owned by built-in commands.

prepare(command, args)

Resolves one immutable provider snapshot for preparation and dispatch.

request_context(store)

Returns trusted request context attached by the server protocol layer.

Types

access()

@type access() :: :read | :write | :rw

acl_category()

@type acl_category() :: atom() | binary()

command_entry()

@type command_entry() :: %{
  :name => binary(),
  optional(:arity) => integer(),
  optional(:flags) => [binary()],
  optional(:first_key) => integer(),
  optional(:last_key) => integer(),
  optional(:step) => integer(),
  optional(:access) => access(),
  optional(:acl_categories) => [acl_category()],
  optional(:summary) => binary()
}

prepared()

@type prepared() :: %{
  ast: {:extension_command, module(), binary(), [binary()], access()},
  keys: [binary()]
}

Callbacks

commands()

@callback commands() :: [command_entry()]

handle(binary, list, map)

@callback handle(binary(), [binary()], map()) :: term()

keys(binary, list)

(optional)

@callback keys(binary(), [binary()]) :: {:ok, [binary()]} | :error

Functions

command?(command)

@spec command?(binary()) :: boolean()

Returns true when a configured provider owns the command.

command_access_type(command)

@spec command_access_type(binary()) :: access() | nil

Returns the key access type for a configured command.

command_names_upper()

@spec command_names_upper() :: MapSet.t(binary())

Returns configured command names in uppercase form.

commands()

@spec commands() :: [map()]

Returns normalized command metadata from all configured providers.

handle(command, args, store)

@spec handle(binary(), [binary()], map()) :: term() | :not_found

Dispatches a configured command to its provider module.

keys(command, args)

@spec keys(binary(), [binary()]) :: {:ok, [binary()]} | :error

Extracts key arguments for a configured command.

lookup(command)

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

Looks up configured command metadata by command name.

lookup_upper(command)

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

Looks up configured command metadata by an already-uppercase command name.

modules()

@spec modules() :: [module()]

Returns intrinsic OSS and configured provider modules.

non_shadowing_command_access_type(command)

@spec non_shadowing_command_access_type(binary()) :: access() | nil

Returns the access type for a non-shadowing configured command.

non_shadowing_command_names_in_acl_category(category)

@spec non_shadowing_command_names_in_acl_category(binary()) :: MapSet.t(binary())

Returns non-shadowing command names assigned to an ACL category.

non_shadowing_command_names_upper()

@spec non_shadowing_command_names_upper() :: MapSet.t(binary())

Returns uppercase configured command names excluding built-in shadows.

non_shadowing_commands()

@spec non_shadowing_commands() :: [map()]

Returns configured command metadata excluding names already owned by built-in commands.

prepare(command, args)

@spec prepare(binary(), [binary()]) ::
  {:ok, prepared()} | {:error, :invalid_keys} | :error

Resolves one immutable provider snapshot for preparation and dispatch.

request_context(store)

@spec request_context(map()) :: map()

Returns trusted request context attached by the server protocol layer.

Extension providers can use this to read authenticated subject, tenant, and scope data without parsing command arguments as authority.