Writing a NanoTorrent plugin

The plugin host has finished loading. The place to draw a first window or restore state from data_get.

Shutting down — best effort. NanoTorrent does not wait for the plugin thread before exiting, so a slow handler may be cut off mid-run. Do not use it to save anything you cannot lose; write state out as you go instead.

A torrent appeared in the session. Lifecycle events are detected by the session itself rather than by the UI, so they fire the same way whether the torrent came from the window, the web interface, a magnet link handed to a second instance, or another plugin.

A torrent finished downloading, on a genuine transition. Torrents that were already complete when NanoTorrent started do not fire it, and a recheck that un-finishes a torrent lets it fire again when it re-completes.

A torrent left the session, with or without its files.

Background work failed. message is the text that went to the log.

Once a minute, for as long as the session runs, on a wall-clock deadline so a busy session cannot starve it. One minute is fixed: a plugin that wants an hour counts sixty ticks, which is cheaper than a scheduler nobody asked for. Poll things here rather than in a loop — nothing else fires it.

Your window was opened. Redraw its lists here rather than keeping them warm.

A row in the main list was clicked. id is the id you gave that row in ui_rows.

A row in the optional upper list was clicked — the feed, category or account whose contents the main list shows.

A button was pressed. input is whatever the text field held at that moment, or an empty string if there is no field.

One of your ui_file_menu items was used on a file. You are told which item and which file, so nothing has to be remembered between drawing the menu and the click arriving. It fires the same way from the desktop details panel and from the web interface — a plugin cannot tell the two apart, and should not try.

An item in your menu-bar dropdown was chosen.

A form was saved. values is a map of field id to value, and every value is a string — a checkbox included — so a script reads them all the same way. It does not close the form for you: call ui_form_close when you are ready, which is what lets a rejected form stay up with what was typed still in it.

Cancel was pressed. Also does not close the form on its own.

The Configure cog on your row in Preferences ▸ Plugins was pressed. Only fires if you called ui_configurable(true).

