cores

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: 29 Imported by: 0

Documentation

Overview

Package cores finds libretro cores on this machine and installs them on an administrator's request. A core is someone else's native code, so downloads are held to one host, one list of names and one file.

Index

Constants

View Source
const MaxInfoSize = 256 << 10

MaxInfoSize is more than any published info file.

View Source
const SourceCustom = "custom"

SourceCustom is Core.Source for a custom core.

Variables

View Source
var DefaultLimits = Limits{Library: 1 << 30, Package: 3 << 29, Unpack: 4 << 30, Entries: 20000}

DefaultLimits are above the largest cores people really use, which reach several hundred megabytes.

Functions

func AvoidTableID added in v0.3.3

func AvoidTableID(id string) string

AvoidTableID gives a name in our table a suffix.

func CanDownload

func CanDownload() bool

CanDownload says whether this platform has prebuilt cores to download.

func CheckFetchURL added in v0.3.3

func CheckFetchURL(raw string) (*url.URL, error)

CheckFetchURL refuses an address before anything connects. Which machine a name really leads to is checked by the client when it connects, because that's the only moment the answer means anything; this catches what never needs a lookup.

func CheckFileName added in v0.3.3

func CheckFileName(name string) error

CheckFileName refuses a name that tries to mean a path. Names are never used to build a path to write to, but one trying this isn't an honest mistake, so it doesn't get quietly cleaned up and accepted either.

func CleanExtensions added in v0.3.3

func CleanExtensions(in []string) []string

CleanExtensions keeps what could be a file extension, without its dot.

func CleanProbe added in v0.3.3

func CleanProbe(p ipc.Probe) ipc.Probe

CleanProbe cleans what a core reported about itself in its test-load.

func CleanText added in v0.3.3

func CleanText(s string, limit int) string

CleanText makes text from a core safe to store and show: valid, one line, no control or invisible characters, and a sensible length.

func DefaultExtra

func DefaultExtra() []string

DefaultExtra are the folders RetroArch and system packages keep cores in. Cores there were put there by someone else and are only ever read.

func DownloadURL

func DownloadURL(id string) (string, error)

DownloadURL is where a core comes from. It is built only from our own table and platform, never from a request.

func HashFile added in v0.3.3

func HashFile(p string) (string, error)

HashFile is a file's SHA-256.

func LibraryExt added in v0.3.3

func LibraryExt() string

LibraryExt is what a core file ends in on this server.

func Offered

func Offered(id string) bool

Offered says whether a core is on our download list. The list only holds cores whose licences allow it (wittyplay.Consoles).

func SuggestID added in v0.3.3

func SuggestID(fileName, reported string) string

SuggestID turns a file name into a core's name here. A name our own table uses gets a suffix: a custom build isn't the core the table vouches for, and must never be mistaken for it or change which core a console already uses.

func ValidCustomID added in v0.3.3

func ValidCustomID(id string) bool

ValidCustomID says whether a name can be a custom core's.

Types

type Binary added in v0.3.3

type Binary struct {
	Format  string `json:"format"`  // pe | elf | macho
	OS      string `json:"os"`      // windows | linux | darwin; elf means any Unix but those two
	Arch    string `json:"arch"`    // amd64 | arm64 | 386 | arm | riscv64 | ...
	Library bool   `json:"library"` // a shared library rather than a program
	Matches bool   `json:"matches"` // it can load on this server
}

Binary is what a file's first bytes say it is. These few fields are read by hand rather than with the standard library's full parsers: this file is hostile until proven otherwise, it is read inside the server, and nothing here needs more than a handful of fixed offsets.

func ReadBinary added in v0.3.3

func ReadBinary(path string) (Binary, error)

ReadBinary looks at a file's headers. It says plainly when a file isn't a program library at all, and answers only for the file itself: Matches says whether its format and processor are this server's.

func (Binary) Describe added in v0.3.3

func (b Binary) Describe() string

Describe names it for people: "Windows, x86-64".

func (Binary) Refusal added in v0.3.3

func (b Binary) Refusal() string

Refusal says why a file can't be used on this server, or "" when it can.

type Core

type Core struct {
	ID            string `json:"id"`
	Name          string `json:"name"`
	License       string `json:"license"` // "" when we don't know this core
	Path          string `json:"-"`
	Source        string `json:"source"` // installed | retroarch | system
	SHA256        string `json:"sha256,omitempty"`
	Installed     int64  `json:"installedAt,omitempty"`
	NonCommercial bool   `json:"nonCommercial,omitempty"`
	// For custom cores.
	Version       string   `json:"version,omitempty"`
	Consoles      []string `json:"consoles,omitempty"`
	LicenseSource string   `json:"licenseSource,omitempty"` // info | table | admin
	Assets        string   `json:"-"`
	WantsGPU      bool     `json:"-"` // a custom core that reported needing a graphics card
	// Unapproved is a file someone placed that our table doesn't know and nobody has
	// added: it stays listed so it can be, and nothing runs it until then.
	Unapproved bool `json:"unapproved,omitempty"`
}

