source

package
v1.18.1 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 26 Imported by: 0

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

View Source
const (
	TypeURL    = "url"
	TypeGitHub = "github"
)

Source types.

View Source
const DefaultPollMinutes = 30

DefaultPollMinutes is how often a source is re-checked when unset.

Variables

View Source
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 HostOSArch

func HostOSArch() string

HostOSArch is this server's "<goos>/<goarch>".

func IsZipURL

func IsZipURL(u string) bool

IsZipURL reports whether u points straight at a .zip (a one-off link source) rather than a plugins.json index.

func RequireHTTPS

func RequireHTTPS(u *url.URL) error

RequireHTTPS rejects plain http except for loopback hosts.

func ValidateIndex

func ValidateIndex(entries []Entry) error

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

func (a *Asset) UnmarshalJSON(b []byte) error

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 NewClient

func NewClient(decrypt func(string) (string, error)) *Client

NewClient returns a Client with sane timeouts and the public GitHub API.

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).

func ParseIndex

func ParseIndex(raw []byte, base string) ([]Entry, error)

ParseIndex parses plugins.json and resolves relative asset URLs against base (the URL plugins.json was fetched from). Entries without a key are dropped; v1 entries that only carry "name" get it as their key.

type FetchResult

type FetchResult struct {
	Entries     []Entry
	Raw         []byte
	ETag        string
	NotModified bool
}

FetchResult is one index fetch. NotModified means the ETag matched and Entries is nil — the caller keeps its cached index.

type HealthFunc

type HealthFunc func(key string) (installed, ok bool, detail string)

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

type Installed struct {
	Key       string
	Kind      string
	Version   string
	ZipSHA256 string
}

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

func InstallPath(ctx context.Context, src string, opts InstallOptions) (Installed, error)

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

func (m *Manager) Check(ctx context.Context, id string) (CheckResult, error)

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) Delete

func (m *Manager) Delete(id, actor string) error

Delete removes a source. Installed plugins stay; they just lose updates.

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

func (m *Manager) Record(actor, action, key, detail string)

Record writes one audit row for an admin change made outside a source (e.g. a service plugin's auto-off setting).

func (*Manager) Run

func (m *Manager) Run(ctx context.Context, tick time.Duration)

Run polls due sources every tick until ctx ends.

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.

func (*Manager) Upload

func (m *Manager) Upload(ctx context.Context, zipPath, actor string) (Installed, error)

Upload installs an uploaded zip (admin). No source, so no updates.

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

Jump to

Keyboard shortcuts

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