loon-plugins

README

loon-plugins

A collection of plugins for the loon framework.

---

New or changed plugins are held to CHECKLIST.md — contract, security, i18n-readiness, admin surface, jobs, docs, tests, and how each item is verified.

Before writing one, read SEAMS.md — every shared system a plugin can reach for (41 declared contracts, grouped by what they are for), the rules they live by, and what is still duplicated across the 49 plugins because nothing was there to reach for. It answers the question an author asks first and currently answers by grepping: does this already exist?

Each plugin is a self-describing module a loon host imports and boots. The job machinery (RegisterJob, RunLoop, off-peak gating, the /admin/jobs view) lives in loon's schedule package, so a plugin inherits the scheduler for free — what a plugin declares is its data surface: its own Postgres schema, or a set of narrow ports the host injects.

Plugins

Plugin	What it is
usenet	A full Usenet indexer — multi-provider fleet with per-backbone crawl state, multi-host coordination (leases + term assignment), pluggable staging (Postgres or Redis), a data-driven 24-rule junk engine + operator blacklist, NZB assembly, and health checking. Runs standalone or, in host-sink mode, hands assembled releases to a host's NZB domain (the ReleaseSink/ReleaseHealthStore seams). Owns its usenet schema; NNTP via loon/nntp.
scraper	Generic metadata scraper — shared jobs over a registry of pluggable catalog.MetadataSource modules (anidb, tmdb, mangadex, …).
catalog	Newznab category-tree taxonomy — the content classification a host and the usenet plugin categorise releases against.
backup	Single-job site backup: pg_dump + static dirs into one archive, with a free-disk pre-flight.
backups	Capability-hook backup — runs every plugin's Backupable hook into one archive.
dbmaint	Database maintenance jobs — pg_repack, reindex, and vacuum, off-peak-gated.
stats	Collects every plugin's StatContributor hook into a cached site-stats snapshot.
dailyreward	A home-page daily-points card (points sink demo).
pointstore	A points sink / profile-flair store.
anidbscraper	Mechanics demo — AniDB as a standalone host-data worker plugin (injected ports + SetDeps).
trackerdir	The external-tracker directory: facts (domains, categories, search precision, auth, politeness) for ~600 trackers, extracted by scripts/gen_trackerdir.py from both Prowlarr corpora — the community Cardigann YAML and the native C# majors (BTN, AnimeBytes, HDBits…). A data library, not a plugin — see the package comment for what is deliberately NOT taken.
pluginapi	Neutral capability contracts both sides import (never each other): UsenetIndex/UsenetAdmin, the ReleaseSink/ReleaseHealthStore seams, CatalogSink/Fillable, Backupable/StatContributor, host-data ports.

Plugin archetypes

Archetype	Owns a schema?	Data access	Example
Self-contained	Yes (Metadata.Migrations)	core.Storage.SchemaDB	usenet
Host-data worker	No	narrow ports injected via SetDeps	anidbscraper
Capability hook	No	reads peers off the extension registry	backups, stats

How a host consumes a plugin

1. In the host's go.mod (sibling-checkout replace until loon tags releases):

   require github.com/the-loon-clan/loon-plugins v0.0.0-...
   replace github.com/the-loon-clan/loon-plugins => ../loon-plugins
   

2. Import the plugin — its init() self-registers. Self-contained plugins need only a blank import; host-data plugins also call SetDeps(...) before core.Boot:

   import _ "github.com/the-loon-clan/loon-plugins/usenet"   // self-contained
   

3. Docker: a replace pointing outside the build context needs a BuildKit build-context (--build-context loonplugins=../loon-plugins + COPY --from=loonplugins) — the same three-way contract loon uses.

See loon-demo-site for a working host that wires usenet, scraper, catalog, backups, stats, dailyreward, and pointstore.

Development

make help      # the targets
make check     # what CI runs: vet, sqllint, sentinels, test
make itest     # the tests that need a real Postgres, against a disposable one

The toolchain runs in a container (scripts/go.sh says why), and that script mounts the PARENT directory: go.mod carries replace github.com/the-loon-clan/loon => ../loon, so keep loon checked out beside this repo or the module graph will not resolve.

CONTRIBUTING.md covers what each check exists for and where member-facing words belong. SECURITY.md covers reporting, and what the shared guards do and do not promise.

License

MIT — see LICENSE.