Documentation
¶
Overview ¶
Package wittymodule is what a WittyMediaServer plugin needs to be a project of its own: the manifest, the rules for version ranges, the protocol a helper process speaks, and the names of a release's files. It has no dependencies, so a plugin that uses it still has none of its own.
Index ¶
- Constants
- Variables
- func ArchiveName(id, ver, goos, goarch string) string
- func Compare(a, b string) int
- func HashHex(sum []byte) string
- func Main(manifest []byte, h Handler)
- func ManifestName(id, ver string) string
- func Notify(method string, params any) error
- func Prerelease(s string) bool
- func ProgramFile(name, goos string) string
- func ReportTask(t TaskReport) error
- func ResolveCatalogURL(catalog, ref string) (string, error)
- func Serve(in io.Reader, out io.Writer, hello Hello, h Handler) error
- func ServeStream(in io.Reader, out io.Writer, hello Hello, h StreamHandler) error
- func SumsName(id, ver string) string
- func TopFolder(id, ver, goos, goarch string) string
- func Valid(s string) bool
- func ValidCatalogURL(s string) bool
- func WebArchiveName(id, ver string) string
- func WebTopFolder(id, ver string) string
- func WithdrawalsName(id string) string
- type CallError
- type Catalog
- type CatalogFile
- type CatalogModule
- type CatalogVersion
- type CatalogWithdrawn
- type Conn
- type DiagFinding
- type DiagJob
- func (j *DiagJob) Add(f DiagFinding)
- func (j *DiagJob) Engine(what string, fn func()) (ok bool)
- func (j *DiagJob) Progress(fraction float64)
- func (j *DiagJob) Rest(ctx context.Context, _ time.Duration) bool
- func (j *DiagJob) SetLabel(label string)
- func (j *DiagJob) Step(phase string, fraction float64)
- type DiagStep
- type Handler
- type Hello
- type Manifest
- func (m *Manifest) Archive(goos, goarch string) string
- func (m *Manifest) Asks(permission string) bool
- func (m *Manifest) EntryFile(goos string) string
- func (m *Manifest) HasWeb() bool
- func (m *Manifest) PerPlatform() bool
- func (m *Manifest) Supports(server string, minAPI, maxAPI int) error
- func (m *Manifest) Top(goos, goarch string) string
- func (m *Manifest) Validate() error
- func (m *Manifest) ValidateRelease() error
- func (m *Manifest) WebFolder() string
- type Page
- type Publisher
- type StreamHandler
- type Target
- type TaskReport
- type Withdrawals
- type Withdrawn
Constants ¶
const ( // CatalogName is the catalogue's file; its signature adds .sig. CatalogName = "catalog.json" // CatalogKeyName is the public key a store offers beside its catalogue, in base64. It is // only ever a suggestion for the first time an admin adds the store: from then on the key // that was agreed to is the one that counts, and a different one here is a refusal. CatalogKeyName = CatalogName + ".key" // PlatformAll is the one platform of a web bundle. PlatformAll = "all" // MaxCatalog is the largest catalogue a reader takes, checked before reading it all. MaxCatalog = 8 << 20 )
const ( NotifyDiagStep = "diag.step" // DiagStep: what it's doing now NotifyDiagProgress = "diag.progress" // a number from 0 to 1 NotifyDiagLabel = "diag.label" // the disc's name, if it has one NotifyDiagFinding = "diag.finding" // DiagFinding )
A module can check what it reads, when an owner asks why a disc won't play. A helper's check reports as it goes, through notifications, and a server shows it with its other checks. What it says is words about the disc's structure: a report holds no disc content.
const ( DiagOK = "ok" DiagInfo = "info" DiagWarn = "warn" DiagProblem = "problem" )
How bad a finding is.
const ( API = 3 MinAPI = 3 )
The module API: the contract between the server and its plugins. A plugin names the version it was built for, and a server takes MinAPI to API. Adding to the contract raises API only; breaking it raises MinAPI too, which disables older plugins, so that is done rarely.
API 2 adds web bundles, programs, attached helpers and streams to API 1. Nothing in API 1 changed, so a version built for it still runs. API 3 adds notifications from a helper and the pages a module adds to the app, and is the first API where nothing of a module is compiled into the server, so it is also the oldest one a server takes: a module has to be built for WittyMediaServer 0.6.0-alpha or newer.
const ( DeliveryHelper = "helper" // a program for each platform, run as a separate process DeliveryProgram = "program" // a program for each platform that the server runs for one job, in its own protocol DeliveryWeb = "web" // a bundle the browser loads DeliveryLibrary = "library" // source only, linked into others: it reaches a server inside them DeliveryBuiltin = "builtin" // not converted yet: it updates with the server )
How a release of a plugin reaches the server.
const ( PermissionNetwork = "network" // it may reach the network PermissionPrograms = "programs" // it may start other programs, such as FFmpeg PermissionDevices = "devices" // it may open this machine's devices, such as a tuner or a graphics card PermissionData = "data" // it may write to a folder of its own, which it is told of in WITTYMODULE_DATA )
Permissions a version can ask for. A helper has neither unless it asks, in its signed manifest, and the server also agrees that its kind of plugin needs it.
const ( PageMain = "main" // with the app's sections PageSettings = "settings" // in Settings )
Where a module's page is listed in the app.
const ( MaxLine = 1 << 20 MaxBlob = 128 << 20 )
The helper protocol (module API 1): one line of JSON per message over stdin and stdout, optionally followed by a binary blob of the announced size. Sizes are checked before anything is read, because the two sides don't trust each other.
const ( TaskRunning = "running" TaskDone = "done" TaskFailed = "failed" )
A task's state. A process that ends has its running tasks ended for it.
const ( // WithdrawalsTag is that release's tag. It isn't a version, so nothing mistakes // it for something to install. WithdrawalsTag = "withdrawals" // SeverityBroken: warn, and never install it automatically. SeverityBroken = "broken" // SeveritySecurity: refuse it, and stop using it where it is in use. SeveritySecurity = "security" )
A release can't be taken back from everyone who has seen it, and GitHub is not trusted to say which ones are bad. So a plugin publishes a signed list of the versions it has withdrawn, as files on one more release of its repository.
const CatalogFormat = 1
CatalogFormat is the format this package writes and reads. A file with a higher one is refused in words, and the last good catalogue stays in use. Adding a field doesn't raise it, since readers ignore fields they don't know.
const FirstServer = "0.6.0-alpha"
FirstServer is the first server this API is for, and what a module's minServer starts from.
const HelperFlag = "--wms-helper"
HelperFlag is what the server starts a helper with.
const ManifestFile = "module.json"
ManifestFile is the manifest's name in a plugin's folder and in a release.
const NoticesFile = "THIRD-PARTY-NOTICES.txt"
NoticesFile holds the licenses of the libraries in a module's programs.
const NotifyTask = "task"
NotifyTask is the notification a helper sends to report work in the background, which the server shows with its own. A server names a task by the module it came from as well as its key, so a module can only ever speak about its own.
Variables ¶
var ErrCatalogSignature = errors.New("the catalogue's signature doesn't check out")
ErrCatalogSignature is a catalogue that none of the keys signed.
var ErrNotServing = errors.New("this process isn't serving calls, so it has nobody to tell")
ErrNotServing is Notify when no Serve is running, or in a process answering with a stream, where anything else on the pipe would be taken for part of the stream.
var ManifestJSON []byte
ManifestJSON is this module's manifest (docs/MODULES.md, "The manifest").
var Targets = []Target{{"windows", "amd64"}, {"windows", "arm64"}, {"darwin", "amd64"}, {"darwin", "arm64"},
{"linux", "amd64"}, {"linux", "arm64"}, {"linux", "arm"}, {"linux", "386"}, {"freebsd", "amd64"}, {"freebsd", "arm64"}}
Targets are the platforms the server ships to, as in scripts/build-release.sh.
Functions ¶
func ArchiveName ¶
ArchiveName is the release archive for a platform.
func Compare ¶
Compare orders two versions: -1 if a is older than b, 0 if equal, 1 if newer. A pre-release (0.4.0-alpha) comes before its release (0.4.0). Versions that cannot be read sort before everything else.
func Main ¶
Main runs a helper program from its manifest. Started by hand, it explains itself instead of waiting silently.
func ManifestName ¶
ManifestName is the copy of the manifest attached to a release, so it can be judged before anything large is downloaded.
func Notify ¶ added in v0.3.0
Notify tells the server something unasked, from any goroutine, at any time while Serve is running. A server treats it as untrusted, and may ignore it or drop it for sending too many. It blocks only while the pipe is full, so don't call it in a tight loop.
func Prerelease ¶
Prerelease reports whether s is a pre-release such as 0.4.0-alpha.
func ProgramFile ¶ added in v0.3.0
ProgramFile is a program's file name on a system.
func ReportTask ¶ added in v0.3.0
func ReportTask(t TaskReport) error
ReportTask tells the server how a task is going. Send it as things change, at most a few times a second.
func ResolveCatalogURL ¶ added in v0.3.0
ResolveCatalogURL turns what a catalogue says into an address, given where the catalogue itself came from.
func ServeStream ¶ added in v0.3.0
ServeStream is Serve for a process that answers one call with a stream: nothing else can be said on the pipe afterwards, so the process exits when the stream ends.
func ValidCatalogURL ¶ added in v0.3.0
ValidCatalogURL says whether a catalogue may point at this: an https address, or a path below the folder the catalogue is in.
func WebArchiveName ¶ added in v0.3.0
WebArchiveName is the archive of a web bundle.
func WebTopFolder ¶ added in v0.3.0
WebTopFolder is the one folder inside a web bundle's archive, the same for every platform.
func WithdrawalsName ¶ added in v0.3.0
WithdrawalsName is the list's file on that release; its signature adds .sig.
Types ¶
type CallError ¶
CallError is an answer from a working helper that says no, such as a file it can't read. It says nothing about the helper's health; any other error from Call means the helper itself failed.
type Catalog ¶ added in v0.3.0
type Catalog struct {
Format int `json:"format"`
Name string `json:"name"`
Serial int64 `json:"serial"`
Generated string `json:"generated"` // RFC 3339
Modules []CatalogModule `json:"modules"`
}
Catalog is the whole file. Serial only ever goes up, and a server keeps the highest it has seen, so nobody can bring back a withdrawn version by replaying an older catalogue.
func ParseCatalog ¶ added in v0.3.0
ParseCatalog reads and checks a catalogue without looking at its signature, which is for the tools that write one. A server uses VerifyCatalog.
func VerifyCatalog ¶ added in v0.3.0
VerifyCatalog checks a catalogue's signature, then reads it. Nothing in it is looked at before the signature passes.
func (*Catalog) Find ¶ added in v0.3.0
func (c *Catalog) Find(id string) *CatalogModule
Find looks a module up.
func (*Catalog) Put ¶ added in v0.3.0
func (c *Catalog) Put(mod CatalogModule, v CatalogVersion) (bool, error)
Put adds a version to a module, adding the module if it's new, and keeps the newest first. A version already there has to be the same one, since versions never change after they are released; the one thing that may change is its being withdrawn. It reports whether anything changed, and only then does the serial go up.
type CatalogFile ¶ added in v0.3.0
type CatalogFile struct {
URL string `json:"url"` // https, or relative to the catalogue's own location
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
}
CatalogFile is one downloadable file, with what it must turn out to be.
type CatalogModule ¶ added in v0.3.0
type CatalogModule struct {
ID string `json:"id"`
Name string `json:"name"`
Summary string `json:"summary"` // a line
Description string `json:"description,omitempty"` // plain text
Icon *CatalogFile `json:"icon,omitempty"` // PNG, at most 256 KiB; never a brand's logo
// Screenshots are PNG or JPEG pictures of the module at work, at most 8 of 2 MiB each. They
// are fetched by the server when someone opens the module's page, and served from there.
Screenshots []CatalogFile `json:"screenshots,omitempty"`
Publisher Publisher `json:"publisher"`
Repo string `json:"repo"` // owner/name on GitHub, where its source and releases are
Group string `json:"group,omitempty"`
Libraries []string `json:"libraries,omitempty"`
Requires []string `json:"requires,omitempty"`
Core bool `json:"core,omitempty"`
Needs []string `json:"needs,omitempty"`
Updates string `json:"updates,omitempty"`
Stays string `json:"stays,omitempty"`
Versions []CatalogVersion `json:"versions"`
}
CatalogModule is one module and its versions, newest first.
func (*CatalogModule) Find ¶ added in v0.3.0
func (m *CatalogModule) Find(version string) *CatalogVersion
Find looks a version up.
type CatalogVersion ¶ added in v0.3.0
type CatalogVersion struct {
Version string `json:"version"`
Delivery string `json:"delivery"`
API int `json:"api"`
MinServer string `json:"minServer"`
MaxServer string `json:"maxServer"`
License string `json:"license"`
Permissions []string `json:"permissions,omitempty"`
Released string `json:"released"` // YYYY-MM-DD
Prerelease bool `json:"prerelease,omitempty"` // also true of any version with a pre-release label
Changelog string `json:"changelog,omitempty"` // plain text; empty when there's nothing to report
// The release's signed files, and an archive for each platform, keyed by GOOS-GOARCH
// ("linux-arm" is the armv7 build), or PlatformAll for a web bundle.
Sums string `json:"sums"`
Sig string `json:"sig"`
Manifest string `json:"manifest"`
Platforms map[string]CatalogFile `json:"platforms"`
Withdrawn *CatalogWithdrawn `json:"withdrawn,omitempty"`
}
CatalogVersion is one release of a module. Everything down to Permissions has to match the release's own signed manifest.
func (*CatalogVersion) MatchesManifest ¶ added in v0.3.0
func (v *CatalogVersion) MatchesManifest(id string, m *Manifest) error
MatchesManifest compares what the catalogue said with what the release itself signed. Any difference refuses the install, so a catalogue can't describe a version as asking for less than it does, or as fitting a server it doesn't.
func (*CatalogVersion) Platform ¶ added in v0.3.0
func (v *CatalogVersion) Platform(goos, goarch string) *CatalogFile
Platform is a version's archive for a system, or nil if it has none.
func (*CatalogVersion) Supports ¶ added in v0.3.0
func (v *CatalogVersion) Supports(name, server string, minAPI, maxAPI int) error
Supports says, in words an owner can read, why this version can't run on a server of the given version and module API range; nil when it can. It answers as the manifest would.
type CatalogWithdrawn ¶ added in v0.3.0
CatalogWithdrawn takes a listed version back, as a module's own signed list does.
type Conn ¶
type Conn struct {
// OnNotify hears what a helper says unasked, if set before the first call. What it is
// given is untrusted and may arrive at any rate, so it checks and limits for itself. It
// runs while the Conn is reading, so it must not block or make a call.
OnNotify func(method string, params json.RawMessage)
// contains filtered or unexported fields
}
Conn is the server's end of the protocol. It makes one call at a time.
func (*Conn) Call ¶
Call asks the helper one thing and decodes the result into out, when given. A *CallError means the helper answered no; any other error means it failed.
func (*Conn) Listen ¶ added in v0.3.0
func (c *Conn) Listen()
Listen keeps reading between calls, for a helper that stays running: without it, nothing reads the pipe while no call is being made, and a helper with a lot to say would stop at Notify until the next call. It ends when the helper's output does. Call it once, before the first call. A Conn that listens can't Stream.
type DiagFinding ¶ added in v0.3.0
type DiagFinding struct {
Severity string `json:"severity"`
Title string `json:"title"`
What string `json:"what,omitempty"`
Fix string `json:"fix,omitempty"`
Details []string `json:"details,omitempty"`
// Names are file names (base names only). They come out of a report downloaded with
// names hidden, so nothing else here may hold one.
Names []string `json:"names,omitempty"`
// More counts what Names and Details left out.
More int `json:"more,omitempty"`
}
DiagFinding is one thing a check found.
type DiagJob ¶ added in v0.3.0
type DiagJob struct{}
DiagJob is a check in a helper, reporting to the server.
func (*DiagJob) Add ¶ added in v0.3.0
func (j *DiagJob) Add(f DiagFinding)
Add reports something found.
func (*DiagJob) Engine ¶ added in v0.3.0
Engine runs a part of a check. A crash there is a result, not a disaster: it's turned into a finding, and the rest of the check carries on. ok is false after a crash.
func (*DiagJob) Rest ¶ added in v0.3.0
Rest gives way to others between pieces of work: a helper runs at a low priority already, so this only says whether to carry on.
type DiagStep ¶ added in v0.3.0
DiagStep is what a check is doing, and how far along it is, from 0 to 1.
type Handler ¶
Handler answers one call with a result to send as JSON, an optional blob, and an error (a *CallError keeps its code).
type Hello ¶
type Hello struct {
Module string `json:"module"`
Version string `json:"version"`
API int `json:"api"`
}
Hello is the first thing a helper says.
type Manifest ¶
type Manifest struct {
ID string `json:"id"`
Name string `json:"name"`
Version string `json:"version"`
Repo string `json:"repo"` // owner/name on GitHub, where its releases are
License string `json:"license,omitempty"`
Delivery string `json:"delivery"`
// Entry is the program, without .exe, or a web bundle's script.
Entry string `json:"entry,omitempty"`
Style string `json:"style,omitempty"` // a web bundle's stylesheet, if it has one
// Programs are more programs that come with a helper, without .exe, built from cmd/<name>.
Programs []string `json:"programs,omitempty"`
// WebEntry and WebStyle are the script and stylesheet of a helper that also has a part in
// the browser. Those files sit in web/ inside each platform's archive.
WebEntry string `json:"webEntry,omitempty"`
WebStyle string `json:"webStyle,omitempty"`
API int `json:"api"`
MinServer string `json:"minServer"`
MaxServer string `json:"maxServer"`
// Capabilities are facts the server needs without starting the helper, such
// as "rawExtensions". Signed along with everything else.
Capabilities map[string][]string `json:"capabilities,omitempty"`
Permissions []string `json:"permissions,omitempty"`
// DataFormat numbers the shape of the data this version keeps, and DataFrom is
// the oldest it can still read. Going back to a version that can't read what is
// there is refused, with the reason. Zero means it keeps none of its own.
DataFormat int `json:"dataFormat,omitempty"`
DataFrom int `json:"dataFrom,omitempty"`
// For the people choosing versions: what it does, which group it belongs in,
// what it needs in order to work, which parts of it a release of its own
// really changes, and which stay with the server.
Group string `json:"group,omitempty"`
Summary string `json:"summary,omitempty"`
Needs []string `json:"needs,omitempty"`
Updates string `json:"updates,omitempty"`
Stays string `json:"stays,omitempty"`
// Libraries are the kinds of library that need this plugin (any one plugin listing
// a kind is enough). Requires names plugins it is built on. Core is one that other
// plugins can't do without, so it can't be taken off a server.
Libraries []string `json:"libraries,omitempty"`
Requires []string `json:"requires,omitempty"`
Core bool `json:"core,omitempty"`
// Pages are the pages it adds to the app, which its web bundle draws.
Pages []Page `json:"pages,omitempty"`
}
Manifest describes one version of a plugin.
func ParseManifest ¶
ParseManifest reads and checks a manifest.
func (*Manifest) Archive ¶ added in v0.3.0
Archive is the archive holding this version for a platform.
func (*Manifest) HasWeb ¶ added in v0.3.0
HasWeb says whether a version has a part that runs in the browser.
func (*Manifest) PerPlatform ¶ added in v0.3.0
PerPlatform says whether a version has a build for each platform, rather than one bundle for all.
func (*Manifest) Supports ¶
Supports says, in words an owner can read, why this version can't run on a server of the given version and module API range; nil when it can.
func (*Manifest) Top ¶ added in v0.3.0
Top is the folder a version's files sit in inside its archive, and in its signed list.
func (*Manifest) ValidateRelease ¶ added in v0.3.0
ValidateRelease adds what only a release must have: something a server can run.
type Page ¶ added in v0.3.0
type Page struct {
ID string `json:"id"`
Title string `json:"title"`
Where string `json:"where"`
Icon string `json:"icon,omitempty"` // a name from the app's own set of icons
Admin bool `json:"admin,omitempty"`
}
Page is a page a module adds to the app, at /m/<module>/<id>. Whether someone may see it is the server's to check, and Admin only asks for that check: it never widens what the bundle can do, since a bundle runs with the access of whoever is signed in.
type Publisher ¶ added in v0.3.0
type Publisher struct {
Name string `json:"name"`
URL string `json:"url,omitempty"`
Key string `json:"key,omitempty"`
}
Publisher says who a module comes from. Key is the base64 Ed25519 public key its releases are signed with, when that isn't the catalogue's own key. A server believes it only from a store an admin added, and never for a stock module.
type StreamHandler ¶ added in v0.3.0
type StreamHandler func(method string, params json.RawMessage) (result any, write func(io.Writer) error, err error)
StreamHandler answers one call for a stream with the answer to send, and what to write after it. The stream ends when write returns or the server stops reading.
type TaskReport ¶ added in v0.3.0
type TaskReport struct {
Key string `json:"key"` // this module's name for it, which stays the same
Title string `json:"title"` // what it is, for people
State string `json:"state"` //
Done int64 `json:"done,omitempty"` // how far along, with Total
Total int64 `json:"total,omitempty"` // zero when nobody knows how long it will be
Item string `json:"item,omitempty"` // what it's on now, such as a file's name
}
TaskReport is one task's state as of now. Reports replace each other, so a server that drops some for coming too quickly loses nothing but steps along the way.
func (*TaskReport) Validate ¶ added in v0.3.0
func (t *TaskReport) Validate() error
Validate checks a report. A server calls this on every one, since it comes from a helper.
type Withdrawals ¶ added in v0.3.0
type Withdrawals struct {
Module string `json:"module"`
Serial int `json:"serial"`
Versions []Withdrawn `json:"versions"`
}
Withdrawals is a plugin's list. Serial only ever goes up, and a server keeps the highest it has seen, so nobody can bring a withdrawn version back by replaying an older list. The module's name is inside what is signed, so one plugin's list can't be passed off as another's.
func ParseWithdrawals ¶ added in v0.3.0
func ParseWithdrawals(b []byte) (*Withdrawals, error)
ParseWithdrawals reads and checks a list.
func (*Withdrawals) Find ¶ added in v0.3.0
func (w *Withdrawals) Find(version string) *Withdrawn
Find looks a version up.
func (*Withdrawals) Restore ¶ added in v0.3.0
func (w *Withdrawals) Restore(version string) error
Restore takes a version off the list, and raises the serial.
func (*Withdrawals) Withdraw ¶ added in v0.3.0
func (w *Withdrawals) Withdraw(version, severity, reason string) error
Withdraw adds or replaces an entry, and raises the serial.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
wittymodule
command
Command wittymodule checks, builds and signs a release of a WittyMediaServer plugin, from the plugin's own folder.
|
Command wittymodule checks, builds and signs a release of a WittyMediaServer plugin, from the plugin's own folder. |
|
kit
|
|
|
facade
command
Command facade writes both ends of a service module's calls, so a server can use a module's packages by name with none of its code compiled in.
|
Command facade writes both ends of a service module's calls, so a server can use a module's packages by name with none of its code compiled in. |
|
Package service is how a module that stays running reaches a server: a process of its own that listens on this machine only, with a secret for each start, where calls can overlap and a browser's connection can be passed straight through.
|
Package service is how a module that stays running reaches a server: a process of its own that listens on this machine only, with a secret for each start, where calls can overlap and a browser's connection can be passed straight through. |

