Documentation
¶
Overview ¶
Package rpc answers a server's calls to WittyPlay's service: gen.go is generated, by kit/facade in WittyModule, and this is what can't be.
Index ¶
- Constants
- Variables
- func Busy() bool
- func CommandLine(e *emulators.Emulator, art *emulators.Artifact, entry string, ...) []string
- func ConsoleItems(req sdui.ItemsRequest) (sdui.ItemsAnswer, error)
- func ConsoleStanding(c *wittyplay.Console, mgr *cores.Manager, offers []Offer) (ready bool, how string)
- func ErrorCode(err error) string
- func NewLog(w io.Writer, level, topics string) *slog.Logger
- func SettingsChanged(values map[string]any)
- func Start()
- func Stop()
- type BiosStatus
- type CatalogEntry
- type Check
- type DockerBackend
- func (b *DockerBackend) CancelInstall(id string) bool
- func (b *DockerBackend) Catalog() ([]CatalogEntry, error)
- func (b *DockerBackend) ConsoleOffers(ctx context.Context, systemDir string) map[string][]Offer
- func (b *DockerBackend) Count() int
- func (b *DockerBackend) Diagnostics(ctx context.Context) (docker.Status, []Check)
- func (b *DockerBackend) Doctor(ctx context.Context) []Finding
- func (b *DockerBackend) Install(id string) (InstallJob, error)
- func (b *DockerBackend) Job(id string) (InstallJob, bool)
- func (b *DockerBackend) Launch(ctx context.Context, o LaunchOptions) (*DockerSession, error)
- func (b *DockerBackend) Offers(ctx context.Context, console, systemDir string) []Offer
- func (b *DockerBackend) Routes(mux *http.ServeMux)
- func (b *DockerBackend) Session(id string) *DockerSession
- func (b *DockerBackend) Settings() docker.Settings
- func (b *DockerBackend) Startup(ctx context.Context)
- func (b *DockerBackend) Stop(ctx context.Context, id string) error
- func (b *DockerBackend) StopAll()
- func (b *DockerBackend) Summary(ctx context.Context) Summary
- type DockerSession
- type Finding
- type InstallJob
- type InstalledJSON
- type LaunchOptions
- type LaunchResult
- type ManualSummary
- type ManualView
- type Offer
- type Refusal
- type Summary
- type SummaryInstalled
Constants ¶
const ( HeaderUser = "X-Witty-User" // the signed-in account's id HeaderAdmin = "X-Witty-Admin" // "1" for an administrator // HeaderSystemDir is the server's BIOS folder, so a page can be told which firmware is // there. The server sets it on everything it passes through, over whatever a browser sent. HeaderSystemDir = "X-Wittyplay-System-Dir" )
Headers the server sets on what it passes through.
const DataEnv = "WITTYMODULE_DATA"
DataEnv is where the server says this module's own folder is (the "data" permission).
Variables ¶
var ConnectDocker func() (docker.Runtime, error)
ConnectDocker reaches the Docker daemon. The module's command sets it to the engine; nothing else imports the Docker SDK. Left nil, Docker is never available.
var Docker = NewDockerBackend(os.Getenv(DataEnv), func() (docker.Runtime, error) { if ConnectDocker == nil { return nil, docker.ErrUnavailable } return ConnectDocker() }, Mgr, Log.With("cat", "emulators"))
Docker is this process's backend for standalone emulators.
var Handlers = map[string]service.Handler{}/* 158 elements not displayed */
Handlers answer the server's calls, by name.
var Log = NewLog(os.Stderr, os.Getenv("WITTYMODULE_LOG"), os.Getenv("WITTYMODULE_LOG_TOPICS"))
Log is this process's one logger. It writes slog's text lines to stderr, which the server reads as its own records: level, msg, cat, session and topic become fields there. What's written follows WITTYMODULE_LOG (debug, info, warn, error or off) and WITTYMODULE_LOG_TOPICS (the topics in module.json's capabilities.logTopics that are on). Libretro games log with "cat" "games", standalone emulators with "cat" "emulators".
var Mgr = stream.NewManager(stream.Config{Log: Log.With("cat", "games")})
Mgr is this process's games.
Functions ¶
func CommandLine ¶ added in v0.4.1
func CommandLine(e *emulators.Emulator, art *emulators.Artifact, entry string, settingsArgs []string, romName string) []string
CommandLine is the emulator's command as a container would see it (the program under /opt/emulator, the game under /game, settings under /saves): the platform's own arguments from the list if it has them, else the emulator's. {game}, {config}, {bios} and {settings} are filled in; a command line without {game} ends with it, one without {settings} has the settings' own arguments just before the game. The host runtime turns these paths into this machine's.
func ConsoleItems ¶ added in v0.7.0
func ConsoleItems(req sdui.ItemsRequest) (sdui.ItemsAnswer, error)
ConsoleItems answers wittyplay.consoles: every console, ready ones first, as tiles that open Settings' page of what this server plays. Package api answers WittyPlay's other sources, and asks this for the rest (api.SDUIItems).
func ConsoleStanding ¶ added in v0.4.1
func ConsoleStanding(c *wittyplay.Console, mgr *cores.Manager, offers []Offer) (ready bool, how string)
ConsoleStanding says whether a console plays here and how, in a few words for a card.
func NewLog ¶ added in v0.4.1
NewLog makes a logger writing to w at the level named and with the topics listed on.
func SettingsChanged ¶ added in v0.7.0
SettingsChanged hears the module's server settings after an administrator saved them.
Types ¶
type BiosStatus ¶ added in v0.4.1
type BiosStatus struct {
Name string `json:"name"`
Present bool `json:"present"`
Note string `json:"note,omitempty"`
}
BiosStatus is one firmware file an emulator looks for, and whether it's in the BIOS folder.
type CatalogEntry ¶ added in v0.4.1
type CatalogEntry struct {
ID string `json:"id"`
Name string `json:"name"`
Systems []string `json:"systems"`
License string `json:"license"`
LicenseURL string `json:"licenseUrl,omitempty"`
Upstream string `json:"upstream"`
Version string `json:"version"`
NonCommercial bool `json:"nonCommercial,omitempty"`
Experimental bool `json:"experimental,omitempty"`
NeedsBios bool `json:"needsBios,omitempty"`
Stream string `json:"stream"`
Requires emulators.Requires `json:"requires,omitzero"`
DownloadBytes int64 `json:"downloadBytes,omitempty"`
Installed *InstalledJSON `json:"installed,omitempty"`
UpdateAvailable bool `json:"updateAvailable"`
Installable bool `json:"installable"`
Why string `json:"why,omitempty"` // why it can't be installed
Runnable bool `json:"runnable"`
WhyNot string `json:"whyNot,omitempty"` // why it can't run here yet
Job *InstallJob `json:"job,omitempty"`
Bios []BiosStatus `json:"bios,omitempty"`
// Manual: never downloaded; the administrator installs it and adds it.
Manual *ManualSummary `json:"manual,omitempty"`
}
CatalogEntry is one emulator for the admin page: the list's entry and how it stands here.
type Check ¶ added in v0.4.1
type Check struct {
ID string `json:"id"`
Label string `json:"label"`
State string `json:"state"` // ok | warn | fail | off
Detail string `json:"detail"`
}
Check is one line of the diagnostics: something looked at, and how it stands.
type DockerBackend ¶ added in v0.4.1
type DockerBackend struct {
// Local is the sandbox without Docker. LocalMissing says what this machine lacks for it.
// Both are set by NewDockerBackend; a test puts a fake in.
Local docker.Runtime
LocalMissing func() []string
// Host runs an emulator on this machine's own desktop (a Mac, a Windows PC). HostMissing
// says what it lacks.
Host docker.Runtime
HostMissing func() []string
// contains filtered or unexported fields
}
DockerBackend holds the standalone-emulator backend's state for one module process. The name is from when Docker was its only sandbox; it runs the local one too.
func NewDockerBackend ¶ added in v0.4.1
func NewDockerBackend(dataDir string, connect func() (docker.Runtime, error), mgr *stream.Manager, log *slog.Logger) *DockerBackend
NewDockerBackend makes a backend keeping its files under dataDir/docker and dataDir/emulators. With dataDir empty, settings live only in memory, and nothing can be installed.
func (*DockerBackend) CancelInstall ¶ added in v0.4.1
func (b *DockerBackend) CancelInstall(id string) bool
CancelInstall stops an install that's running. What it had downloaded stays, and the next install carries on from there.
func (*DockerBackend) Catalog ¶ added in v0.4.1
func (b *DockerBackend) Catalog() ([]CatalogEntry, error)
Catalog is the list as it stands on this machine.
func (*DockerBackend) ConsoleOffers ¶ added in v0.4.1
ConsoleOffers is Offers for every console an emulator in the list plays, those with none left out. With the backend off it's empty.
func (*DockerBackend) Count ¶ added in v0.4.1
func (b *DockerBackend) Count() int
Count is how many emulators this module is running.
func (*DockerBackend) Diagnostics ¶ added in v0.4.1
Diagnostics looks over everything a game in a standalone emulator depends on, and says in plain words what it found. It changes nothing.
func (*DockerBackend) Doctor ¶ added in v0.7.0
func (b *DockerBackend) Doctor(ctx context.Context) []Finding
Doctor checks that standalone emulators can run the way the owner chose: a Mac's permissions for the native host, and the backend itself. Nothing is downloaded.
func (*DockerBackend) Install ¶ added in v0.4.1
func (b *DockerBackend) Install(id string) (InstallJob, error)
Install starts installing an emulator, and returns at once. The work carries on in the background, whoever asked having gone or not, and Job says how it's going.
func (*DockerBackend) Job ¶ added in v0.4.1
func (b *DockerBackend) Job(id string) (InstallJob, bool)
Job says how an install is going.
func (*DockerBackend) Launch ¶ added in v0.4.1
func (b *DockerBackend) Launch(ctx context.Context, o LaunchOptions) (*DockerSession, error)
Launch starts a game in a standalone emulator, or says in a Refusal why it can't.
func (*DockerBackend) Offers ¶ added in v0.4.1
func (b *DockerBackend) Offers(ctx context.Context, console, systemDir string) []Offer
Offers lists the emulators that are set up to play a console's games here: installed, or with an image of their own pinned. With the backend off it's empty, and a page shows nothing.
func (*DockerBackend) Routes ¶ added in v0.4.1
func (b *DockerBackend) Routes(mux *http.ServeMux)
Routes adds the backend's routes.
func (*DockerBackend) Session ¶ added in v0.4.1
func (b *DockerBackend) Session(id string) *DockerSession
Session finds a game in a standalone emulator.
func (*DockerBackend) Settings ¶ added in v0.4.1
func (b *DockerBackend) Settings() docker.Settings
Settings are the current settings.
func (*DockerBackend) Startup ¶ added in v0.4.1
func (b *DockerBackend) Startup(ctx context.Context)
Startup removes containers a crash left behind, when the backend is on and its runtime is reachable. It never fails: with it off or missing it does nothing, and says why in the log.
func (*DockerBackend) Stop ¶ added in v0.4.1
func (b *DockerBackend) Stop(ctx context.Context, id string) error
Stop ends a game in a standalone emulator.
func (*DockerBackend) StopAll ¶ added in v0.4.1
func (b *DockerBackend) StopAll()
StopAll ends every emulator, as the module goes away.
type DockerSession ¶ added in v0.4.1
type DockerSession struct {
ID string
UserID int64
ItemID int64
Title string
Emulator string
Name string // the emulator's name
Backend docker.Backend
KasmURL string // for docker+kasmvnc: the proxy's address, relative to the module's routes
Started time.Time
Width int
Height int
FPS int
Players int
Notices []string
// contains filtered or unexported fields
}
DockerSession is a game in a standalone emulator.
func (*DockerSession) Done ¶ added in v0.4.1
func (s *DockerSession) Done() <-chan struct{}
Done is closed when its emulator has gone.
func (*DockerSession) MarshalJSON ¶ added in v0.4.1
func (s *DockerSession) MarshalJSON() ([]byte, error)
MarshalJSON is what a server gets back from a start: the id, as for a game, and how to reach it.
type Finding ¶ added in v0.7.0
type Finding struct {
Check string `json:"check"`
Key string `json:"key"`
Severity string `json:"severity"` // info | warn | problem
Title string `json:"title"`
What string `json:"what"`
Steps []string `json:"steps,omitempty"`
}
Finding is one thing WittyPlay's own checks found, for the server's Repair page. The server asks with the service call doctor.Check; module.json lists the checks under capabilities.doctor.
type InstallJob ¶ added in v0.4.1
type InstallJob struct {
ID string `json:"id"`
State string `json:"state"` // running | done | failed | cancelled
Phase string `json:"phase"`
Got int64 `json:"got"`
Total int64 `json:"total"` // -1: not known
Resumed int64 `json:"resumed,omitempty"`
Error string `json:"error,omitempty"`
Installed *emulators.Installed `json:"installed,omitempty"`
Started time.Time `json:"started"`
// contains filtered or unexported fields
}
InstallJob is an install under way or finished.
type InstalledJSON ¶ added in v0.4.1
type InstalledJSON struct {
ID string `json:"id"`
Version string `json:"version"`
SHA256 string `json:"sha256"`
Source string `json:"source"`
InstalledAt int64 `json:"installedAt"`
}
InstalledJSON is an installed emulator without where it is on disk, which no page needs.
type LaunchOptions ¶ added in v0.4.1
type LaunchOptions struct {
UserID, ItemID int64
Title string
Console string
ROM string
SystemDir string
Emulator string
}
LaunchOptions start a game in a standalone emulator. Only the server sends them: the paths are ones it has checked this person may play.
type LaunchResult ¶ added in v0.4.1
type LaunchResult struct {
Session *DockerSession `json:"session,omitempty"`
Refusal *Refusal `json:"refusal,omitempty"`
}
LaunchResult is the answer to docker.Launch: a session, or why not.
type ManualSummary ¶ added in v0.4.1
type ManualSummary struct {
Download string `json:"download"`
Notes string `json:"notes,omitempty"`
}
ManualSummary is what the list says about an emulator added by hand.
type ManualView ¶ added in v0.4.1
type ManualView struct {
Download string `json:"download"`
Notes string `json:"notes,omitempty"`
Programs []string `json:"programs"`
DropFolder string `json:"dropFolder,omitempty"`
File string `json:"file,omitempty"` // manual.json, for setting it up without the page
System string `json:"system"` // the system it will run on: linux in a container
Detected *emulators.Identified `json:"detected,omitempty"`
Installed *emulators.Installed `json:"installed,omitempty"`
}
ManualView is what the page shows about adding one.
type Offer ¶ added in v0.4.1
type Offer struct {
ID string `json:"id"`
Name string `json:"name"`
Version string `json:"version"`
Stream string `json:"stream"`
Experimental bool `json:"experimental,omitempty"`
NeedsBios bool `json:"needsBios,omitempty"`
Ready bool `json:"ready"`
Why string `json:"why,omitempty"`
}
Offer is an emulator that could play a game, for the game's page.
type Refusal ¶ added in v0.4.1
type Refusal struct {
Code string `json:"code"`
Text string `json:"error"`
// Busy: there's no room right now, and there may be later.
Busy bool `json:"busy,omitempty"`
}
Refusal is a start that can't happen, said in a sentence for whoever asked. It isn't a fault.
type Summary ¶ added in v0.4.1
type Summary struct {
Backend string `json:"backend"` // docker | local | host | off
Available bool `json:"available"`
Error string `json:"error,omitempty"`
Missing []string `json:"missing"` // what the native host lacks, in words
Permissions []host.Permission `json:"permissions"` // a Mac's, for the native host only
Installed []SummaryInstalled `json:"installed"`
Sessions int `json:"sessions"`
}
Summary is how standalone emulators stand, for the server's diagnostics and log pages. It carries no secrets, no file contents, no paths and no addresses.
type SummaryInstalled ¶ added in v0.4.1
type SummaryInstalled struct {
ID string `json:"id"`
Version string `json:"version"`
Source string `json:"source"` // catalogue | manual | own
}
SummaryInstalled is one emulator that can run.