@spec all_request_types(module()) :: [String.t()]

Gets all request_type strings from all resources in the domain.

Returns a flat list of all request types across all resources that have gen_api configured.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.all_request_types(MyApp.Chat)
["send_direct_message", "get_conversation", "send_group_message", ...]

@spec check_permission(module()) ::
  false | :any_authenticated | {:arg, String.t()} | {:role, [String.t()]}

Gets the effective default check_permission for the domain.

Returns the check_permission configured in the domain's gen_api section, or the built-in default of false if not configured.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.check_permission(MyApp.Chat)
false

@spec choose_node_mode(module()) ::
  :random | :hash | {:hash, String.t()} | :round_robin

Gets the effective default choose_node_mode for the domain.

Returns the choose_node_mode configured in the domain's gen_api section, or the built-in default of :random if not configured.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.choose_node_mode(MyApp.Chat)
:random

@spec define_supporter?(module()) :: boolean()

Checks whether the supporter module should be auto-generated.

Returns true if gen_api define_supporter? is true (the default), false otherwise.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.define_supporter?(MyApp.Chat)
true

@spec fun_config(module(), String.t()) :: PhoenixGenApi.Structs.FunConfig.t() | nil

Gets a specific FunConfig by request_type from the domain's aggregated configs.

Searches across all resources in the domain for a FunConfig with the given request_type. Returns the first match, or nil if not found.

Parameters

• domain - The Ash domain module
• request_type - The PhoenixGenApi request type string

Examples

iex> AshPhoenixGenApi.Domain.Info.fun_config(MyApp.Chat, "send_direct_message")
%PhoenixGenApi.Structs.FunConfig{request_type: "send_direct_message", ...}

iex> AshPhoenixGenApi.Domain.Info.fun_config(MyApp.Chat, "nonexistent")
nil

@spec fun_configs(module()) :: [PhoenixGenApi.Structs.FunConfig.t()]

Gets all FunConfig structs aggregated from all resources in the domain that have the AshPhoenixGenApi.Resource extension.

This function collects the generated FunConfigs from each resource's __ash_phoenix_gen_api_fun_configs__/0 function and concatenates them into a single list.

Returns an empty list if no resources have gen_api configured or if the FunConfigs haven't been generated yet.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.fun_configs(MyApp.Chat)
[
  %PhoenixGenApi.Structs.FunConfig{request_type: "send_direct_message", ...},
  %PhoenixGenApi.Structs.FunConfig{request_type: "get_conversation", ...},
  ...
]

@spec gen_api_check_permission(dsl_or_extended :: module() | map()) ::
  {:ok, any()} | :error

Default permission check mode for all resources in this domain.

• false - No permission check (default)
• :any_authenticated - Requires a valid user_id
• {:arg, "arg_name"} - The specified argument must match user_id
• {:role, ["admin"]} - User must have one of the listed roles

@spec gen_api_check_permission!(dsl_or_extended :: module() | map()) ::
  any() | no_return()

Default permission check mode for all resources in this domain.

• false - No permission check (default)
• :any_authenticated - Requires a valid user_id
• {:arg, "arg_name"} - The specified argument must match user_id
• {:role, ["admin"]} - User must have one of the listed roles

@spec gen_api_choose_node_mode(dsl_or_extended :: module() | map()) ::
  {:ok, any()} | :error

Default node selection strategy for all resources in this domain.

• :random - Select a random node (default)
• :hash - Hash-based selection using request_type
• {:hash, key} - Hash-based selection using the specified argument key
• :round_robin - Round-robin across nodes

@spec gen_api_choose_node_mode!(dsl_or_extended :: module() | map()) ::
  any() | no_return()

Default node selection strategy for all resources in this domain.

• :random - Select a random node (default)
• :hash - Hash-based selection using request_type
• {:hash, key} - Hash-based selection using the specified argument key
• :round_robin - Round-robin across nodes

@spec gen_api_define_supporter?(dsl_or_extended :: module() | map()) :: boolean()

