ProtoRune.Bot.Server (proto_rune v0.5.1)

Copy Markdown

The ProtoRune.Bot.Server module is responsible for managing bot processes in ProtoRune. It handles bot initialization, session management, and event/message dispatching. This module also integrates with the polling system to retrieve real-time notifications from ATProto and Bluesky services.

The bot server can operate in two modes:

Features

  • Bot Lifecycle Management: The server manages the entire bot lifecycle, from login and session refresh to handling messages and events.
  • Polling Strategy: Supports polling for notifications at regular intervals via the ProtoRune.Bot.Poller.
  • Session Management: Automatically handles session creation, refresh, and expiration.
  • Event and Message Handling: Provides a unified interface for handling events and messages via handle_message/1 and handle_event/2.

Options

  • :name (required) - The name of the bot process.
  • :lang - A list of languages the bot supports (default: ["en"]).
  • :service - The service endpoint the bot will connect to (default: "https://bsky.social").
  • :identifier - The bot's login identifier (e.g., email or username).
  • :password - The bot's password for login.
  • :polling - Polling configuration (e.g., interval and process_from).
  • :firehose - Firehose configuration (e.g., relay_uri, cursor and auto_reconnect).
  • :strategy - The bot's strategy for receiving notifications (:polling or :firehose).

Polling Configuration

Polling can be configured with the following options:

  • :interval - How often (in seconds) the bot should poll for notifications (default: 5 seconds).
  • :process_from - Start processing notifications from a specific timestamp (default: current time).

Example:

ProtoRune.Bot.Server.start_link(
  name: :my_bot,
  strategy: :polling,
  service: "https://bsky.social",
  polling: %{interval: 10}
)

Firehose Configuration

The firehose strategy streams real-time repo events using a WebSocket connection to a relay. Firehose configuration includes:

  • :relay_uri - The WebSocket URI for the relay server (default: "wss://bsky.network").
  • :auto_reconnect - Automatically reconnect if the connection drops (default: true).
  • :cursor - The starting sequence number for reading the stream, used to backfill events missed while disconnected. Accepts an integer, a numeric string or "latest" (default: "latest").

Example:

ProtoRune.Bot.Server.start_link(
  name: :my_bot,
  strategy: :firehose,
  service: "https://bsky.social",
  firehose: %{cursor: 32_625_482_169}
)

Functions

  • start_link/1: Starts the bot process with the given configuration options.
  • handle_message/2: Handles incoming messages for the bot.
  • handle_event/3: Handles events dispatched to the bot.
  • format_status/1: Formats the bot's internal state for debugging.

Session Management

The bot manages its session by authenticating with the ATProto server upon startup. It also refreshes the session token periodically. If the session expires or cannot be refreshed, the bot will stop.

Example

ProtoRune.Bot.Server.start_link([
  name: :my_bot,
  strategy: :polling,
  service: "https://bsky.social",
  identifier: "my-bot-id",
  password: "super-secret-password"
])

This will start a bot that uses the polling strategy to retrieve notifications from the Bsky service every 5 seconds.

The bot can handle messages and events like this:

ProtoRune.Bot.Server.handle_message(:my_bot, "hello")
ProtoRune.Bot.Server.handle_event(:my_bot, :user_joined, %{user: "user123"})

Internal State

The server maintains a state that includes:

  • name: The bot's name.
  • service: The endpoint to connect to.
  • session: The session data for making authenticated requests.
  • poller: The PID of the polling process (if using the polling strategy).
  • langs: The languages the bot supports.

Error Handling

  • The bot gracefully handles errors such as rate limits and API failures by retrying or stopping the process when necessary.
  • Errors are dispatched as events to the bot, allowing custom error handling.

Telemetry

The server emits the following :telemetry events (see the ProtoRune.Bot moduledoc for the full list of bot events):

  • [:proto_rune, :bot, :event, :start] / [:proto_rune, :bot, :event, :stop] / [:proto_rune, :bot, :event, :exception] - wrap each handle_event/2 dispatch via :telemetry.span/3. Metadata includes :bot (the bot module) and :event (the event type); exception events also carry :kind, :reason and :stacktrace.
  • [:proto_rune, :bot, :event, :dispatch] - emitted once per dispatched event with measurement %{count: 1} and the same :bot / :event metadata, suitable for counting the event type distribution.

Summary

Types

firehose_t()
kwargs()
mapargs()
option()
options_t()
polling_t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

firehose_t(data)
firehose_t!(data)
firehose_t_changeset(data)
get_schema(atom)
handle_event(name, event, payload \\ %{})
handle_message(name, message)
options_t(data)
options_t!(data)
options_t_changeset(data)
polling_t(data)
polling_t!(data)
polling_t_changeset(data)
start_link(opts)

Types

firehose_t()

@type firehose_t() :: %{
  optional(:relay_uri) => String.t(),
  optional(:auto_reconnect) => boolean(),
  optional(:cursor) => String.t() | non_neg_integer()
}

kwargs()

@type kwargs() :: [option(), ...]

mapargs()

@type mapargs() :: %{
  :name => atom(),
  :strategy => :polling | :firehose,
  :service => String.t(),
  optional(:langs) => [String.t()],
  optional(:identifier) => String.t(),
  optional(:password) => String.t(),
  optional(:polling) => polling_t(),
  optional(:firehose) => firehose_t()
}

option()

@type option() ::
  {:name, atom()}
  | {:lang, [String.t()]}
  | {:service, String.t()}
  | {:identifier, String.t() | nil}
  | {:password, String.t() | nil}
  | {:polling, polling_t() | nil}
  | {:firehose, firehose_t() | nil}
  | {:strategy, :polling | :firehose}

options_t()

@type options_t() :: kwargs() | mapargs()

polling_t()

@type polling_t() :: %{
  optional(:interval) => integer(),
  optional(:process_from) => NaiveDateTime.t()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

firehose_t(data)

firehose_t!(data)

firehose_t_changeset(data)

get_schema(atom)

handle_event(name, event, payload \\ %{})

@spec handle_event(pid() | atom(), atom(), map()) :: :ok

handle_message(name, message)

@spec handle_message(pid() | atom(), String.t()) :: :ok

options_t(data)

options_t!(data)

options_t_changeset(data)

polling_t(data)

polling_t!(data)

polling_t_changeset(data)

start_link(opts)

@spec start_link(options_t()) :: {:ok, pid()} | {:error, term()}