plugin

package
v1.17.0 Latest Latest
Warning

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

Go to latest
Published: Oct 18, 2026 License: MIT Imports: 35 Imported by: 0

Documentation

Overview

Package plugin is the host side of the connector plugin platform: it spawns connector subprocesses on demand, hands out live gRPC clients, and reaps idle ones.

Index

Constants

View Source
const (
	OriginOfficial = "official"
	OriginSource   = "source"
	OriginURLZip   = "url-zip"
	OriginUpload   = "upload"
)

Plugin origins recorded in PluginState.Origin. "" means not recorded.

Variables

This section is empty.

Functions

func BuildModule

func BuildModule(mod connector.Module, getConn ConnGetter) connector.Module

BuildModule wires a parsed connector.Module's operations to gRPC closures that dispatch to the plugin subprocess. The host engine (service.Execute) calls these closures exactly like in-proc ops — same pattern as custom-MCP. The envelope parsing and verification happen in the loader before this is called.

func DataDirFor added in v1.16.0

func DataDirFor(key string) string

DataDirFor is the persistent data dir of the connector plugin key: <plugins root>/<key>, the sibling of the connectors/ dir. It is the same path wickplugin.DataDir derives inside an installed binary, so wick passes it as wickplugin.EnvDataDir and a binary run from elsewhere (a development-mode candidate) shares the installed plugin's data.

func DefaultDir

func DefaultDir() string

DefaultDir is the runtime location wick scans for installed connector plugins: <appDataDir>/plugins/connectors, overridable with WICK_PLUGINS_DIR. It matches the layout `make plugins` writes to.

func ExtractArchive

func ExtractArchive(archive, destBase string) (string, error)

ExtractArchive extracts a .tar.gz or .zip into destBase and returns the directory that holds plugin.json (the archive root or its single subdir).

func InstallFromDir

func InstallFromDir(srcDir, destRoot string) error

InstallFromDir verifies the {binary, plugin.json} in srcDir and copies them into destRoot/<key>/. The manifest's sha256 + signature are checked against the binary BEFORE anything is written, so an unverified plugin never lands in the plugins dir.

func InstallFromURL

func InstallFromURL(ctx context.Context, url, destRoot string) error

InstallFromURL downloads an archive (zip or tar.gz) from url, extracts it, verifies the manifest, and installs into destRoot. Used by the marketplace install action and `<app> plugin install <url|name>`.

func InstallFromURLProgress added in v0.28.5

func InstallFromURLProgress(ctx context.Context, url, destRoot string, onProgress ProgressFunc) error

InstallFromURLProgress is InstallFromURL with staged progress reporting. The archive lands in a temp dir first; the on-disk plugin is only touched in the Replacing phase, so a failed download/verify never disturbs the existing install (download-succeeds-then-replace).

func KindDir added in v1.2.9

func KindDir(kind string) string

KindDir is where plugins of one kind are installed: RootDir()/<kind>s (connectors, jobs, tools, services). The connector dir keeps its WICK_PLUGINS_DIR override via DefaultDir.

func ManifestFromZipBytes added in v0.27.0

func ManifestFromZipBytes(data []byte) (*wickplugin.Manifest, error)

ManifestFromZipBytes reads and parses plugin.json from a plugin release zip's raw bytes. Shared by the live fetcher and by tests (which build zips in-mem).

func MarshalCatalog added in v0.27.0

func MarshalCatalog(entries []Available) ([]byte, error)

MarshalCatalog renders the catalog as the pretty JSON written to plugins/plugins.json (2-space indent, trailing newline) for a stable diff.

func ResolveSource

func ResolveSource(ctx context.Context, src string) (string, func(), error)

ResolveSource turns a path / url / archive into a directory containing {binary, plugin.json}, returning the dir and a cleanup func. A bare existing directory is returned as-is.

func RootDir added in v1.2.9

func RootDir() string

RootDir is the plugins root holding one folder per kind: <appDataDir>/plugins, overridable with WICK_PLUGINS_ROOT.

func RunDir

func RunDir() string

RunDir is where wick pins plugin Unix sockets: <appDataDir>/run, overridable with WICK_PLUGIN_SOCKET_DIR. go-plugin creates the socket under here (0700) instead of the OS temp dir.

func Spawn added in v1.2.9

func Spawn(spec SpawnSpec) (*goplugin.Client, any, error)

