ProtoRune.Bot.Poller (proto_rune v0.1.0)

A GenServer module that handles periodic polling of notifications for a bot, and dispatches these notifications to the appropriate handler functions within the bot.

The Poller connects to the ATProto or Bluesky notification systems and periodically polls for new notifications, processes them, and dispatches them as events to the bot server. It handles various types of notifications including replies, mentions, likes, reposts, and follows.

Features

  • Periodic polling of notifications based on a customizable interval.
  • Supports exponential backoff in case of rate limiting or errors.
  • Handles session refresh when required.
  • Dispatches notifications like replies, mentions, quotes, likes, reposts, and follows to the bot.
  • Extensible to handle other types of notifications and custom behavior.

Options

  • :name (required) - The name of the GenServer instance.
  • :interval (required) - The polling interval in seconds for checking new notifications.
  • :process_from - Start polling from a specific date/time.
  • :last_seen - The last seen date of notifications.
  • :cursor - The cursor to fetch subsequent notifications from the API.
  • :attempt - Number of polling attempts, used for backoff.
  • :server_pid (required) - The server process that handles events from the poller.
  • :session (required) - The session information used to authenticate API requests.

Functions

  • start_link/1: Starts the Poller process with the given options.
  • poll_notifications/1: Fetches the latest notifications from the service and handles them.
  • handle_notifications/2: Dispatches each notification to the appropriate event handler in the bot server.
  • handle_rate_limited/2: Handles the rate-limiting case by applying exponential backoff before the next poll.
  • handle_error/2: Sends error events to the bot server.
  • dispatch_notification/2: Dispatches different types of notifications (e.g., replies, quotes, mentions, likes, reposts, follows) to the bot server.

Example

You can start the poller like this:

ProtoRune.Bot.Poller.start_link([
  name: :my_bot_poller,
  interval: 30,
  session: my_session,
  server_pid: self()
])

The poller will then periodically fetch notifications and dispatch them to the bot server based on the event type.

Backoff Strategy

The poller implements an exponential backoff strategy when rate-limited or in case of errors. The backoff starts with the defined interval and increases exponentially with each failed attempt, up to a maximum of 5 minutes.

Internal State

The State struct is used to keep track of:

  • name: The name of the poller process.
  • interval: The polling interval in seconds.
  • last_seen: The last notification timestamp.
  • cursor: API cursor for fetching new notifications.
  • attempt: The number of failed attempts.
  • session: The current session for API requests.
  • server_pid: The PID of the server handling the notifications.

Summary

Functions

Returns a specification to start this module under a supervisor.

Types

@type kwargs() :: [option(), ...]
@type option() ::
  {:name, atom()}
  | {:interval, integer()}
  | {:process_from, NaiveDateTime.t()}
  | {:last_seen, Date.t()}
  | {:cursor, String.t()}
  | {:attempt, integer()}
  | {:server_pid, pid()}
  | {:session, map()}

Functions

Link to this function

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

start_link(opts)

@spec start_link(kwargs()) :: GenServer.on_start()