Lidarr.Plugin.Common

Shared utilities, resilience policies, and packaging helpers for Lidarr streaming plugins. Lidarr.Plugin.Abstractions stays host-owned; each plugin ships its own copy of Lidarr.Plugin.Common inside a private AssemblyLoadContext.

Quick start

Role	Start here
Plugin author	Quickstart: Build a Plugin
Host maintainer	Quickstart: Load Plugins Safely
Library contributor	Developer guide

Key capabilities

• ALC isolation — each plugin loads Common in a private AssemblyLoadContext; the host shares Lidarr.Plugin.Abstractions and two Microsoft.Extensions abstractions. → Plugin Isolation
• Streaming plugin bridge — StreamingPlugin<TModule, TSettings> base class wires DI, settings, lifecycle, and the host bridge. → Plugin Bridge
• Resilient HTTP pipeline — builder → options → executor → cache flow with retries, deadlines, concurrency caps, and request deduplication. → HTTP Flow · Key Services
• Security helpers — PathTraversalGuard, SecureMemory, TokenProtectorFactory, LLM prompt sanitization. → Shared Helpers Catalog
• TestKit — reusable test fixtures, HTTP handlers, ALC harness, and ecosystem-parity guard tests. → Testing with the TestKit
• Packaging — PluginPack.psm1 standardises build, manifest validation, and ZIP packaging for every plugin release. → Packaging
• Ecosystem parity — mechanical guard tests enforce that all plugins follow the same canonical patterns. → Ecosystem Parity and Guards

What's New

Latest release: v1.17.0 — May 25, 2026. Current dev: v1.18.0-dev (unreleased — see CHANGELOG).

• v1.18.0-dev (unreleased) — release-size consolidation (AlbumSizeEstimator, MultiQualityReleaseBuilder); shared streaming/manifest seams (HlsManifestParser alongside DashManifestParser, CencSampleDecryptor); HeuristicQueryOptimizer (rule-based IQueryOptimizer); PathTraversalGuard trailing-separator fix; opt-in canonical-abstractions packaging gate; IAuthFailureGateRegistry deprecated.
• v1.17.0 — Wave-21 parity helpers (PathTraversalGuard.ContainsTraversalAttempt probe, AlbumDownloadUri parser, AlbumReleaseInfoBuilder Edition/Explicit/Live slots, unified plugin version-bump helper).
• v1.16.0 — SlidingWindowAuthFailureHandler (K-of-N-in-W sliding-window circuit semantics, sibling of DefaultAuthFailureHandler); unblocks brainarr's LlmAuthCircuit convergence onto the shared Common stack.
• v1.15.0 — BoundedConcurrentDictionary richer API surface (indexer setter, ContainsKey, Values, IEnumerable<KeyValuePair>); SecureMemory + Conservative rate-limit profile + PagedResponseValidator.
• v1.14.x — AuthFailureGate surface (registry, delegating handler, gated exception) + multi-plugin ALC coexistence proof + ecosystem version contract enforcement.
• v1.13.x — Plugin packaging contract + plugin version contract + published-release installability checks (test kit).
• v1.12.0 — AlbumReleaseInfoBuilder (lift wave A item 8); HostBridgeDownloadOrchestrator (lift wave A item 2); RetryPolicyOptions.ForLocalProviders preset.
• v1.8.0 — ecosystem version contract via versionContract section in scripts/parity-spec.json; forbiddenFields enforcement wired into parity-lint; ALC multi-plugin co-existence fix.

Release notes: v1.17.0 · v1.16.0

Ecosystem-wide parity (every plugin × every cross-cutting concern): see docs/ECOSYSTEM_PARITY_MATRIX.md.

Choose your adventure

Plugin authors

• Create a plugin project
• Use the streaming plugin bridge
• Test a streaming plugin end-to-end
• Map settings with the bridge
• Understand the HTTP flow (Builder → Options → Executor → Cache)
• Key services and utilities
• Manage sessions/tokens
• Test with the shared TestKit
• Package with PluginPack.psm1
• FAQ for plugin authors
• Bump the submodule in downstream repos

Host maintainers

• AssemblyLoadContext isolation
• Plugin manifest schema & validation
• Compatibility matrix & EOL policy
• Migration checklist for legacy plugins

Library contributors

• Abstractions overview & API baselines
• Developer guide
• Docs & tooling guide
• Packaging playbook
• Upgrade checklist for releases

Wiki

Orientation pages that map what exists and where to find it — full details live in the linked docs/.

Page	Scope
Home	Wiki index and orientation for plugin authors
Architecture Overview	ALC isolation, bridge runtime, layer diagram
SDK and Extension Points	StreamingPlugin<TModule,TSettings>, DI seams, provider interfaces
Shared Helpers Catalog	Security, resilience, HTTP defaults, collections, validation
Ecosystem Parity and Guards	Parity matrix, promotion checklist, drift enforcement
Versioning and Submodule Pinning	Version contract, submodule workflow, upgrade checklist
Testing with the TestKit	TestKit fixtures, HTTP handlers, ALC harness
CI and Packaging	PluginPack.psm1, reusable workflows, SHA pins

Documentation workflow

• Markdown lives under docs/; every page is the single source for its topic.

• Code samples use snippet includes ( ```csharp file=...) verified by tools/DocTools/SnippetVerifier.

• Run the docs toolchain locally:

  # lint + spell check + links + snippets
  gh workflow run docs.yml --ref <branch>
  # or run manually
  dotnet run --project tools/DocTools/SnippetVerifier

• GitHub Actions docs.yml enforces markdownlint, cspell, and link checking on every documentation PR; Vale prose-linting and snippet compilation also run but are non-blocking (continue-on-error).

Repository layout

• src/ – library source (Lidarr.Plugin.Common, Lidarr.Plugin.Abstractions).
• tests/ – unit/integration tests.
• examples/ – sample hosts, plugin bridge snippets, manifest helpers.
• docs/ – knowledge base described above.
• tools/ – Snippet verifier, manifest/package automation, docs lint scripts.

Documentation

• Changelog
• Contributing
• Security
• Glossary
• Docs directory

License

MIT – see LICENSE.

Note: All product and company names (e.g., Qobuz, TIDAL, Spotify) are trademarks of their respective owners; usage here is for descriptive purposes only and does not imply endorsement.