AshPhoenixGenApi (ash_phoenix_gen_api v1.0.3)

Copy Markdown View Source

Ash extension for generating PhoenixGenApi function configurations from Ash resources.

AshPhoenixGenApi bridges the Ash Framework and PhoenixGenApi by allowing you to define PhoenixGenApi endpoints directly in your Ash resource and domain DSLs. It automatically generates PhoenixGenApi.Structs.FunConfig structs from your Ash actions, including type mappings, argument ordering, and configuration defaults.

Architecture

Resource Extension (AshPhoenixGenApi.Resource)

Added to Ash resources to define which actions should be exposed as PhoenixGenApi endpoints. Each action is configured with routing, timeout, permission, and other settings.

Domain Extension (AshPhoenixGenApi.Domain)

Added to Ash domains to provide domain-level defaults and auto-generate a "supporter" module that aggregates FunConfigs from all resources. The supporter module implements the PhoenixGenApi client config interface (get_config/1, get_config_version/1), allowing gateway nodes to pull API configurations.

Quick Start

# In your resource:
defmodule MyApp.Chat.DirectMessage do
  use Ash.Resource,
    extensions: [AshPhoenixGenApi.Resource]

  gen_api do
    service "chat"
    nodes {ClusterHelper, :get_nodes, [:chat]}
    choose_node_mode :random
    timeout 5_000

    action :send_direct_message do
      request_type "send_direct_message"
      timeout 10_000
      check_permission {:arg, "from_user_id"}
    end

    action :create do
      # Minimal config — request_type and args are auto-derived
    end
  end
end

# In your domain:
defmodule MyApp.Chat do
  use Ash.Domain,
    extensions: [AshPhoenixGenApi.Domain]

  gen_api do
    service "chat"
    nodes {ClusterHelper, :get_nodes, [:chat]}
    version "0.0.1"
    supporter_module MyApp.Chat.GenApiSupporter
  end

  resources do
    resource MyApp.Chat.DirectMessage
  end
end

# The supporter module is auto-generated:
MyApp.Chat.GenApiSupporter.fun_configs()
MyApp.Chat.GenApiSupporter.get_config(:gateway_1)
MyApp.Chat.GenApiSupporter.get_config_version(:gateway_1)

# On the gateway node (config.exs):
config :phoenix_gen_api, :gen_api,
  service_configs: [
    %{
      service: "chat",
      nodes: {ClusterHelper, :get_nodes, [:chat]},
      module: MyApp.Chat.GenApiSupporter,
      function: :get_config,
      args: [:gateway_1]
    }
  ]

Type Mapping

Ash types are automatically mapped to PhoenixGenApi argument types:

Ash TypePhoenixGenApi Type
:string, :uuid, :date, etc.:string
{:string, max_length}{:string, max_bytes}
:integer, :float, :decimal:num
:boolean:boolean
:datetime, :utc_datetime:datetime
:naive_datetime:naive_datetime
:map, :json, :struct, :keyword:map
{:map, max_items}{:map, max_items}
{:array, :string}, {:array, :uuid}{:list_string, max_items, max_item_length}
{:array, :integer}, {:array, :float}{:list_num, max_items}
{:array, :map}, {:array, :boolean}, etc.{:list, max_items}

See AshPhoenixGenApi.TypeMapper for the complete mapping table.

Modules

Summary

Functions

defaults()

Returns the built-in defaults for the gen_api DSL section.

extensions()

Returns the list of Spark DSL extensions provided by AshPhoenixGenApi.

modules()

Lists all modules that are part of the AshPhoenixGenApi extension.

version()

Returns the version of the AshPhoenixGenApi library.

Functions

defaults()

@spec defaults() :: map()

Returns the built-in defaults for the gen_api DSL section.

These defaults are used when no explicit value is provided at any level:

  • timeout — 5000 (5 seconds)
  • response_type — :async
  • request_info — true
  • check_permission — false
  • permission_callback — nil (no custom callback)
  • choose_node_mode — :random
  • nodes — :local
  • version — "0.0.1"
  • retry — nil (no retry)
  • code_interface? — true (auto-generate code interface functions)
  • push_nodes — nil (no push nodes)
  • push_on_startup — false
  • result_encoder — :struct (return Ash resource struct as-is)

extensions()

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

Returns the list of Spark DSL extensions provided by AshPhoenixGenApi.

These are the extensions you add to your Ash resources and domains:

Examples

iex> AshPhoenixGenApi.extensions()
[AshPhoenixGenApi.Resource, AshPhoenixGenApi.Domain]

modules()

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

Lists all modules that are part of the AshPhoenixGenApi extension.

Returns a list of module atoms for the resource extension, domain extension, and their supporting modules.

Examples

iex> AshPhoenixGenApi.modules()
[
  AshPhoenixGenApi.Resource,
  AshPhoenixGenApi.Resource.Info,
  AshPhoenixGenApi.Resource.ActionConfig,
  AshPhoenixGenApi.Resource.SharedTypes,
  AshPhoenixGenApi.Resource.EffectiveField,
  AshPhoenixGenApi.Domain,
  AshPhoenixGenApi.Domain.Info,
  AshPhoenixGenApi.TypeMapper,
  ...
]

version()

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

Returns the version of the AshPhoenixGenApi library.