rpc

package
v0.7.2 Latest Latest
Warning

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

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

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

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

View Source
const DataEnv = "WITTYMODULE_DATA"

DataEnv is where the server says this module's own folder is (the "data" permission).

Variables

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

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

View Source
var Handlers = map[string]service.Handler{}/* 158 elements not displayed */

Handlers answer the server's calls, by name.

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

View Source
var Mgr = stream.NewManager(stream.Config{Log: Log.With("cat", "games")})

Mgr is this process's games.

Functions

func Busy

func Busy() bool

Busy says a game is being played, by a core or in a container.

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 ErrorCode

func ErrorCode(err error) string

ErrorCode names an error the server has its own copy of.

func NewLog added in v0.4.1

func NewLog(w io.Writer, level, topics string) *slog.Logger

NewLog makes a logger writing to w at the level named and with the topics listed on.

func SettingsChanged added in v0.7.0

func SettingsChanged(values map[string]any)

SettingsChanged hears the module's server settings after an administrator saved them.

func Start added in v0.7.0

func Start()

Start is what the service does as it starts, beside its routes (package api): containers a crash left behind are removed, in the background, only when Docker is on and reachable; nothing about Docker can stop the service starting.

func Stop

func Stop()

Stop saves and ends every game, as the server goes away.

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

func (b *DockerBackend) ConsoleOffers(ctx context.Context, systemDir string) map[string][]Offer

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

func (b *DockerBackend) Diagnostics(ctx context.Context) (docker.Status, []Check)

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

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.

func (*DockerBackend) Summary added in v0.4.1

func (b *DockerBackend) Summary(ctx context.Context) Summary

Summary answers at once: nothing is downloaded or pulled, and a Docker daemon is asked only whether it's there, briefly.

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.

func (*Refusal) Error added in v0.4.1

func (r *Refusal) Error() string

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.

Jump to

Keyboard shortcuts

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