Whether to auto-generate the supporter module. Set to false if you want to define the supporter module manually.

When false, the extension will still collect FunConfigs from resources but will not generate the supporter module. You can use AshPhoenixGenApi.Domain.Info.fun_configs/1 to get the aggregated FunConfigs and build your own supporter module.

@spec gen_api_nodes(dsl_or_extended :: module() | map()) :: {:ok, any()} | :error

Default target nodes for all resources in this domain.

Can be:

• A list of node atoms: [:"node1@host", :"node2@host"]
• An MFA tuple that returns a node list at runtime: {ClusterHelper, :get_nodes, [:chat]}
• :local - Execute on the local node (default)

@spec gen_api_nodes!(dsl_or_extended :: module() | map()) :: any() | no_return()

Default target nodes for all resources in this domain.

Can be:

• A list of node atoms: [:"node1@host", :"node2@host"]
• An MFA tuple that returns a node list at runtime: {ClusterHelper, :get_nodes, [:chat]}
• :local - Execute on the local node (default)

@spec gen_api_options(dsl_or_extended :: module() | map()) :: %{
  required(atom()) => any()
}

gen_api DSL options

Returns a map containing the and any configured or default values.

@spec gen_api_permission_callback(dsl_or_extended :: module() | map()) ::
  {:ok, any()} | :error

Default permission callback MFA for all resources in this domain. When set, takes precedence over check_permission.

Accepts {Module, :function, []} or nil. The callback function receives request_type (string) and args (map) as arguments and returns true (continue) or false (permission denied).

The callback function signature:

@callback check_permission(request_type :: String.t(), args :: map()) :: boolean()

Example callback:

def check_permission(request_type, args) do
  case request_type do
    "delete_user" -> args["role"] == "admin"
    "update_profile" -> args["user_id"] == args["target_user_id"]
    _ -> true
  end
end

When both permission_callback and check_permission are set, permission_callback takes precedence and is stored in the FunConfig's permission_callback field.

Defaults to nil.

@spec gen_api_permission_callback!(dsl_or_extended :: module() | map()) ::
  any() | no_return()

Default permission callback MFA for all resources in this domain. When set, takes precedence over check_permission.

Accepts {Module, :function, []} or nil. The callback function receives request_type (string) and args (map) as arguments and returns true (continue) or false (permission denied).

The callback function signature:

@callback check_permission(request_type :: String.t(), args :: map()) :: boolean()

Example callback:

def check_permission(request_type, args) do
  case request_type do
    "delete_user" -> args["role"] == "admin"
    "update_profile" -> args["user_id"] == args["target_user_id"]
    _ -> true
  end
end

When both permission_callback and check_permission are set, permission_callback takes precedence and is stored in the FunConfig's permission_callback field.

Defaults to nil.

@spec gen_api_push_nodes(dsl_or_extended :: module() | map()) :: {:ok, any()} | :error

Target gateway nodes to push config to.

Can be:

• A list of node atoms: [:"gateway1@host", :"gateway2@host"]
• An MFA tuple that returns a node list at runtime: {ClusterHelper, :get_gateway_nodes, []}
• nil - No push nodes configured (default)

When set, the generated supporter module will include functions to actively push its configuration to the specified gateway nodes.

@spec gen_api_push_nodes!(dsl_or_extended :: module() | map()) :: any() | no_return()

Target gateway nodes to push config to.

Can be:

• A list of node atoms: [:"gateway1@host", :"gateway2@host"]
• An MFA tuple that returns a node list at runtime: {ClusterHelper, :get_gateway_nodes, []}
• nil - No push nodes configured (default)

When set, the generated supporter module will include functions to actively push its configuration to the specified gateway nodes.

@spec gen_api_push_on_startup(dsl_or_extended :: module() | map()) ::
  {:ok, boolean()} | :error

Whether to automatically push config to the configured push_nodes on application startup.

When true, the supporter module's push_on_startup/2 function can be called during application startup to push the config to gateway nodes. Note: you still need to hook this into your application's supervision tree or startup sequence manually.

