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
- Variables
- func AcceptsProfiles(info *sourcev1.PluginInfo) bool
- func AcceptsSolver(info *sourcev1.PluginInfo) bool
- func HasHealthChecks(info *sourcev1.PluginInfo) bool
- func HasJobs(info *sourcev1.PluginInfo) bool
- func HasPackages(info *sourcev1.PluginInfo) bool
- func ImageKey(sourceID string) string
- func PackageKey(pluginID, pkg string) string
- func RatingName(r sourcev1.ContentRating) string
- func RemoteDialer(u, apiKey string) client.Client
- type Config
- type Dialer
- type Host
- func (h *Host) Applied(ctx context.Context, sourceID string) (string, string, error)
- func (h *Host) CancelJobRun(ctx context.Context, id, run string) (*jobsv1.JobRunSummary, error)
- func (h *Host) Chapters(ctx context.Context, v Viewer, id, key string) ([]*sourcev1.Chapter, error)
- func (h *Host) ClearPackageImageRetries(ctx context.Context, pluginID, pkg string) error
- func (h *Host) ClearSourceImageRetries(ctx context.Context, sourceID string) error
- func (h *Host) Client(ctx context.Context, id string) (client.Client, error)
- func (h *Host) Config(ctx context.Context, id string) (Config, error)
- func (h *Host) Delete(ctx context.Context, id string) error
- func (h *Host) Filters(ctx context.Context, v Viewer, id string) (*sourcev1.GetFiltersResponse, error)
- func (h *Host) Get(ctx context.Context, id string) (Plugin, error)
- func (h *Host) Icon(ctx context.Context, id, ref string) (string, io.Reader, error)
- func (h *Host) Image(ctx context.Context, v Viewer, id, ref string) (string, []byte, error)
- func (h *Host) Job(ctx context.Context, id, job string) (*jobsv1.Job, error)
- func (h *Host) JobRun(ctx context.Context, id, run string) (*jobsv1.JobRun, error)
- func (h *Host) JobRuns(ctx context.Context, id, job string, status jobsv1.JobRunStatus, ...) ([]*jobsv1.JobRunSummary, string, error)
- func (h *Host) Jobs(ctx context.Context, id string) ([]*jobsv1.Job, error)
- func (h *Host) Latest(ctx context.Context, v Viewer, id string, page uint32) (Page, error)
- func (h *Host) List(ctx context.Context) ([]Plugin, error)
- func (h *Host) ListChapters(ctx context.Context, v Viewer, id, key string, refresh bool) ([]*sourcev1.Chapter, error)
- func (h *Host) Load(ctx context.Context) error
- func (h *Host) Origins(ctx context.Context, id string) ([]*sourcev1.Origin, error)
- func (h *Host) Package(ctx context.Context, id, pkg string) (*sourcev1.Package, error)
- func (h *Host) PackageIcon(ctx context.Context, id, pkg string) (string, io.Reader, error)
- func (h *Host) PackageImageRetries(ctx context.Context, pluginID, pkg string) (ImageRetries, error)
- func (h *Host) Packages(ctx context.Context, id string, q PackageQuery) ([]*sourcev1.Package, error)
- func (h *Host) PageImage(ctx context.Context, v Viewer, id, ref string, ...) (string, []byte, error)
- func (h *Host) Pages(ctx context.Context, v Viewer, id, chapterKey string) ([]*sourcev1.Page, error)
- func (h *Host) PendingPackageTasks(ctx context.Context, id string) (map[string]uuid.UUID, error)
- func (h *Host) Popular(ctx context.Context, v Viewer, id string, page uint32) (Page, error)
- func (h *Host) PushProfiles(ctx context.Context, id string, force bool) (pushed, failed int, err error)
- func (h *Host) QueuePackage(ctx context.Context, by uuid.UUID, p PackagePayload) (db.Task, error)
- func (h *Host) ReadyCheck(ctx context.Context) error
- func (h *Host) RefreshOrigin(ctx context.Context, id, origin string) (*sourcev1.Origin, error)
- func (h *Host) Register(ctx context.Context, n NewPlugin) (Plugin, error)
- func (h *Host) RegisterPackageTasks(q *queue.Queue)
- func (h *Host) ReloadPackage(ctx context.Context, id, pkg string) (*sourcev1.Package, error)
- func (h *Host) ResolveURL(ctx context.Context, v Viewer, rawURL string) (Resolved, error)
- func (h *Host) RunJob(ctx context.Context, id, job string, params map[string]string, who string) (*jobsv1.JobRunSummary, error)
- func (h *Host) Search(ctx context.Context, v Viewer, id, query string, page uint32, ...) (Page, error)
- func (h *Host) Series(ctx context.Context, v Viewer, id, key string) (*sourcev1.Series, error)
- func (h *Host) SetConfig(ctx context.Context, id string, values map[string]any) (Config, error)
- func (h *Host) SetConfigFollowUp(delays ...time.Duration)
- func (h *Host) SetDefaultImageRetries(delays ...time.Duration)
- func (h *Host) SetHealthCheck(ctx context.Context, sourceID string, enabled bool) (Source, error)
- func (h *Host) SetHub(hub *events.Hub)
- func (h *Host) SetLimits(reg *limits.Registry)
- func (h *Host) SetMetrics(m *metrics.Metrics)
- func (h *Host) SetNetwork(n *network.Service, q *queue.Queue, also ...func(context.Context) error)
- func (h *Host) SetPackageImageRetries(ctx context.Context, pluginID, pkg string, delays []time.Duration) (ImageRetries, error)
- func (h *Host) SetPackageLanguages(ctx context.Context, id, pkg string, langs []string) (*sourcev1.Package, error)
- func (h *Host) SetRecheck(delays ...time.Duration)
- func (h *Host) SetSettings(ctx context.Context, id string, values map[string]any) (SourceSettings, error)
- func (h *Host) SetSourceEnabled(ctx context.Context, id string, enabled bool) (Source, error)
- func (h *Host) SetSourceImageRetries(ctx context.Context, sourceID string, delays []time.Duration) (ImageRetries, error)
- func (h *Host) SetSourcesChanged(fn func(ctx context.Context, sourceIDs []string))
- func (h *Host) SetStartupGrace(delays ...time.Duration)
- func (h *Host) SetStartupWindow(d time.Duration)
- func (h *Host) Settings(ctx context.Context, id string) (SourceSettings, error)
- func (h *Host) Source(ctx context.Context, id string, v Viewer) (Source, error)
- func (h *Host) SourceIcon(ctx context.Context, v Viewer, id, ref string) (string, io.Reader, error)
- func (h *Host) SourceImageRetries(ctx context.Context, sourceID string) (ImageRetries, error)
- func (h *Host) Sources(ctx context.Context, v Viewer, all bool) ([]Source, error)
- func (h *Host) Sync(ctx context.Context, id string) (Plugin, error)
- func (h *Host) SyncAll(ctx context.Context) (ok, down int, err error)
- func (h *Host) Update(ctx context.Context, id string, p Patch) (Plugin, error)
- type ImageRetries
- type ImageRetrySetting
- type NewPlugin
- type PackagePayload
- type PackageQuery
- type Page
- type Patch
- type Plugin
- type Resolved
- type Source
- type SourceSettings
- type UnreachableError
- type Viewer
Constants ¶
const ( ActionInstall = "install" ActionUpdate = "update" ActionUninstall = "uninstall" )
Package actions.
const ( RetryLevelSource = "source" RetryLevelPackage = "package" RetryLevelDefault = "default" )
Levels a source's image retries come from.
const ( MaxImageRetries = 5 MaxImageRetryDelay = 30 * time.Second )
Image retry setting limits.
const KindNetworkPush = "network.push"
KindNetworkPush is the task kind that pushes profiles after a change.
const KindPackage = "plugin.package"
KindPackage is the task kind of installing, updating and uninstalling a package.
const MaxIconBytes = 2 << 20
MaxIconBytes caps an icon (of a package or a source).
const MaxImageBytes = 15 << 20
MaxImageBytes caps one image from a plugin.
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).
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.
const Unbounded = 1024
Unbounded is the concurrency of a key nobody caps.
Variables ¶
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.
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.
DefaultImageRetries are the waits before each extra attempt at a page image: two more attempts, after 1 s and then 3 s.
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.
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.
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.
var ErrBadConfig = errors.New("plugins: invalid configuration")
ErrBadConfig is configuration the server can't even encode.
var ErrBadImageRetries = errors.New("at most 5 waits, each from 0 to 30000 ms")
ErrBadImageRetries is a setting out of bounds.
var ErrNoHealthChecks = errors.New("plugins: the plugin doesn't run source health checks")
ErrNoHealthChecks is a plugin without the health checks capability.
var ErrNoJobs = errors.New("plugins: the plugin has no jobs")
ErrNoJobs is a plugin without the jobs capability.
var ErrNoPackages = errors.New("plugins: the plugin doesn't install packages")
ErrNoPackages is a plugin without the package capability.
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 ¶
ImageKey is the limits key of a source's image fetches, apart from its other calls ("source:<id>").
func PackageKey ¶
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 ¶
RemoteDialer speaks gRPC to plugins running as services.
Types ¶
type Host ¶
type Host struct {
// contains filtered or unexported fields
}
Host manages the plugins.
func (*Host) Applied ¶
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 ¶
CancelJobRun cancels a plugin job's running run.
func (*Host) ClearPackageImageRetries ¶
ClearPackageImageRetries removes a package's setting: its sources use the default (or their own).
func (*Host) ClearSourceImageRetries ¶
ClearSourceImageRetries removes a source's own setting: it inherits its package's or the default.
func (*Host) Config ¶
Config returns a plugin's configuration as the plugin reports it (secrets left empty).
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) Icon ¶
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 ¶
Image fetches an image through the source's plugin (its headers and network settings apply).
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) 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 ¶
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 ¶
Origins lists where a plugin's packages come from (e.g. stores), with their state.
func (*Host) PackageIcon ¶
PackageIcon fetches a package's own icon. ErrNotFound when it has none.
func (*Host) PackageImageRetries ¶
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 ¶
PendingPackageTasks maps a plugin's packages to their queued or running task.
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 ¶
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 ¶
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 ¶
RefreshOrigin fetches an origin's package list again now.
func (*Host) RegisterPackageTasks ¶
RegisterPackageTasks lets q run package tasks, one at a time.
func (*Host) ReloadPackage ¶
ReloadPackage loads an installed package again (retrying a failed load, or applying settings that need it), then syncs the plugin.
func (*Host) ResolveURL ¶
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) SetConfig ¶
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 ¶
SetConfigFollowUp changes the waits of the syncs after a settings save.
func (*Host) SetDefaultImageRetries ¶
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 ¶
SetHealthCheck turns a source's scheduled health checks on or off, then syncs its plugin so the source shows it.
func (*Host) SetHub ¶
SetHub makes the host tell admins about each plugin sync (plugin.health events).
func (*Host) SetLimits ¶
SetLimits makes the host keep each source's limits (from its plugin's declared limits) in reg.
func (*Host) SetMetrics ¶
SetMetrics makes the host count page image retries.
func (*Host) SetNetwork ¶
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 ¶
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 ¶
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 ¶
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 ¶
SetStartupGrace changes the waits for plugins not answering at startup (none: a single try).
func (*Host) SetStartupWindow ¶
SetStartupWindow changes how long after startup plugins not answering yet are waited for.
func (*Host) SourceIcon ¶
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 ¶
SourceImageRetries returns what a source uses for its page images.
func (*Host) Sources ¶
Sources lists the sources v may see; with all (admins), every source, including disabled and absent ones.
func (*Host) Sync ¶
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.
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 ¶
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 ¶
PackageQuery narrows a plugin's package list.
type Plugin ¶
type Plugin struct {
db.Plugin
Info *sourcev1.PluginInfo
SourceCount int64
}
Plugin is a registered plugin with its last known info.
type SourceSettings ¶
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.
Source Files
¶
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). |