source

package
v1.15.3 Latest Latest
Warning

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

Go to latest
Published: Oct 8, 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

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