PhoenixKit.Modules.Emails.SQSPollingManager (phoenix_kit v1.7.62)

Copy Markdown View Source

Manager module for SQS polling via Oban jobs.

This module provides a unified API for managing SQS polling that can be enabled/disabled dynamically without application restart.

Features

  • Enable/Disable Polling: Start or stop polling without restart
  • Manual Triggering: Force immediate polling when needed
  • Status Monitoring: Get current polling status and job information
  • Settings Integration: Automatically uses PhoenixKit Settings
  • Interval Control: Dynamically adjust polling frequency

Architecture

Instead of using a GenServer, this manager uses Oban jobs for polling:

  • Each job polls SQS once and schedules the next job
  • Jobs check settings before executing (dynamic control)
  • No need to restart GenServer when settings change

Usage

# Enable polling
iex> PhoenixKit.Modules.Emails.SQSPollingManager.enable_polling()
{:ok, %Oban.Job{}}

# Disable polling
iex> PhoenixKit.Modules.Emails.SQSPollingManager.disable_polling()
:ok

# Check status
iex> PhoenixKit.Modules.Emails.SQSPollingManager.status()
%{
  enabled: true,
  interval_ms: 5000,
  pending_jobs: 1,
  last_run: ~U[2025-09-20 15:30:45Z],
  queue_url: "https://sqs.eu-north-1.amazonaws.com/..."
}

# Trigger immediate poll
iex> PhoenixKit.Modules.Emails.SQSPollingManager.poll_now()
{:ok, %Oban.Job{}}

# Change polling interval
iex> PhoenixKit.Modules.Emails.SQSPollingManager.set_polling_interval(3000)
{:ok, %Setting{}}

Integration

This manager works alongside the existing SQSWorker for backward compatibility. The SQSWorker can delegate to this manager when needed.

Summary

Functions

disable_polling()

Disables SQS polling by updating the configuration.

enable_polling()

Enables SQS polling by setting the configuration and starting the first job.

poll_now()

Triggers an immediate polling job.

set_polling_interval(interval_ms)

Sets the polling interval in milliseconds.

status()

Returns the current status of SQS polling.

Functions

disable_polling()

Disables SQS polling by updating the configuration.

Note: Existing scheduled jobs will check this setting and skip execution.

Returns

  • :ok - Successfully disabled

Examples

iex> PhoenixKit.Modules.Emails.SQSPollingManager.disable_polling()
:ok

enable_polling()

Enables SQS polling by setting the configuration and starting the first job.

Returns

  • {:ok, job} - Successfully enabled and started first job
  • {:error, reason} - Failed to enable polling

Examples

iex> PhoenixKit.Modules.Emails.SQSPollingManager.enable_polling()
{:ok, %Oban.Job{id: 1, queue: "sqs_polling"}}

poll_now()

Triggers an immediate polling job.

This creates a new job that will execute as soon as possible, regardless of the normal polling schedule.

Returns

  • {:ok, job} - Successfully created immediate job
  • {:error, reason} - Failed to create job

Examples

iex> PhoenixKit.Modules.Emails.SQSPollingManager.poll_now()
{:ok, %Oban.Job{}}

set_polling_interval(interval_ms)

Sets the polling interval in milliseconds.

The new interval will be used for subsequent job scheduling.

Parameters

  • interval_ms - Interval in milliseconds (minimum 1000ms)

Returns

  • {:ok, setting} - Successfully updated
  • {:error, reason} - Failed to update

Examples

iex> PhoenixKit.Modules.Emails.SQSPollingManager.set_polling_interval(3000)
{:ok, %Setting{}}

status()

Returns the current status of SQS polling.

Returns

A map with:

  • enabled - Whether polling is enabled
  • interval_ms - Current polling interval
  • pending_jobs - Number of scheduled jobs
  • last_run - Timestamp of last completed job (if any)
  • queue_url - Configured SQS queue URL

Examples

iex> PhoenixKit.Modules.Emails.SQSPollingManager.status()
%{
  enabled: true,
  interval_ms: 5000,
  pending_jobs: 1,
  last_run: ~U[2025-09-20 15:30:45Z],
  queue_url: "https://sqs.eu-north-1.amazonaws.com/..."
}