Documentation
¶
Overview ¶
Package source installs and updates plugins from remote sources: a plugins.json URL, a direct .zip link, or GitHub releases (public or private with a PAT). Every zip goes through the same verification as a local install — zip_sha256 from the index, then the binary sha256 + signature from the manifest inside the zip — before it lands in its kind folder.
Index ¶
- Constants
- Variables
- func Due(s entity.PluginSource, now time.Time) bool
- func HostOSArch() string
- func IsZipURL(u string) bool
- func RequireHTTPS(u *url.URL) error
- func ValidateIndex(entries []Entry) error
- type Asset
- type CheckResult
- type Client
- func (c *Client) Fetch(ctx context.Context, src *entity.PluginSource, etag string) (FetchResult, error)
- func (c *Client) InstallEntry(ctx context.Context, src *entity.PluginSource, e Entry, opts InstallOptions) (Installed, error)
- func (c *Client) Test(ctx context.Context, src *entity.PluginSource, health HealthFunc) []Step
- type Entry
- type FetchResult
- type HealthFunc
- type InstallOptions
- type Installed
- type Manager
- func (m *Manager) Add(ctx context.Context, in SourceInput, actor string, health HealthFunc) (*entity.PluginSource, []Step, error)
- func (m *Manager) Audit(limit int) ([]entity.PluginAudit, error)
- func (m *Manager) Check(ctx context.Context, id string) (CheckResult, error)
- func (m *Manager) Delete(id, actor string) error
- func (m *Manager) Get(id string) (*entity.PluginSource, error)
- func (m *Manager) InstallFromIndex(ctx context.Context, indexURL, key, wantKind, actor string) (Installed, error)
- func (m *Manager) InstallFromSource(ctx context.Context, id, key, actor string, pf connplugin.ProgressFunc) (Installed, error)
- func (m *Manager) List() ([]entity.PluginSource, error)
- func (m *Manager) Record(actor, action, key, detail string)
- func (m *Manager) Run(ctx context.Context, tick time.Duration)
- func (m *Manager) Save(id string, in SourceInput, actor string) (*entity.PluginSource, error)
- func (m *Manager) TestInput(ctx context.Context, id string, in SourceInput, health HealthFunc) ([]Step, error)
- func (m *Manager) Update(ctx context.Context, key, actor string, pf connplugin.ProgressFunc) (Installed, error)
- func (m *Manager) Upload(ctx context.Context, zipPath, actor string) (Installed, error)
- type SourceInput
- type StatusError
- type Step
- type ValidationError
Constants ¶
const ( TypeURL = "url" TypeGitHub = "github" )
Source types.
const DefaultPollMinutes = 30
DefaultPollMinutes is how often a source is re-checked when unset.
Variables ¶
var ErrNotInIndex = errors.New("plugin not offered by the catalog")
ErrNotInIndex means the plugins.json InstallFromIndex read does not offer the key (or not as the wanted kind).
Functions ¶
func Due ¶
func Due(s entity.PluginSource, now time.Time) bool
Due reports whether s should be polled now.
func IsZipURL ¶
IsZipURL reports whether u points straight at a .zip (a one-off link source) rather than a plugins.json index.
func RequireHTTPS ¶
RequireHTTPS rejects plain http except for loopback hosts.
func ValidateIndex ¶
ValidateIndex reports the first schema problem: invalid or duplicate key, non-semver version, unknown kind.
Types ¶
type Asset ¶
type Asset struct {
URL string `json:"url"`
ZipSHA256 string `json:"zip_sha256,omitempty"`
Signature string `json:"signature,omitempty"`
// APIURL is the GitHub asset API endpoint, set for private repos where
// browser_download_url does not work. Serialized so it survives the
// IndexJSON cache round-trip between Check and InstallFromSource.
APIURL string `json:"api_url,omitempty"`
}
Asset is one os/arch build of a plugin in plugins.json v2. The v1 index carried a bare download URL string; UnmarshalJSON accepts both.
func (*Asset) UnmarshalJSON ¶
type CheckResult ¶
type CheckResult struct {
Entries []Entry `json:"entries"`
Updates []string `json:"updates"`
NotModified bool `json:"not_modified"`
AutoUpdated []string `json:"auto_updated,omitempty"`
}
CheckResult is one source check: the plugins it offers and which installed ones now have a newer version.
type Client ¶
type Client struct {
HTTP *http.Client
GitHubAPI string
// Decrypt turns the stored PAT token back into plaintext for one call.
Decrypt func(string) (string, error)
}
Client fetches indexes and zips. GitHubAPI is overridable so tests run against httptest instead of the real GitHub.
func (*Client) Fetch ¶
func (c *Client) Fetch(ctx context.Context, src *entity.PluginSource, etag string) (FetchResult, error)
Fetch resolves the source's current plugin list. etag is the cached ETag ("" forces a full fetch).
func (*Client) InstallEntry ¶
func (c *Client) InstallEntry(ctx context.Context, src *entity.PluginSource, e Entry, opts InstallOptions) (Installed, error)
InstallEntry downloads the host build of e and installs it after the full check chain: zip_sha256 → signature (when pinned or required) → extract → manifest kind/arch/proto/binary sha256 → atomic copy into the kind folder.
func (*Client) Test ¶
func (c *Client) Test(ctx context.Context, src *entity.PluginSource, health HealthFunc) []Step
Test runs the six-step health check in order. A failed step skips the steps that depend on it, so the admin sees exactly where it broke.
type Entry ¶
type Entry struct {
Key string `json:"key"`
Kind string `json:"kind,omitempty"`
Name string `json:"name,omitempty"`
Description string `json:"description,omitempty"`
Version string `json:"version"`
ProtoVersion int `json:"proto_version,omitempty"`
Assets map[string]Asset `json:"assets"`
DefaultTags []entity.DefaultTag `json:"default_tags,omitempty"`
}
Entry is one plugin in plugins.json (always an array, even for one plugin).
func Entries ¶
func Entries(s *entity.PluginSource) []Entry
Entries returns the source's cached index (no network).
type FetchResult ¶
FetchResult is one index fetch. NotModified means the ETag matched and Entries is nil — the caller keeps its cached index.
type HealthFunc ¶
HealthFunc reports the runtime health of an installed plugin key; ok=false with installed=false means it is not installed.
type InstallOptions ¶
type InstallOptions struct {
DryRun bool
Root func(kind string) string
Progress connplugin.ProgressFunc
}
InstallOptions tunes one install. Root maps a kind to its install folder (connplugin.KindDir by default; tests point it at a temp dir).
type Installed ¶
Installed describes a verified (and, unless dry-run, installed) plugin.
func InstallDir ¶
func InstallDir(dir string, opts InstallOptions) (Installed, error)
InstallDir installs an already-extracted {binary, plugin.json} directory (the CLI's path/archive/URL/registry sources) through the same manifest checks and kind routing as an upload.
func InstallPath ¶
InstallPath installs from a local directory, a local .zip / .tar.gz, or a direct http(s) archive URL — the `plugin install` CLI sources — routing the plugin into its kind folder like an upload.
func InstallZip ¶
func InstallZip(path string, opts InstallOptions) (Installed, error)
InstallZip installs an uploaded zip (no index, so no zip_sha256 to match); the manifest checks still apply.
type Manager ¶
type Manager struct {
DB *gorm.DB
Client *Client
Encrypt func(string) (string, error)
Install InstallOptions
// OnInstalled runs after a plugin landed on disk (reconcile the reloader,
// restart a service plugin). nil is fine.
OnInstalled func(ctx context.Context, kind, key string)
// contains filtered or unexported fields
}
Manager owns plugin sources: CRUD, checks (with ETag), installs and updates from a source, uploads, polling and the audit trail.
func (*Manager) Add ¶
func (m *Manager) Add(ctx context.Context, in SourceInput, actor string, health HealthFunc) (*entity.PluginSource, []Step, error)
Add runs the same check as TestInput and saves only when it passes, so a failed Add never leaves a half-made source row behind. "After install" is not a gate: it reports on plugins already installed, not on the source.
func (*Manager) Audit ¶
func (m *Manager) Audit(limit int) ([]entity.PluginAudit, error)
Audit returns the newest audit rows.
func (*Manager) Check ¶
Check fetches the source (ETag-aware), caches the index, and flags AvailableVersion on installed plugins it provides. With AutoUpdate on, the newer versions are installed right away.
func (*Manager) Get ¶
func (m *Manager) Get(id string) (*entity.PluginSource, error)
Get loads one source.
func (*Manager) InstallFromIndex ¶ added in v1.18.1
func (m *Manager) InstallFromIndex(ctx context.Context, indexURL, key, wantKind, actor string) (Installed, error)
InstallFromIndex installs key straight from the plugins.json at indexURL (the official catalog) without a saved source, through the same checks as InstallFromSource: zip_sha256 and its signature when the index has them, then the manifest kind, arch, binary sha256 and signature. wantKind, when set, must match the plugin's kind. The install is recorded with the official origin and OnInstalled runs.
func (*Manager) InstallFromSource ¶
func (m *Manager) InstallFromSource(ctx context.Context, id, key, actor string, pf connplugin.ProgressFunc) (Installed, error)
InstallFromSource installs (or updates) key from source id, records its state and audit row, then runs OnInstalled.
func (*Manager) List ¶
func (m *Manager) List() ([]entity.PluginSource, error)
List returns every source, newest first.
func (*Manager) Record ¶
Record writes one audit row for an admin change made outside a source (e.g. a service plugin's auto-off setting).
func (*Manager) Save ¶
func (m *Manager) Save(id string, in SourceInput, actor string) (*entity.PluginSource, error)
Save creates (id=="") or updates a source.
func (*Manager) TestInput ¶
func (m *Manager) TestInput(ctx context.Context, id string, in SourceInput, health HealthFunc) ([]Step, error)
TestInput runs the source health check on in without storing anything, so the Add form can be checked before it is saved. id is the source being edited ("" for a new one) so a stored PAT is still used when left empty.
func (*Manager) Update ¶
func (m *Manager) Update(ctx context.Context, key, actor string, pf connplugin.ProgressFunc) (Installed, error)
Update reinstalls key from the source it came from.
type SourceInput ¶
type SourceInput struct {
Name string `json:"name"`
Type string `json:"type"`
URL string `json:"url"`
Repo string `json:"repo"` // owner/repo
Private bool `json:"private"`
PAT string `json:"pat"`
ClearPAT bool `json:"clear_pat"`
PubKey string `json:"pub_key"`
KeyFilter string `json:"key_filter"`
AllowPrerelease bool `json:"allow_prerelease"`
AutoUpdate bool `json:"auto_update"`
PollMinutes int `json:"poll_minutes"`
Enabled *bool `json:"enabled"`
}
SourceInput is the editable part of a source. PAT is plaintext on the way in ("" on edit keeps the stored one) and encrypted before it is stored.
type StatusError ¶
type StatusError struct {
Code int
URL string
Body string
// RateLimited is a 429, or a 403 with X-RateLimit-Remaining: 0 (GitHub).
RateLimited bool
}
StatusError is a non-200 answer from a source.
func (*StatusError) Error ¶
func (e *StatusError) Error() string
type Step ¶
type Step struct {
N int `json:"n"`
Name string `json:"name"`
Status string `json:"status"` // ok | fail | skip
Message string `json:"message"`
}
Step is one row of the source health check.
type ValidationError ¶
type ValidationError struct{ Steps []Step }
ValidationError is an Add rejected by the health check; Steps say where.
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string