ProtoRune.Bot.Server (proto_rune v0.1.0)
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:
- Polling: Periodically fetches notifications using the
ProtoRune.Bot.Poller
module. - Firehose: (Not yet implemented) Stream real-time events using a websocket-like connection.
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
andhandle_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 (not implemented yet).: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 (Not Implemented)
While not yet available, the firehose strategy will enable real-time notifications using a websocket connection. Firehose configuration includes:
:relay_uri
- The WebSocket URI for the relay server.:auto_reconnect
- Automatically reconnect if the connection drops (default: true).:cursor
- The starting cursor for reading the stream.
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.
Summary
Functions
Returns a specification to start this module under a supervisor.
Types
firehose_t()
kwargs()
@type kwargs() :: [option(), ...]
mapargs()
option()
options_t()
polling_t()
@type polling_t() :: %{ optional(:interval) => integer(), optional(:process_from) => NaveDateTime.t() }
Functions
child_spec(init_arg)
Returns a specification to start this module under a supervisor.
See Supervisor
.