Core is a core file on this machine.

type CoreFileState added in v0.3.3

type CoreFileState struct {
	State string `json:"state"`           // ok | changed | missing | link
	Found string `json:"found,omitempty"` // the hash it has now
}

CoreFileState is what a core's file looks like against what was approved.

type CustomStore added in v0.3.3

type CustomStore struct {
	Dir    string // <data>/gaming/custom-cores
	System string // the BIOS folder a package's system/ files go to
	Placed []string
	Limits Limits
	// Client fetches addresses. It must refuse private addresses when it connects,
	// because a name can resolve to anything. There's deliberately no default.
	Client *http.Client
}

CustomStore is the folder custom cores live in.

func (*CustomStore) AddExtras added in v0.3.3

func (st *CustomStore) AddExtras(r io.Reader, name, id, sum string) (added, kept []string, err error)

AddExtras adds an info file or a package's assets/ and system/ folders to a version already approved. The core file itself can't change this way.

func (*CustomStore) AssetsPath added in v0.3.3

func (st *CustomStore) AssetsPath(id, sum string) string

AssetsPath is a version's own folder of support files, or "" when it has none.

func (*CustomStore) ClearStaging added in v0.3.3

func (st *CustomStore) ClearStaging()

ClearStaging removes whatever was left waiting; a stage doesn't outlive a restart.

func (*CustomStore) Commit added in v0.3.3

func (st *CustomStore) Commit(s *Staged, id string) (added, kept []string, err error)

Commit makes a stage an approved version of a core. It re-reads the hash first: what gets approved has to be what was tested. It returns the system files it added to the BIOS folder, so removing the core can take back only those, and anything it left because the owner already has a file by that name.

func (*CustomStore) CorePath added in v0.3.3

func (st *CustomStore) CorePath(id, sum string) string

CorePath is the file of one approved version.

func (*CustomStore) Discard added in v0.3.3

func (st *CustomStore) Discard(s *Staged)

Discard removes a stage.

func (*CustomStore) ListPlaced added in v0.3.3

func (st *CustomStore) ListPlaced() []PlacedFile

ListPlaced lists candidate files. A request can only name a Key from this list, so no request can name a path: there's nothing to climb out of.

func (*CustomStore) ReadVersionInfo added in v0.3.3

func (st *CustomStore) ReadVersionInfo(id, sum string) *Info

ReadVersionInfo reads a version's info file, if it has one.

func (*CustomStore) RemoveCore added in v0.3.3

func (st *CustomStore) RemoveCore(id string, systemFiles []string) error

RemoveCore deletes everything of a core, and only the files it added to the BIOS folder. Saves live elsewhere and are never touched.

func (*CustomStore) RemoveVersion added in v0.3.3

func (st *CustomStore) RemoveVersion(id, sum string)

RemoveVersion deletes one kept version. A file in use on Windows simply stays until next time.

func (*CustomStore) StagePlaced added in v0.3.3

func (st *CustomStore) StagePlaced(key string) (*Staged, error)

StagePlaced copies a listed file in. It's a copy, so a link could only ever have shown us its contents, and what was tested is what runs. It's refused anyway: a link out of the folder isn't something anyone should need.

func (*CustomStore) StageReader added in v0.3.3

func (st *CustomStore) StageReader(r io.Reader, name string) (*Staged, error)

StageReader takes a core or a zip from an upload, up to the size limit. Nothing is held in memory: a low-end server with a large core still has its RAM.

func (*CustomStore) StageURL added in v0.3.3

func (st *CustomStore) StageURL(ctx context.Context, raw string) (*Staged, error)

StageURL downloads a core or zip. The client refuses private addresses when it connects, redirects stay on https and are re-checked, and the size is capped however much the far end says it will send.

func (*CustomStore) Verify added in v0.3.3

func (st *CustomStore) Verify(id, sum string) CoreFileState

Verify reads the whole file and compares it. It can't be a link: everything in this folder got here by being written by us.

func (*CustomStore) VersionFolder added in v0.3.3

func (st *CustomStore) VersionFolder(id, sum string) string

VersionFolder is where one approved version lives.

type Firmware added in v0.3.3

type Firmware struct {
	File     string `json:"file"`
	Desc     string `json:"desc,omitempty"`
	Required bool   `json:"required"`
	Present  bool   `json:"present"` // it's in this server's BIOS folder
}

