@spec add_global_limit(map()) :: :ok

Adds a single global rate limit at runtime.

If a limit with the same :key already exists, it will be replaced.

Parameters

• limit - A map with :key, :max_requests, and :window_ms

Returns

• :ok - Limit was added

Examples

PhoenixGenApi.add_global_limit(%{
  key: :ip_address,
  max_requests: 100,
  window_ms: 60_000
})

@spec attach_telemetry(String.t(), function(), map()) :: :ok

Attaches a telemetry handler to all PhoenixGenApi events.

This is a convenience function that attaches handlers to both executor and rate limiter events with a single call.

Events

Executor Events

• [:phoenix_gen_api, :executor, :request, :start]
• [:phoenix_gen_api, :executor, :request, :stop]
• [:phoenix_gen_api, :executor, :request, :exception]

Rate Limiter Events

• [:phoenix_gen_api, :rate_limiter, :check]
• [:phoenix_gen_api, :rate_limiter, :exceeded]
• [:phoenix_gen_api, :rate_limiter, :reset]
• [:phoenix_gen_api, :rate_limiter, :cleanup]

Parameters

• handler_id - A unique string identifier for the handler
• function - A 4-arity function: fn(event, measurements, metadata, config) -> any end
• config - Optional configuration map passed to the handler (default: %{})

Examples

# Attach a simple logging handler
PhoenixGenApi.attach_telemetry("my-app", fn event, measurements, metadata, _config ->
  ...
end)

# Attach with custom config
PhoenixGenApi.attach_telemetry("metrics", &MyApp.Metrics.handle_event/4, %{prefix: "phoenix_gen_api"})

[Shell Helper] Quick view of ConfigDb cache status.

Usage in IEx

iex> PhoenixGenApi.cache_status()

@spec call_flow(String.t() | atom(), String.t(), String.t() | nil) :: map()

[Shell Helper] Traces the call flow for a service/request_type from the gateway to its target nodes.

Usage in IEx

iex> PhoenixGenApi.call_flow("user_service", "get_user")

[Shell Helper] Print a formatted call flow trace to the console.

Usage in IEx

iex> PhoenixGenApi.call_flow_print("user_service", "get_user")
iex> PhoenixGenApi.call_flow_print("user_service", "get_user", "1.0.0")

@spec check_rate_limit(PhoenixGenApi.Structs.Request.t()) ::
  :ok | {:error, :rate_limited, map()}

Checks rate limit for a request.

This function checks both global and per-API rate limits. It is automatically called during request execution, but can also be called manually for custom rate limiting logic.

Parameters

• request - The Request struct to check

Returns

• :ok - Request is within all rate limits
• {:error, :rate_limited, details} - Request exceeds a rate limit

Examples

request = %Request{user_id: "user_123", service: "my_service", request_type: "my_api"}

case PhoenixGenApi.check_rate_limit(request) do
  :ok ->
    # Proceed with execution

  {:error, :rate_limited, details} ->
    # Handle rate limit exceeded
end

@spec cleanup_failed_configs() :: non_neg_integer()

Cleans up expired failed config entries (older than 24h). Returns the number of entries removed.

@spec clear_failed_configs() :: :ok

Clears all failed config entries regardless of expiry.

[Shell Helper] Print a formatted cluster topology view to the console.

Usage in IEx

iex> PhoenixGenApi.cluster_print()

@spec cluster_view() :: map()

[Shell Helper] Returns the cluster topology view from this node.

Usage in IEx

iex> PhoenixGenApi.cluster_view()

[Shell Helper] Print a formatted debug report to the console.

Usage in IEx

iex> PhoenixGenApi.debug_print(process_limit: 10)

@spec debug_report(keyword()) :: map()

Returns a debug-oriented runtime report.

Delegates to PhoenixGenApi.Diagnostics.debug_report/1.

@spec detach_telemetry(String.t()) :: :ok

Detaches all telemetry handlers with the given ID.

Parameters

• handler_id - The handler ID used when attaching

Examples

PhoenixGenApi.detach_telemetry("my-app")

[Shell Helper] Quick view of failed FunConfig entries.

Shows configs that failed validation during pull or push, with their service, request_type, version, source, node, and reason.

Usage in IEx

iex> PhoenixGenApi.failed_configs()
iex> PhoenixGenApi.failed_configs(source: :pull)
iex> PhoenixGenApi.failed_configs(source: :push, limit: 20)

[Shell Helper] Print a formatted table of failed FunConfig entries to the console.

Usage in IEx

