Documentation
¶
Overview ¶
Package plugin hosts third-party plugins in MyGo apps.
A plugin is a folder with a plugin.json and a JavaScript or TypeScript module. The host reads it, compiles it once, and runs it in a moejs runtime of its own, so a plugin never shares a runtime, a heap or an event loop with another. The app calls exports by name and gets JSON values back; the plugin reaches the app only through the host global, whose permissions the manifest declares.
The manifest is the one MyGo Music uses, so its plugins load here unchanged.
Index ¶
- Constants
- Variables
- func CompareVersions(a, b string) (int, error)
- func Pack(dir string, w io.Writer) error
- func Uninstall(pluginsDir, id string) error
- type Host
- type Manifest
- type Navigation
- type NeedsNewerApp
- type Options
- type Permissions
- type Plugin
- func (p *Plugin) Call(method string, args, out any) error
- func (p *Plugin) CallWithin(timeout time.Duration, method string, args, out any) error
- func (p *Plugin) Can(method string) bool
- func (p *Plugin) Close()
- func (p *Plugin) DataDir() string
- func (p *Plugin) Dir() string
- func (p *Plugin) Exports() []string
- func (p *Plugin) ID() string
- func (p *Plugin) Manifest() Manifest
- type Programs
- type Setting
- type SignInPrompt
Constants ¶
const ( // MaxArchive is the largest accepted zip. MaxArchive = 1 << 30 // MaxUnpacked is the largest a zip may unpack to. MaxUnpacked = 2 << 30 // MaxFiles is the most files a zip may hold. MaxFiles = 50000 )
const ( // DefaultMemoryLimit is what one plugin may keep, in bytes. DefaultMemoryLimit = 256 << 20 // DefaultCallTimeout is how long one call may take. DefaultCallTimeout = 30 * time.Second )
const DefaultMain = "index.js"
DefaultMain is the module a manifest names when it doesn't.
Variables ¶
var ( // ErrSignIn says the listener has to sign in for this. ErrSignIn = errors.New("sign in first") // ErrSetup says a setting the plugin needs is missing. ErrSetup = errors.New("the plugin needs setting up") ErrUnavailable = errors.New("not available") // ErrUnsupported says the plugin doesn't do this. ErrUnsupported = errors.New("not supported by this plugin") )
var ErrInstalled = errors.New("a plugin with this id is already installed")
ErrInstalled says a plugin with that id is already installed.
Functions ¶
func CompareVersions ¶
CompareVersions compares two versions as 0.1.8: -1 when a is older, 0 when they are the same, and 1 when a is newer.
Types ¶
type Host ¶
type Host struct {
// Language is the listener's language, as a BCP 47 tag: zh-CN, en.
Language func() string
// OpenURL opens a web page in the listener's browser.
OpenURL func(url string) error
// SignInPrompt shows what a plugin wants shown as it signs in.
SignInPrompt func(pluginID string, prompt SignInPrompt)
// Setting is the value the listener gave a setting of the plugin.
Setting func(pluginID, key string) string
// Logf receives what a plugin logs. Nil logs to the standard logger.
Logf func(format string, args ...any)
}
Host is what a plugin reaches of the app. The zero value reaches nothing and logs to the standard logger.
type Manifest ¶
type Manifest struct {
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
Version string `json:"version,omitempty"`
Author string `json:"author,omitempty"`
Homepage string `json:"homepage,omitempty"`
// Main is the module to run, relative to the plugin's folder.
Main string `json:"main,omitempty"`
// MinAppVersion is the oldest host version that can run the plugin.
MinAppVersion string `json:"minAppVersion,omitempty"`
// Playback tells the host how the plugin plays: "stream" when it answers
// a URL the host fetches and plays itself, as MyGo Music's sources do.
Playback string `json:"playback,omitempty"`
Permissions Permissions `json:"permissions"`
Settings []Setting `json:"settings,omitempty"`
}
Manifest is a plugin's plugin.json.
func Inspect ¶
Inspect reads and compiles a plugin without running it: what plugin.json says, and the exports the host can call.
func InstallDir ¶
InstallDir copies the plugin in src into pluginsDir, under its id. It doesn't replace a plugin that's already there.
func InstallZip ¶
InstallZip unpacks the zip into pluginsDir, under its id. plugin.json is at the zip's root, or in its one folder, as GitHub's archives have it. It doesn't replace a plugin that's already there.
func List ¶
List reads the manifests of the plugins in pluginsDir, leaving out the ones that don't read: one broken plugin shouldn't hide the others.
func ReadManifest ¶
ReadManifest reads the plugin.json in dir, fills in what it leaves out, and checks it.
type Navigation ¶
type Navigation struct {
Page string `json:"page,omitempty"`
Builtin string `json:"builtin,omitempty"`
Icon string `json:"icon,omitempty"`
}
Navigation is an entry in the host's sidebar.
type NeedsNewerApp ¶
type NeedsNewerApp struct {
Plugin string // its name
Version string // the oldest host version it works with
}
NeedsNewerApp is why a plugin doesn't load: it needs a newer host.
func (*NeedsNewerApp) Error ¶
func (e *NeedsNewerApp) Error() string
type Options ¶
type Options struct {
// AppVersion is the host's version, which minAppVersion is checked
// against. Empty loads any plugin, as in development.
AppVersion string
// DataDir is where the host keeps the plugins' data, one folder per
// plugin. It is required, and should belong to the app, so that two
// apps with the same plugin don't share its storage.
DataDir string
// Host is what the app offers the plugin.
Host Host
// MemoryLimit is what one runtime may keep. Zero means 256 MiB.
MemoryLimit int64
// CallTimeout is how long one call may take. Zero means 30 seconds.
CallTimeout time.Duration
// HTTPClient sends fetch's requests. Nil means an http.Client with a
// ten minute timeout.
HTTPClient *http.Client
}
Options say where a plugin keeps its data and what it may reach.
type Permissions ¶
type Permissions struct {
// Network lists the hosts fetch may reach: example.com, *.example.com
// for its subdomains, or * for any. Empty reaches nothing.
Network []string `json:"network,omitempty"`
// Process lists the programs the plugin may start, once the listener
// grants it. This version declares them but doesn't start any: a host
// that does reads them from here.
Process Programs `json:"process,omitempty"`
}
Permissions are what a plugin asks for beyond its own folder and data.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is one plugin, compiled and ready to run. It starts on the first call, in a runtime of its own, and starts over after it gets stuck.
func Discover ¶
Discover loads every plugin folder in dir. One that doesn't load is logged and left out, so it can't take the others with it.
func (*Plugin) Call ¶
Call calls an export with args and decodes its answer into out, unless out is nil. An export the module doesn't have is ErrUnsupported.
func (*Plugin) CallWithin ¶
CallWithin is Call with a timeout of its own.
func (*Plugin) Close ¶
func (p *Plugin) Close()
Close stops the plugin. It starts again on the next call.
type Programs ¶
type Programs []string
Programs is a permission's list of programs: names on PATH, paths from the plugin's folder, patterns as filepath.Match has them, or true for any.
func (*Programs) UnmarshalJSON ¶
UnmarshalJSON accepts a list of programs, or true for any.
type Setting ¶
type Setting struct {
Key string `json:"key"`
Label string `json:"label"`
Help string `json:"help,omitempty"`
Link string `json:"link,omitempty"`
}
Setting is a value the listener fills in, which the plugin reads with host.setting.
type SignInPrompt ¶
SignInPrompt is what a plugin wants shown while the listener signs in.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
mygo-plugin
command
Command mygo-plugin checks, packs and starts plugins for MyGo apps.
|
Command mygo-plugin checks, packs and starts plugins for MyGo apps. |