Firmware is a BIOS file an info file names.

type Info added in v0.3.3

type Info struct {
	DisplayName string     `json:"displayName,omitempty"`
	CoreName    string     `json:"coreName,omitempty"`
	System      string     `json:"system,omitempty"`
	License     string     `json:"license,omitempty"`
	Version     string     `json:"version,omitempty"`
	Extensions  []string   `json:"extensions,omitempty"`
	Firmware    []Firmware `json:"firmware,omitempty"`
	Notes       string     `json:"notes,omitempty"`
	HWRender    bool       `json:"hwRender,omitempty"` // it says it wants a graphics card
}

Info is what a core's .info file says. These are the small text files libretro publishes beside its cores. An administrator supplied this one, and it says what its author wanted to say, so nothing in it is believed beyond being shown.

func ParseInfo added in v0.3.3

func ParseInfo(r io.Reader) Info

ParseInfo reads key = "value" lines. Anything else is skipped: these files have grown many fields over the years, and none of the rest matter here.

type Limits added in v0.3.3

type Limits struct {
	Library int64 // one core file
	Package int64 // one upload or download, zipped or not
	Unpack  int64 // everything a package unpacks to
	Entries int   // how many files a package may hold
}

Limits bound what adding a core can cost. They're fields so a test can make a "huge file" without writing a gigabyte.

type Manager

type Manager struct {
	Dir    string // installs go here; an administrator may also place files here
	System string // a core's support files go here, in the folder cores are told is theirs
	Client *http.Client
	Extra  []string // folders to read cores from; DefaultExtra if nil
	// Custom lists the approved custom cores, when they are switched on.
	Custom func() []Core
}

Manager looks in one folder it owns, plus folders other programs own.

func (*Manager) AllForConsole added in v0.3.3

func (m *Manager) AllForConsole(c *wittyplay.Console, preferred string) []Core

AllForConsole is every core here that can play a console, the one asked for first.

func (*Manager) Find

func (m *Manager) Find(id string) *Core

Find returns a core by name, or nil.

func (*Manager) ForConsole

func (m *Manager) ForConsole(c *wittyplay.Console, preferred string) *Core

ForConsole picks the core to play a console with: the one asked for if it's here, else the first in the console's list that is.

func (*Manager) Install

func (m *Manager) Install(ctx context.Context, id string) (*Core, error)

Install downloads one core: from one host, over HTTPS, with its size capped, taking exactly one file from the archive and writing it in one step.

func (*Manager) InstallProgress added in v0.4.1

func (m *Manager) InstallProgress(id string) (got, total int64, ok bool)

InstallProgress says how far an Install under way has got with the file it's fetching now: the bytes received, and the size the download server gave, 0 when it didn't give one. A core with support files fetches those after itself, and the count starts again for them. ok is false when the core isn't being installed.

func (*Manager) List

func (m *Manager) List() []Core

List returns the cores here. A core installed through us wins over the same core elsewhere.

func (*Manager) Playable added in v0.3.3

func (m *Manager) Playable(c *wittyplay.Console, preferred, systemDir string) (ok, blocked *Core)

Playable is ForConsole for a game about to start: a core that would refuse to run for want of a BIOS gives way to the next one that can. It also returns the core wanted, when nothing can run, so the message can say what's missing.

func (*Manager) Remove

func (m *Manager) Remove(id string) error

Remove deletes a core we installed. Cores elsewhere belong to whoever put them there.

type PlacedFile added in v0.3.3

type PlacedFile struct {
	Key    string `json:"key"`
	Name   string `json:"name"`
	Folder string `json:"folder"`
	Ours   bool   `json:"ours"` // our own cores folder; a copy is moved out of it once approved
	Size   int64  `json:"size"`
	Refuse string `json:"refuse,omitempty"` // why it can't be picked, such as being a link
}

PlacedFile is a file someone put where cores go.

type Staged added in v0.3.3

type Staged struct {
	Token       string
	Dir         string // the whole of this stage
	Library     string // the core file inside it
	OrigName    string
	SHA256      string
	DownloadSHA string // of the file as it arrived, for comparing with a published hash
	Size        int64
	Binary      Binary
	GPUHint     bool // the file mentions graphics APIs, so it might want a card
	Info        *Info
	HasInfo     bool
	Assets      int // files in its assets/ folder
	System      int // files in its system/ folder
	Ignored     []string
	Source      string // upload | url | placed
	SourceURL   string
	Placed      string // the file it came from, when picked from a folder we own
	Created     time.Time
}

Staged is a file waiting to be approved.

Jump to

Keyboard shortcuts

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