iex> PhoenixGenApi.failed_configs_print()
iex> PhoenixGenApi.failed_configs_print(source: :pull, limit: 10)

[Shell Helper] Print a summary of failed FunConfig entries to the console.

Usage in IEx

iex> PhoenixGenApi.failed_configs_summary()

[Shell Helper] Print a formatted list of all registered call flows.

Usage in IEx

iex> PhoenixGenApi.flows_print()
iex> PhoenixGenApi.flows_print(include_disabled: true)

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

Gets the current global rate limits (may differ from config.exs if changed at runtime).

Returns

A list of global rate limit maps.

Examples

PhoenixGenApi.get_global_limits()
# => [%{key: :user_id, max_requests: 2000, window_ms: 60_000}]

@spec get_rate_limit_config() :: %{global: list(), api: list()}

Gets all configured rate limits.

Returns

A map with :global and :api keys containing the configured limits.

@spec get_rate_limit_status(
  String.t(),
  :global | {String.t() | atom(), String.t()},
  atom() | String.t()
) :: map()

Gets current rate limit status for a key.

Returns

A list of maps with current usage information for all applicable rate limits.

@spec health_check(keyword()) :: map()

Returns a runtime health check for the VM, distribution, and PhoenixGenApi processes.

Delegates to PhoenixGenApi.Diagnostics.health_check/1.

[Shell Helper] Print a formatted health check summary to the console.

Usage in IEx

iex> PhoenixGenApi.health_print()
iex> PhoenixGenApi.health_print(max_memory_bytes: 100_000_000)

[Shell Helper] Print a formatted request inspection to the console.

Usage in IEx

iex> PhoenixGenApi.inspect_print(%{service: "user_service", request_type: "get_user"})

@spec inspect_request(map()) :: map()

[Shell Helper] Inspects a request and returns its full execution plan.

Usage in IEx

iex> PhoenixGenApi.inspect_request(%{service: "user_service", request_type: "get_user"})

@spec list_call_flows(keyword()) :: [map()]

[Shell Helper] Lists all registered call flows across all services.

Usage in IEx

iex> PhoenixGenApi.list_call_flows()
iex> PhoenixGenApi.list_call_flows(include_disabled: true)

[Shell Helper] Quick view of Worker Pool status.

Usage in IEx

iex> PhoenixGenApi.pool_status()

@spec push_config(
  PhoenixGenApi.Structs.PushConfig.t() | map(),
  keyword()
) :: {:ok, :accepted} | {:ok, :skipped, term()} | {:error, term()}

Pushes a PushConfig to this server node.

This is the server-side API for receiving pushed configs from remote nodes. Remote nodes should use ConfigPusher.push/2 or ConfigPusher.push_on_startup/3 instead, which make RPC calls to this function.

Parameters

• push_config - A %PushConfig{} struct or map that can be decoded into one
• opts - Options keyword list:
  • :force - Force push even if version matches (default: false)

Returns

• {:ok, :accepted} - New configs were stored successfully
• {:ok, :skipped, reason} - Push was skipped (e.g., version matches)
• {:error, reason} - Push failed (validation error, etc.)

Examples

alias PhoenixGenApi.Structs.PushConfig

push_config = %PushConfig{
  service: "my_service",
  nodes: [:"node1@host"],
  config_version: "1.0.0",
  fun_configs: [%FunConfig{...}]
}

{:ok, :accepted} = PhoenixGenApi.push_config(push_config)
{:ok, :skipped, :version_matches} = PhoenixGenApi.push_config(push_config)
{:ok, :accepted} = PhoenixGenApi.push_config(push_config, force: true)

[Shell Helper] Quick view of pushed services status.

Shows all services that have been registered via push, along with their config versions and auto-pull registration status.

Usage in IEx

iex> PhoenixGenApi.pushed_services_status()

@spec remove_global_limit(atom() | String.t()) :: :ok

Removes a global rate limit by key at runtime.

Parameters

• key - The rate limit key to remove (:user_id, :device_id, etc.)

Returns

