wittymodule

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: Apache-2.0 Imports: 10 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. Go, no dependencies.

go run github.com/wittywilla/wittymodule/cmd/wittymodule check .
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

A helper is a small program:

func main() {
	wittymodule.Main(manifestJSON, func(method string, params json.RawMessage) (any, []byte, error) {
		// answer one call
	})
}

The design, including what each version range means, is in WittyMediaServer's docs/MODULES.md.

WittyModule is developed by WittyWilla. Apache-2.0.

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 (
	API    = 1
	MinAPI = 1
)

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.

View Source
const (
	DeliveryHelper  = "helper"  // a program for each platform, run as a separate process
	DeliveryWeb     = "web"     // a bundle the browser loads
	DeliveryBuiltin = "builtin" // not converted yet: it updates with the server
)

How a release of a plugin reaches the server.

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

Variables

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

func Prerelease(s string) bool

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

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

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 Conn

type Conn struct {
	// 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) ReadHello

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

ReadHello reads what a helper says first.

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
	Delivery  string `json:"delivery"`
	Entry     string `json:"entry,omitempty"` // the helper program, without .exe
	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"`
}

Manifest describes one version of a plugin.

func ParseManifest

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

ParseManifest reads and checks a manifest.

func (*Manifest) EntryFile

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

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

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

func (m *Manifest) Validate() error

Validate checks that a manifest makes sense on its own.

type Target

type Target struct{ GOOS, GOARCH string }

Target is a platform a helper is built for.

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.

Jump to

Keyboard shortcuts

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