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
- func ValidRepo(s string) bool
- type GitHub
- func (g *GitHub) Inspect(ctx context.Context, repo string) (*Manifest, []string, error)
- func (g *GitHub) Install(ctx context.Context, repo, pluginsDir string) (*Manifest, error)
- func (g *GitHub) InstallVersion(ctx context.Context, repo, version, wantSHA, pluginsDir string) (*Manifest, error)
- func (g *GitHub) Manifest(ctx context.Context, repo string) (*Manifest, error)
- func (g *GitHub) Repos(ctx context.Context, topic string) ([]string, error)
- type Health
- type Host
- type Item
- type Manifest
- func Inspect(dir, appVersion string) (*Manifest, []string, error)
- func InstallDir(src, pluginsDir string) (*Manifest, error)
- func InstallZip(path, pluginsDir string) (*Manifest, error)
- func List(pluginsDir string) ([]*Manifest, error)
- func ParseManifest(b []byte) (*Manifest, error)
- func ReadManifest(dir string) (*Manifest, error)
- type Navigation
- type NeedsNewerApp
- type Options
- type Page
- type Permissions
- type Plugin
- func (p *Plugin) Browse(page string) (*Page, error)
- 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 Registry
- type RegistryEntry
- type Section
- 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.
const HostTypeScript = `` /* 1347-byte string literal not displayed */
HostTypeScript declares the host global that a plugin's TypeScript sees. spec/host.d.ts holds the same bytes for editors; sdk_test.go keeps the two from drifting.
const HostTypeScriptVersion = 1
HostTypeScriptVersion is the version of the host global that HostTypeScript describes. The host bumps it when the global changes.
const RegistrySchema = 1
RegistrySchema is the version of the registry file this code writes.
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 GitHub ¶ added in v0.2.0
type GitHub struct {
Client *http.Client
Token string
// API, Raw and Web override the three hosts, for tests.
API string
Raw string
Web string
}
GitHub reaches GitHub's API, raw files and archives. The zero value uses github.com; a Token raises the rate limit, and reads private repositories when the token may.
func (*GitHub) Inspect ¶ added in v0.3.0
Inspect reads a repository's plugin.json and its main module from the default branch, and compiles the module without running it: what the manifest says and the exports the host can call.
func (*GitHub) Install ¶ added in v0.2.0
Install downloads the latest release of repo, or its source at the default branch, and installs it into pluginsDir.
func (*GitHub) InstallVersion ¶ added in v0.3.0
func (g *GitHub) InstallVersion(ctx context.Context, repo, version, wantSHA, pluginsDir string) (*Manifest, error)
InstallVersion installs the release of repo at version, or the latest when version is empty. Only the latest falls back to the source at the default branch: a version that has no release is an error. A wantSHA, hex with or without a "sha256:" prefix, must match the zip before it is installed.
type Health ¶ added in v0.3.0
type Health struct {
Status string `json:"status"` // "ok" or "error"
Error string `json:"error,omitempty"`
Exports []string `json:"exports,omitempty"`
CheckedAt time.Time `json:"checkedAt"`
}
Health says whether a repository's module compiles, and what it exports when it does.
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 Item ¶ added in v0.3.0
type Item struct {
// ID identifies the item within its page, and is what the host passes
// back when the listener acts on it.
ID string `json:"id"`
Title string `json:"title"`
Subtitle string `json:"subtitle,omitempty"`
ImageURL string `json:"imageURL,omitempty"`
// Kind names the kind of item for this host, such as track, playlist or
// show. A host that doesn't know it draws a plain row.
Kind string `json:"kind,omitempty"`
// Meta is JSON the host may interpret; the plugin host doesn't.
Meta map[string]any `json:"meta,omitempty"`
}
Item is one row in a Section. Kind and Meta are hints the host defines; this layer only carries them.
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 ParseManifest ¶ added in v0.2.0
ParseManifest reads a plugin.json, fills in what it leaves out, and checks it.
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 Page ¶ added in v0.3.0
type Page struct {
Title string `json:"title"`
Subtitle string `json:"subtitle,omitempty"`
Sections []Section `json:"sections"`
}
Page is one page a plugin contributes, as data for the host to draw. It is not a view: the host owns layout, chrome, icons and actions.
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) Browse ¶ added in v0.3.0
Browse asks a plugin for the page named by a navigation entry's page, and decodes it as a Page. A plugin that doesn't export browse is ErrUnsupported.
A plugin may instead answer MyGo Music's richer shape, whose sections hold tracks, playlists and shows. That shape is out of scope here: the host adapts it, and this method does not read its fields.
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 Registry ¶ added in v0.2.0
type Registry struct {
Schema int `json:"schema"`
GeneratedAt time.Time `json:"generatedAt"`
Entries []RegistryEntry `json:"entries"`
}
Registry is a list of plugins, built from their repositories.
func BuildRegistry ¶ added in v0.2.0
BuildRegistry reads the plugin.json and main module of each repository and collects them, one entry per plugin id. A repository that doesn't read is left out and reported; it doesn't take the others with it. One whose module doesn't compile is kept, with Health saying why.
func ReadRegistry ¶ added in v0.2.0
ReadRegistry reads a registry file.
type RegistryEntry ¶ added in v0.2.0
type RegistryEntry struct {
ID string `json:"id"`
Name string `json:"name"`
Version string `json:"version"`
Description string `json:"description,omitempty"`
Author string `json:"author,omitempty"`
Homepage string `json:"homepage,omitempty"`
Repo string `json:"repo"`
Main string `json:"main,omitempty"`
MinAppVersion string `json:"minAppVersion,omitempty"`
Permissions Permissions `json:"permissions,omitempty"`
// SHA256 is the sha256 of the latest release's first zip asset, when
// GitHub lists one and a token was used.
SHA256 string `json:"sha256,omitempty"`
// Health is what the last build saw of the module: whether it compiles,
// and what it exports when it does.
Health *Health `json:"health,omitempty"`
}
RegistryEntry is one plugin a registry knows, without its code.
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.
Source Files
¶
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. |
|
Package plugintest loads a plugin the way an app does, for the plugin author's own tests.
|
Package plugintest loads a plugin the way an app does, for the plugin author's own tests. |