• :ok - Limit was removed (or didn't exist)

Examples

PhoenixGenApi.remove_global_limit(:ip_address)

@spec reset_rate_limit(
  String.t(),
  :global | {String.t() | atom(), String.t()},
  atom() | String.t()
) :: :ok

Resets rate limit counters for a specific key.

Parameters

• key_value - The key value to reset (e.g., user ID)
• scope - Either :global or {service, request_type} tuple
• rate_limit_key - The type of key (:user_id, :device_id, etc.)

Returns

• :ok - Counters were reset

Examples

# Reset all rate limits for a user
PhoenixGenApi.reset_rate_limit("user_123", :global, :user_id)

# Reset API-specific rate limit
PhoenixGenApi.reset_rate_limit("user_123", {"my_service", "my_api"}, :user_id)

[Shell Helper] Quick view of current rate limit configuration.

Usage in IEx

iex> PhoenixGenApi.rl_config()

[Shell Helper] Quick view and management of global rate limits.

Usage in IEx

# View current global limits
iex> PhoenixGenApi.rl_global()

# Set new global limits
iex> PhoenixGenApi.rl_global([%{key: :user_id, max_requests: 2000, window_ms: 60_000}])

# Add a single limit
iex> PhoenixGenApi.rl_global(:add, %{key: :ip_address, max_requests: 100, window_ms: 60_000})

# Remove a limit by key
iex> PhoenixGenApi.rl_global(:remove, :ip_address)

[Shell Helper] Quick view of rate limit status for a user.

Usage in IEx

iex> PhoenixGenApi.rl_status("user_123")

@spec set_global_limits([map()]) :: :ok

Sets (replaces) all global rate limits at runtime.

Parameters

• limits - A list of global rate limit maps, each with:
  • :key - The rate limit key (:user_id, :device_id, :ip_address, or custom string)
  • :max_requests - Maximum requests allowed in the window
  • :window_ms - Window duration in milliseconds

Returns

• :ok - Limits were updated

Examples

PhoenixGenApi.set_global_limits([
  %{key: :user_id, max_requests: 2000, window_ms: 60_000},
  %{key: :device_id, max_requests: 10000, window_ms: 60_000}
])

@spec statistics(keyword()) :: map()

Returns runtime VM and PhoenixGenApi statistics.

Delegates to PhoenixGenApi.Diagnostics.statistics/1.

[Shell Helper] Print formatted VM and PhoenixGenApi statistics to the console.

Usage in IEx

iex> PhoenixGenApi.stats_print()

@spec stop_stream(pid()) :: :ok

Stops an active streaming call.

This function gracefully terminates a streaming call process and sends a completion message to the receiver. The stream call process is identified by its PID.

Parameters

• stream_pid - The PID of the streaming call process to stop

Returns

• :ok - The stop signal was sent successfully

Examples

# Start a stream
{:ok, stream_pid} = StreamCall.start_link(%{
  request: request,
  fun_config: config,
  receiver: self()
})

# Later, stop the stream
PhoenixGenApi.stop_stream(stream_pid)

# Receive the completion message
receive do
  {:stream_response, response} ->
    assert response.has_more == false
end

Notes

• The stream call will send a completion response to its receiver before terminating
• This does not notify the data generator process; it only stops the stream relay
• If you need to stop the data generation itself, handle that in your generator function

@spec stop_trace(
  term(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Disables legacy Erlang tracing for processes or ports.

Requires the :disable_tracing admin action.

@spec stop_trace_functions(term()) :: {:ok, map()} | {:error, term()}

Disables call tracing for specific MFAs.

Requires the :disable_tracing admin action.

@spec trace_functions(
  term(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Enables call tracing for specific MFAs.

Requires the :enable_tracing admin action.

@spec trace_processes(
  term(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Enables legacy Erlang tracing for processes or ports.

Requires the :enable_tracing admin action.

@spec trace_status() :: map()

Returns a small trace status snapshot.

@spec update_rate_limit_config(map()) :: :ok

Updates rate limit configuration at runtime.

Parameters

• config - A map with :global_limits and/or :api_limits keys

Returns

• :ok - Configuration was updated

Examples

PhoenixGenApi.update_rate_limit_config(%{
  global_limits: [
    %{key: :user_id, max_requests: 2000, window_ms: 60_000}
  ]
})

@spec verify_config(String.t() | atom(), String.t()) ::
  {:ok, :matched} | {:ok, :mismatch, String.t()} | {:error, :not_found}

Verifies that the server has the given service and config version.

Useful for checking whether a push is necessary before sending the full configuration. Remote nodes should use ConfigPusher.verify/3 instead.

Parameters

• service - The service name (string or atom)
• config_version - The config version string to verify

Returns

• {:ok, :matched} - Version matches what is stored
• {:ok, :mismatch, stored_version} - Version differs from what is stored
• {:error, :not_found} - Service is not known

Examples

{:ok, :matched} = PhoenixGenApi.verify_config("my_service", "1.0.0")
{:ok, :mismatch, "0.9.0"} = PhoenixGenApi.verify_config("my_service", "1.0.0")
{:error, :not_found} = PhoenixGenApi.verify_config("unknown_service", "1.0.0")