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-:prodor: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. Seefcm_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 theapplicationServerKeyyour front end uses.
Testing
:delivery-:live(default) or:test— record sends locally instead of contacting the providers; seePushX.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 use1in 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;:infinitydisables). 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); seePushX.ReconnectGuard. ManualPushX.reconnect/0is not gated.
Batch Sending
:batch_concurrency- Default:concurrencyforPushX.push_batch/4,push_batch_stream/4and the providersend_batch/3functions (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:webpushkey 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 asapply(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(defaultfalse) lets Web Push subscriptions carry plainhttp://endpoints (RFC 8030 requires TLS, so production rejects them as:invalid_token);:finch_version_overridemakes 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
@spec apns_configured?() :: boolean()
Checks if APNS is configured.
@spec apns_key_id() :: String.t()
Gets the APNS Key ID.
@spec apns_mode() :: :prod | :sandbox
Gets the APNS mode (:prod or :sandbox).
@spec apns_private_key() :: String.t()
Gets the APNS private key content. Supports file paths, environment variables, and raw strings.
@spec apns_team_id() :: String.t()
Gets the APNS Team ID.
@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.
@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.
@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.
@spec circuit_breaker_enabled?() :: boolean()
Checks if the circuit breaker is enabled.
Default: false (opt-in feature).
@spec circuit_breaker_threshold() :: pos_integer()
Gets the number of consecutive failures before the circuit opens. Default: 5.
@spec connect_timeout() :: pos_integer()
Gets the TCP connection timeout in milliseconds. Default: 10 seconds.
@spec delivery() :: :live | :test
Delivery mode: :live (default) sends to the providers; :test records
sends locally instead — see PushX.Test.
@spec fcm_configured?() :: boolean()
Checks if FCM is configured.
Gets the FCM credentials for Goth. Returns a map suitable for Goth configuration.
@spec fcm_project_id() :: String.t()
Gets the FCM project ID.
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)
endThe 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.
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.
@spec finch_name() :: atom()
Gets the Finch pool name.
@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)
@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)
@spec finch_request_opts() :: keyword()
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.
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, []}
@spec pool_timeout() :: pos_integer()
Gets the pool timeout (time to wait for a connection from pool) in milliseconds. Default: 5 seconds.
@spec receive_timeout() :: pos_integer()
Gets the receive timeout (time to wait for response data) in milliseconds. Default: 15 seconds.
@spec retry_base_delay_ms() :: pos_integer()
Gets the base delay for exponential backoff in milliseconds. Default: 10 seconds (Google's recommended minimum).
@spec retry_enabled?() :: boolean()
Checks if retry is enabled.
@spec retry_max_attempts() :: pos_integer()
Gets the maximum number of retry attempts.
@spec retry_max_delay_ms() :: pos_integer()
Gets the maximum delay for exponential backoff in milliseconds. Default: 60 seconds.
@spec webpush_configured?() :: boolean()
Checks if Web Push (VAPID subject + private key) is configured.