wittymodule

package module
v0.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: AGPL-3.0 Imports: 22 Imported by: 0

README

WittyModule

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 tool that builds and signs a release. It's for people who make modules.

The specification of a module, everything one is held to at module API 4 (and where API 3 differs), is docs/SPEC.md: its manifest, delivery kinds, permissions, the helper protocol, its SDUI, releases and signing, catalogues and stores, withdrawals, forks, its status, and the overrides a server allows.

The module store in WittyMediaServer

What a module becomes: its entry in the store, here from a local test catalogue.

A module's page in the store

A module's own page in the store.

What it does

  • The manifest: module.json, parsed and checked here.
  • Version ranges: which servers a version fits.
  • The helper protocol: what a helper program and a server say to each other. A helper is a small program:
func main() {
	wittymodule.Main(manifestJSON, func(method string, params json.RawMessage) (any, []byte, error) {
		// answer one call
	})
}
  • The module's SDUI (module API 4): sdui/ writes and checks the sdui.json every module carries: what it adds to every app, as data the server checks and every app draws. kit/sdui/ is the same for web bundles in TypeScript. WittyMediaServer's docs/SDUI-MODULES.md describes it.
  • The catalogue: the code that reads and checks a store's signed list of modules.
  • Withdrawing a version: the signed list that takes a version back.
  • The wittymodule tool:
Command What it does
check Checks a folder's manifest and sdui.json, listing every problem by file and field
pack Builds a release: a program for every system, or a browser bundle with -web
sign, keygen Signs a checksum list, and makes a key
bump, needs-bump Raises the version everywhere it's written, and fails if code changed since the last tag with no new version
withdraw, restore Takes a version back, and undoes that
catalog-add, catalog-check, catalog-sign Works on a store's catalogue
  • kit/: kit/module-kit.sh writes a module's workflows and the Releasing section of its README, and kit/facade writes the stubs a server uses to call a module.

The specification is docs/SPEC.md. The reasoning behind it, including what each version range means, is in Making a module, in Help inside WittyMediaServer.

How to get it

Modules bring it in as a Go dependency:

go get github.com/wittywilla/wittymodule
go run github.com/wittywilla/wittymodule/cmd/wittymodule check .

A server gets it inside the modules built with it, so there's nothing to add from the store. Modules built with this version work with WittyMediaServer 0.6.0-alpha or later, through Settings → Modules, and nothing older.

What it needs

Go 1.26 or newer. It has no dependencies, and no cgo.

Platforms

It's plain Go, and CI builds it for Windows, macOS, Linux and FreeBSD. Its tests have been run on Linux, and pack has built modules for all four from there, including FreeBSD on amd64 and arm64. Those have not been run on a real Mac or on FreeBSD. kit/module-kit.sh needs bash.

Building and testing

go vet ./...
go test ./... -count=1
go run ./cmd/wittymodule check .

A module's own pack and sign go like this:

go run github.com/wittywilla/wittymodule/cmd/wittymodule pack -out release .
go run github.com/wittywilla/wittymodule/cmd/wittymodule sign release/<id>-<version>-SHA256SUMS.txt

To make or refresh a module's workflows:

kit/module-kit.sh ../WittyPhotos

Licence

GNU Affero General Public License v3.0 (or later): see LICENSE and NOTICE. If you redistribute it or build on it, please keep the NOTICE attribution.

WittyModule is an independent open-source project. It isn't associated with, sponsored by or endorsed by any publisher, rights holder, service or other media software project. A module built with it comes from whoever published that module. Any third-party names here only describe what it works with, and belong to their owners. It's provided “as is”, with no warranty; see LICENSE. Local law applies to how you use it. This isn't legal advice.

Releasing

WittyModule reaches a server inside the projects built with it, so a release has no files of its own: a version tag runs the tests and publishes a release that those projects can require.

Versions move in small steps as work lands. go run github.com/wittywilla/wittymodule/cmd/wittymodule@v0.4.0 bump . raises it everywhere it is written (add -part minor for a bigger step). A bump isn't a release: nothing is tagged or published until you tag it. CI fails when code changed since the last tag and the version didn't, because tags never move.

To release:

  1. Check that version in module.json is the one to publish, with the bump committed.
  2. Tag that commit and push the tag: git tag vX.Y.Z, then git push origin vX.Y.Z. A tag with a suffix, such as v1.2.0-beta, is published as a prerelease.
  3. Watch the Actions tab. There is nothing to sign.

Licensed under AGPL-3.0-or-later: see LICENSE and NOTICE.

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

View Source
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
)
View Source
const (
	MaxUIPages      = 32
	MaxUIPageTitle  = 120 // characters
	MaxUINavigation = 16
	MaxUILabel      = 40 // characters
	MaxUISources    = 64
	MaxUIInserts    = 32
)

Limits on a version's UI summary, which match what sdui.json itself may carry.

View Source
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.

View Source
const (
	DiagOK      = "ok"
	DiagInfo    = "info"
	DiagWarn    = "warn"
	DiagProblem = "problem"
)