@spec gen_api_push_on_startup!(dsl_or_extended :: module() | map()) ::
  boolean() | no_return()

Whether to automatically push config to the configured push_nodes on application startup.

When true, the supporter module's push_on_startup/2 function can be called during application startup to push the config to gateway nodes. Note: you still need to hook this into your application's supervision tree or startup sequence manually.

@spec gen_api_request_info(dsl_or_extended :: module() | map()) ::
  {:ok, boolean()} | :error

Default for whether to pass request info (user_id, device_id, request_id) as the last argument to the MFA function for all resources in this domain.

@spec gen_api_request_info!(dsl_or_extended :: module() | map()) ::
  boolean() | no_return()

Default for whether to pass request info (user_id, device_id, request_id) as the last argument to the MFA function for all resources in this domain.

@spec gen_api_response_type(dsl_or_extended :: module() | map()) ::
  {:ok, atom()} | :error

Default response mode for all resources in this domain.

• :sync - Client waits for the result
• :async - Client receives an ack, then the result later (default)
• :stream - Client receives streamed chunks
• :none - Fire and forget

@spec gen_api_response_type!(dsl_or_extended :: module() | map()) ::
  atom() | no_return()

Default response mode for all resources in this domain.

• :sync - Client waits for the result
• :async - Client receives an ack, then the result later (default)
• :stream - Client receives streamed chunks
• :none - Fire and forget

@spec gen_api_result_encoder(dsl_or_extended :: module() | map()) ::
  {:ok, any()} | :error

Default result encoding mode for all resources in this domain.

Determines how the result returned from the action MFA call is encoded before being returned to the caller.

• :struct — Return the Ash resource struct as-is (default)
• :map — Convert the Ash resource struct to a map containing only public fields (using Ash.Resource.Info.public_fields/1 to filter; falls back to Map.from_struct/1 for non-Ash-resource structs)
• {Module, :function, args} — Custom encoder MFA. The function receives the result as its first argument, followed by args, and must return the encoded result.

Individual resources and actions can override this with their own result_encoder option.

For :map encoding, Ash resource structs are converted to maps containing only their public fields (attributes, calculations, aggregates, relationships). Lists of structs are mapped accordingly. Non-Ash-resource structs fall back to Map.from_struct/1. For custom MFA encoders, the function receives the result and must return the encoded value.

Defaults to :struct.

@spec gen_api_result_encoder!(dsl_or_extended :: module() | map()) ::
  any() | no_return()

Default result encoding mode for all resources in this domain.

Determines how the result returned from the action MFA call is encoded before being returned to the caller.

• :struct — Return the Ash resource struct as-is (default)
• :map — Convert the Ash resource struct to a map containing only public fields (using Ash.Resource.Info.public_fields/1 to filter; falls back to Map.from_struct/1 for non-Ash-resource structs)
• {Module, :function, args} — Custom encoder MFA. The function receives the result as its first argument, followed by args, and must return the encoded result.

Individual resources and actions can override this with their own result_encoder option.

For :map encoding, Ash resource structs are converted to maps containing only their public fields (attributes, calculations, aggregates, relationships). Lists of structs are mapped accordingly. Non-Ash-resource structs fall back to Map.from_struct/1. For custom MFA encoders, the function receives the result and must return the encoded value.

Defaults to :struct.

@spec gen_api_retry(dsl_or_extended :: module() | map()) :: {:ok, any()} | :error

Default retry configuration for all resources in this domain.

• nil - No retry (default)
• A positive number n - Equivalent to {:all_nodes, n}
• {:same_node, n} - Retry on the same node(s)
• {:all_nodes, n} - Retry across all available nodes

@spec gen_api_retry!(dsl_or_extended :: module() | map()) :: any() | no_return()

Default retry configuration for all resources in this domain.

• nil - No retry (default)
• A positive number n - Equivalent to {:all_nodes, n}
• {:same_node, n} - Retry on the same node(s)
• {:all_nodes, n} - Retry across all available nodes

@spec gen_api_service(dsl_or_extended :: module() | map()) :: {:ok, any()} | :error

