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 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 Routes(mux *http.ServeMux)
- 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) 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 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{}/* 159 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.
var UI = sdui.Answers{Items: consoleItems, SettingsChanged: settingsChanged}
UI is what cmd/wittyplay-module hands the service for the server's SDUI calls.
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 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 Routes ¶
Routes are what isn't a call: a browser's connection to a game, passed straight through, and the Docker backend's routes (docker.go). Containers a crash left behind are removed here, in the background, only when Docker is on and reachable; nothing about Docker can stop the service starting.
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) 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 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.