PushX.Config (PushX v1.0.0)

Copy Markdown View Source

Configuration management for PushX.

Configuration Options

APNS (Apple Push Notification Service)

  • :apns_key_id - The Key ID from Apple Developer Portal
  • :apns_team_id - Your Apple Developer Team ID
  • :apns_private_key - The private key, either:
    • A raw PEM string
    • {:file, "/path/to/AuthKey.p8"}
    • {:system, "ENV_VAR_NAME"}
  • :apns_mode - :prod or :sandbox (default: :prod)

FCM (Firebase Cloud Messaging)

  • :fcm_project_id - Your Firebase project ID
  • :fcm_credentials - Service account credentials, either:
    • {:file, "/path/to/service-account.json"}
    • {:json, "...json string..."}
    • {:system, "ENV_VAR_NAME"} (expects JSON string)
  • :fcm_token_fetcher - (optional, advanced) bring your own OAuth: an {module, function, args} tuple that replaces the Goth process PushX would otherwise start. See fcm_token_fetcher/0.

Web Push (VAPID)

  • :webpush_vapid_subject - contact for push services: "mailto:..." or an https URL
  • :webpush_vapid_private_key - base64url 32-byte scalar (web-push CLI format) or EC PEM
  • :webpush_vapid_public_key - (optional) base64url 65-byte point; derived from the private key when omitted. This is the applicationServerKey your front end uses.

Testing

  • :delivery - :live (default) or :test — record sends locally instead of contacting the providers; see PushX.Test

