Documentation
¶
Overview ¶
Package gamearchive reads the archives game collections come in, and unpacks them to play. See docs/GAMING.md.
Archives are treated as hostile. Everything that decodes one runs in a short-lived child process (worker.go), because the decoders can be made to panic or to ask for enormous amounts of memory by a crafted header, and neither of those may take the server down. Nothing here ever writes beside the archive.
The region order (moved with this package from the server's gameregion) holds the owner's order of regions: which version of a game to prefer when there's more than one. USA first isn't right for everyone.
zipCheck (moved with this package from the server's zipsafe) checks a zip before anything allocates for it. Reading a zip's directory takes memory for each entry and its name, and looking a name up in it takes memory for every folder of every name, so a file can ask for far more memory than it takes on disk.
Index ¶
- Constants
- Variables
- func BaseName(name string) string
- func CodeOf(err error) string
- func HoldsGame(exts []string, c *wittyplay.Console) bool
- func IsArchive(name string) bool
- func IsLaterVolume(name string) bool
- func RankRegion(tags string) int
- func Score(name, base string) int
- func SetRegionOrder(setting string)
- func Transient(err error) bool
- func ValidRegionOrder(setting string) bool
- type Cache
- func (c *Cache) Acquire(ctx context.Context, p string, console *wittyplay.Console) (rom string, release func(), err error)
- func (c *Cache) AcquireEntry(ctx context.Context, p string, console *wittyplay.Console, entry string) (rom string, release func(), err error)
- func (c *Cache) Clear()
- func (c *Cache) Close()
- func (c *Cache) Prepare(p string, console *wittyplay.Console) Status
- func (c *Cache) PrepareEntry(p string, console *wittyplay.Console, entry string) Status
- func (c *Cache) Used() int64
- type Entry
- type Error
- type Lister
- type Listing
- type Plan
- type Status
- type Want
- type Written
Constants ¶
const ( // MaxEntries is far above any game: a disc with every track is under a hundred files. MaxEntries = 10000 // MaxUnpacked is above several dual-layer discs; the cache's own limit is usually lower. MaxUnpacked = int64(32) << 30 // MaxRatio applies above ratioFloor. Blank space in a disc image compresses // well, but not this well. A small file may be mostly padding. MaxRatio = 2000 )
const ( USA = "usa" Europe = "europe" Australia = "australia" Japan = "japan" Asia = "asia" Brazil = "brazil" )
The regions someone can put in order, and what's the default order. Anything else comes after them all.
const PeekSize = 2 << 20
PeekSize is how much of a file a scan looks at. A disc's SYSTEM.CNF is within this nearly always, and nothing else needs more than the first few kilobytes.
const ScanBudget = int64(64) << 20
ScanBudget is how much of a compressed tar a scan reads through.
Variables ¶
var ( ErrEncrypted = &Error{"encrypted", "This archive is protected by a password, and this server doesn't open those. Unpack it yourself and put the game in the folder."} ErrUnsafe = &Error{"unsafe", "This archive tries to put files outside its own folder, so it was refused."} ErrTooBig = &Error{"toobig", "This archive unpacks to far more than a game should, so it was refused."} ErrTooMany = &Error{"toomany", "This archive holds too many files to be a game, so it was refused."} ErrDamaged = &Error{"damaged", "This archive is damaged or isn't the kind of file its name says."} ErrMethod = &Error{"method", "This archive uses a kind of compression this server can't read. Unpack it yourself and put the game in the folder."} ErrNoSpace = &Error{"nospace", "There isn't enough free disk space to unpack this game."} )
var ErrNoGame = errors.New("this archive holds no game for this console")
ErrNoGame: nothing in the archive is a game for this console.
Functions ¶
func BaseName ¶
BaseName is an archive's name without what makes it an archive: "Game (USA).tar.gz", "Game (USA).part1.rar" and "Game (USA).7z.001" are all "Game (USA)". Region and dump tags stay.
func IsArchive ¶
IsArchive says whether a file's name is one of the kinds of archive a game library can read.
func IsLaterVolume ¶
IsLaterVolume: the second and later parts of a split RAR. They are read through the first part, and aren't games by themselves.
func RankRegion ¶
RankRegion is rankRegion for whoever else orders versions of a game by region: which of a game's files leads it in a games library (package gamescan).
func Score ¶
Score says how good a choice a file in an archive is, against the archive's own name without its extension, in lower case.
func SetRegionOrder ¶
func SetRegionOrder(setting string)
SetRegionOrder makes this order the one in use.
func Transient ¶
Transient says an error isn't a lasting fact about the archive, and is worth trying again at the next scan.
func ValidRegionOrder ¶
ValidRegionOrder says a setting names only known regions, each once.
Types ¶
type Cache ¶
Cache unpacks games on demand. Limit is its size in bytes, asked for each time so that a setting takes effect at once.
func (*Cache) Acquire ¶
func (c *Cache) Acquire(ctx context.Context, p string, console *wittyplay.Console) (rom string, release func(), err error)
Acquire waits until the game is unpacked and gives the file a core should open. Until release is called, the game can't be evicted. Giving up on ctx doesn't stop the unpack, since someone else may be waiting for it, or may come back.
func (*Cache) AcquireEntry ¶
func (c *Cache) AcquireEntry(ctx context.Context, p string, console *wittyplay.Console, entry string) (rom string, release func(), err error)
AcquireEntry is Acquire for one chosen file of the archive.
func (*Cache) Clear ¶
func (c *Cache) Clear()
Clear removes every unpacked game that isn't being played, to give the disk space back. It's only a cache: they unpack again when next played.
func (*Cache) Close ¶
func (c *Cache) Close()
Close stops what's unpacking. What's finished stays for next time.
func (*Cache) Prepare ¶
Prepare starts unpacking if it isn't running and isn't done, and says how it's going. It never waits, so it's what a client polls.
func (*Cache) PrepareEntry ¶
PrepareEntry is Prepare for one chosen file of the archive.
type Entry ¶
type Entry struct {
Name string `json:"n"`
Size int64 `json:"s"`
// CRC is the file's CRC-32 as the archive records it, or 0 if it doesn't. Game
// databases are keyed on these, so a game can be recognised without unpacking it.
CRC uint32 `json:"c,omitempty"`
}
An Entry is one regular file in an archive. Size is -1 when the archive doesn't say.
type Error ¶
An Error is why an archive can't be used, in words for the owner. The Code stays the same across the pipe from the worker, and into the scan's report.
type Lister ¶
type Lister struct {
// contains filtered or unexported fields
}
A Lister reads archive headers one after another through one worker, so a scan of thousands costs one process and not thousands. A crash or a hang costs only the archive that caused it: that one is reported as damaged, and the next gets a new worker. Not for use by several goroutines at once.
type Listing ¶
A Listing is what an archive holds, read from its headers. Partial: a .tar.gz has no index, so a scan looks only so far into one.
type Plan ¶
type Plan struct {
// Want is what to unpack and where to.
Want []Want
// Entry is the file the core opens, relative to the game's folder.
Entry string
// Discs, when set, are the discs of a set with no playlist of its own. The
// playlist is written to Entry once they've arrived.
Discs []string
// Size is how much unpacking should write, as far as the archive says.
Size int64
}
A Plan is which files of an archive to unpack and which one a core opens.
type Status ¶
type Status struct {
State string `json:"state"` // ready, waiting, reading, unpacking or failed
Done int64 `json:"done"` // bytes written so far
Total int64 `json:"total"` // bytes to write, as far as the archive says
Error string `json:"error,omitempty"`
}
Status says how preparing a game is going.
type Want ¶
A Want is one file to unpack: Name is its name in the archive, Out its name in the folder (relative, already checked by the caller).