gamearchive

package
v0.7.1 Latest Latest
Warning

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

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

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

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

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

View Source
const ScanBudget = int64(64) << 20

ScanBudget is how much of a compressed tar a scan reads through.

Variables

View Source
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."}
	ErrUnavailable = &Error{"unavailable", "This archive couldn't be read."}
)
View Source
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

func BaseName(name string) string

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 CodeOf

func CodeOf(err error) string

CodeOf says which Error an error is, or "" for any other.

func HoldsGame

func HoldsGame(exts []string, c *wittyplay.Console) bool

HoldsGame says whether these extensions include a game for a console.

func IsArchive

func IsArchive(name string) bool

IsArchive says whether a file's name is one of the kinds of archive a game library can read.

func IsLaterVolume

func IsLaterVolume(name string) bool

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

func RankRegion(tags string) int

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

func Score(name, base string) int

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

func Transient(err error) bool

Transient says an error isn't a lasting fact about the archive, and is worth trying again at the next scan.

func ValidRegionOrder

func ValidRegionOrder(setting string) bool

ValidRegionOrder says a setting names only known regions, each once.

Types

type Cache

type Cache struct {
	Dir   string
	Limit func() int64
	// contains filtered or unexported fields
}

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

func (c *Cache) Prepare(p string, console *wittyplay.Console) Status

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

func (c *Cache) PrepareEntry(p string, console *wittyplay.Console, entry string) Status

PrepareEntry is Prepare for one chosen file of the archive.

func (*Cache) Used

func (c *Cache) Used() int64

Used is how much the unpacked games hold, for the settings page.

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

type Error struct {
	Code string
	Msg  string
}

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.

func (*Error) Error

func (e *Error) Error() string

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.

func NewLister

func NewLister() *Lister

NewLister starts nothing until the first archive.

func (*Lister) Close

func (l *Lister) Close()

Close ends the worker.

func (*Lister) List

func (l *Lister) List(path string, budget int64) (*Listing, error)

List reads one archive's headers. budget is as for ScanBudget; 0 reads everything.

func (*Lister) Peek

func (l *Lister) Peek(path, name string) ([]byte, error)

Peek reads the start of one file in an archive. A worker that hangs on it is killed, and the file counts as not read.

type Listing

type Listing struct {
	Entries []Entry `json:"e"`
	Partial bool    `json:"p,omitempty"`
}

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.

func List

func List(path string) (*Listing, error)

List reads one archive's headers, all of them, in a worker of its own.

func (*Listing) Exts

func (l *Listing) Exts() []string

Exts are the lower-case extensions in a listing, once each, in archive order.

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.

func Choose

func Choose(l *Listing, c *wittyplay.Console, archiveName string) (*Plan, error)

Choose decides what to unpack for a console. archiveName is the archive's own file name: a file inside named the same is the likely one.

func ChooseEntry

func ChooseEntry(l *Listing, c *wittyplay.Console, archiveName, entry string) (*Plan, error)

ChooseEntry is Choose when someone has picked which file to play. If it's gone from the archive, the rules choose as usual.

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

type Want struct {
	Name string `json:"n"`
	Out  string `json:"o"`
}

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).

type Written

type Written struct {
	Out  string `json:"o"`
	Size int64  `json:"s"`
}

A Written is one file that arrived.

func Unpack

func Unpack(ctx context.Context, path, dst string, want []Want, limit int64) ([]Written, error)

Unpack takes these files out of an archive into a folder, in a worker of its own, writing no more than limit bytes.

Jump to

Keyboard shortcuts

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