enricher plugin

Writing a metadata enricher

An enricher adds fields to a link that has just resolved — a season and an episode read from a release name, a rating looked up at a service. What it adds is stored beside the core fields with the plugin that said so, and shown on the candidate in the LinkGrabber and on the package and the queue row it becomes.

Scaffold	rdownloader plugin new --type enricher
plugin_type	enricher
World	enricher-plugin
Exports	enrich
Template	sdk/templates/enricher
Contract	Interface enricher

What the host promises

• Your fields are added, never substituted. A name that collides with something the core already resolved is dropped and counted, so you cannot rewrite a file name or a size. Prefix every name with your slug and it never collides.
• You are only asked once the person has switched enrichment on. It is off by default, which is why it is safe for an enricher to reach outwards.
• What reaches you is filtered. Credentials in the indexer's attributes are dropped or redacted before known is handed over.

Permissions

The scaffold asks for nothing: it reads the file name it is handed. An enricher that looks something up adds net_http with exactly the hosts it calls. An enricher runs without an account, so no {{secret:…}} is expanded for it: a service that wants an API key cannot be reached from one.

[extension] claims narrows which links it is offered — empty means every link.

Ask for exactly what you use: the install preview shows every grant, and a component importing an interface its manifest does not grant cannot be instantiated. Every capability is listed under Capabilities.

Rules worth knowing first

An empty list means nothing to add, not a failure — most links have nothing for any given enricher. A source that is silent, slow or talking nonsense should leave the row exactly as the online check left it.

Step by step

1. Scaffold it

plugin new reads its templates from sdk/templates, so run it from a checkout of the repository:

git clone https://github.com/degoya/rDownloader.git
cd rDownloader
rdownloader plugin new --type enricher --out ../myenricher
cd ../myenricher

Without an installation of rDownloader, the packaging tool rd-pack — cargo build --profile release-test -p rd-pack in the checkout — takes the same arguments: target/release-test/rd-pack plugin new --type enricher --out ../myenricher.

The directory name becomes the crate name and the plugin's slug (--name sets another). The scaffold gets its own plugin id, its own copy of the contract in wit/rdownloader.wit and its own Ed25519 key pair: plugin-signing.key, whose public half is already in manifest.toml. Keep that file out of version control.

2. Make it yours

• src/lib.rs reads the name; replace it with what your enricher knows.
• src/guest.rs holds enrich.
• manifest.toml: [extension] claims, and net_http if you look something up.
• locales/en.json: the English text of every failure code you report.

Change description and author under [metadata], and read the comment at the top of src/lib.rs: it states what the host promises this type.

3. Test it

cargo test

The unit tests need no WebAssembly toolchain: only src/guest.rs is wasm32-specific. Give every answer of your provider you read a test of its own.

4. Build the component

cargo build --release --target wasm32-unknown-unknown
wasm-tools component new target/wasm32-unknown-unknown/release/myenricher.wasm -o target/myenricher.wasm

This needs the wasm32-unknown-unknown target and wasm-tools 1.261.0, the version the bundled plugins are made with: cargo build makes a core module that carries the world src/guest.rs generates, and wasm-tools component new turns it into the component. The plugin is built without WASI: a component importing anything outside rdownloader:plugin is refused — see Building without WASI.

5. Package and sign it

rdownloader plugin package --manifest manifest.toml \
  --component target/myenricher.wasm \
  --locales locales --key plugin-signing.key --output myenricher.rdplug
rdownloader plugin conformance myenricher.rdplug --json

conformance answers whether this application would run the package; it has to be clean before you publish. For a key that outlives the scaffold, rdownloader plugin keygen --role plugin --output ./keys writes a pair: the Base64 in the .pub file goes into public_key, and key_id gets a name of your own. In CI, RDOWNLOADER_PLUGIN_SIGNING_KEY holding the private key's PEM text replaces --key. Details: Packaging, signing and distribution.

6. Install and trust it

For a first try without signing, package with --development instead of --key and start rdownloader serve --plugin-development-mode, the only mode that accepts an unsigned package.

Install a signed package under Settings → Plugins → Add as an upload, or with rdownloader plugin install myenricher.rdplug --root data/plugins. Review before installing shows every permission and the signing key; a key this installation has not seen asks to be trusted — compare its fingerprint. The message after installing says whether the plugin runs at once or after the next restart; see Installing and trust.

Switch on Ask enricher plugins about links under Settings → Post-processing → Scripts & upload, then paste a link your plugin is offered: your fields show as chips on the candidate.

7. Publish it

Publish the .rdplug together with your key's fingerprint, or — so that people get your new versions in the Catalogue — in a plugin repository of your own: a signed index built with rdownloader plugin index build and a repository-role key. A repository only delivers: every package in it still needs your plugin key, approved by the person installing it. See A repository index and Running a plugin repository.

The SDK's reusable CI workflow, sdk/ci/plugin.yml, builds, checks the imports, packages and runs conformance on every push and pull request; it signs only on a push to the default branch or a tag, so a pull request never sees the key.

Read next

• Metadata enrichers in the plugin reference — what the host does with each call, in full
• Interface enricher — every function and type, generated from the contract
• Developing a plugin — the tools, translations, errors and what every type shares
• The enricher template on GitHub