Documentation
¶
Overview ¶
Package installer installs, updates and removes WebAssembly plugins from the plugin directory at runtime, for the admin UI. Yaegi (.go) plugins that were installed before the directory went wasm-only can still be updated (to a wasm release) and uninstalled.
Index ¶
- Constants
- Variables
- func Compatible(running, min string) bool
- func Newer(candidate, current string) bool
- type Available
- type Fetcher
- func (f *Fetcher) Detail(name string) (*directory.Detail, error)
- func (f *Fetcher) Ensure(indexURL string)
- func (f *Fetcher) Entry(name string) (directory.Entry, bool)
- func (f *Fetcher) FetchedAt() time.Time
- func (f *Fetcher) Index() (raw []byte, entries []directory.Entry, ok bool)
- func (f *Fetcher) Refresh(indexURL string) error
- func (f *Fetcher) SetUserAgent(ua string)
- type Installed
- type Installer
- func (i *Installer) AutoUpdate(ctx context.Context) []Result
- func (i *Installer) Install(ctx context.Context, name string) (Result, error)
- func (i *Installer) Refresh() error
- func (i *Installer) Status() Status
- func (i *Installer) Uninstall(name string) error
- func (i *Installer) Update(ctx context.Context, name string) (Result, error)
- type Result
- type Status
Constants ¶
const DefaultIndexURL = "https://www.goblog.live/plugins/index.json"
DefaultIndexURL is the public plugin directory index.
Variables ¶
var ( ErrWasmDisabled = errors.New("WebAssembly plugins are disabled (ENABLE_WASM_PLUGINS=false); remove that setting and make plugins/wasm/ writable to install plugins") ErrIncompatible = errors.New("this plugin requires a newer goblog") ErrChecksum = errors.New("the downloaded file does not match the checksum in the directory index; the index may be stale, refresh and try again") ErrNotDynamic = errors.New("this plugin type cannot be installed from the directory") ErrAlreadyInstalled = errors.New("a plugin with this name is already installed") ErrNotInstalled = errors.New("this plugin is not installed as a dynamic plugin") ErrNotFound = errors.New("this plugin is not in the directory") ErrLoad = errors.New("the plugin failed to load") ErrUpToDate = errors.New("plugin is already at the directory's version") ErrDownload = errors.New("could not download the plugin") ErrWrite = errors.New("could not write to the plugins/wasm directory; check that it exists and goblog can write to it") )
Typed errors; the admin API maps them to 4xx responses with their text.
Functions ¶
func Compatible ¶
Compatible reports whether a goblog at version running satisfies a plugin's (or theme's) min_goblog_version. Dev builds ("development", "latest", or anything unparseable) and an unparseable minimum are treated as compatible.
Types ¶
type Available ¶
type Available struct {
directory.Entry
Compatible bool `json:"compatible"`
Reason string `json:"reason,omitempty"` // why Install is disabled
}
Available is a directory entry that is not installed.
type Fetcher ¶
type Fetcher struct {
// contains filtered or unexported fields
}
Fetcher keeps an in-memory copy of a remote directory's index (goblog.live's by default) and of the detail JSON for plugins that have been viewed. Every fetch that fails keeps the previous copy, so the directory degrades to "slightly stale" rather than "empty" when the registry is unreachable.
func NewFetcher ¶
NewFetcher returns a Fetcher using client (nil means a 10s-timeout default).
func (*Fetcher) Detail ¶
Detail returns the detail JSON for a plugin, fetching and caching it on first use. It fails when the plugin is not in the index or the fetch fails and no cached copy exists.
func (*Fetcher) Ensure ¶
Ensure fetches the index if nothing is cached yet, throttled to at most one attempt per ensureRetryInterval so a registry outage does not turn every request into a blocking synchronous fetch. Fetch errors are logged here; the cache is simply left empty (or stale, if there is an older copy).
func (*Fetcher) FetchedAt ¶
FetchedAt is when the index was last fetched successfully (zero if never).
func (*Fetcher) Index ¶
Index returns the cached index bytes and entries; ok is false when nothing has been fetched successfully yet.
func (*Fetcher) Refresh ¶
Refresh downloads and parses indexURL, replacing the cached index on success and re-fetching the details of every plugin already cached. On any error the previous index and details are kept and the error returned.
func (*Fetcher) SetUserAgent ¶
SetUserAgent sets the User-Agent sent to the registry.
type Installed ¶
type Installed struct {
Name string `json:"name"`
DisplayName string `json:"display_name"`
Version string `json:"version"`
Enabled bool `json:"enabled"`
Dynamic bool `json:"dynamic"`
Runtime string `json:"runtime"` // "wasm", "go" or "builtin"
UpdateAvailable bool `json:"update_available"`
LatestVersion string `json:"latest_version,omitempty"`
Path string `json:"path,omitempty"`
Health string `json:"health,omitempty"` // "ok", "busy" or "closed" for plugins that report it (wasm)
}
Installed is a registered plugin as shown on the Installed tab.
type Installer ¶
type Installer struct {
Dir string // plugins/dynamic: previously installed Yaegi plugins (update/uninstall only)
WasmDir string // plugins/wasm: where directory installs go
Registry *plugin.Registry
Directory *Fetcher // own instance; not the directory plugin's
Version string // running goblog version, e.g. "v0.2.7" or "development"
Client *http.Client // downloads; nil → 30s timeout default
Enabled bool // ENABLE_DYNAMIC_PLUGINS (Yaegi); reported in Status only
WasmEnabled bool // ENABLE_WASM_PLUGINS != "false"; gates Install/Update/Uninstall
IndexURL func() string // current plugin_directory_url setting
// contains filtered or unexported fields
}
Installer wires the directory index, the plugin registry and the plugins/wasm directory together.
func (*Installer) AutoUpdate ¶
AutoUpdate updates every installed dynamic plugin that Status says has a compatible update. A failure is logged and leaves that plugin as it was (Update rolls back); it never stops the others.
func (*Installer) Install ¶
Install downloads, verifies, writes, loads and registers a directory plugin.
func (*Installer) Status ¶
Status lists installed plugins (with update info for dynamic ones) and the directory entries that are not installed, sorted by stars then name.
func (*Installer) Uninstall ¶
Uninstall unregisters a dynamic plugin, releases its instance and deletes its files, settings, stored data and the pages it declared.
func (*Installer) Update ¶
Update replaces an installed dynamic plugin with the index version. If the new module fails to load, the previous files and plugin are restored. A Yaegi plugin (Runtime "go") is replaced by the wasm module: its .go file stays until the new plugin is registered and is removed afterwards.
type Result ¶
type Result struct {
Name string `json:"name"`
Version string `json:"version"`
Message string `json:"message"`
}
Result reports a successful install or update.
type Status ¶
type Status struct {
Installed []Installed `json:"installed"`
Available []Available `json:"available"`
DirectoryURL string `json:"directory_url"`
DynamicEnabled bool `json:"dynamic_enabled"`
WasmEnabled bool `json:"wasm_enabled"`
IndexFetchedAt string `json:"index_fetched_at,omitempty"`
IndexError string `json:"index_error,omitempty"`
DirWritable bool `json:"dir_writable"` // WasmDir (Dir when WasmDir is unset)
DirError string `json:"dir_error,omitempty"`
DirectoryHosted bool `json:"directory_hosted"` // this site hosts a directory (set by admin, not the installer)
}
Status is everything the admin page needs in one call.