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
- 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) 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 ¶
This section is empty.
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) 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