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
- Variables
- func AvoidTableID(id string) string
- func CanDownload() bool
- func CheckFetchURL(raw string) (*url.URL, error)
- func CheckFileName(name string) error
- func CleanExtensions(in []string) []string
- func CleanProbe(p ipc.Probe) ipc.Probe
- func CleanText(s string, limit int) string
- func DefaultExtra() []string
- func DownloadURL(id string) (string, error)
- func HashFile(p string) (string, error)
- func LibraryExt() string
- func Offered(id string) bool
- func SuggestID(fileName, reported string) string
- func ValidCustomID(id string) bool
- type Binary
- type Core
- type CoreFileState
- type CustomStore
- func (st *CustomStore) AddExtras(r io.Reader, name, id, sum string) (added, kept []string, err error)
- func (st *CustomStore) AssetsPath(id, sum string) string
- func (st *CustomStore) ClearStaging()
- func (st *CustomStore) Commit(s *Staged, id string) (added, kept []string, err error)
- func (st *CustomStore) CorePath(id, sum string) string
- func (st *CustomStore) Discard(s *Staged)
- func (st *CustomStore) ListPlaced() []PlacedFile
- func (st *CustomStore) ReadVersionInfo(id, sum string) *Info
- func (st *CustomStore) RemoveCore(id string, systemFiles []string) error
- func (st *CustomStore) RemoveVersion(id, sum string)
- func (st *CustomStore) StagePlaced(key string) (*Staged, error)
- func (st *CustomStore) StageReader(r io.Reader, name string) (*Staged, error)
- func (st *CustomStore) StageURL(ctx context.Context, raw string) (*Staged, error)
- func (st *CustomStore) Verify(id, sum string) CoreFileState
- func (st *CustomStore) VersionFolder(id, sum string) string
- type Firmware
- type Info
- type Limits
- type Manager
- func (m *Manager) AllForConsole(c *wittyplay.Console, preferred string) []Core
- func (m *Manager) Find(id string) *Core
- func (m *Manager) ForConsole(c *wittyplay.Console, preferred string) *Core
- func (m *Manager) Install(ctx context.Context, id string) (*Core, error)
- func (m *Manager) InstallProgress(id string) (got, total int64, ok bool)
- func (m *Manager) List() []Core
- func (m *Manager) Playable(c *wittyplay.Console, preferred, systemDir string) (ok, blocked *Core)
- func (m *Manager) Remove(id string) error
- type PlacedFile
- type Staged
Constants ¶
const MaxInfoSize = 256 << 10
MaxInfoSize is more than any published info file.
const SourceCustom = "custom"
SourceCustom is Core.Source for a custom core.
Variables ¶
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
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
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
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
CleanExtensions keeps what could be a file extension, without its dot.
func CleanProbe ¶ added in v0.3.3
CleanProbe cleans what a core reported about itself in its test-load.
func CleanText ¶ added in v0.3.3
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 ¶
DownloadURL is where a core comes from. It is built only from our own table and platform, never from a request.
func LibraryExt ¶ added in v0.3.3
func LibraryExt() string
LibraryExt is what a core file ends in on this server.
func Offered ¶
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
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
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
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.
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
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
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.
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
AllForConsole is every core here that can play a console, the one asked for first.
func (*Manager) ForConsole ¶
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 ¶
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
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 ¶
List returns the cores here. A core installed through us wins over the same core elsewhere.
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.