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 InRange(v int, r string) bool
- func Main(manifest []byte, h Handler)
- func ManifestName(id, ver string) string
- func Notify(method string, params any) error
- func ParseSize(s string) (int64, 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 CardHook
- type Catalog
- type CatalogFile
- type CatalogModule
- type CatalogUI
- type CatalogUIPage
- type CatalogVersion
- type CatalogWithdrawn
- type Conn
- type DataPart
- 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 Integration
- type IntegrationSummary
- type ItemFields
- type ItemTitles
- type Lifecycle
- type LifecycleArgs
- type Limits
- type LivePart
- 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) NeedsIntegration() bool
- func (m *Manifest) NeedsSDUI() bool
- func (m *Manifest) PerPlatform() bool
- func (m *Manifest) Problems() []Problem
- func (m *Manifest) StatusOrStable() string
- func (m *Manifest) Supports(server string, minAPI, maxAPI int) error
- func (m *Manifest) Top(goos, goarch string) string
- func (m *Manifest) Unfinished() bool
- func (m *Manifest) Validate() error
- func (m *Manifest) ValidateRelease() error
- func (m *Manifest) WebFolder() string
- type NavFold
- type NetworkHost
- type NetworkPart
- type Op
- type Page
- type PlayerHook
- type Problem
- type Publisher
- type ReaderHook
- type Route
- type SDUIPart
- type ScanChoice
- type ScanChoices
- type ScanChoicesArgs
- type ScanDescribeArgs
- type ScanDescribeItem
- type ScanDescribed
- type ScanFile
- type ScanIdentified
- type ScanIdentifyArgs
- type ScanItem
- type ScanLibrary
- type ScanPart
- type SettingsTab
- type SetupLater
- type SetupStep
- type SetupWhen
- type StreamHandler
- type Takeover
- type Target
- type TaskReport
- type WebPart
- type WebRoute
- 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 ( MaxUIPages = 32 MaxUIPageTitle = 120 // characters MaxUILabel = 40 // characters MaxUISources = 64 MaxUIInserts = 32 )
Limits on a version's UI summary, which match what sdui.json itself may carry.
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 ( AuthUser = "user" AuthAdmin = "admin" AuthTicket = "ticket" )
Route auth values.
const ( FrameFullscreen = "fullscreen" FrameApp = "app" FrameTV = "tv" )
Frames.
const ( CallInstall = "lifecycle.install" CallUpgrade = "lifecycle.upgrade" CallEnable = "lifecycle.enable" CallDisable = "lifecycle.disable" CallUninstall = "lifecycle.uninstall" )
Lifecycle calls, on the helper protocol.
const ( HostHTTP = "http" // routes, and what the server checks for them HostWeb = "web" // the web app's host object (web host API) HostSDUI = "sdui" // the SDUI catalogue revision HostAPI = "host" // the host API a module calls back on )
Host features a server offers, and their versions now.
const ( API = 5 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.
API 4 makes a module's SDUI part of the module: a release carries sdui.json beside its manifest (package sdui; WittyMediaServer docs/SDUI-MODULES.md), which the server checks against its catalogue, and a version built for API 4 without one is refused. A server that takes API 4 still takes API 3, so nothing breaks until a module is upgraded.
API 5 makes a module own its whole feature: its HTTP routes, the screens it adds to the web app, its data and its lifecycle, declared in integration.json (integration.go), and a host API it calls back on (package host). A server that takes API 5 still takes 3 and 4, and runs its own copy of a module's feature for those until every module has moved.
const ( SDUIFromAPI = 4 SDUIFile = "sdui.json" )
SDUIFromAPI is the API from which a module must carry its SDUI, and SDUIFile its name.
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 ( StatusStable = "stable" // the default: nothing known to be missing StatusBeta = "beta" // complete, and still being tried out StatusExperimental = "experimental" // works in parts, may change or break StatusIncomplete = "incomplete" // parts are missing, which StatusNote names )
How finished a version says it is. A server installs an experimental or incomplete version only after an administrator has read its note and agreed (an override of kind incomplete).
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 ( CallScanChoices = "scan.choices" CallScanIdentify = "scan.identify" CallScanDescribe = "scan.describe" )
Scan calls, to the module's service.
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 IntegrationFile = "integration.json"
IntegrationFile is its name in a module's folder and at the root of every archive.
const IntegrationFormat = "wittymodule-integration"
IntegrationFormat is integration.json's format.
const IntegrationFromAPI = 5
IntegrationFromAPI is the module API from which a module that adds anything to a server must carry integration.json.
const ManifestFile = "module.json"
ManifestFile is the manifest's name in a plugin's folder and in a release.
const MaxIntegration = 256 << 10
MaxIntegration is the most a server reads of one.
const MaxStatusNote = 500
MaxStatusNote is the longest statusNote, in characters.
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.
const ScanAuto = "auto"
ScanAuto is the facet value of a library that holds any of the module's choices.
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 ItemFieldNames = []string{"title", "tagline", "overview", "year", "genres", "rating", "contentRating", "studio", "poster", "backdrop", "provider", "titles"}
ItemFieldNames are the fields ItemFields can set or clear, as Clear and Edited name them.
var ManifestJSON []byte
ManifestJSON is this module's manifest (docs/MODULES.md, "The manifest").
var SetupAnchors = []string{"modules", "libraries", "details", "people", "remote", "ready"}
SetupAnchors are the built-in steps a module's step may name.
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 InRange ¶ added in v0.5.0
InRange reports whether version v (a host feature's number) is within a range such as ">=1 <2" or "5".
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 CardHook ¶ added in v0.5.0
type CardHook struct {
MediaKind string `json:"mediaKind"`
Art bool `json:"art,omitempty"`
Detail bool `json:"detail,omitempty"`
Link bool `json:"link,omitempty"`
}
CardHook draws cards of a media kind: their art, their detail panel's bio, where they link.
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 CatalogUI ¶ added in v0.4.0
type CatalogUI struct {
Pages []CatalogUIPage `json:"pages,omitempty"`
Settings bool `json:"settings,omitempty"`
Sources int `json:"sources,omitempty"`
Inserts int `json:"inserts,omitempty"`
}
CatalogUI sums up a version's sdui.json: its pages, its menu entries by label, whether it has settings, and how many data sources and inserts into built-in pages it has.
type CatalogUIPage ¶ added in v0.4.0
CatalogUIPage is one page a version adds.
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"`
// Status and StatusNote are the release manifest's own, for the store to show before
// anything is downloaded. What a server goes by is the signed manifest, which an install
// reads anyway: these are never a reason to install or refuse.
Status string `json:"status,omitempty"`
StatusNote string `json:"statusNote,omitempty"`
// UI sums up what the version's sdui.json adds to the apps, for the store's page. It is
// written by `wittymodule catalog-add` from the file in the signed release; a version
// with no sdui.json has none.
UI *CatalogUI `json:"ui,omitempty"`
// Integration sums up what the version's integration.json adds to a server (module API 5):
// how many routes, which screens, which settings, whether it keeps data of its own.
Integration *IntegrationSummary `json:"integration,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 DataPart ¶ added in v0.5.0
type DataPart struct {
Store string `json:"store"` // "sqlite": a database in its data folder
Backup string `json:"backup,omitempty"` // which part of a backup it goes in: settings, saves, library
}
DataPart is the module's own data.
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 Integration ¶ added in v0.5.0
type Integration struct {
Schema string `json:"$schema,omitempty"`
Format string `json:"format"` // always IntegrationFormat
FormatVersion int `json:"formatVersion"` // always 1
Module string `json:"module"` // the module's id, as in module.json
// Host is the host features it needs, as ranges: "http", "web", "sdui", "host". A server
// that offers less (or more than a range allows) doesn't run this version, and says why.
Host map[string]string `json:"host,omitempty"`
// Feature is the parental and profile-limits feature everything here belongs to, such as
// "games" or "livetv": a profile without it can't reach the routes or see the screens.
Feature string `json:"feature,omitempty"`
HTTP []Route `json:"http,omitempty"`
Web *WebPart `json:"web,omitempty"`
SDUI *SDUIPart `json:"sdui,omitempty"`
Data *DataPart `json:"data,omitempty"`
Lifecycle *Lifecycle `json:"lifecycle,omitempty"`
Live *LivePart `json:"live,omitempty"`
// Scan says which kinds of library the module scans: the server walks their files and asks
// the module what they are (scan hooks).
Scan *ScanPart `json:"scan,omitempty"`
// Network is what the module reaches on the internet by itself.
Network *NetworkPart `json:"network,omitempty"`
}
Integration is integration.json.
func ParseIntegration ¶ added in v0.5.0
func ParseIntegration(b []byte) (*Integration, error)
ParseIntegration reads integration.json strictly: one object, no unknown field anywhere, no more than MaxIntegration.
func (*Integration) Check ¶ added in v0.5.0
func (in *Integration) Check(m *Manifest) []Problem
Check reports every problem with the file for this manifest, as problems with a field each.
func (*Integration) Summary ¶ added in v0.5.0
func (in *Integration) Summary() IntegrationSummary
Summary sums the file up.
func (*Integration) Validate ¶ added in v0.5.0
func (in *Integration) Validate(m *Manifest) error
ValidateIntegration is Check as one error, or nil.
type IntegrationSummary ¶ added in v0.5.0
type IntegrationSummary struct {
Routes int `json:"routes,omitempty"`
Screens []string `json:"screens,omitempty"` // web routes
Settings []string `json:"settings,omitempty"`
Data bool `json:"data,omitempty"`
Feature string `json:"feature,omitempty"`
Scans []string `json:"scans,omitempty"` // kinds of library it scans
}
Summary is what a catalogue says of a version's integration.json, for the store to show.
type ItemFields ¶ added in v0.5.3
type ItemFields struct {
ID int64 `json:"id"`
Title string `json:"title,omitempty"`
SortTitle string `json:"sortTitle,omitempty"`
Tagline string `json:"tagline,omitempty"`
Overview string `json:"overview,omitempty"`
Year int `json:"year,omitempty"`
Genres []string `json:"genres,omitempty"`
Rating *float64 `json:"rating,omitempty"` // 0-10
ContentRating string `json:"contentRating,omitempty"`
Studio string `json:"studio,omitempty"`
Poster string `json:"poster,omitempty"` // an address PutImage gave
Backdrop string `json:"backdrop,omitempty"` // likewise
Provider string `json:"provider,omitempty"` // where it came from: "game:libretro"
ProviderID string `json:"providerId,omitempty"`
Titles *ItemTitles `json:"titles,omitempty"`
Clear []string `json:"clear,omitempty"`
}
ItemFields are an item's generic fields as a module sets them. A field left empty stays as it is; Clear names fields to empty. The server never changes a field a person typed.
type ItemTitles ¶ added in v0.5.3
type ItemTitles struct {
Native string `json:"native,omitempty"`
English string `json:"english,omitempty"`
}
ItemTitles are an item's other names: in its own script, and in English.
type Lifecycle ¶ added in v0.5.0
type Lifecycle struct {
Install bool `json:"install,omitempty"`
Upgrade bool `json:"upgrade,omitempty"`
Enable bool `json:"enable,omitempty"`
Disable bool `json:"disable,omitempty"`
Uninstall string `json:"uninstall,omitempty"` // "", "ask-keep-data", "keep-data", "remove-data"
}
Lifecycle says which lifecycle calls the module answers.
type LifecycleArgs ¶ added in v0.5.0
type LifecycleArgs struct {
From string `json:"from,omitempty"` // the version before, for upgrade
To string `json:"to,omitempty"` // the version now
KeepData bool `json:"keepData,omitempty"` // for uninstall
}
LifecycleArgs is what a lifecycle call is given.
type Limits ¶ added in v0.5.0
type Limits struct {
Body string `json:"body,omitempty"` // "256KB", "4MB": the most a request may carry
Answer string `json:"answer,omitempty"` // the most an answer may carry (not for streams)
Time string `json:"time,omitempty"` // "45s", "10m": how long an answer may take
}
Limits on one route.
type LivePart ¶ added in v0.5.0
type LivePart struct {
Sessions bool `json:"sessions,omitempty"` // games, streams: counted for metrics, screen time and "playing now"
Doctor bool `json:"doctor,omitempty"` // it answers doctor checks
}
LivePart is what the module reports while it runs.
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"`
// Status says how finished this version is (module API 4 adds it; an older server ignores
// it): stable when left out, beta, experimental or incomplete. StatusNote says, in one
// line, what isn't done or may break, and is required for experimental and incomplete.
Status string `json:"status,omitempty"`
StatusNote string `json:"statusNote,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) NeedsIntegration ¶ added in v0.5.0
NeedsIntegration reports whether a version must carry integration.json.
func (*Manifest) NeedsSDUI ¶ added in v0.4.0
NeedsSDUI reports whether a release of this version must carry sdui.json: one built for SDUIFromAPI or newer that a server installs (a library reaches it inside others).
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) Problems ¶ added in v0.4.0
Problems is everything wrong with a manifest on its own, in the order of its fields, each with where it is: what `wittymodule check` lists.
func (*Manifest) StatusOrStable ¶ added in v0.4.0
StatusOrStable is the version's status, with stable for one that says nothing.
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) Unfinished ¶ added in v0.4.0
Unfinished says whether a version says it is experimental or incomplete: a server warns before installing it, and installs it only when an administrator agrees.
func (*Manifest) Validate ¶
Validate checks that a manifest makes sense on its own. It reports the first problem; Problems has them all.
func (*Manifest) ValidateRelease ¶ added in v0.3.0
ValidateRelease adds what only a release must have: something a server can run.
type NavFold ¶ added in v0.5.0
type NavFold struct {
}
NavFold folds the menu entries of a kind of library into one of the module's.
type NetworkHost ¶ added in v0.5.0
type NetworkHost struct {
Host string `json:"host"` // api.example.com, or *.example.com
Why string `json:"why"` // in plain words, at most 200 characters
}
NetworkHost is one host.
type NetworkPart ¶ added in v0.5.0
type NetworkPart struct {
Hosts []NetworkHost `json:"hosts,omitempty"`
}
NetworkPart lists every host a module contacts by itself, each with why: shown at install, on the server's privacy list, and enforced where a system's sandbox can.
type Op ¶ added in v0.5.0
type Op struct {
ID string `json:"id"` // "<module>.<name>"
HTTP string `json:"http"` // "POST /rooms": a method and one of the module's own route paths
}
Op is one SDUI command.
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 PlayerHook ¶ added in v0.5.0
type PlayerHook struct {
MediaKind string `json:"mediaKind"`
}
PlayerHook plays items of a media kind.
type Problem ¶ added in v0.4.0
Problem is one thing wrong with a manifest: the field it is in, as module.json spells it (pages[2].title for a part of one), and what is wrong, in words.
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 ReaderHook ¶ added in v0.5.0
type ReaderHook struct {
Format string `json:"format"` // epub, pdf, cbz
}
ReaderHook reads a book format.
type Route ¶ added in v0.5.0
type Route struct {
Path string `json:"path"` // "/games/{id}/play": Go ServeMux style, starting with "/"
Methods []string `json:"methods"` // GET, HEAD, POST, PUT, PATCH, DELETE
// Auth is who may call it: user (anyone signed in), admin, ticket (no sign-in; the module
// checks a secret in the path, and the answer is only ever shown in a sandboxed frame).
Auth string `json:"auth"`
// Item names a path parameter holding a library item's id. The server checks the profile
// may see that item, and tells the module about it (X-Witty-Item) with its files.
Item string `json:"item,omitempty"`
// Upgrade allows a WebSocket on this route.
Upgrade string `json:"upgrade,omitempty"` // "websocket"
// Stream: the answer is a stream, sent on as it comes, with no size or time limit.
Stream bool `json:"stream,omitempty"`
// Plays: calling it starts or goes on playing something, so it counts towards a profile's
// screen time and is refused when that time is up (leaving, a DELETE, never is).
Plays bool `json:"plays,omitempty"`
// Limits on a request and its answer; the server's defaults when left out.
Limits *Limits `json:"limits,omitempty"`
// CSP is a policy for an answer that is a page: "sandboxed-page" only, for ticket routes.
CSP string `json:"csp,omitempty"`
// Confirm: a request may carry the person's password (X-WMS-Confirm-Password, and
// X-WMS-Confirm-Code with two-factor sign-in). The server checks it, refuses a wrong one
// itself (403), and tells the module only that it was right (X-Witty-Confirmed: 1). The
// password never reaches the module, on this route or any other.
Confirm bool `json:"confirm,omitempty"`
}
Route is one HTTP route the module answers. The server mounts it at /api/modules/<id><path> (and /api/v1/modules/...), checks who may call it before the module hears of the request, and passes it to the module's service at /http<path>. Apps call it there: a module's API is its own.
type SDUIPart ¶ added in v0.5.0
type SDUIPart struct {
Ops []Op `json:"ops,omitempty"`
}
SDUIPart is the module's SDUI ops: commands its pages send, each answered by one of its routes.
type ScanChoice ¶ added in v0.5.3
type ScanChoice struct {
ID string `json:"id"`
Name string `json:"name"`
Short string `json:"short,omitempty"` // SNES, Mega Drive: for a card
}
ScanChoice is one of them: a console.
type ScanChoices ¶ added in v0.5.3
type ScanChoices struct {
Facet string `json:"facet"`
Values []ScanChoice `json:"values"`
}
ScanChoices is scan.choices' answer.
type ScanChoicesArgs ¶ added in v0.5.3
type ScanChoicesArgs struct {
LibraryKind string `json:"libraryKind"`
// Testing: the server shows test choices (a test console) too.
Testing bool `json:"testing,omitempty"`
}
ScanChoicesArgs asks which values a kind of library can be held to.
type ScanDescribeArgs ¶ added in v0.5.3
type ScanDescribeArgs struct {
Library ScanLibrary `json:"library"`
Items []ScanDescribeItem `json:"items"`
Refresh bool `json:"refresh,omitempty"`
}
ScanDescribeArgs is one call of scan.describe: items a scan added or found changed, or one an administrator asked to be looked up again (Refresh).
type ScanDescribeItem ¶ added in v0.5.3
type ScanDescribeItem struct {
ID int64 `json:"id"`
Kind string `json:"kind"`
Title string `json:"title"`
Files []string `json:"files"`
Facets map[string]string `json:"facets,omitempty"`
// Edited are the fields a person typed: the server keeps them whatever the module says.
Edited []string `json:"edited,omitempty"`
}
ScanDescribeItem is an item to describe.
type ScanDescribed ¶ added in v0.5.3
type ScanDescribed struct {
Items []ItemFields `json:"items,omitempty"`
}
ScanDescribed is scan.describe's answer: what the module knows now, item by item. What it finds out later (from the internet) it sets with the host API's PATCH /items/{id}.
type ScanFile ¶ added in v0.5.3
type ScanFile struct {
Path string `json:"path"`
Root string `json:"root"` // the library folder it's under
Size int64 `json:"size"`
MTime int64 `json:"mtime"` // Unix seconds
}
ScanFile is a file the walk found. Path is for reading only.
type ScanIdentified ¶ added in v0.5.3
type ScanIdentified struct {
Items []ScanItem `json:"items,omitempty"`
// Problems is how many files the module couldn't make sense of, for the scan's result.
Problems int `json:"problems,omitempty"`
// Result is what the scan's task says when it's done ("Found 2,292 games in 41s."); "" for
// the server's own words.
Result string `json:"result,omitempty"`
}
ScanIdentified is scan.identify's answer: nothing until the last call, which lists every item the library holds now. An item the library had whose path isn't listed (and isn't under an offline folder) is missing from now on.
type ScanIdentifyArgs ¶ added in v0.5.3
type ScanIdentifyArgs struct {
Scan string `json:"scan"` // the same for every call of one scan
Library ScanLibrary `json:"library"`
Files []ScanFile `json:"files,omitempty"`
// Total is how many files the walk found in all, for the module's own progress.
Total int `json:"total,omitempty"`
Done bool `json:"done,omitempty"`
// Offline are folders that couldn't be read this time: what was under them stays.
Offline []string `json:"offline,omitempty"`
}
ScanIdentifyArgs is one call of scan.identify. A scan sends its files in batches, in the order the walk found them, and then a last call with Done and no files. A scan that's stopped sends no last call; the next scan has another Scan id.
type ScanItem ¶ added in v0.5.3
type ScanItem struct {
// Files are the item's files, the first the one it's known by (its path): a game on several
// discs is one item with a file for each.
Files []string `json:"files"`
Kind string `json:"kind"` // the item kind: game
Title string `json:"title"`
SortTitle string `json:"sortTitle,omitempty"`
Tagline string `json:"tagline,omitempty"` // region, revision
Year int `json:"year,omitempty"`
Container string `json:"container,omitempty"` // the file's type: 7z, nes
Size int64 `json:"size,omitempty"`
MTime int64 `json:"mtime,omitempty"`
Facets map[string]string `json:"facets,omitempty"` // console
// VersionOf is the path of the item this one is another version of (a region, a revision),
// shown under it; "" when it stands on its own. VersionLabel says which version it is.
VersionOf string `json:"versionOf,omitempty"`
VersionLabel string `json:"versionLabel,omitempty"`
}
ScanItem is an item a scan found.
type ScanLibrary ¶ added in v0.5.3
type ScanLibrary struct {
ID int64 `json:"id"`
Kind string `json:"kind"`
Facet string `json:"facet,omitempty"` // the value it's held to, or ScanAuto
Paths []string `json:"paths"`
}
ScanLibrary is the library a scan is of.
type ScanPart ¶ added in v0.5.3
type ScanPart struct {
// LibraryKinds are the kinds of library the module scans ("games"). Each must be one of
// module.json's libraries. A library of such a kind can't be made while the module is
// missing.
LibraryKinds []string `json:"libraryKinds"`
// Identify: the module answers scan.identify (needed).
Identify bool `json:"identify"`
// Describe: the module answers scan.describe.
Describe bool `json:"describe,omitempty"`
// Facet is the facet a library of the kind can be held to ("console": a library of one
// console's games), whose values scan.choices gives. "" for none.
Facet string `json:"facet,omitempty"`
}
ScanPart is integration.json's scan part.
type SettingsTab ¶ added in v0.5.0
type SettingsTab struct {
ID string `json:"id"`
Label string `json:"label"`
Admin bool `json:"admin,omitempty"`
After string `json:"after,omitempty"` // another section's id
Search []string `json:"search,omitempty"` // words Settings' search finds it by
// Launch makes the row open a place of the module's own instead of drawing a section in
// Settings: one interface, the module's (WittyPlay's store for cores and emulators).
Launch string `json:"launch,omitempty"`
// Hidden takes a built-in section of this id out of Settings' menu; its address goes to Launch.
Hidden bool `json:"hidden,omitempty"`
}
SettingsTab is a section of the web app's Settings the module draws.
type SetupLater ¶ added in v0.5.0
SetupLater is a step's place in Settings.
type SetupStep ¶ added in v0.5.0
type SetupStep struct {
ID string `json:"id"`
Title string `json:"title,omitempty"`
After string `json:"after,omitempty"` // a built-in step it goes after
Before string `json:"before,omitempty"` // or before; not both
When *SetupWhen `json:"when,omitempty"`
// Page is an SDUI page of the module's (sdui.json) that is the step's form, so every app
// can draw it; a web bundle may register a richer component for the same id.
Page string `json:"page,omitempty"`
// Saves names what the step may change: the module's own settings keys.
Saves []string `json:"saves,omitempty"`
// Later says where the step lives in Settings afterwards.
Later *SetupLater `json:"later,omitempty"`
// Version is raised when the step changes enough to be shown again to a server that did it.
Version int `json:"version,omitempty"`
}
SetupStep is a step of the first-run setup the module adds (and a "Finish setting up" step later, for a module installed or upgraded after setup).
type SetupWhen ¶ added in v0.5.0
type SetupWhen struct {
LibraryKinds []string `json:"libraryKinds,omitempty"` // such a library exists or is being added
}
SetupWhen is when a step is shown.
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 Takeover ¶ added in v0.5.0
type Takeover struct {
LibraryKind string `json:"libraryKind"`
Route string `json:"route"` // with {library}
}
Takeover has the module draw every library of a kind, at its own route.
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 WebPart ¶ added in v0.5.0
type WebPart struct {
Routes []WebRoute `json:"routes,omitempty"`
Takeover []Takeover `json:"takeover,omitempty"`
Cards []CardHook `json:"cards,omitempty"`
Players []PlayerHook `json:"players,omitempty"`
Readers []ReaderHook `json:"readers,omitempty"`
Settings []SettingsTab `json:"settings,omitempty"`
Setup []SetupStep `json:"setup,omitempty"`
}
WebPart is what the module's web bundle adds to the web app. Its bundle exports register(host) to hand over the components; this says what it claims, so a server can check it and apps can tell what's missing before any code loads.
type WebRoute ¶ added in v0.5.0
type WebRoute struct {
Path string `json:"path"` // "/wittyplay/*", "/game/:id": react-router style
// Frame: fullscreen (replaces the app's frame), app (inside it), tv (a screen of the TV frame).
Frame string `json:"frame"`
}
WebRoute is a place in the web app the module draws.
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. |
|
Package host is a module's way back to the server that runs it (module API 5): library items and their files, whether a person may do something, the module's settings and secrets, pictures, live sessions, notifications, tasks and events.
|
Package host is a module's way back to the server that runs it (module API 5): library items and their files, whether a person may do something, the module's settings and secrets, pictures, live sessions, notifications, tasks and events. |
|
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 sdui is the kit a module describes its part of every app with: its pages, sections, components, data sources, views, menu entries, settings and theme scope, in the sdui.json that ships in each release (WittyMediaServer docs/SDUI-MODULES.md).
|
Package sdui is the kit a module describes its part of every app with: its pages, sections, components, data sources, views, menu entries, settings and theme scope, in the sdui.json that ships in each release (WittyMediaServer docs/SDUI-MODULES.md). |
|
core
Package sdui is WittyMediaServer's server-driven UI: the model an administrator writes pages in, the catalogue that describes it, the validator, and the renderer that turns one page into the tree of components one profile's app draws on one device.
|
Package sdui is WittyMediaServer's server-driven UI: the model an administrator writes pages in, the catalogue that describes it, the validator, and the renderer that turns one page into the tree of components one profile's app draws on one device. |
|
sduitest
Package sduitest keeps a module's sdui.json equal to its Go definition, in the module's own tests:
|
Package sduitest keeps a module's sdui.json equal to its Go definition, in the module's own tests: |
|
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. |