How bad a finding is.

View Source
const (
	AuthUser   = "user"
	AuthAdmin  = "admin"
	AuthTicket = "ticket"
)

Route auth values.

View Source
const (
	FrameFullscreen = "fullscreen"
	FrameApp        = "app"
	FrameTV         = "tv"
)

Frames.

View Source
const (
	CallInstall   = "lifecycle.install"
	CallUpgrade   = "lifecycle.upgrade"
	CallEnable    = "lifecycle.enable"
	CallDisable   = "lifecycle.disable"
	CallUninstall = "lifecycle.uninstall"
)

Lifecycle calls, on the helper protocol.

View Source
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.

View Source
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.

View Source
const (
	SDUIFromAPI = 4
	SDUIFile    = "sdui.json"
)

SDUIFromAPI is the API from which a module must carry its SDUI, and SDUIFile its name.

View Source
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.

View Source
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.

View Source
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).

View Source
const (
	PageMain     = "main"     // with the app's sections
	PageSettings = "settings" // in Settings
)

Where a module's page is listed in the app.

View Source
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.

View Source
const (
	TaskRunning = "running"
	TaskDone    = "done"
	TaskFailed  = "failed"
)

A task's state. A process that ends has its running tasks ended for it.

View Source
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.

View Source
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.

View Source
const FirstServer = "0.6.0-alpha"

FirstServer is the first server this API is for, and what a module's minServer starts from.

View Source
const HelperFlag = "--wms-helper"

HelperFlag is what the server starts a helper with.

View Source
const IntegrationFile = "integration.json"

IntegrationFile is its name in a module's folder and at the root of every archive.

View Source
const IntegrationFormat = "wittymodule-integration"

IntegrationFormat is integration.json's format.

View Source
const IntegrationFromAPI = 5

IntegrationFromAPI is the module API from which a module that adds anything to a server must carry integration.json.

View Source
const ManifestFile = "module.json"

ManifestFile is the manifest's name in a plugin's folder and in a release.

View Source
const MaxIntegration = 256 << 10

MaxIntegration is the most a server reads of one.

View Source
const MaxStatusNote = 500

MaxStatusNote is the longest statusNote, in characters.

View Source
const NoticesFile = "THIRD-PARTY-NOTICES.txt"

NoticesFile holds the licenses of the libraries in a module's programs.

View Source
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

View Source
var ErrCatalogSignature = errors.New("the catalogue's signature doesn't check out")

ErrCatalogSignature is a catalogue that none of the keys signed.

View Source
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.

View Source
var ManifestJSON []byte

ManifestJSON is this module's manifest (docs/MODULES.md, "The manifest").

View Source
var SetupAnchors = []string{"modules", "libraries", "details", "people", "remote", "ready"}

SetupAnchors are the built-in steps a module's step may name.

View Source
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

func ArchiveName(id, ver, goos, goarch string) string

ArchiveName is the release archive for a platform.

func Compare

func Compare(a, b string) int

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 HashHex added in v0.3.0

func HashHex(sum []byte) string

HashHex is the form a catalogue writes a SHA-256 in.

func InRange added in v0.5.0

func InRange(v int, r string) bool

