source-api

module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: Apache-2.0

README

source-api

The source plugin API of Panelarr: the panelarr.source.v1 protos, the code generated from them, and a Go SDK for writing and hosting source plugins.

A source plugin serves one or more sources: catalogues of series that can be browsed (popular, latest, search with filters), with chapters made of pages. Plugins run out of process. The Panelarr server starts them as child processes (managed) or connects to them by URL (standalone), and talks to them over gRPC.

What's here

Path What
proto/panelarr/source/v1 The protos: SourcePluginService and its messages
proto/panelarr/jobs/v1 The job and run model Panelarr's services share, used by the JOBS calls
gen/ Generated Go (messages, gRPC, Connect) and the OpenAPI document of the HTTP/JSON mapping
sdk/plugin Write a plugin: plugin.Main runs it managed (go-plugin) or standalone (--listen), errors with reasons, plugin configuration
sdk/client Host plugins: managed, remote (gRPC), over your own gRPC connection, or in-process
sdk/httpx HTTP clients per source that follow network profiles: proxies, solvers, rate limits, DoH, cookies
sdk/jobs Background jobs for plugins: schedules, runs, history and the JOBS calls
sdk/settings JSON Schema settings and configuration: validation and defaults
sdk/conformance, cmd/source-conformance The conformance suite every plugin must pass, as a library and a CLI
sdk/plugintest, sdk/examples/static-source A made-up plugin for tests, and an example plugin built on it

Any language can implement the API: plain protobuf and gRPC are enough. Go plugins and hosts get the SDK: see writing a plugin and hosting plugins.

Using the protos

  • Go: go get github.com/panelarr/source-api and import github.com/panelarr/source-api/gen/panelarr/source/v1.
  • Other languages: copy proto/ at a tagged version (or use it as a buf input) and generate code with your usual tools.

Development

make setup   # installs pinned tools (buf, protoc plugins, golangci-lint, govulncheck) into ./bin
make gen     # regenerates gen/ from the protos
make check   # format check, lint, breaking-change check, vulnerabilities and tests
make help    # lists every target

See CONTRIBUTING.md and docs/.

Licence

Apache License 2.0 (LICENSE): the protos, the generated code and the SDK, so that plugins and hosts under any licence can use them.

Directories

Path Synopsis
cmd
source-conformance command
Command source-conformance checks a running source plugin (or a plugin binary it starts itself) against the panelarr.source.v1 protocol and prints a report.
Command source-conformance checks a running source plugin (or a plugin binary it starts itself) against the panelarr.source.v1 protocol and prints a report.
gen
openapi
Package openapi embeds the OpenAPI document generated from the source API protos: the HTTP/JSON mapping of panelarr.source.v1.
Package openapi embeds the OpenAPI document generated from the source API protos: the HTTP/JSON mapping of panelarr.source.v1.
sdk
client
Package client connects a host (the Panelarr server, or any program) to source plugins: managed binaries it starts itself, remote plugins it reaches by URL, and in-process plugins for tests.
Package client connects a host (the Panelarr server, or any program) to source plugins: managed binaries it starts itself, remote plugins it reaches by URL, and in-process plugins for tests.
conformance
Package conformance checks that a source plugin follows the panelarr.source.v1 protocol.
Package conformance checks that a source plugin follows the panelarr.source.v1 protocol.
examples/static-source command
Command static-source is a minimal source plugin that serves two made-up sources.
Command static-source is a minimal source plugin that serves two made-up sources.
httpx
Package httpx gives source plugins HTTP clients that follow the network profiles their host pushes per source (SetNetworkProfile): the proxy (http, https or socks5, with credentials), a challenge solver (FlareSolverr/Byparr), a rate limit (per source or per host), a concurrency cap, the user agent, extra headers, DNS over HTTPS, a cookie jar (its own or shared with other sources) and timeouts.
Package httpx gives source plugins HTTP clients that follow the network profiles their host pushes per source (SetNetworkProfile): the proxy (http, https or socks5, with credentials), a challenge solver (FlareSolverr/Byparr), a rate limit (per source or per host), a concurrency cap, the user agent, extra headers, DNS over HTTPS, a cookie jar (its own or shared with other sources) and timeouts.
jobs
Package jobs runs a plugin's background jobs and answers the job calls of the JOBS capability (ListJobs, GetJob, ListJobRuns, GetJobRun, RunJob, CancelJobRun) with the shared panelarr.jobs.v1 model.
Package jobs runs a plugin's background jobs and answers the job calls of the JOBS capability (ListJobs, GetJob, ListJobRuns, GetJobRun, RunJob, CancelJobRun) with the shared panelarr.jobs.v1 model.
plugin
Package plugin is the Go SDK for writing source plugins for Panelarr.
Package plugin is the Go SDK for writing source plugins for Panelarr.
plugintest
Package plugintest provides a made-up source plugin for tests: hosts can run against it, and the SDK's own tests and the example plugin use it.
Package plugintest provides a made-up source plugin for tests: hosts can run against it, and the SDK's own tests and the example plugin use it.
settings
Package settings helps plugins describe and validate their settings with JSON Schema (draft 2020-12), the format Panelarr hosts use to render settings and configuration forms.
Package settings helps plugins describe and validate their settings with JSON Schema (draft 2020-12), the format Panelarr hosts use to render settings and configuration forms.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL