plugins

package
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: GPL-3.0 Imports: 34 Imported by: 0

Documentation

Overview

Package plugins hosts source plugins. Plugins run as their own services (remote mode) and the server talks to them over the source plugin contract. The host keeps their settings, syncs the sources they list with their health, hands them their configuration and decides which sources each user may use.

Index

Constants

View Source
const (
	ActionInstall   = "install"
	ActionUpdate    = "update"
	ActionUninstall = "uninstall"
)

Package actions.

View Source
const (
	RetryLevelSource  = "source"
	RetryLevelPackage = "package"
	RetryLevelDefault = "default"
)

Levels a source's image retries come from.

View Source
const (
	MaxImageRetries    = 5
	MaxImageRetryDelay = 30 * time.Second
)

Image retry setting limits.

View Source
const KindNetworkPush = "network.push"

KindNetworkPush is the task kind that pushes profiles after a change.

View Source
const KindPackage = "plugin.package"

KindPackage is the task kind of installing, updating and uninstalling a package.

View Source
const MaxIconBytes = 2 << 20

MaxIconBytes caps an icon (of a package or a source).

View Source
const MaxImageBytes = 15 << 20

MaxImageBytes caps one image from a plugin.

View Source
const MaxImageRetryAfter = 30 * time.Second

MaxImageRetryAfter is the longest retry-after a page image waits out; a source asking for longer fails at once with its rate-limit error (the reader's user is waiting; downloads try again later as a task).

View Source
const PackageIconRef = "package:"

PackageIconRef is a source's icon ref meaning "its package's icon", for sources without an icon of their own. It isn't an http(s) URL, so it never names a real icon.

View Source
const Unbounded = 1024

Unbounded is the concurrency of a key nobody caps.

Variables

View Source
var (
	ErrNotFound     = errors.New("plugins: not found")
	ErrIDTaken      = errors.New("plugins: a plugin with this ID exists")
	ErrInvalidID    = errors.New("plugins: the ID must be lowercase letters, digits, '-' or '_' (up to 40)")
	ErrInvalidURL   = errors.New("plugins: the URL must be http(s)://host[:port]")
	ErrDisabled     = errors.New("plugins: the plugin is disabled")
	ErrNoConfig     = errors.New("plugins: the plugin has no configuration")
	ErrSourceAbsent = errors.New("plugins: the plugin no longer lists this source")
)

Errors callers map to responses.

View Source
var DefaultConfigFollowUp = []time.Duration{5 * time.Second, 30 * time.Second}

DefaultConfigFollowUp are the waits before each sync of a plugin after its settings were saved: plugins apply new settings in the background (adding stores, installing extensions) and report problems in their health, which these syncs pick up.

View Source
var DefaultImageRetries = []time.Duration{time.Second, 3 * time.Second}

DefaultImageRetries are the waits before each extra attempt at a page image: two more attempts, after 1 s and then 3 s.

View Source
var DefaultRecheck = []time.Duration{10 * time.Second, 30 * time.Second, time.Minute}

DefaultRecheck are the waits before each recheck of a plugin found down, so one that was only briefly away (restarting next to the server) shows as ok again within seconds instead of at the next full sync.

View Source
var DefaultStartupGrace = []time.Duration{time.Second, 2 * time.Second, 4 * time.Second}

DefaultStartupGrace are the waits between tries to reach a plugin that doesn't answer yet at startup; the last one repeats until the startup window ends.

View Source
var DefaultStartupWindow = 30 * time.Second

DefaultStartupWindow is how long after the server starts a plugin that doesn't answer yet is waited for before its first sync marks it down. Plugins started together with the server may take a while, and in a container network their names may not even resolve for the first seconds.

View Source
var ErrBadConfig = errors.New("plugins: invalid configuration")

ErrBadConfig is configuration the server can't even encode.

View Source
var ErrBadImageRetries = errors.New("at most 5 waits, each from 0 to 30000 ms")

ErrBadImageRetries is a setting out of bounds.

View Source
var ErrNoHealthChecks = errors.New("plugins: the plugin doesn't run source health checks")

ErrNoHealthChecks is a plugin without the health checks capability.

View Source
var ErrNoJobs = errors.New("plugins: the plugin has no jobs")

ErrNoJobs is a plugin without the jobs capability.

View Source
var ErrNoPackages = errors.New("plugins: the plugin doesn't install packages")

ErrNoPackages is a plugin without the package capability.

View Source
var ErrUnsupported = errors.New("plugins: the source doesn't support this")

ErrUnsupported is a call the source doesn't support (its capabilities).

Functions

func AcceptsProfiles

func AcceptsProfiles(info *sourcev1.PluginInfo) bool

AcceptsProfiles reports whether a plugin declares the network profile service: only those receive network profiles.

func AcceptsSolver

func AcceptsSolver(info *sourcev1.PluginInfo) bool

AcceptsSolver reports whether a plugin declares the solver service: only those receive a profile's solver.

func HasHealthChecks

func HasHealthChecks(info *sourcev1.PluginInfo) bool

HasHealthChecks reports whether a plugin runs scheduled source health checks that can be turned off per source.

func HasJobs

func HasJobs(info *sourcev1.PluginInfo) bool

HasJobs reports whether a plugin declares the jobs capability.

func HasPackages

func HasPackages(info *sourcev1.PluginInfo) bool

HasPackages reports whether a plugin declares the package capability.

func ImageKey

func ImageKey(sourceID string) string

ImageKey is the limits key of a source's image fetches, apart from its other calls ("source:<id>").

func PackageKey

func PackageKey(pluginID, pkg string) string

PackageKey is a package's target ID, "plugin:package".

func RatingName

func RatingName(r sourcev1.ContentRating) string

RatingName is a content rating's name: safe, mixed, nsfw or unknown.

func RemoteDialer

func RemoteDialer(u, apiKey string) client.Client

RemoteDialer speaks gRPC to plugins running as services.

Types

type Config

type Config struct {
	Schema *structpb.Struct
	Values map[string]any
}

Config is a plugin's configuration: its schema and current values.

type Dialer

type Dialer func(url, apiKey string) client.Client

Dialer returns a client for a plugin at url.

type Host

type Host struct {
	// contains filtered or unexported fields
}

Host manages the plugins.

func NewHost

func NewHost(st *store.Store, box *secret.Box, dial Dialer, log *slog.Logger) *Host

NewHost returns a host that reaches plugins with dial.

func (*Host) Applied

func (h *Host) Applied(ctx context.Context, sourceID string) (string, string, error)

Applied is what a plugin says it applies to a source: "pushed" (the server's profile), "plugin" (its own settings) or "none" (direct), or "unknown" when the plugin can't say.

func (*Host) CancelJobRun

func (h *Host) CancelJobRun(ctx context.Context, id, run string) (*jobsv1.JobRunSummary, error)

CancelJobRun cancels a plugin job's running run.

func (*Host) Chapters

func (h *Host) Chapters(ctx context.Context, v Viewer, id, key string) ([]*sourcev1.Chapter, error)

Chapters lists a series' chapters as the source reports them.

func (*Host) ClearPackageImageRetries

func (h *Host) ClearPackageImageRetries(ctx context.Context, pluginID, pkg string) error

ClearPackageImageRetries removes a package's setting: its sources use the default (or their own).

func (*Host) ClearSourceImageRetries

func (h *Host) ClearSourceImageRetries(ctx context.Context, sourceID string) error

ClearSourceImageRetries removes a source's own setting: it inherits its package's or the default.

func (*Host) Client

func (h *Host) Client(ctx context.Context, id string) (client.Client, error)

Client returns the client of an enabled plugin.

func (*Host) Config

func (h *Host) Config(ctx context.Context, id string) (Config, error)

Config returns a plugin's configuration as the plugin reports it (secrets left empty).

func (*Host) Delete

func (h *Host) Delete(ctx context.Context, id string) error

Delete removes a plugin and its sources.

func (*Host) Filters

func (h *Host) Filters(ctx context.Context, v Viewer, id string) (*sourcev1.GetFiltersResponse, error)

Filters returns a source's search filters.

func (*Host) Get

func (h *Host) Get(ctx context.Context, id string) (Plugin, error)

Get returns one plugin.

func (*Host) Icon

func (h *Host) Icon(ctx context.Context, id, ref string) (string, io.Reader, error)

Icon fetches a package's or a source's icon from ref, its icon URL as the plugin gave it: a path relative to the plugin's address (served by the plugin over HTTP with the API's credentials), or an absolute URL. The plugin's key goes only to the plugin's own address. Icons never go through the image RPC, which is for covers and pages.

func (*Host) Image

func (h *Host) Image(ctx context.Context, v Viewer, id, ref string) (string, []byte, error)

Image fetches an image through the source's plugin (its headers and network settings apply).

func (*Host) Job

func (h *Host) Job(ctx context.Context, id, job string) (*jobsv1.Job, error)

Job returns one of a plugin's jobs.

func (*Host) JobRun

func (h *Host) JobRun(ctx context.Context, id, run string) (*jobsv1.JobRun, error)

JobRun returns a plugin job's run in full.

func (*Host) JobRuns

func (h *Host) JobRuns(ctx context.Context, id, job string, status jobsv1.JobRunStatus, pageSize int32, token string) ([]*jobsv1.JobRunSummary, string, error)

JobRuns lists a plugin job's runs, newest first.

func (*Host) Jobs

func (h *Host) Jobs(ctx context.Context, id string) ([]*jobsv1.Job, error)

Jobs lists a plugin's jobs.

func (*Host) Latest

func (h *Host) Latest(ctx context.Context, v Viewer, id string, page uint32) (Page, error)

Latest lists a source's latest updates.

func (*Host) List

func (h *Host) List(ctx context.Context) ([]Plugin, error)

List returns every plugin.

func (*Host) ListChapters

func (h *Host) ListChapters(ctx context.Context, v Viewer, id, key string, refresh bool) ([]*sourcev1.Chapter, error)

ListChapters lists a series' chapters; refresh asks the plugin to skip its cache (update checks).

func (*Host) Load

func (h *Host) Load(ctx context.Context) error

Load connects to every stored plugin, hands each its configuration and syncs its sources. Failures are recorded, not fatal. ctx is the host's lifetime: rechecks of plugins found down run until it ends.

func (*Host) Origins

func (h *Host) Origins(ctx context.Context, id string) ([]*sourcev1.Origin, error)

Origins lists where a plugin's packages come from (e.g. stores), with their state.

func (*Host) Package

func (h *Host) Package(ctx context.Context, id, pkg string) (*sourcev1.Package, error)

Package returns one of a plugin's packages.

func (*Host) PackageIcon

func (h *Host) PackageIcon(ctx context.Context, id, pkg string) (string, io.Reader, error)

PackageIcon fetches a package's own icon. ErrNotFound when it has none.

func (*Host) PackageImageRetries

func (h *Host) PackageImageRetries(ctx context.Context, pluginID, pkg string) (ImageRetries, error)

PackageImageRetries returns what a package's sources use for their page images (unless one has its own setting).

func (*Host) Packages

func (h *Host) Packages(ctx context.Context, id string, q PackageQuery) ([]*sourcev1.Package, error)

Packages lists what a plugin offers and has installed, all pages.

func (*Host) PageImage

func (h *Host) PageImage(ctx context.Context, v Viewer, id, ref string, wait func(context.Context) error) (string, []byte, error)

PageImage fetches a page image like Host.Image, trying again after errors that may pass (see DefaultImageRetries). wait, when set, paces every attempt (the source's image limits), so retries spend the same budget as first tries.

func (*Host) Pages

func (h *Host) Pages(ctx context.Context, v Viewer, id, chapterKey string) ([]*sourcev1.Page, error)

Pages lists a chapter's pages in reading order.

func (*Host) PendingPackageTasks

func (h *Host) PendingPackageTasks(ctx context.Context, id string) (map[string]uuid.UUID, error)

PendingPackageTasks maps a plugin's packages to their queued or running task.

func (*Host) Popular

func (h *Host) Popular(ctx context.Context, v Viewer, id string, page uint32) (Page, error)

Popular lists a source's popular series.

func (*Host) PushProfiles

func (h *Host) PushProfiles(ctx context.Context, id string, force bool) (pushed, failed int, err error)

PushProfiles pushes a plugin's sources' profiles that changed (all of them with force) and keeps the server's own source limits in line with them. It returns how many pushes went and failed; failures are retried at the next sync.

func (*Host) QueuePackage

func (h *Host) QueuePackage(ctx context.Context, by uuid.UUID, p PackagePayload) (db.Task, error)

QueuePackage queues installing, updating or uninstalling a package. The same action on the same package is queued once; a plugin without the capability or turned off, or a package it doesn't know, is refused up front.

func (*Host) ReadyCheck

func (h *Host) ReadyCheck(ctx context.Context) error

ReadyCheck reports enabled plugins that are down, from their last sync (it calls no plugin). Plugins are optional: this only marks the server degraded.

func (*Host) RefreshOrigin

func (h *Host) RefreshOrigin(ctx context.Context, id, origin string) (*sourcev1.Origin, error)

RefreshOrigin fetches an origin's package list again now.

func (*Host) Register

func (h *Host) Register(ctx context.Context, n NewPlugin) (Plugin, error)

Register checks a plugin, stores it and syncs its sources.

func (*Host) RegisterPackageTasks

func (h *Host) RegisterPackageTasks(q *queue.Queue)

RegisterPackageTasks lets q run package tasks, one at a time.

func (*Host) ReloadPackage

func (h *Host) ReloadPackage(ctx context.Context, id, pkg string) (*sourcev1.Package, error)

ReloadPackage loads an installed package again (retrying a failed load, or applying settings that need it), then syncs the plugin.

func (*Host) ResolveURL

func (h *Host) ResolveURL(ctx context.Context, v Viewer, rawURL string) (Resolved, error)

ResolveURL finds the series a URL points to, asking each enabled plugin with a source v may use that resolves URLs. ErrNotFound when none knows it.

func (*Host) RunJob

func (h *Host) RunJob(ctx context.Context, id, job string, params map[string]string, who string) (*jobsv1.JobRunSummary, error)

RunJob starts a plugin's job now, on behalf of who (recorded by the plugin as who triggered it).

func (*Host) Search

func (h *Host) Search(ctx context.Context, v Viewer, id, query string, page uint32, filters []*sourcev1.FilterValue) (Page, error)

Search searches a source, with optional filter values.

func (*Host) Series

func (h *Host) Series(ctx context.Context, v Viewer, id, key string) (*sourcev1.Series, error)

Series returns a series' details.

func (*Host) SetConfig

func (h *Host) SetConfig(ctx context.Context, id string, values map[string]any) (Config, error)

SetConfig validates values with the plugin, applies them and stores them (encrypted) to hand back whenever the plugin restarts. Secret fields (writeOnly in the schema) left empty keep their stored value.

func (*Host) SetConfigFollowUp

func (h *Host) SetConfigFollowUp(delays ...time.Duration)

SetConfigFollowUp changes the waits of the syncs after a settings save.

func (*Host) SetDefaultImageRetries

func (h *Host) SetDefaultImageRetries(delays ...time.Duration)

SetDefaultImageRetries changes the default waits before each extra attempt at a page image (none: no retries), for sources without a setting of their own or their package's.

func (*Host) SetHealthCheck

func (h *Host) SetHealthCheck(ctx context.Context, sourceID string, enabled bool) (Source, error)

SetHealthCheck turns a source's scheduled health checks on or off, then syncs its plugin so the source shows it.

func (*Host) SetHub

func (h *Host) SetHub(hub *events.Hub)

SetHub makes the host tell admins about each plugin sync (plugin.health events).

func (*Host) SetLimits

func (h *Host) SetLimits(reg *limits.Registry)

SetLimits makes the host keep each source's limits (from its plugin's declared limits) in reg.

func (*Host) SetMetrics

func (h *Host) SetMetrics(m *metrics.Metrics)

SetMetrics makes the host count page image retries.

func (*Host) SetNetwork

func (h *Host) SetNetwork(n *network.Service, q *queue.Queue, also ...func(context.Context) error)

SetNetwork makes the host push network profiles from n, and queue a push whenever a profile or assignment changes; also runs in that push (e.g. to metadata providers).

func (*Host) SetPackageImageRetries

func (h *Host) SetPackageImageRetries(ctx context.Context, pluginID, pkg string, delays []time.Duration) (ImageRetries, error)

SetPackageImageRetries sets the waits for a package's sources (empty: no retries for them).

func (*Host) SetPackageLanguages

func (h *Host) SetPackageLanguages(ctx context.Context, id, pkg string, langs []string) (*sourcev1.Package, error)

SetPackageLanguages sets which of a package's languages its sources are offered in (empty: every language the plugin allows), then syncs the plugin so its sources follow.

func (*Host) SetRecheck

func (h *Host) SetRecheck(delays ...time.Duration)

SetRecheck changes the waits between rechecks of a plugin found down (none: no rechecks).

func (*Host) SetSettings

func (h *Host) SetSettings(ctx context.Context, id string, values map[string]any) (SourceSettings, error)

SetSettings changes some of a source's settings (keys left out keep their value; a secret left empty too) and returns them all.

func (*Host) SetSourceEnabled

func (h *Host) SetSourceEnabled(ctx context.Context, id string, enabled bool) (Source, error)

SetSourceEnabled turns a source on or off for everyone.

func (*Host) SetSourceImageRetries

func (h *Host) SetSourceImageRetries(ctx context.Context, sourceID string, delays []time.Duration) (ImageRetries, error)

SetSourceImageRetries sets a source's own waits before each extra attempt at its page images (empty: no retries for it).

func (*Host) SetSourcesChanged

func (h *Host) SetSourcesChanged(fn func(ctx context.Context, sourceIDs []string))

SetSourcesChanged sets what runs when sources become usable or stop being usable (turned on or off, listed again or no longer, their plugin turned on or off), with their IDs; chapters choose their copies again.

func (*Host) SetStartupGrace

func (h *Host) SetStartupGrace(delays ...time.Duration)

SetStartupGrace changes the waits for plugins not answering at startup (none: a single try).

func (*Host) SetStartupWindow

func (h *Host) SetStartupWindow(d time.Duration)

SetStartupWindow changes how long after startup plugins not answering yet are waited for.

func (*Host) Settings

func (h *Host) Settings(ctx context.Context, id string) (SourceSettings, error)

Settings returns a source's settings, read from its plugin.

func (*Host) Source

func (h *Host) Source(ctx context.Context, id string, v Viewer) (Source, error)

Source returns one source v may see, or ErrNotFound.

func (*Host) SourceIcon

func (h *Host) SourceIcon(ctx context.Context, v Viewer, id, ref string) (string, io.Reader, error)

SourceIcon fetches the icon of a source v may see (see Host.Icon). When the plugin has no icon at ref (it answers 404, e.g. for a source in a language turned off) or ref is PackageIconRef, the icon of the package that provides the source stands in. ErrNotFound when neither exists.

func (*Host) SourceImageRetries

func (h *Host) SourceImageRetries(ctx context.Context, sourceID string) (ImageRetries, error)

SourceImageRetries returns what a source uses for its page images.

func (*Host) Sources

func (h *Host) Sources(ctx context.Context, v Viewer, all bool) ([]Source, error)

Sources lists the sources v may see; with all (admins), every source, including disabled and absent ones.

func (*Host) Sync

func (h *Host) Sync(ctx context.Context, id string) (Plugin, error)

Sync refreshes a plugin's info, health and sources. A plugin that doesn't answer is recorded as down (its sources stay as they were) and rechecked soon after.

func (*Host) SyncAll

func (h *Host) SyncAll(ctx context.Context) (ok, down int, err error)

SyncAll syncs every enabled plugin and reports how many are ok and down.

func (*Host) Update

func (h *Host) Update(ctx context.Context, id string, p Patch) (Plugin, error)

Update changes a plugin. A new address or key is checked first.

type ImageRetries

type ImageRetries struct {
	// TargetKind is "package" or "source"; TargetID "plugin:package" or
	// the source's ID.
	TargetKind, TargetID string
	// Own is the setting at this level; nil when there is none (it
	// inherits).
	Own *ImageRetrySetting
	// Effective is what applies; Level where it comes from, and FromID
	// the target there (empty for the default).
	Effective []time.Duration
	Level     string
	FromID    string
}

ImageRetries is what a package or source uses for its page images.

type ImageRetrySetting

type ImageRetrySetting struct {
	Delays    []time.Duration
	UpdatedAt time.Time
}

ImageRetrySetting is the setting at one level.

type NewPlugin

type NewPlugin struct {
	// ID names this plugin instance; empty takes the plugin's own ID.
	ID     string
	URL    string
	APIKey string
}

NewPlugin is a plugin to register.

type PackagePayload

type PackagePayload struct {
	PluginID  string `json:"plugin_id"`
	PackageID string `json:"package_id"`
	Action    string `json:"action"`
	OriginID  string `json:"origin_id,omitempty"`
}

PackagePayload is a package task's payload.

type PackageQuery

type PackageQuery struct {
	Query, Lang, OriginID      string
	InstalledOnly, UpdatesOnly bool
}

PackageQuery narrows a plugin's package list.

type Page

type Page struct {
	Series      []*sourcev1.Series
	HasNextPage bool
}

Page is one page of series from a source.

type Patch

type Patch struct {
	URL     *string
	APIKey  *string
	Enabled *bool
}

Patch changes a plugin; nil fields stay. An empty APIKey removes it.

type Plugin

type Plugin struct {
	db.Plugin
	Info        *sourcev1.PluginInfo
	SourceCount int64
}

Plugin is a registered plugin with its last known info.

type Resolved

type Resolved struct {
	Source     Source
	Series     *sourcev1.Series
	BestEffort bool
}

Resolved is a series found from a pasted URL.

type Source

type Source struct {
	db.Source
	PluginEnabled bool
}

Source is a source with whether its plugin is enabled.

func (Source) Usable

func (s Source) Usable() bool

Usable reports whether the source can be called: listed by an enabled plugin and enabled itself.

type SourceSettings

type SourceSettings struct {
	Schema map[string]any
	Values map[string]any
}

SourceSettings is a source's own settings: its JSON Schema and values, with secret (writeOnly) values blanked.

type UnreachableError

type UnreachableError struct{ Reason string }

UnreachableError is a plugin that couldn't be reached or doesn't speak the source contract.

func (*UnreachableError) Error

func (e *UnreachableError) Error() string

type Viewer

type Viewer struct {
	Grants users.Grants
	Admin  bool
	// HideUnknown hides sources without a content rating from users.
	HideUnknown bool
	// Testing lets an admin browse a source turned off, to try it before
	// turning it on. It never reaches sources no longer listed or of a
	// plugin turned off.
	Testing bool
	// AnyKnown lets an admin see every known source, absent ones too (for
	// their icons on the admin's source list; nothing is called on them).
	AnyKnown bool
}

Viewer is who is browsing: it decides which sources show.

func (Viewer) Visible

func (v Viewer) Visible(s Source) bool

Visible reports whether v may see and use s. Admins see every usable source (testing, also ones turned off); users only allowed ones within their ceiling.

Directories

Path Synopsis
Package pluginstest serves made-up source plugins for tests over the real wire (gRPC on cleartext HTTP/2).
Package pluginstest serves made-up source plugins for tests over the real wire (gRPC on cleartext HTTP/2).

Jump to

Keyboard shortcuts

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