Spawn starts a plugin subprocess (env scrubbed, same transport as connector plugins) and dispenses its client. The caller owns the returned client and must Kill it. Used by kinds whose lifecycle is not the connector pool, e.g. a job plugin that lives for exactly one Run.

func VersionNewer added in v0.27.2

func VersionNewer(a, b string) bool

VersionNewer reports whether catalog version a is strictly newer than the installed version b, by semver. Versions may be bare ("1.4.2") or "v"-prefixed; both are normalized. Unparseable versions fall back to a plain string != comparison so a malformed tag still surfaces *some* update hint rather than silently hiding one.

Types

type Available

type Available struct {
	Key         string `json:"key"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Version     string `json:"version"`
	// DefaultTags are the plugin's Meta.DefaultTags, carried verbatim from the
	// released manifest — the SAME []entity.DefaultTag a built-in connector
	// declares. The app derives the category from them with connectorCategory,
	// exactly as for built-ins, so a plugin groups under its real category.
	DefaultTags []entity.DefaultTag `json:"default_tags,omitempty"`
	// Assets maps "<goos>/<goarch>" → direct download URL of the release zip.
	Assets map[string]string `json:"assets"`
}

Available is one installable connector surfaced by the catalog.

Key vs Name mirrors connector.Meta: Key is the slug (= source folder = zip name = install dir = registry key — the one identity used for matching and install); Name is the free display string shown in the UI. Older catalog entries that only have "name" are tolerated: parseCatalog backfills Key from Name when Key is absent.

func BuildCatalog added in v0.27.0

func BuildCatalog(releases []GHRelease, fetchManifest ManifestFetcher) []Available

BuildCatalog folds releases into one Available entry per plugin key (the tag prefix before "/v"), keeping the highest semver version, and maps each zip asset to its os/arch download URL. When fetchManifest is non-nil it is used to lift Meta.Name / Meta.Description from the chosen release's first asset; failures there are non-fatal (the entry keeps key-derived defaults).

Tag convention: plugin releases are tagged "<key>/v<version>"; core wick releases ("v<version>", no slash) are ignored.

func (Available) AssetFor

func (a Available) AssetFor(host string) string

AssetFor returns the download URL matching host (e.g. "linux/arm64"), or "".

type Catalog

type Catalog struct {
	// contains filtered or unexported fields
}

Catalog discovers connector plugins that are AVAILABLE to install from a single curated JSON file checked into the wick repo's default branch (raw.githubusercontent.com/yogasw/wick/master/plugins/plugins.json).

This is deliberately NOT the GitHub Releases API: listing is a plain raw-file fetch, so it never hits the API rate limit and needs no token. The JSON carries, per plugin, the direct release download URL for each os/arch — the binary is pulled from the GitHub Release only when the user clicks Download.

func DefaultRegistry

func DefaultRegistry() *Catalog

DefaultRegistry builds a Catalog from env overrides:

WICK_PLUGIN_CATALOG  full URL to plugins.json (default: wick repo master, plugins/plugins.json)

Named DefaultRegistry for call-site compatibility with the earlier API.

func (*Catalog) FetchedAt added in v1.2.9

func (c *Catalog) FetchedAt() time.Time

FetchedAt is when the catalog was last fetched or revalidated; zero before the first List.

func (*Catalog) List

func (c *Catalog) List(ctx context.Context) ([]Available, error)

List returns every installable connector from the catalog JSON. Served from cache while the TTL is fresh; otherwise a conditional GET (ETag) reuses the cache on a 304.

func (*Catalog) Resolve

func (c *Catalog) Resolve(ctx context.Context, name, host string) (Available, string, error)

Resolve returns the arch-matching download URL for the named connector. host defaults to the current runtime when empty.

func (*Catalog) URL added in v1.2.9

func (c *Catalog) URL() string

URL is the plugins.json this catalog reads (shown as the official source).

type ConnGetter

type ConnGetter func(key string) (*Lease, error)

ConnGetter returns a lease on a live plugin connection for a connector key. The manager's Client method satisfies it; tests pass a fake.

type Found

type Found struct {
	Key        string
	BinaryPath string
	Manifest   wickplugin.Manifest
}

Found is one discovered plugin: its key, on-disk binary, and parsed manifest envelope.

func Scan

func Scan(dir string) ([]Found, error)

Scan walks dir/<name>/plugin.json and returns one Found per connector. Each plugin.json is a manifest envelope; the binary is resolved from the manifest's Entry (falling back to the directory name). A missing dir is not an error (returns nil) — plugins are optional.

func ScanKind added in v1.2.9

func ScanKind(dir, kind string) ([]Found, error)

ScanKind is Scan restricted to one kind: a manifest whose kind does not match the folder it sits in is rejected (logged, not returned), so a job binary dropped into plugins/connectors never loads as a connector and vice versa.

type GHAsset added in v0.27.0

type GHAsset struct {
	Name        string `json:"name"`
	DownloadURL string `json:"browser_download_url"`
}

GHAsset is one downloadable file on a release.

type GHRelease added in v0.27.0

type GHRelease struct {
	TagName string    `json:"tag_name"`
	Assets  []GHAsset `json:"assets"`
}

GHRelease is the slice of a GitHub release this needs. Decode the `GET /repos/{owner}/{repo}/releases` response into []GHRelease.

type Lease

type Lease struct {
	Conn wickplugin.GRPCConn
	// contains filtered or unexported fields
}

Lease is a borrowed plugin connection. Release MUST be called exactly once (the adapter does so via defer) so the Manager can account for in-flight calls and free the subprocess for eviction.

func (*Lease) Release

func (l *Lease) Release()

Release returns the lease to the Manager. Safe to call on a nil-release lease.

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager owns connector plugin subprocesses keyed by connector Meta.Key.

func Load

func Load(dir string, idleTimeout time.Duration, enabled func(string) bool) (*Manager, int, error)

Load scans dir, builds a Manager over the discovered binaries, registers each plugin module via connectors.Register (replace-by-key so a plugin overrides the compiled-in builtin of the same key), and returns the Manager (caller owns its KillAll on shutdown). Returns a nil Manager when no plugins are present. When enabled is non-nil, keys for which it returns false are excluded from the Manager (not spawnable) and not registered; a nil enabled treats all discovered plugins as enabled.

func NewManager

func NewManager(binaries map[string]string, idleTimeout time.Duration) *Manager

func (*Manager) Client

func (m *Manager) Client(key string) (*Lease, error)

Client returns a lease on a live gRPC connection for key, spawning the subprocess on first use (lazy) and re-spawning if a previous process died. Release the lease when the call completes.

func (*Manager) InflightCount added in v1.2.9

func (m *Manager) InflightCount() int

NewManager builds a Manager and starts the idle sweeper. InflightCount sums the in-flight calls across every plugin subprocess. KillAll ignores this on a hard stop by design; the graceful path uses it to avoid killing a plugin mid-request.

func (*Manager) IsPlugin

func (m *Manager) IsPlugin(key string) bool

IsPlugin reports whether key is served by a plugin subprocess.

func (*Manager) KillAll

func (m *Manager) KillAll()

KillAll reaps every subprocess (call on app shutdown). It is safe to call more than once: the stop channel is closed at most once.

func (*Manager) RemoveBinary

func (m *Manager) RemoveBinary(key string)

RemoveBinary drops a connector key and kills its running subprocess (if any).

func (*Manager) ResolveIdentity

func (m *Manager) ResolveIdentity(ctx context.Context, key, token string) (string, string, error)

ResolveIdentity spawns-if-needed and asks the plugin to resolve an OAuth token's owner.

func (*Manager) SetBinary

func (m *Manager) SetBinary(key, path string)

SetBinary registers or updates the on-disk binary path for a connector key. If a subprocess is already running for this key it is killed so the next Client call spawns the new binary.

func (*Manager) SetDNSServersLoader added in v1.2.9

func (m *Manager) SetDNSServersLoader(fn func() string)

SetDNSServersLoader supplies the runtime-editable Termux DNS override.

func (*Manager) WarmUp

func (m *Manager) WarmUp()

WarmUp eagerly spawns every warm connector that has a registered binary so it is hot before the first call. Failures are logged and skipped — boot must not abort. Call once at boot after Load wires the binaries.

type ManifestFetcher added in v0.27.0

type ManifestFetcher func(zipURL string) (*wickplugin.Manifest, error)

ManifestFetcher reads a plugin.json out of a release zip given its download URL, returning the parsed manifest. Returns an error the caller may ignore (Name/Description backfill is best-effort). Injected so BuildCatalog stays testable without network.

type Phase added in v0.28.5

type Phase string

Phase names an install step, streamed to the caller so the UI can show a staged progress indicator instead of one opaque spinner.

const (
	PhaseDownloading Phase = "downloading"
	PhaseVerifying   Phase = "verifying"
	PhaseReplacing   Phase = "replacing"
	PhaseDone        Phase = "done"
)

type Progress added in v0.28.5

type Progress struct {
	Phase Phase `json:"phase"`
	Pct   int   `json:"pct"`
}

Progress is one install-progress update. Pct is the download percentage (0–100) and is only meaningful while Phase==PhaseDownloading and the server sent a Content-Length; it is -1 when the total size is unknown.

type ProgressFunc added in v0.28.5

type ProgressFunc func(Progress)

ProgressFunc receives install-progress updates. nil is allowed (no-op).

type Reloader

type Reloader struct {
	// contains filtered or unexported fields
}

Reloader watches the plugins dir and reconciles installed plugins into the running service without a restart. It polls on a fixed interval (no fsnotify dependency).

func NewReloader

func NewReloader(dir string, svc moduleSink, mgr *Manager, interval time.Duration, store enabledChecker) *Reloader

NewReloader builds a Reloader. interval <= 0 defaults to 5s.

func (*Reloader) Reload

func (r *Reloader) Reload(ctx context.Context)

Reload triggers an immediate reconcile (for in-process callers, e.g. CLI install).

func (*Reloader) Start

func (r *Reloader) Start(ctx context.Context)

Start runs the poll loop until Stop is called or ctx is cancelled. Call once.

func (*Reloader) Stop

func (r *Reloader) Stop()

Stop ends the poll loop. Idempotent: shutdown paths overlap (a graceful drain stops the reloader, then the process-exit handler runs too), and a second close of the channel used to panic and take the daemon down with it.

type SpawnSpec added in v1.2.9

type SpawnSpec struct {
	Binary    string
	Plugins   map[int]goplugin.PluginSet // the kind's versioned plugin set
	Dispense  string                     // plugin name to dispense (wickplugin.PluginName, wickplugin.JobPluginName, ...)
	SocketDir string                     // "" = RunDir()
	Env       []string                   // extra env on top of the scrubbed OS env
	Stderr    io.Writer                  // nil = go-plugin's default (logged)
	// Release runs once the process is gone (or failed to start): it
	// revokes the process's Host API token. nil = nothing to release.
	Release func()
}

SpawnSpec describes one plugin subprocess of any kind.

type StateStore

type StateStore struct {
	// contains filtered or unexported fields
}

StateStore reads and writes the plugin enable/disable overlay.

func NewStateStore

func NewStateStore(db *gorm.DB) *StateStore

NewStateStore wraps db. A nil db yields a store whose Enabled defaults to true.

func (*StateStore) All added in v1.2.9

func (s *StateStore) All() ([]entity.PluginState, error)

All returns every overlay row (origin, source, health, versions).

func (*StateStore) ClearInstalled added in v1.2.9

func (s *StateStore) ClearInstalled(key string) error

ClearInstalled forgets the installed and available versions of key after an uninstall, so Check updates stops reporting it. The row itself stays (enable flag, origin, source link) and a reinstall records a version again.

func (*StateStore) Enabled

func (s *StateStore) Enabled(key string) bool

Enabled reports whether key may be registered/spawned. Missing row or any error -> true (default-on; never hide a plugin because of a read error).

func (*StateStore) EnabledErr added in v1.16.0

func (s *StateStore) EnabledErr(key string) (bool, error)

EnabledErr is Enabled for a caller that polls: a missing row is still default-on, but a read error is returned instead of turning into true, so a poller can keep its last known state rather than re-enable a plugin an admin disabled because the database blinked.

func (*StateStore) Get added in v1.2.9

func (s *StateStore) Get(key string) (entity.PluginState, bool)

Get returns the overlay row for key; ok=false when there is none.

func (*StateStore) List

func (s *StateStore) List() (map[string]bool, error)

List returns key -> enabled for all overlay rows.

func (*StateStore) Record added in v1.2.9

func (s *StateStore) Record(key, kind, version string) error

Record upserts the kind + installed version for key without touching the enable flag (a new row starts enabled).

func (*StateStore) SetEnabled

func (s *StateStore) SetEnabled(key string, enabled bool) error

SetEnabled upserts the overlay row for key. A map is used so gorm writes the literal enabled value; a struct would let the `default:true` tag override a zero-value false on insert.

func (*StateStore) SetOrigin added in v1.2.9

func (s *StateStore) SetOrigin(key, origin string) error

SetOrigin records how key was installed. Call after Record so the row exists.

Jump to

Keyboard shortcuts

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