returns [ #{ … } ] — an array of maps, one per torrent in the session.

returns #{ … }, or () if that torrent is gone.

returns bool — cheaper than fetching the map when all you want is presence.

returns #{ download: int, upload: int } — bytes per second, session-wide.

returns [ #{ index, name, length, progress, priority } ] — one per file, in the torrent’s own order. index is what every per-file call takes.

returns [ #{ addr, state, fetched_bytes, pieces } ] — the swarm as this client sees it.

returns [ #{ url, tier } ]

URLs and tiers, not the Trackers tab’s status column: that column is translated, and a plugin branching on it would work in English and quietly stop working in the other 75 languages.

returns #{ ratio, seed_minutes }, or () where the torrent has no override of its own.

returns a magnet link for a torrent already added, or "".

returns the routing table size, 0 when DHT is off.

returns the port peers are told to reach, 0 if it is not listening.

returns a URL a media player can open for that one file, or "".

This is how a plugin hands a file to something that is not NanoTorrent. It points at 127.0.0.1 and carries a capability token, not your password: the token is good for that one file of that one torrent, dies half an hour after its last use, and is never written to disk. A plugin cannot read the web interface’s password and does not need to.

The URL serves byte ranges out of a file that is still downloading, so a player can start before the torrent finishes. It returns "" when the web interface is switched off, because then there is nothing listening to stream from — check for that rather than handing a player a URL into a closed port.

Pause one torrent. A torrent a plugin pauses reads as paused in the window and the web interface too — all three read the same session.

Resume one torrent.

Force a recheck of the data on disk.

Announce to the trackers now, rather than at the next interval.

returns bool — false for anything that is not "top", "up", "down" or "bottom".

0 skips the file, 1 is normal, higher is sooner. index is the one files gave you.

Either may be () to clear that half, so a plugin can set a ratio limit without inventing a time one.

Point the torrent at where its data lives, without moving what is already there — for data you moved by hand or restored from a backup. move_storage is the one that moves it.

returns bool — the URL is validated exactly as it is in the UI.

Tracker editing needs both permissions, which no other call does. Adding a tracker is a control operation on a torrent, but its consequence is disclosure: the torrent starts announcing to a server the plugin chose, which is your address and what you are downloading going somewhere new. A plugin holding only control can stop and start a torrent; it cannot redirect where that torrent tells the world about itself.

returns bool. Changes live in the database, never written back into the .torrent.

Take one announce URL off the torrent.

returns bool — a .torrent the plugin already holds, as base64.

The other half of http_get. add_torrent_url fetches for you, which is no use when the file sits behind a header, a cookie or a POST — fetch it yourself, then hand over the bytes.

Remove the torrent, keeping its files.

Remove the torrent, deleting the downloaded data when delete_files is true. Two arities rather than a default argument: Rhai has no optional parameters, and remove(hash) deleting files by accident is a mistake a plugin author only makes once.

Move the downloaded files to another folder, the way the context menu's Move storage does.

Apply a label by its numeric id — the ids Preferences ▸ Labels assigns.

Take the label off.

Add a magnet link, into the default save path.

Add a magnet link into a folder you name.

Raise a native desktop notification. Windows and macOS always can; on Linux it goes to the D-Bus notification daemon, so a session without one logs a warning and shows nothing.

returns #{ ok: bool, status: int, body: string, error: string }

Only http and https; file:// is refused before the request is made, so the network permission cannot be turned into a filesystem read. Capped at 4 MB and 30 seconds. An unreachable server is not an error that kills your handler — it comes back as ok: false with error set, because a plugin polling the internet on a timer will meet one sooner or later.

returns bool

Takes a magnet link as-is and fetches anything else as a .torrent, which is what feeds actually contain. Needs both permissions.

returns bool — the same, into a folder you name.

returns bool — the same, with options.

Take any of the three; anything left out keeps its default, so a plugin that only wants to add something paused does not have to name a folder as well. label is a label name and is looked up, never created — a plugin should not be able to fill somebody’s label list by getting a rule wrong — so a name that does not exist means no label, and says so in the log. paused is true for any non-empty value except "0" and "false", the same convention a form checkbox follows.

returns true if it started — not if it worked.

The child is not waited on: a media player runs for hours. A program that is not installed comes back false rather than raising, which is what makes “try these four paths until one of them is VLC” the obvious way to find a player without being able to look at the file system.

Hand a URL, a file or a folder to whatever the desktop opens it with. It names no program: the association is one the user already made, so this is how a plugin reaches “the player they chose” without being told which it is.

returns the string for key in the user’s language, with {0} and {1} filled in.

A key with no string in the current language falls back to en-US, and then to the key itself — so t("play") on a plugin nobody has translated yet reads play, which is obviously a missing string rather than a blank control.

returns maps, arrays and scalars — or () if it will not parse.

returns #{ tag, attrs, text, children }, or ().

Not a full document model — no namespaces, no comments — but enough to walk an RSS or Atom feed, which is the job it exists for. Entities and CDATA are decoded, and each element's text is trimmed. Without it, writing a feed reader would have meant writing an XML parser in Rhai.

returns seconds since the Unix epoch, as an integer.

Without one, “ignore this for a week” cannot be written at all. Combine it with data_set to hold a deadline across restarts — the plugin scope does not survive one.

returns the stored string, or () if there is none. Test for () before using it.

returns false if the store is full — check it, prune and retry rather than ignoring the result.

Forget one key.

returns an array of every key this plugin has stored.

Name the window. A plugin with no name has no window — declaring one is what lists it in the menu.

Show a single text field with this placeholder. An empty string means no field. Its contents arrive as the second argument to on_ui_button.

A row of buttons. Clicks call on_ui_button(id, input).

The main list. Clicks call on_ui_row(id). Which row is current is yours to decide, not the window's — set selected: true on it when you redraw, so the two can never end up disagreeing.

An optional second list above the main one, for when the main list shows the contents of something the user picks: feeds, categories, accounts. Clicks call on_ui_group(id). Leave it empty and the window is the single-list one it was before.

One line under the list. This is where a failure belongs: a window stuck on “Checking…” with a healthy log file somewhere else is indistinguishable from a hang.

Put the window on screen now. Separate from ui_window so a plugin can prepare one at load without a window appearing unasked.

Your own dropdown in the main window's menu bar, after File, View and Help. An empty title falls back to the plugin's name; choosing an item calls on_ui_menu(id). This is where a plugin puts the things a person does with it — “Feeds…”, “Check now”.

One dropdown per plugin, structurally rather than by a rule the host checks: a plugin holds a single menu title and item list, so calling ui_menu twice replaces the menu instead of adding another. Capped at 20 items; the rest are dropped with a line in the log.

Your items on the context menu of a file, in a torrent’s details panel and on the matching row in the web interface. Using one calls on_file_menu. This is the only place a plugin draws outside its own window, and it is deliberately the smallest shape that works: items, no submenus, no icons, no say in where they go. They sit below NanoTorrent’s own Open file, under a separator, in plugin name order — you cannot get above it or replace it.

Items are labelled with your plugin’s name — “Player: Play”, not “Play”. That is not decoration. A menu item is text of your choosing appearing inside NanoTorrent’s own window, which is the shape of every convincing phishing prompt ever written; the prefix means an item reading “Verify your password” is at least visibly somebody’s.

The same list is offered on every file: the host draws the menu before it knows which file it will be used on, so a plugin that only handles video checks the name it is given in on_file_menu and says why, rather than expecting the item to hide itself. A plugin with file-menu items needs no window at all.

Your own mark beside your plugin’s name. The argument is SVG path data on a 16×16 grid — ui_icon("M 4 2 L 14 8 L 4 14 Z") is a play triangle. One string, both front ends: the desktop hands it to Slint’s Path and the web interface to <svg><path d="">, which read the same syntax, so it is sharp at any size in either and takes its colour from the theme rather than carrying one of its own.

Straight lines only, in practice: Slint’s Path does not lean on SVG arc support, so A commands are best avoided — the shipped RSS icon is three rising bars rather than the usual arcs for exactly this reason. And the string is checked before it is stored: anything that is not path data — a tag, an &, a quote, or more than 2 KB of it — is dropped and your plugin falls back to its initial. None of those mean anything in path data, and it is what lets the web interface put your icon in its markup without having to trust it.

A form, in place of the lists. One text field is enough to add a feed and nowhere near enough to edit a rule with a dozen settings on it — this describes the controls you want, and the window draws them and hands the values back in one go through on_ui_form. An empty field list closes the form, so ui_form(id, title, []) and ui_form_close() do the same thing.

A form replaces the lists while it is up, in the window and the web interface alike: it is a different thing to be doing, and half a list behind a form is neither. It also means the redraw a plugin does on a timer will not disturb one — the window only re-pushes a form whose fields have actually changed, so it cannot wipe out what somebody is typing.

Put the lists back. Neither saving nor cancelling does this for you.

Put a cog on your row in Preferences ▸ Plugins, which calls on_ui_configure(). For a plugin that will not work until it is set up — the RSS reader has no feeds until you give it one. It is not a second way to open your window: declare it only if there is genuinely something to configure, or the cog becomes noise on every row.

Write a line to the NanoTorrent log, tagged plugin. Always available — a script that declares no permissions can still do this, which is why declaring nothing needs no approval.