InRange reports whether version v (a host feature's number) is within a range such as ">=1 <2" or "5".

func Main

func Main(manifest []byte, h Handler)

Main runs a helper program from its manifest. Started by hand, it explains itself instead of waiting silently.

func ManifestName

func ManifestName(id, ver string) string

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

func Notify(method string, params any) error

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 ParseSize added in v0.5.0

func ParseSize(s string) (int64, error)

ParseSize reads "256KB", "4MB".

func Prerelease

func Prerelease(s string) bool

Prerelease reports whether s is a pre-release such as 0.4.0-alpha.

func ProgramFile added in v0.3.0

func ProgramFile(name, goos string) string

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

func ResolveCatalogURL(catalog, ref string) (string, error)

ResolveCatalogURL turns what a catalogue says into an address, given where the catalogue itself came from.

func Serve

func Serve(in io.Reader, out io.Writer, hello Hello, h Handler) error

Serve is a helper's loop: it says hello and answers calls until in closes.

func ServeStream added in v0.3.0

func ServeStream(in io.Reader, out io.Writer, hello Hello, h StreamHandler) error

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 SumsName

func SumsName(id, ver string) string

SumsName is the signed list of a release's hashes; its signature adds .sig.

func TopFolder

func TopFolder(id, ver, goos, goarch string) string

TopFolder is the one folder inside a release's archive.

func Valid

func Valid(s string) bool

Valid reports whether s is a version this package can compare.

func ValidCatalogURL added in v0.3.0

func ValidCatalogURL(s string) bool

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

func WebArchiveName(id, ver string) string

WebArchiveName is the archive of a web bundle.

func WebTopFolder added in v0.3.0

func WebTopFolder(id, ver string) string

WebTopFolder is the one folder inside a web bundle's archive, the same for every platform.

func WithdrawalsName added in v0.3.0

func WithdrawalsName(id string) string

WithdrawalsName is the list's file on that release; its signature adds .sig.

Types

type CallError

type CallError struct {
	Code    string // for the caller to act on; may be empty
	Message string
}

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.

func (*CallError) Error

func (e *CallError) Error() string

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

func ParseCatalog(b []byte) (*Catalog, error)

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

func VerifyCatalog(raw, sig []byte, keys []ed25519.PublicKey) (*Catalog, error)

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.

func (*Catalog) Validate added in v0.3.0

func (c *Catalog) Validate() error

Validate checks that a catalogue makes sense on its own.

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"`
	Navigation []string        `json:"navigation,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

type CatalogUIPage struct {
	ID    string `json:"id"`
	Title string `json:"title"`
}

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

type CatalogWithdrawn struct {
	Severity string `json:"severity"`
	Reason   string `json:"reason"`
}

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 NewConn

func NewConn(fromHelper io.Reader, toHelper io.Writer) *Conn

NewConn wraps a helper's stdout and stdin.

func (*Conn) Call

func (c *Conn) Call(method string, params, out any) ([]byte, error)

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.

func (*Conn) ReadHello

func (c *Conn) ReadHello() (*Hello, error)

ReadHello reads what a helper says first.

func (*Conn) Stream added in v0.3.0

func (c *Conn) Stream(method string, params, out any) (io.Reader, error)

Stream makes a call that a helper answers with a stream (ServeStream). It returns what comes after the answer. Nothing else can be asked on this Conn afterwards.

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

func (j *DiagJob) Engine(what string, fn func()) (ok bool)

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) Progress added in v0.3.0

func (j *DiagJob) Progress(fraction float64)

Progress says how far along it is.

func (*DiagJob) Rest added in v0.3.0

func (j *DiagJob) Rest(ctx context.Context, _ time.Duration) bool

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.

func (*DiagJob) SetLabel added in v0.3.0

func (j *DiagJob) SetLabel(label string)

SetLabel gives the disc's name.

func (*DiagJob) Step added in v0.3.0

func (j *DiagJob) Step(phase string, fraction float64)

Step says what it's doing now.

type DiagStep added in v0.3.0

type DiagStep struct {
	Phase    string  `json:"phase"`
	Fraction float64 `json:"fraction"`
}

DiagStep is what a check is doing, and how far along it is, from 0 to 1.

type Handler

type Handler func(method string, params json.RawMessage) (result any, blob []byte, err error)

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"`
	// 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"`
}

Summary is what a catalogue says of a version's integration.json, for the store to show.

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

func ParseManifest(b []byte) (*Manifest, error)

ParseManifest reads and checks a manifest.

func (*Manifest) Archive added in v0.3.0

func (m *Manifest) Archive(goos, goarch string) string

Archive is the archive holding this version for a platform.

func (*Manifest) Asks added in v0.3.0

func (m *Manifest) Asks(permission string) bool

Asks reports whether this version asks for a permission.

func (*Manifest) EntryFile

func (m *Manifest) EntryFile(goos string) string

EntryFile is the helper program's file name on a system.

func (*Manifest) HasWeb added in v0.3.0

func (m *Manifest) HasWeb() bool

HasWeb says whether a version has a part that runs in the browser.

func (*Manifest) NeedsIntegration added in v0.5.0

func (m *Manifest) NeedsIntegration() bool

NeedsIntegration reports whether a version must carry integration.json.

func (*Manifest) NeedsSDUI added in v0.4.0

func (m *Manifest) NeedsSDUI() bool

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

func (m *Manifest) PerPlatform() bool

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

func (m *Manifest) Problems() []Problem

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

func (m *Manifest) StatusOrStable() string

StatusOrStable is the version's status, with stable for one that says nothing.

func (*Manifest) Supports

func (m *Manifest) Supports(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.

func (*Manifest) Top added in v0.3.0

func (m *Manifest) Top(goos, goarch string) string

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

func (m *Manifest) Unfinished() bool

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

func (m *Manifest) Validate() error

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

func (m *Manifest) ValidateRelease() error

ValidateRelease adds what only a release must have: something a server can run.

func (*Manifest) WebFolder added in v0.3.0

func (m *Manifest) WebFolder() string

WebFolder is ProgramFile's folder for that part: where its files sit inside the version.

type NavFold struct {
	LibraryKind string `json:"libraryKind"`
	Into        string `json:"into"` // a navigation entry id from sdui.json
}

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

type Problem struct {
	Field   string
	Message string
}

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.

func (Problem) String added in v0.4.0

func (p Problem) String() string

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 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

type SetupLater struct {
	Where string `json:"where"`
	To    string `json:"to"`
}

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 Target

type Target struct{ GOOS, GOARCH string }

Target is a platform a helper is built for.

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"`
	NavFold  []NavFold     `json:"navFold,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.

type Withdrawn added in v0.3.0

type Withdrawn struct {
	Version  string `json:"version"`
	Severity string `json:"severity"`
	Reason   string `json:"reason"`
}

Withdrawn is one version taken back, and why.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL