@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 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 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")

@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.

[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 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 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")