Finch Pool

  • :finch_name - Name of the Finch pool (default: PushX.Finch)
  • :finch_pool_count - HTTP/2 connections per provider origin (APNS, FCM): each Finch HTTP/2 "pool" is one multiplexed connection, so this is the knob for APNS/FCM capacity and redundancy (default: 2; don't use 1 in production — a single socket is a single point of failure and a retry burst lands entirely on it)
  • :finch_pool_size - connections per pool for HTTP/1 pools only (the default pool used for Web Push and as a fallback); Finch ignores it for HTTP/2 (default: 25)
  • :finch_http2_ping_interval - HTTP/2 PING after this many ms of idleness to keep APNS/FCM connections alive and detect dead ones before a send does (default: 60_000; :infinity disables). Requires finch ≥ 0.22; on older finch the option is ignored with a warning at boot.
  • :finch_http2_max_connection_age - ms after which an HTTP/2 connection is gracefully drained and replaced (default: :infinity); useful behind rotating DNS / load balancers. finch ≥ 0.22.
  • :finch_http2_max_connection_age_jitter - random ms added to the age so connections don't all recycle together (default: 0). finch ≥ 0.22.
  • :finch_http2_wait_for_server_settings - hold requests on a fresh HTTP/2 connection until the server's SETTINGS arrived (default: false; requests sent before SETTINGS fail fast with :connection_not_ready, which PushX retries). finch ≥ 0.22.

Request Timeouts

  • :receive_timeout - Timeout for receiving response in ms (default: 15_000)
  • :pool_timeout - Timeout for acquiring connection from pool in ms (default: 5_000)
  • :connect_timeout - TCP connection timeout in ms (default: 10_000)

Retry Settings

  • :retry_enabled - Enable automatic retry (default: true)
  • :retry_max_attempts - Maximum retry attempts (default: 3)
  • :retry_base_delay_ms - Base delay in milliseconds (default: 10_000)
  • :retry_max_delay_ms - Maximum delay in milliseconds (default: 60_000)
  • :reconnect_cooldown_ms - Minimum time between automatic Finch pool restarts triggered by connection errors, per pool (default: 5_000); see PushX.ReconnectGuard. Manual PushX.reconnect/0 is not gated.

Batch Sending

  • :batch_concurrency - Default :concurrency for PushX.push_batch/4, push_batch_stream/4 and the provider send_batch/3 functions (default: 50)

Circuit Breaker (opt-in)

  • :circuit_breaker_enabled - (default: false)
  • :circuit_breaker_threshold - consecutive failures that open the breaker (default: 5)
  • :circuit_breaker_cooldown_ms - open → half-open delay (default: 30_000)

See PushX.CircuitBreaker.

Rate Limiting (opt-in)

  • :rate_limit_enabled - (default: false)
  • :rate_limit_apns, :rate_limit_fcm, :rate_limit_webpush - max sends per window per provider (default: 5_000; the :webpush key spans every push service)
  • :rate_limit_window_ms - fixed window length (default: 1_000)

See PushX.RateLimiter.

Token Cleanup

  • :on_invalid_token - {module, function, args} invoked asynchronously as apply(module, function, [provider, token | args]) whenever a response says the token should be removed (PushX.Response.should_remove_token?/1); see the README's "Token Cleanup Callback".

Internal / test-only

  • :apns_url_override, :fcm_url_override - point the real send paths at a local HTTP server; :webpush_allow_http (default false) lets Web Push subscriptions carry plain http:// endpoints (RFC 8030 requires TLS, so production rejects them as :invalid_token); :finch_version_override makes the HTTP/2-option checks believe another finch version is installed. Used by PushX's own test suite; not for production. For testing your application use :delivery (PushX.Test) instead.

Example Configuration

config :pushx,
  apns_key_id: "ABC123DEFG",
  apns_team_id: "TEAM123456",
  apns_private_key: {:file, "priv/keys/AuthKey.p8"},
  apns_mode: :prod,
  fcm_project_id: "my-project-id",
  fcm_credentials: {:file, "priv/keys/firebase.json"}

Summary

Functions

Checks if APNS is configured.

Gets the APNS Key ID.

Gets the APNS mode (:prod or :sandbox).

Gets the APNS private key content. Supports file paths, environment variables, and raw strings.

Gets the APNS Team ID.

Default per-task timeout for batch sends, in milliseconds.

Like batch_timeout_ms/0, but for a specific per-call retry policy: retry: :none means a single attempt, so the budget is the 30 s floor.

Gets the cooldown time in milliseconds before the circuit transitions from :open to :half_open. Default: 30 seconds.

Checks if the circuit breaker is enabled. Default: false (opt-in feature).

Gets the number of consecutive failures before the circuit opens. Default: 5.

Gets the TCP connection timeout in milliseconds. Default: 10 seconds.

Delivery mode: :live (default) sends to the providers; :test records sends locally instead — see PushX.Test.

Checks if FCM is configured.

Gets the FCM credentials for Goth. Returns a map suitable for Goth configuration.

Gets the FCM project ID.

Returns the custom FCM OAuth token fetcher, if one is configured.

The Finch http2: pool options built from :finch_http2_* config (ping_interval, max_connection_age, max_connection_age_jitter, wait_for_server_settings?), or [] when the installed finch predates them (< 0.22). overrides (e.g. an instance's config) win over the global config.

Gets the Finch pool name.

Gets finch_pool_count: HTTP/2 connections per provider origin (APNS/FCM).

Gets finch_pool_size: connections in the HTTP/1 pool (Web Push) — ignored for the HTTP/2 pools (APNS/FCM).

Returns the Finch request options with configured timeouts.

Gets a configuration value.

Gets a required configuration value. Raises if the value is not configured.

Gets the callback for invalid token cleanup.

Gets the pool timeout (time to wait for a connection from pool) in milliseconds. Default: 5 seconds.

Gets the receive timeout (time to wait for response data) in milliseconds. Default: 15 seconds.

Gets the base delay for exponential backoff in milliseconds. Default: 10 seconds (Google's recommended minimum).

Checks if retry is enabled.

Gets the maximum number of retry attempts.

Gets the maximum delay for exponential backoff in milliseconds. Default: 60 seconds.

Checks if Web Push (VAPID subject + private key) is configured.

Functions

apns_configured?()

(since 0.1.0)
@spec apns_configured?() :: boolean()

Checks if APNS is configured.

apns_key_id()

(since 0.1.0)
@spec apns_key_id() :: String.t()

Gets the APNS Key ID.

apns_mode()

(since 0.1.0)
@spec apns_mode() :: :prod | :sandbox

Gets the APNS mode (:prod or :sandbox).

apns_private_key()

(since 0.1.0)
@spec apns_private_key() :: String.t()

Gets the APNS private key content. Supports file paths, environment variables, and raw strings.

apns_team_id()

(since 0.1.0)
@spec apns_team_id() :: String.t()

Gets the APNS Team ID.

batch_timeout_ms()

(since 0.12.0)
@spec batch_timeout_ms() :: pos_integer()

Default per-task timeout for batch sends, in milliseconds.

Retries block the sending task (see PushX.Retry), so a batch task can legitimately outlive any flat timeout while it backs off between attempts. When retries are enabled this covers the worst-case retry budget:

attempts × (receive_timeout + pool_timeout)
  + (attempts − 1) × max(retry_max_delay_ms, 60s rate-limit delay)

With retries disabled — globally (retry_enabled: false) or for the call (retry: :none, see batch_timeout_ms/1) — it is 30 seconds. An explicit :timeout option on PushX.push_batch/4 / send_batch/3 always takes precedence.

batch_timeout_ms(list)

(since 0.13.0)
@spec batch_timeout_ms([{:retry, :blocking | :none}]) :: pos_integer()

Like batch_timeout_ms/0, but for a specific per-call retry policy: retry: :none means a single attempt, so the budget is the 30 s floor.

circuit_breaker_cooldown_ms()

(since 0.8.0)
@spec circuit_breaker_cooldown_ms() :: pos_integer()

Gets the cooldown time in milliseconds before the circuit transitions from :open to :half_open. Default: 30 seconds.

circuit_breaker_enabled?()

(since 0.8.0)
@spec circuit_breaker_enabled?() :: boolean()

Checks if the circuit breaker is enabled. Default: false (opt-in feature).

circuit_breaker_threshold()

(since 0.8.0)
@spec circuit_breaker_threshold() :: pos_integer()

Gets the number of consecutive failures before the circuit opens. Default: 5.

connect_timeout()

(since 0.6.1)
@spec connect_timeout() :: pos_integer()

Gets the TCP connection timeout in milliseconds. Default: 10 seconds.

delivery()

(since 0.14.0)
@spec delivery() :: :live | :test

Delivery mode: :live (default) sends to the providers; :test records sends locally instead — see PushX.Test.

fcm_configured?()

(since 0.1.0)
@spec fcm_configured?() :: boolean()

Checks if FCM is configured.

fcm_credentials()

(since 0.1.0)
@spec fcm_credentials() :: map() | {:file, String.t()}

Gets the FCM credentials for Goth. Returns a map suitable for Goth configuration.

fcm_project_id()

(since 0.1.0)
@spec fcm_project_id() :: String.t()

Gets the FCM project ID.

fcm_token_fetcher()

(since 0.13.0)
@spec fcm_token_fetcher() :: {module(), atom(), list()} | nil

Returns the custom FCM OAuth token fetcher, if one is configured.

By default PushX starts a Goth process (PushX.Goth) from :fcm_credentials and calls Goth.fetch/1 before every FCM send. Set :fcm_token_fetcher to an {module, function, args} tuple to supply the OAuth access token yourself instead — for example to reuse a Goth process your application already runs, or to fetch tokens from a secrets service:

# config/runtime.exs
config :pushx,
  fcm_project_id: "my-project",
  fcm_token_fetcher: {MyApp.PushOAuth, :fetch, []}

defmodule MyApp.PushOAuth do
  # PushX passes the Goth name it would have used as the first argument;
  # a fetcher that reuses your own Goth simply ignores it.
  def fetch(_goth_name), do: Goth.fetch(MyApp.Goth)
end

The function is invoked as apply(module, function, [goth_name | args]) and must return {:ok, %{token: access_token}} or {:error, reason}. It runs on the send path, so keep it cheap (Goth caches; do the same). PushX guards the call: a fetcher that raises, exits, or returns {:error, _} is reported as a retryable :connection_error; one that returns any other shape as :auth_error. Neither escapes as an exception.

When a fetcher is set, PushX starts no PushX.Goth process and :fcm_credentials becomes optional. This option applies to the static configuration only: named FCM instances (PushX.Instance) authenticate with their own :credentials, or their own per-instance :token_fetcher config key — a global fetcher never silently takes over a tenant's OAuth. The test suite uses this seam to exercise the real FCM send path without Google.

finch_http2_opts(overrides \\ [])

(since 0.15.0)
@spec finch_http2_opts(keyword()) :: keyword()

The Finch http2: pool options built from :finch_http2_* config (ping_interval, max_connection_age, max_connection_age_jitter, wait_for_server_settings?), or [] when the installed finch predates them (< 0.22). overrides (e.g. an instance's config) win over the global config.

finch_name()

(since 0.1.0)
@spec finch_name() :: atom()

Gets the Finch pool name.

finch_pool_count()

(since 0.1.0)
@spec finch_pool_count() :: pos_integer()

Gets finch_pool_count: HTTP/2 connections per provider origin (APNS/FCM).

Default: 2 (increased from 1 in v0.6.0 to handle traffic bursts better)

finch_pool_size()

(since 0.1.0)
@spec finch_pool_size() :: pos_integer()

Gets finch_pool_size: connections in the HTTP/1 pool (Web Push) — ignored for the HTTP/2 pools (APNS/FCM).

Default: 25 (increased from 10 in v0.6.0 to handle traffic bursts better)

finch_request_opts()

(since 0.6.1)
@spec finch_request_opts() :: keyword()

Returns the Finch request options with configured timeouts.

get(key, default \\ nil)

(since 0.1.0)
@spec get(atom(), any()) :: any()

Gets a configuration value.

get!(key)

(since 0.1.0)
@spec get!(atom()) :: any()

Gets a required configuration value. Raises if the value is not configured.

on_invalid_token()

(since 0.8.0)
@spec on_invalid_token() :: {module(), atom(), list()} | nil

Gets the callback for invalid token cleanup.

When set, this MFA tuple is called asynchronously whenever a push returns :invalid_token, :expired_token, or :unregistered.

The callback receives (provider, token, ...extra_args).

Example

config :pushx,
  on_invalid_token: {MyApp.Push, :handle_invalid_token, []}

pool_timeout()

(since 0.6.1)
@spec pool_timeout() :: pos_integer()

Gets the pool timeout (time to wait for a connection from pool) in milliseconds. Default: 5 seconds.

receive_timeout()

(since 0.6.1)
@spec receive_timeout() :: pos_integer()

Gets the receive timeout (time to wait for response data) in milliseconds. Default: 15 seconds.

retry_base_delay_ms()

(since 0.2.0)
@spec retry_base_delay_ms() :: pos_integer()

Gets the base delay for exponential backoff in milliseconds. Default: 10 seconds (Google's recommended minimum).

retry_enabled?()

(since 0.2.0)
@spec retry_enabled?() :: boolean()

Checks if retry is enabled.

retry_max_attempts()

(since 0.2.0)
@spec retry_max_attempts() :: pos_integer()

Gets the maximum number of retry attempts.

retry_max_delay_ms()

(since 0.2.0)
@spec retry_max_delay_ms() :: pos_integer()

Gets the maximum delay for exponential backoff in milliseconds. Default: 60 seconds.

webpush_configured?()

(since 0.15.0)
@spec webpush_configured?() :: boolean()

Checks if Web Push (VAPID subject + private key) is configured.