The service name for this domain's API endpoints. This serves as the default for all resources in the domain.

Accepts a string or atom. Example: "chat", "user_service", :notification

@spec gen_api_service!(dsl_or_extended :: module() | map()) :: any() | no_return()

The service name for this domain's API endpoints. This serves as the default for all resources in the domain.

Accepts a string or atom. Example: "chat", "user_service", :notification

@spec gen_api_supporter_module(dsl_or_extended :: module() | map()) ::
  {:ok, atom()} | :error

The name of the module to generate that will serve as the PhoenixGenApi supporter for this domain.

This module will be auto-generated with functions:

• get_config/1 - Returns {:ok, fun_configs()} for PhoenixGenApi pull
• get_config_version/1 - Returns {:ok, version} for version checking
• fun_configs/0 - Returns the aggregated list of FunConfig structs
• list_request_types/0 - Returns all available request type strings
• get_fun_config/1 - Returns a specific FunConfig by request_type

Example: MyApp.Chat.GenApiSupporter

@spec gen_api_supporter_module!(dsl_or_extended :: module() | map()) ::
  atom() | no_return()

The name of the module to generate that will serve as the PhoenixGenApi supporter for this domain.

This module will be auto-generated with functions:

• get_config/1 - Returns {:ok, fun_configs()} for PhoenixGenApi pull
• get_config_version/1 - Returns {:ok, version} for version checking
• fun_configs/0 - Returns the aggregated list of FunConfig structs
• list_request_types/0 - Returns all available request type strings
• get_fun_config/1 - Returns a specific FunConfig by request_type

Example: MyApp.Chat.GenApiSupporter

@spec gen_api_timeout(dsl_or_extended :: module() | map()) :: {:ok, any()} | :error

Default timeout in milliseconds for all resources in this domain. Individual resources and actions can override this.

Accepts a positive integer or :infinity.

@spec gen_api_timeout!(dsl_or_extended :: module() | map()) :: any() | no_return()

Default timeout in milliseconds for all resources in this domain. Individual resources and actions can override this.

Accepts a positive integer or :infinity.

@spec gen_api_version(dsl_or_extended :: module() | map()) ::
  {:ok, String.t()} | :error

Default version string for all resources in this domain. Used for PhoenixGenApi API versioning.

@spec gen_api_version!(dsl_or_extended :: module() | map()) ::
  String.t() | no_return()

Default version string for all resources in this domain. Used for PhoenixGenApi API versioning.

@spec has_gen_api?(module()) :: boolean()

Checks if a domain has the gen_api extension configured.

Returns true if the domain uses the AshPhoenixGenApi.Domain extension and has a gen_api section configured, false otherwise.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.has_gen_api?(MyApp.Chat)
true

iex> AshPhoenixGenApi.Domain.Info.has_gen_api?(MyApp.SomeOtherDomain)
false

@spec nodes(module()) :: [atom()] | {module(), atom(), [any()]} | :local

Gets the effective default nodes for the domain.

Returns the nodes configured in the domain's gen_api section, or the built-in default of :local if not configured.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.nodes(MyApp.Chat)
{ClusterHelper, :get_nodes, [:chat]}

@spec permission_callback(module()) :: {module(), atom(), [any()]} | nil

Gets the default permission callback MFA for the domain.

Returns the permission_callback configured in the domain's gen_api section, or nil if not configured.

When set, permission_callback takes precedence over check_permission and is stored in the FunConfig's permission_callback field.

The callback function receives a map with request context (same params as FunConfig) and returns true (continue) or false (permission denied).

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.permission_callback(MyApp.Chat)
nil

iex> AshPhoenixGenApi.Domain.Info.permission_callback(MyApp.Chat)
{MyApp.Permissions, :check, []}

@spec push_nodes(module()) :: [atom()] | {module(), atom(), [any()]} | nil

Gets the push_nodes configuration for the domain.

Returns the push_nodes configured in the domain's gen_api section, or nil if not configured.

Can be:

