porla_events

Emits events for various things in Porla - torrents, sessions, presets, plugins and the key/value store.

Exports

on(event: string, callback: function): PoCancellable

v0.51.0

Registers callback for the given event and returns a cancellable that you can use to remove the handler.

The callback is called with a single argument - an event table. All event tables include a name field with the name of the event.

Raises an error if event is not a valid event name.

Example

local events = require("porla_events")

local cancellable = events.on("torrent.added", function(event)
    local status = event.torrent:status()
    print("added torrent", status.name, "to session", event.session.name)
end)

-- some time later, to stop listening
cancellable:cancel()

Events

Key/value store

kv.updated

v0.51.0

Field	Type	Description
keys	string[]	The keys that were written.

Emitted when one or more keys in the key/value store are written. Updating a key to the same value will emit this event. Read-only keys are never written and are not published.

Plugins

plugin.added

v0.51.0

Field	Type	Description
plugin_id	number	The ID of the added plugin.

Emitted when a plugin is added. A plugin.loaded event will follow if it then loads.

plugin.loaded

v0.51.0

Field	Type	Description
plugin_id	number	The ID of the loaded plugin.

Emitted when a plugin has been loaded.

plugin.unloaded

v0.51.0

Field	Type	Description
plugin_id	number	The ID of the unloaded plugin.

Emitted when a plugin has been unloaded, for example on reload or removal.

plugin.updated

v0.51.0

Field	Type	Description
plugin_id	number	The ID of the updated plugin.

Emitted when a plugin's settings are updated. The plugin is then reloaded so plugin.unloaded and plugin.loaded will follow this event.

plugin.removed

v0.51.0

Field	Type	Description
plugin_id	number	The ID of the removed plugin.
plugin_path	string	The path where the plugin was loaded from.

Emitted when a plugin has been removed.

Presets

preset.added

v0.51.0

Field	Type	Description
preset_id	number	The ID of the added preset.

Emitted when a preset is added.

preset.updated

v0.51.0

Field	Type	Description
preset_id	number	The ID of the updated preset.

Emitted when a preset is updated. Making a preset the default also emits this event for the previous default preset. Removing a session emits this event for each preset that used it.

preset.removed

v0.51.0

Field	Type	Description
preset_id	number	The ID of the removed preset.
preset_name	string	The name of the removed preset.

Emitted when a preset is removed.

Sessions

session.added

v0.51.0

Field	Type	Description
session_id	number	The ID of the added session.
session	PoSessionHandle	The session that was added.

Emitted when a session is added.

session.dht_stats

Fires once per DHT node every timer_dht_stats ms.

session.loaded

v0.51.0

Field	Type	Description
session_id	number	The ID of the loaded session.
session	PoSessionHandle	The session that was loaded.
torrents	number	The number of torrents loaded.
failed	boolean	true if loading stopped early because of an error.

Emitted when a session has loaded its torrents, both at startup and when a session is added.

session.updated

v0.51.0

Field	Type	Description
session_id	number	The ID of the updated session.
session	PoSessionHandle	The session that was updated.

Emitted when a session is updated (renamed, set as default, etc).

session.unloaded

v0.51.0

Field	Type	Description
session_id	number	The ID of the unloaded session.
session_name	string	The name of the session.

Emitted when a session is unloaded.

session.removed

v0.51.0

Field	Type	Description
session_id	number	The ID of the removed session.
session_name	string	The name of the session.

Emitted when a session is removed.

session.stats

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
stats	table	Session counters, keyed by libtorrent metric name (for example net.sent_payload_bytes).

Emitted periodically with session statistics.

Torrents

torrent.added

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.

torrent.checked

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.

torrent.error

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.
error	error	The error.
filename	string	The file involved, if any.

torrent.file_error

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.
error	error	The error.
filename	string	The file that failed.
op	string	The operation that failed, for example file_open.

torrent.finished

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.
first	boolean	true the first time this torrent finished, if this session downloaded any payload data for it to trigger.

Emitted each time a torrent finishes - this can happen both due to downloading all pieces, rechecking, etc.

The first field can be checked to make sure it finished due to downloading payload data, and is only true once per downloaded torrent.

events.on("torrent.finished", function(event)
    if not event.first then return end
    -- runs once per downloaded torrent
end)

torrent.metadata_received

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.

torrent.need_cert

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.

Emitted when a torrent needs an SSL certificate.

Call event.torrent:set_ssl_certificate(...) from the handler. It arrives before torrent.added for a torrent that has metadata, and after metadata for a magnet.

torrent.paused

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.

torrent.removed

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.

torrent.resumed

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.

torrent.state_changed

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.
state	string	The new state.
prev_state	string	The previous state.

States are checking_files, downloading_metadata, downloading, finished, seeding and checking_resume_data.

torrent.storage_moved

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.
storage_path	string	The new save path.
old_path	string	The previous save path.

Emitted as a response to calling move_storage on a LtTorrentHandle.

torrent.storage_moved_failed

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.
error	error	The error.
file_path	string	The file involved, if any.
op	string	The operation that failed.

Emitted when moving a torrent's storage fails.

torrent.tracker_error

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.
tracker_url	string	The tracker.
local_endpoint	{ string, number }	Local address and port used for the announce.
times_in_row	number	Number of failures in a row.
error	error	The error.
op	string	The operation that failed.
failure_reason	string	The failure reason given by the tracker, if any.

torrent.tracker_reply

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.
tracker_url	string	The tracker.
local_endpoint	{ string, number }	Local address and port used for the announce.
num_peers	number	Number of peers returned.

torrent.tracker_warning

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.
tracker_url	string	The tracker.
local_endpoint	{ string, number }	Local address and port used for the announce.
warning_message	string	The warning.

torrent.userdata_updated

v0.51.0

Field	Type	Description
session_id	number	The ID of the session.
session	PoSessionHandle	The session.
info_hash	LtInfoHash	The torrent info hash.
torrent	LtTorrentHandle	The torrent handle.
fields	string[]	Which fields changed: category, metadata and/or tags.