wittymodule

package module
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: Apache-2.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 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 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
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 design, 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

Apache-2.0: see LICENSE and NOTICE. If you redistribute it or build on it, 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.3.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 Apache-2.0: 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 (
	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 (
	API    = 3
	MinAPI = 3
)

The module API: the contract between the server and its plugins. A plugin names the version it was built for, and a server takes MinAPI to API. Adding to the contract raises API only; breaking it raises MinAPI too, which disables older plugins, so that is done rarely.

API 2 adds web bundles, programs, attached helpers and streams to API 1. Nothing in API 1 changed, so a version built for it still runs. API 3 adds notifications from a helper and the pages a module adds to the app, and is the first API where nothing of a module is compiled into the server, so it is also the oldest one a server takes: a module has to be built for WittyMediaServer 0.6.0-alpha or newer.

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 (
	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 ManifestFile = "module.json"

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

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

type CatalogVersion struct {
	Version     string   `json:"version"`
	Delivery    string   `json:"delivery"`
	API         int      `json:"api"`
	MinServer   string   `json:"minServer"`
	MaxServer   string   `json:"maxServer"`
	License     string   `json:"license"`
	Permissions []string `json:"permissions,omitempty"`

	Released   string `json:"released"`             // YYYY-MM-DD
	Prerelease bool   `json:"prerelease,omitempty"` // also true of any version with a pre-release label
	Changelog  string `json:"changelog,omitempty"`  // plain text; empty when there's nothing to report

	// The release's signed files, and an archive for each platform, keyed by GOOS-GOARCH
	// ("linux-arm" is the armv7 build), or PlatformAll for a web bundle.
	Sums      string                 `json:"sums"`
	Sig       string                 `json:"sig"`
	Manifest  string                 `json:"manifest"`
	Platforms map[string]CatalogFile `json:"platforms"`

	Withdrawn *CatalogWithdrawn `json:"withdrawn,omitempty"`
}

CatalogVersion is one release of a module. Everything down to Permissions has to match the release's own signed manifest.

func (*CatalogVersion) MatchesManifest added in v0.3.0

func (v *CatalogVersion) MatchesManifest(id string, m *Manifest) error

MatchesManifest compares what the catalogue said with what the release itself signed. Any difference refuses the install, so a catalogue can't describe a version as asking for less than it does, or as fitting a server it doesn't.

func (*CatalogVersion) Platform added in v0.3.0

func (v *CatalogVersion) Platform(goos, goarch string) *CatalogFile

Platform is a version's archive for a system, or nil if it has none.

func (*CatalogVersion) Supports added in v0.3.0

func (v *CatalogVersion) Supports(name, server string, minAPI, maxAPI int) error

Supports says, in words an owner can read, why this version can't run on a server of the given version and module API range; nil when it can. It answers as the manifest would.

type CatalogWithdrawn added in v0.3.0

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

type Manifest struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Version  string `json:"version"`
	Repo     string `json:"repo"` // owner/name on GitHub, where its releases are
	License  string `json:"license,omitempty"`
	Delivery string `json:"delivery"`
	// Entry is the program, without .exe, or a web bundle's script.
	Entry string `json:"entry,omitempty"`
	Style string `json:"style,omitempty"` // a web bundle's stylesheet, if it has one
	// Programs are more programs that come with a helper, without .exe, built from cmd/<name>.
	Programs []string `json:"programs,omitempty"`
	// WebEntry and WebStyle are the script and stylesheet of a helper that also has a part in
	// the browser. Those files sit in web/ inside each platform's archive.
	WebEntry  string `json:"webEntry,omitempty"`
	WebStyle  string `json:"webStyle,omitempty"`
	API       int    `json:"api"`
	MinServer string `json:"minServer"`
	MaxServer string `json:"maxServer"`
	// Capabilities are facts the server needs without starting the helper, such
	// as "rawExtensions". Signed along with everything else.
	Capabilities map[string][]string `json:"capabilities,omitempty"`
	Permissions  []string            `json:"permissions,omitempty"`

	// DataFormat numbers the shape of the data this version keeps, and DataFrom is
	// the oldest it can still read. Going back to a version that can't read what is
	// there is refused, with the reason. Zero means it keeps none of its own.
	DataFormat int `json:"dataFormat,omitempty"`
	DataFrom   int `json:"dataFrom,omitempty"`

	// For the people choosing versions: what it does, which group it belongs in,
	// what it needs in order to work, which parts of it a release of its own
	// really changes, and which stay with the server.
	Group   string   `json:"group,omitempty"`
	Summary string   `json:"summary,omitempty"`
	Needs   []string `json:"needs,omitempty"`
	Updates string   `json:"updates,omitempty"`
	Stays   string   `json:"stays,omitempty"`

	// Libraries are the kinds of library that need this plugin (any one plugin listing
	// a kind is enough). Requires names plugins it is built on. Core is one that other
	// plugins can't do without, so it can't be taken off a server.
	Libraries []string `json:"libraries,omitempty"`
	Requires  []string `json:"requires,omitempty"`
	Core      bool     `json:"core,omitempty"`

	// Pages are the pages it adds to the app, which its web bundle draws.
	Pages []Page `json:"pages,omitempty"`
}

Manifest describes one version of a plugin.

func ParseManifest

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

func (m *Manifest) Validate() error

Validate checks that a manifest makes sense on its own.

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

type Page struct {
	ID    string `json:"id"`
	Title string `json:"title"`
	Where string `json:"where"`
	Icon  string `json:"icon,omitempty"` // a name from the app's own set of icons
	Admin bool   `json:"admin,omitempty"`
}

Page is a page a module adds to the app, at /m/<module>/<id>. Whether someone may see it is the server's to check, and Admin only asks for that check: it never widens what the bundle can do, since a bundle runs with the access of whoever is signed in.

type Publisher added in v0.3.0

type Publisher struct {
	Name string `json:"name"`
	URL  string `json:"url,omitempty"`
	Key  string `json:"key,omitempty"`
}

Publisher says who a module comes from. Key is the base64 Ed25519 public key its releases are signed with, when that isn't the catalogue's own key. A server believes it only from a store an admin added, and never for a stock module.

type StreamHandler added in v0.3.0

type StreamHandler func(method string, params json.RawMessage) (result any, write func(io.Writer) error, err error)

StreamHandler answers one call for a stream with the answer to send, and what to write after it. The stream ends when write returns or the server stops reading.

type 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 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.
kit
facade command
Command facade writes both ends of a service module's calls, so a server can use a module's packages by name with none of its code compiled in.
Command facade writes both ends of a service module's calls, so a server can use a module's packages by name with none of its code compiled in.
Package service is how a module that stays running reaches a server: a process of its own that listens on this machine only, with a secret for each start, where calls can overlap and a browser's connection can be passed straight through.
Package service is how a module that stays running reaches a server: a process of its own that listens on this machine only, with a secret for each start, where calls can overlap and a browser's connection can be passed straight through.

Jump to

Keyboard shortcuts

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