• A list of node atoms: [:"gateway1@host", :"gateway2@host"]
• An MFA tuple that returns a node list at runtime: {ClusterHelper, :get_gateway_nodes, []}
• nil - No push nodes configured (default)

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.push_nodes(MyApp.Chat)
[:"gateway1@host", :"gateway2@host"]

iex> AshPhoenixGenApi.Domain.Info.push_nodes(MyApp.Chat)
{ClusterHelper, :get_gateway_nodes, []}

@spec push_on_startup?(module()) :: boolean()

Checks whether push_on_startup is enabled for the domain.

Returns true if gen_api push_on_startup is true, false otherwise (the default).

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.push_on_startup?(MyApp.Chat)
false

@spec request_info(module()) :: boolean()

Gets the effective default request_info for the domain.

Returns the request_info configured in the domain's gen_api section, or the built-in default of true if not configured.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.request_info(MyApp.Chat)
true

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

Gets all resources in the domain that have the AshPhoenixGenApi.Resource extension configured.

Returns a list of resource modules that have gen_api configured.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.resources_with_gen_api(MyApp.Chat)
[MyApp.Chat.DirectMessage, MyApp.Chat.GroupMessage]

@spec response_type(module()) :: :sync | :async | :stream | :none

Gets the effective default response_type for the domain.

Returns the response_type configured in the domain's gen_api section, or the built-in default of :async if not configured.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.response_type(MyApp.Chat)
:async

@spec result_encoder(module()) :: :struct | :map | {module(), atom(), [any()]} | nil

Gets the default result_encoder for this domain.

The result_encoder determines how the result returned from the action MFA call is encoded before being returned to the caller:

• :struct — Return the Ash resource struct as-is (default)
• :map — Convert the Ash resource struct to a map containing only public fields (using Ash.Resource.Info.public_fields/1 to filter; falls back to Map.from_struct/1 for non-Ash-resource structs)
• {Module, :function, args} — Custom encoder MFA

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.result_encoder(MyApp.Chat)
:struct

iex> AshPhoenixGenApi.Domain.Info.result_encoder(MyApp.Chat)
:map

@spec retry(module()) ::
  nil
  | pos_integer()
  | {:same_node, pos_integer()}
  | {:all_nodes, pos_integer()}

Gets the effective default retry for the domain.

Returns the retry configured in the domain's gen_api section, or nil if not configured.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.retry(MyApp.Chat)
nil

@spec service(module()) :: String.t() | atom() | nil

Gets the service name for the domain.

Returns the service name configured in the domain's gen_api section, or nil if not configured.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.service(MyApp.Chat)
"chat"

@spec summary(module()) :: map()

Gets a summary of the domain's PhoenixGenApi configuration.

Returns a map with the domain's gen_api settings and a list of resources with their request types.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.summary(MyApp.Chat)
%{
  service: "chat",
  version: "0.0.1",
  supporter_module: MyApp.Chat.GenApiSupporter,
  total_fun_configs: 5,
  resources: [
    %{resource: MyApp.Chat.DirectMessage, request_types: ["send_direct_message", ...]},
    %{resource: MyApp.Chat.GroupMessage, request_types: ["send_group_message", ...]}
  ]
}

@spec supporter_module(module()) :: module() | nil

Gets the supporter module name for the domain.

Returns the module name configured in gen_api supporter_module, or nil if the domain doesn't have gen_api configured.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.supporter_module(MyApp.Chat)
MyApp.Chat.GenApiSupporter

@spec timeout(module()) :: pos_integer() | :infinity

Gets the effective default timeout for the domain.

Returns the timeout configured in the domain's gen_api section, or the built-in default of 5000 if not configured.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.timeout(MyApp.Chat)
5000

@spec version(module()) :: String.t()

Gets the version string for the domain.

Returns the version configured in the domain's gen_api section, or the default "0.0.1" if not configured.

Parameters

• domain - The Ash domain module

Examples

iex> AshPhoenixGenApi.Domain.Info.version(MyApp.Chat)
"0.0.1"