Mantle plugins
The plugins that make Mantle a real client: where its titles, details, schedules and streams come from. Each folder is one plugin. This folder is meant to become its own repository (Mantle's official plugin catalog); until then the app bundles it, every plugin installed but off.
| Plugin | What it does | Needs |
|---|---|---|
cinemeta |
Popular, new and featured movies and series, search, details (IMDb ids) | nothing |
tvmaze |
Episodes, air dates and runtimes; what airs this week; Airing today | nothing |
themoviedb |
Trending and popular lists, search, full details with cast, ratings, trailers, reviews | a free TMDB API key |
opensubtitles |
Subtitles in many languages for what plays (Stremio's open OpenSubtitles addon) | nothing |
torznab |
Finds releases through your own Jackett or Prowlarr | your Torznab feed and API key |
realdebrid |
Plays torrents through your Real-Debrid account | a Real-Debrid account |
torbox |
Plays torrents through your TorBox account; knows what TorBox has cached | a TorBox API key |
aniskip |
Where anime episodes' openings, endings and recaps are, for Skip intro | nothing |
introdb |
Where intros, recaps and end credits are, crowd-sourced, for Skip intro | nothing |
skipdb |
Where intros, recaps, credits and previews are, open (ODbL), matched by a file's length | nothing |
theintrodb |
Where intros, recaps, credits and previews are, crowd-sourced | nothing |
trakt |
Brings your Trakt history, watchlist, collection and lists in; titles like one | a Trakt account |
stremioaccount |
Brings your Stremio library in: what you added, watched and how far you got | a Stremio account |
nuvio |
Brings a Nuvio profile's library in: its titles, what you watched and where you stopped | a Nuvio account |
jellyfin |
Your own Jellyfin server: its films and series, details, its files as sources for any title it has, and what you watched there | your Jellyfin server |
A finder (torznab, or a Stremio addon) finds releases of a title; a
resolver (realdebrid, torbox) turns one into a stream. Direct links
from an addon play as they are.
Stremio addons are plugins of their own: installed from the link to an
addon's manifest (Plugins, From a link; or from a collection of addons added
as a repository), each is a file of one line,
return mantle.stremio.addon("https://…/manifest.json"), made of what the
addon's manifest offers: its catalogs as shelves, search, details, streams
and subtitles.
Write your first plugin
A plugin that adds one shelf of films, with a test: two files in a folder
hello/ here, beside the others.
hello/init.lua:
local M = {
name = "Hello",
version = "0.1.0",
kind = "Metadata",
description = "A shelf of one list of films.",
permissions = { net = { "api.example.com" } },
off = true,
}
M.init = function()
mantle.catalog.add({
ids = { "tt" },
lists = { { id = "top", title = "Top films", type = "movie", shelf = { title = "Top films" } } },
page = function(req)
local res = mantle.http.get("https://api.example.com/top")
if not res.ok then error("Example answered " .. res.status) end
local out = {}
for _, f in ipairs(res:json().films) do
out[#out + 1] = { id = f.imdb, type = "movie", name = f.title, year = f.year }
end
return out
end,
})
end
return M
hello/tests/top.json records what the service answers and what the plugin
must return:
{
"about": "The list is the films the service names.",
"call": "catalog.page",
"arg": { "list": "top" },
"http": [
{ "url": "https://api.example.com/top", "body": { "films": [{ "imdb": "tt0000001", "title": "First Film", "year": 2001 }] } }
],
"want": [{ "id": "tt0000001", "type": "movie", "name": "First Film", "year": 2001 }]
}
- Run the test with
go test ./internal/plugin -run TestPlugins/hello. Nothing reaches the network: the plugin gets the recorded answer, and a request the test does not answer fails it. - Run the app with
go run ./tools/mk dev. It reads the plugins from this folder and reloads one as soon as one of its files is saved (its earlier answers are asked again). Turn the plugin on in Plugins. Check on its page runs its health, and the Inspector's log shows what it answered, how long it took, what it logged and why it failed. - Edit the plugin and its test, and run the test again. For a real service, record its answers and trim them to the few items a test needs (see Tests).
api.example.com does not exist, so turned on, the example shows no films: its
test is what proves it works. Everything else in this file is the reference for
what a plugin can add and use.
A plugin
A plugin is Lua, written the way a Neovim plugin is: a package, or one file.
myplugin/
init.lua the plugin object: who it is, what it may reach, init and health
api.lua its other modules, required as require("myplugin.api")
tests/*.json recorded tests of its functions
or myplugin.lua alone. The folder's (or file's) name is the plugin's id:
lowercase letters, digits, - and _.
The plugin object
init.lua returns the plugin object, M: who the plugin is, what it may
reach and its settings, then its functions.
local http = mantle.http
local M = {
name = "My plugin",
version = "0.1.0",
kind = "Metadata",
description = "One or two sentences for the Plugins page.",
permissions = { net = { "api.example.com", "*.example.com", "setting:url" }, credentials = true },
settings = {
{ id = "url", label = "Server", type = "url", placeholder = "http://localhost:1234", help = "…" },
{ id = "key", label = "API key", type = "secret" },
},
off = true,
}
local function page(req)
local res = http.get(mantle.o.url .. "/list/" .. req.list)
if not res.ok then error("Example is not answering. Try again in a moment.") end
local out = {}
for _, x in ipairs(res:json().items) do
out[#out + 1] = { id = x.imdb, type = "movie", name = x.title, year = x.year, poster = x.image }
end
return out
end
M.init = function()
mantle.catalog.add({
ids = { "tt" },
lists = { { id = "top", title = "Top movies", type = "movie", shelf = { title = "Top movies", more = "browse" } } },
page = page,
})
end
M.health = function(h)
if (mantle.o.url or "") == "" then return h.warn("Set the server's address.") end
h.ok("Asks " .. mantle.o.url)
end
return M
Mantle reads M before anything is granted: the file runs with no network
and no secrets, so at the top it only defines. A field no plugin has
(permisions) is refused, naming it. Its fields:
- name, version (both needed), kind (shown as a badge), description, off (installed off), native (it needs the desktop or Android app: its service does not let a web page call it, so the web build, which runs in the browser, cannot turn it on).
- configure: the address of a page on its service where it is set up (a Stremio addon's own configure page); its page in Plugins opens it with Configure on its site.
- permissions.net: the hosts its functions may reach (
*.example.comis any subdomain).setting:urlis the host of whatever address the user sets in theurlsetting (each one, for a list of addresses). Nothing else is reachable, redirects included (unlessfollow, below). The user can refuse the network, and then the plugin has none. permissions.art: where the files it passes on (artwork, subtitles) may come from besides those hosts ("*": any public address). permissions.follow: its hosts may send a request of it on (redirect it) to any public address, as a Stremio addon's service may; allowed with the network. Artwork and following are part of the network permission: granted with it, and an update that asks for a new host, for them, or for another category is not granted it until the user allows it in the permission step. A plugin that holds credentials and asks for"*"artwork says so there: an address it asks Mantle to fetch could carry what it holds. - permissions.credentials: it may keep secrets (tokens, keys) with
mantle.cred. Secret settings are kept there too. - settings:
text,url,urls(one per line),secret(never shown again once set),number,toggle,choice(withchoices:{{value, label}, …}). Its functions read them asmantle.o.<id>, secrets asmantle.cred.get("<id>"). A setting with adefaulthas that value until the user sets another; one without (and a secret) must be set before the plugin signs in. A provider's app id that is public by design (an OAuth client id) can be a default. A client secret cannot: one shipped in an app is anyone's, so sign in through the provider's flow that needs none. A secret withshareable = truemay go in a shared setup, where the user chooses to include it (and whoever brings it in, to take it): only a key the provider lets work from more than one place, never a sign-in's tokens. A setting withrequired = trueis one the plugin cannot do without: the first run's setup asks for it, the Plugins page says it is still to be set, and until it is Home shows none of the plugin's shelves (a setting with adefaultis never missing).mantle.account.set'srequired = truesays the same of signing in. - setup: what to do on the provider's site before signing in, a step a
line, shown with the settings still needed. Addresses
(
example.com/apps) open, and text in backquotes copies.
Its functions:
- init() hooks in what the plugin offers (below), as a Neovim plugin's
setup does with
vim's functions. - health(h) says how it is doing, as
:checkhealthasks a Neovim plugin:h.ok(text),h.info(text),h.warn(text),h.error(text), a line each, shown when the user presses Check on its page. - refresh() renews what what it offers comes from (the manifests of the
addons it was given, say, or the libraries of the media server the user is
signed in to), keeping it in
mantle.store; Mantle calls it when the app starts, when the plugin is turned on, signs in or out, and when its settings change, then reads the plugin again, so itsinitcan add what its store now says (offline too). That is how a plugin's lists and shelves can depend on its service:initmakes them from the store, one for each library, say. A shelf's id is stable (<plugin>:<list>), so the Home layout keeps its place and whether it shows, and one that saysoff = truestarts off Home.
What init adds
Each call takes a table: what it adds (its fields as the table below gives
them), and the functions that answer for it, which Mantle calls by their
place (catalog.page). A part's functions in bold it must be given.
| Call | Adds | Its table | Its functions |
|---|---|---|---|
mantle.nav.add |
a destination in the rail | {id, label, icon} |
|
mantle.shelf.add |
a shelf on Home of the titles it lists, or of one of its own lists | {id, title, sub, shape, more, badge, quietBadge, off, replaces, genres, genre, titles}, or query = "<plugin>:<list>" for one of its lists |
|
mantle.action.add |
a button on a title's page | {id, label, icon, copy, done} |
|
mantle.control.add |
a button in the player over a section | {id, label, section} |
|
mantle.rule.add |
a field in the smart-list builder | {id, label, ops, vals} |
|
mantle.artwork.add |
where a provider keeps its pictures, by id | {id, label, ids, poster, backdrop} |
|
mantle.catalog.add |
lists to browse, and search | {label, ids, lists = {{id, title, type, shelf}}, searches} |
page, search |
mantle.metadata.add |
details | {label, ids, types} |
details |
mantle.similar.add |
titles like one | {label, ids, types} |
titles |
mantle.skips.add |
where intros, recaps, credits and previews are | {label, ids, types} |
find |
mantle.calendar.add |
when episodes air | {label} |
airing |
mantle.subtitles.add |
online subtitles | {label} |
find |
mantle.importer.add |
another app's library, brought in | {label} |
run |
mantle.finder.add |
a title's releases, for a resolver | {label, ranked} |
find |
mantle.resolver.add |
streams from releases | {label, accepts = {"torrent"}, library = {shelf, list}} (the kinds of release it takes: torrents; a direct link plays as it is) |
resolve, progress, cancel, check, library.list |
mantle.account.set |
signing in to the provider's account | {kind = "device", label, site, required, share, keeps} |
start, poll, sign_out, info, signed_in |
- A provider (the calls with functions) is the plugin's own, one of each
kind; its
labelis the plugin's name unless it says another. - A shelf of one of its catalog's lists is said in that list (
shelf = {title, …}), and one of what its resolver's account has ready in itslibrary: its id is what it shows (myplugin:top,myplugin:library).mantle.shelf.addis for a shelf of the titles it lists itself, or of one of its own lists (query = "<plugin>:<list>"; one installed from a link may name none but its own). - A shelf's
badgeis a word on each of its cards (over the one a list gives a title), shown only on hover and focus withquietBadge = true. Withoff = trueit starts off Home, and shows once the profile turns it on in Home layout (a plugin with many keeps its first few on).replaceslists the ids of shelves it stands for (ones an earlier version had): a layout saved with them has it where they were, hidden if all were, once the plugin has refreshed and is set up. A shelf the layout does not name yet goes after the plugin's shelf before it; ids of the plugin's that no shelf has are dropped then. Arefreshthat fails changes none of that.genresare what its list can be browsed by ({"Drama", …}), offered as a choice on its page, the one chosen asked ofcatalog.pageasgenre;genreis the one it lists until another is chosen (for a list that must be given one: without it, the choices start with all genres). - A catalog's
searchesare the kinds of title itssearchtakes ({"movie", "series"}). idsare the title ids a provider knows:ttfor IMDb's, or a prefix of its own (tmdb:).types:movie,series.player.controls: a button over a section (intro,credits,recap,preview) while it plays, which skips it, and the section marked on the seek bar: only where the playing file's own chapters name one (Intro, Opening, OP; Credits, Ending, ED; Recap, Previously; Preview).metadata.artwork:{id}inposterandbackdropstands for the title's: a title it knows that came without pictures (a list of similar titles) shows them at once, its details asked for only if the picture is not there.skips: asked once the playing file is read (so, for a file as long as it is), answers kept a week; the file's own chapters come first, and of the providers' answers, the one most of them agree on.ranked: the finder's list is in the order to try (kept as it is).account.share = true: the provider lets one sign-in be used from more than one place at once (as ashareablesecret's key), so the sign-in syncs with the other devices of the household's Mantle account: what the plugin keeps incred(but its declared settings' keys, which sync apiece), and thestorevalueskeepsnames ({"expires"}: the tokens' expiry). A device that renews it gives the others the renewal;sign_outcalled by the user signs every device out, while a sign-in the plugin drops itself (a token refused) takes the account's newer one back instead. Leave it off for a provider that allows one place at a time (Real-Debrid).
A function a part needs and is not given, one it does not take, or a provider added twice stops the plugin at that line, saying why. What is added must also have what Mantle needs to use it, or it is left out and the log (Plugins → Log) says so, naming the plugin:
| Adds | Needs |
|---|---|
| a shelf | id, title, and query or titles |
| a destination, an action | id, label |
| a rule | id, label, ops |
| a control | id, label, and a section of intro, credits, recap or preview |
| metadata, similar titles, skips | ids |
| artwork | ids, and poster or backdrop |
| a resolver | accepts |
What the functions take and return
Mantle calls a function with a table and uses what it returns. Errors
(error("…")) are shown to the user as they are: say what went wrong and
what to do.
A title (from catalog.page, catalog.search and metadata.details):
{ id = "tt0111161", type = "movie" or "series", name, year, years = "2008–2013",
poster, backdrop, logo, -- image addresses on a granted host
shape = "landscape", -- its poster is a wide picture: a shelf of mostly such is a wide one
rating = 9.3, genres = {…}, overview, runtime = 142, -- minutes (an episode's)
released = "1994-10-14", latest = "2013-09-29", ended = true,
ids = { imdb = "tt…", tmdb = 278, tvdb = …, tvmaze = … },
-- in a list, also: episode = "2.3", sub, badge
-- from details, also:
tagline, rated = "R",
cast = {{ name, role }}, crew = {{ job = "Directed by", name }},
countries = {…}, languages = {…}, studios = {…},
ratings = {{ source = "IMDb", value = "9.3" }},
reviews = {{ who, rating, text, when, source }},
trailers = {{ name, youtube = "id" }},
facts = {{ label, text }},
episodes = {{ season, number, name, released, runtime, overview, still, video }},
-- video: its own id at this provider (an addon's video id), if it has one:
-- finder.find and subtitles.find are given it, for the episode
similar = {…titles}, -- titles like it, if its details say (no extra request)
-- what else finds it when the Library or Search is searched (kept with
-- the title, so a search stays on the device; each once, whatever its
-- case, the first 30 given):
aka = {"Star Wars: Episode V - The Empire Strikes Back"}, -- its other names: original, elsewhere
collection = "Star Wars Collection", -- what it is part of
keywords = {"space opera"} } -- after its names; only near misses later
| Function | Takes | Returns |
|---|---|---|
catalog.page |
{list, skip, genre, today} |
titles |
catalog.search |
{query, type} |
titles |
metadata.details |
{id, type, ids, today} |
a title, or nil if unknown |
similar.titles |
{id, type, ids} |
titles |
skips.find |
{id, type, season, episode, absolute, duration} |
{{kind, from, to}}, seconds (from nil: from the start; to nil: to the end; absolute: the episode's place among all of the series') |
calendar.airing |
{from = "2026-10-05", days = 7, series = {{id, ids}}} |
{{id, season, number, name, released, aired}} |
marks.list |
{ids, imdb, tmdb, tvdb}: what the plugin's provider has (a server of the user's own), as lists of its own ids (as its titles have them) and IMDb's, TMDB's and TVDB's (a TMDB or TVDB number as "movie:603" or "series:1396", since they number films and series apart, marks a title of that kind alone; a bare one, either); each title it has wears its mark (mantle.marks.add({icon, label, list}): a small icon on the card, the label saying it), asked again every 15 minutes |
|
finder.find |
{id, type, name, year, season, episode, ids, video} |
{{name, label, size, seeders, infohash, magnet, url, file, from, headers, subtitles, group, previews, id, private, exact}}; exact, the title's own file, found by the ids it was asked by (a server of the user's own): what its name says of the title (a year, a season) is not checked against it; id, the provider's own id for it, the same however its link changes (a server's key in it renewed), and none other's in the answer: Mantle knows it by that, else by its link; private, a direct link (url, no infohash or magnet) that holds the user's credential (a server's key): a download from it saves neither its link nor its headers, and asks again when it needs one, finding it by its id (so give one: a source known by its link is not found again once the link changes); video, a series' episode's own id at the provider that listed it (its video in metadata.details), if it said; label, what the provider calls it besides its release name ("[RD] 1080p HEVC"), read for what the name does not say of its quality; headers, a direct link's: {request = {…}, response = {…}}, what its host must be asked with and what its answer must say besides its own (a Stremio addon's proxyHeaders: Mantle relays the stream, as the player cannot set headers); subtitles, those it comes with, {{id, lang, url, name, format}} as subtitles.find gives them; group, which of the finder's it is like (a Stremio addon's bingeGroup): the next episode plays one alike; previews, the provider's own pictures of a direct link's file for the seek bar until Mantle's own come: {url, every, columns, rows, width, height, count}, sheets of columns × rows pictures width × height, one every every seconds, count in all, {i} in url the sheet's number from 0 (Mantle fetches them, with the link's headers) |
resolver.resolve |
{candidate, season, episode} |
{status = "ready", url, name, size} or {status = "preparing", progress = 0.4, ref} |
resolver.progress |
{ref, candidate, season, episode} |
as resolve (candidate is the release being prepared, as resolve was given it) |
resolver.cancel |
{ref} |
|
resolver.check |
{hashes = {…}} |
{cached = {…}, refused = {…}} |
resolver.library.list |
{{name, infohash, size, added}} |
|
subtitles.find |
{id, type, season, episode, ids, video, filename, size, hash} |
{{id, lang = "eng", url, name, format = "srt"}}, at an address on its hosts: format "srt" or "vtt", text; "pgs", a Blu-ray's pictures (the .sup stream as it is), which Mantle draws; "vobsub" (a DVD's), "dvb" (a TV broadcast's) or "xsub" (DivX's) pictures, which Mantle lists but cannot show (no url, as a "pgs" one a server cannot send); video, as for finder.find; it is asked first with the title alone, then again once a stream plays, with that file's filename, size (bytes) and hash (the OpenSubtitles hash, 16 hex digits, left out if the file cannot be read in parts), so subtitles made for that very file can be found: what it answers then replaces the first answer |
importer.run |
{library = {{…title, added}}, watched = {{…title, season, episode, at}}, progress = {{…title, season, episode, seconds, length, percent, at}}, lists = {{name, items = {…titles}}}}; times in seconds since 1970, a title as {id, type, name, year, poster, ids}. Mantle merges it into the profile: new titles keep their order, only what changed changes, nothing comes twice and nothing goes. |
|
account.start |
{code, url, open, expires_in, interval} |
|
account.poll |
{pending = true} or {done = true} |
|
account.info |
{name, plan, expires} |
|
account.sign_out, account.signed_in |
; whether there is an account to use |
A source's name is its release name ("Show.S01E02.1080p.WEB-DL…"): Mantle
reads its quality and matches it to the episode itself.
What a plugin can use
The sandbox is Lua 5.1 (gopher-lua) with string, table and math, and no
io, os, debug, load or dofile. require("myplugin.api") loads
one of the plugin's own modules (api.lua), and nothing else. Mantle's own
functions are the mantle table's, as Neovim's are vim's:
mantle.json |
decode(text), encode(v), null, array([t]) (a table that leaves as an array even when empty; an empty table is otherwise null) |
mantle.http |
get(url, opts), post, put, delete, request{method, url, …}. opts: query, headers, form, json, body, timeout (seconds), redirect = false (answer a redirect as it is). Returns {status, ok, headers, body, url} and res:json(). all({request, …} [, each]) asks several at once (each as request takes it; 16 at a time, 64 at most in a call) and returns their answers in order once all have come; one that failed is {ok = false, status = 0, error} and does not stop the others. each(i, answer), if given, hears each as it comes, first come first. Only with the net permission, and only to its hosts. |
mantle.xml |
parse(text) → {name, attr, text, children}; children(node, name), first(node, name), text(node, name) |
mantle.re |
Go regular expressions (RE2): test(s, p), match(s, p) (its groups), find_all(s, p), replace(s, p, with), split(s, p) |
mantle.url |
escape(s), path(s), query(t), parse(u), unescape(s) |
mantle.html |
unescape(s): text with its HTML character references read as what they stand for (O'Dea, ', &), once; only whole ones, ended by ; |
mantle.torrent |
infohash(file): a .torrent file's info hash (nil if it is not one). hash(candidate): a release's info hash, from its infohash or its magnet link, as 40 lower-case hex digits (a base-32 one is converted; nil if it has none). pick(files, req): which of a torrent's files plays, as its place in files (each {name, size, index}, index from 0 as a finder's fileIdx counts): the one the finder named, else the largest video of req.season/req.episode, else the largest video; never a sample (nil if none is a video) |
mantle.release |
parse(name) → {title, year, season, episode, episodes, resolution, source, codec, hdr, audio, group, quality, tag, …} |
mantle.time |
now() (seconds), parse(text [, layout]), date(t) → "2006-01-02", format(t, layout) |
mantle.store |
get(k), set(k, v), delete(k): the plugin's own data, kept between runs (256 KB a value, 2 MB in all) |
mantle.cred |
get(k), set(k, v), delete(k): secrets (256 KB a value, 1 MB in all). Only with the credentials permission. |
mantle.log |
info(…), warn(…), error(…), and print: the plugin log in Mantle's inspector |
mantle.hash, mantle.base64 |
hash.sha1/sha256/md5(s) (hex), base64.encode/decode |
mantle.sleep(seconds) |
waits, within the call's time (at most 30 seconds) |
mantle.so_far(v) |
what the call has so far, as it would return it: Search shows a catalog.search's finds so far while the rest come (an addon's catalogs that have answered, while a slow one has not). What the call returns is its answer all the same. |
mantle.o, mantle.plugin |
the plugin's settings, as the call is made (read them there, not into a local at the top); plugin.id, plugin.version |
mantle.stremio |
Stremio's addon protocol: addon(link) is the plugin a Stremio addon is (an installed addon is the file return mantle.stremio.addon("https://…/manifest.json")); title(meta) and details(meta) read the protocol's metas as Mantle's titles, as Cinemeta does |
mantle.debrid |
what the debrid plugins share (Real-Debrid, TorBox): listing(fetch) (the account's torrents, kept 20 seconds), changed(), refuse(hash) and refused(want) (the hashes a rights holder reported), added(key) and forget(key, remove) (what this plugin added), pick(files, req, shape), magnet(hash, magnet), stuck(ref, metadata, idle), done(ref), retry(res, opts) (a 429 is asked again) |
mantle.service |
what a service's plugins share: unanswered(res, who) (logs a refused answer; returns what to tell the user) and expired(ends, forget) (a device sign-in whose code has run out) |
Write patterns in long brackets: mantle.re.match(s, [[(\d+)\s*min]]). In a
quoted Lua string "\d" is just d.
Limits: a call has 30 seconds (60 for a request's timeout), kept also
while Mantle reads what the call returns or encodes; a response 16 MB, and all
of one http.all together 64 MB; a table that crosses out of the script (a
return value, json.encode, a store or request body) at most 4 MB of text,
a million values and 64 levels deep. Memory is held by what makes it, as the
interpreter counts none: string.rep makes at most 1 MB; table.concat,
string.format, string.gsub and mantle.re.replace at most 32 MB, refused
before they are made where their size is known: gsub and re.replace count
their matches first, so a replacement put in once is sized by what it puts in
(a gsub replacement function or table is counted as it returns, and stopped
past 32 MB). What Mantle hands
to one call (response bodies, decoded JSON, what it kept, the strings
mantle.re.match and find_all return) is counted against 256 MB, and so is
the reading of the plugin (its file, and its init), which may take 5
seconds. The app's heap growing by more than 1 GB while a call runs stops it
(a backstop for what cannot be counted: the .. operator, tables that only
grow; growth by anything else at the same time counts too). Lua patterns
(string.find, match, gmatch, gsub) cannot be stopped from outside: a
call that goes on 0.2 seconds past its deadline is answered with an error and
abandoned, and its worker is closed when it ends. At most 8 abandoned workers
run in the whole app, and while that many are still running a call that needs
a worker fails at once; each abandonment is logged with the plugin's id. Up to
four calls into a plugin run at once, each in its own Lua state, so variables
at the top of the script are not shared between calls: keep what must last in
mantle.store.
Tests
Every plugin has tests in tests/: a call, what the network answers while
it runs, and what must come back. Nothing else is reachable, so they run the
same anywhere, without an account.
{
"about": "What this shows.",
"call": "metadata.details",
"arg": { "id": "tt0111161", "type": "movie" },
"now": "2026-10-05T12:00:00Z",
"settings": { "url": "…" }, "secrets": { "key": "…" }, "store": { "k": 1 },
"http": [
{ "method": "GET", "url": "https://api.example.com/meta/tt0111161", "status": 200, "body": { … } },
{ "method": "POST", "url": "…", "form": { "code": "x" }, "requestHeaders": { "Authorization": "Bearer t" }, "text": "<xml/>", "headers": { "Content-Type": "text/xml" } }
],
"want": { "name": "The Shawshank Redemption", "cast": [{ "name": "Tim Robbins" }], "episodes": null },
"wantSecrets": { "access": "…" }, "wantStore": { "device": null }
}
callis a function by its place:catalog.page,account.start,refresh.healthruns the health check:wantis its lines,[{ "level": "ok", "text": "…" }].- A request matches on its method (
GETif none), its address (its path as escaped, its query in any order), and what it must send:formfields,json(its JSON body, matched in part aswantis) andrequestHeaders. It is answered withstatus(200 if none),headers, and a body:body(JSON),text, orfile. Each answers once unless"repeat": true; a request with no answer fails the test, as does an answer never asked for. wantis matched in part: an object's keys (more are fine), a list's first items in order ({"$count": n, "$items": […]}for an exact count),"*"for anything,nullfor nothing. Or"error": part of the error."file": "pages/big.json"answers with a file beside the test (in a folder of its own: everytests/*.jsonis a test)."together": trueon answers makes each come only once every answer marked so has been asked for: the test fails for a plugin that asks for them one after another instead of at once (http.all).
Run them all from the app's repository with go test ./internal/plugin -run TestPlugins. Record answers from the real service, then trim them to the
few items a test needs.
This page is made from plugins/README.md in the repository.