fetch

Documentation

Overview

The fetch package is used to retrieve information about Roblox builds.

Several different types of information can be retrieved:

• Builds: A list of builds, including version hashes.
• Latest: Information about the latest build.
• APIDump: An API dump for a given hash.
• ReflectionMetadata: Reflection metadata for a given hash.
• ExplorerIcons: Explorer class icons for a given hash.

The fetch package specializes only in the newer JSON dump format.

Index

• type Build
  • func (b *Build) UnmarshalJSON(p []byte) (err error)
• type CacheMode
• type Client
  • func (client *Client) APIDump(hash string) (root *rbxapijson.Root, err error)
  • func (client *Client) Builds() (builds []Build, err error)
  • func (client *Client) ExplorerIcons(hash string) (icons image.Image, err error)
  • func (client *Client) Get(loc Location, hash string) (format string, rc io.ReadCloser, err error)
  • func (client *Client) Latest() (build Build, err error)
  • func (client *Client) Live() (builds []Build, err error)
  • func (client *Client) ReflectionMetadata(hash string) (root *rbxfile.Root, err error)
• type Config
  • func (cfg *Config) Load(r io.Reader) (err error)
  • func (cfg *Config) Save(w io.Writer) (err error)
• type Location
  • func NewLocation(s string) (loc Location)
  • func NewLocations(s ...string) (locs []Location)
  • func (loc *Location) Ext() string
  • func (loc *Location) FromString(s string) (err error)
  • func (loc Location) MarshalJSON() (b []byte, err error)
  • func (loc *Location) UnmarshalJSON(b []byte) (err error)
• type UnsupportedFormatError
• type Version

Types

type Build

type Build struct {
	Hash    string
	Date    time.Time
	Version Version
}

Build represents information about a single Roblox build.

func (*Build) UnmarshalJSON

func (b *Build) UnmarshalJSON(p []byte) (err error)

type CacheMode

type CacheMode int

CacheMode specifies how data is cached between calls.

const (
	// Data is never cached.
	CacheNone CacheMode = iota
	// Data is cached in the temporary directory.
	CacheTemp
	// Data is cached in the user cache directory. If unavailable, the
	// temporary directory is used instead.
	CachePerm
	// Data is cached to a custom directory specified by CacheLocation.
	CacheCustom
)

type Client

type Client struct {
	// Config specifies the locations from which data will be retrieved.
	Config Config
	// CacheMode specifies how to cache files.
	CacheMode CacheMode
	// CacheLocation specifies the path to store cached files, when CacheMode
	// is CacheCustom.
	CacheLocation string
	// Client is the HTTP client that performs requests.
	Client *http.Client
	// API is an optional rbxapi.Root that improves parsing of information
	// formatted as Roblox files.
	API rbxapi.Root
}

Client is used to perform the fetching of information. It controls where data is retrieved from, and how the data is cached.

Each type of information is retrieved by a specific method on a Client. Each method corresponds to the field of the same name in Config. They read data in one of several formats, specified by each configured location. The formats accepted by a particular method are described in the documentation for the method.

There are also global formats read by every method. The following global formats are available:

• .zip: The file is a zip archive. A file within this archive is retrieved and read by the method as usual. This file is referred to by the fragment of the URL. For example, the following URL refers to the "file.txt" file: https://example.com/archive.zip#file.txt. The extension of the filename determines the new format.

func (*Client) APIDump

func (client *Client) APIDump(hash string) (root *rbxapijson.Root, err error)

APIDump returns the API dump of the given hash. The following formats are readable:

• .json: An API dump in JSON format.

func (*Client) Builds

func (client *Client) Builds() (builds []Build, err error)

Builds returns a list of builds. The following formats are readable:

• .txt: A deployment log. Builds from here are filtered and curated to include only those that are interoperable with the fetch package.
• .json: A build list in JSON format.

func (*Client) ExplorerIcons

func (client *Client) ExplorerIcons(hash string) (icons image.Image, err error)

ExplorerIcons returns the studio explorer icons for the given hash. The following formats are readable:

• .png: A PNG image.
• (other): A PNG embedded within an arbitrary stream of bytes. Because the stream may contain multiple images, the following heuristic is used: the height of the image is 16, the width is a multiple of 16, and is the widest such image.

func (*Client) Get

func (client *Client) Get(loc Location, hash string) (format string, rc io.ReadCloser, err error)

Get performs a generic request. The loc argument specifies the address of the request. Within the location URL, variables of the form "$var" or "${var}" are replaced with the referred value. That said, only the $HASH variable (case-insensitive) is replaced with the value of the hash argument.

When the URL scheme is "file", the URL is interpreted as a path to a file on the file system. In this case, caching is skipped.

Returns the format indicating how the file should be interpreted (loc.Format), a ReadCloser that reads the contents of the file, and any error the may have occurred.

If loc.Format specifies a global format, it is handled here. In this case, the processed format is returned, along with the processed file, which must still be closed as usual.

func (*Client) Latest

func (client *Client) Latest() (build Build, err error)

Latest returns the latest build, the hash from which can be passed to other methods to fetch data corresponding to the latest version. The following formats are readable:

• .json: A single build in JSON format. May be a JSON string containing the hash, or a full object containing the hash, date, and version.
• (other): A raw stream indicating a version hash. Other build information is empty.

func (*Client) Live

func (client *Client) Live() (builds []Build, err error)

Live returns the current live build, the hash from which can be passed to other methods to fetch data corresponding the current live version. Live visits every configured location, returning a list of builds. It returns the first error that occurs. If no locations are configured, Live returns an empty slice.

The Client deals primarily with builds that have been deployed. Latest returns the most recently deployed build. However, the latest build is not necessarily the "live" build, or the build currently running on production.

The following formats are readable:

• .json: A single build in JSON format. May be a JSON string containing the hash, or a full object containing the hash, date, and version.
• (other): A raw stream indicating a version hash. Other build information is empty.

func (*Client) ReflectionMetadata

func (client *Client) ReflectionMetadata(hash string) (root *rbxfile.Root, err error)

ReflectionMetadata returns the reflection metadata for the given hash. The following formats are readable:

• .xml: The RBXMX format.

type Config

type Config struct {
	Builds,
	Latest,
	APIDump,
	ReflectionMetadata,
	ExplorerIcons,
	Live []Location
}

Config contains locations for each type of data, which consequentially specify where and how the data is fetched.

func (*Config) Load

func (cfg *Config) Load(r io.Reader) (err error)

Load sets the config from a JSON-formatted stream.

func (*Config) Save

func (cfg *Config) Save(w io.Writer) (err error)

Save writes the config to a stream in JSON format.

type Location

type Location struct {
	URL    url.URL
	Format string
}

Location represents where and how a type of data is fetched. See Client.Get for how Locations are interpreted.

func NewLocation

func NewLocation(s string) (loc Location)

NewLocation parses a given URL into a Location. The URL is assumed to be well-formed. The Format is derived from the extension of the URL path.

func NewLocations

func NewLocations(s ...string) (locs []Location)

NewLocations is like NewLocation, but parses a number of URLs into a slice of Locations.

func (*Location) Ext

func (loc *Location) Ext() string

Ext returns the extension of the URL path.

func (*Location) FromString

func (loc *Location) FromString(s string) (err error)

FromString sets the fields of the Location from a URL string.

func (Location) MarshalJSON

func (loc Location) MarshalJSON() (b []byte, err error)

MarshalJSON implements the json.Marshaller interface. When the Format field matches the URL path extension, the Location is written as a JSON string, and is otherwise written as a JSON object matching the structure of the Location.

func (*Location) UnmarshalJSON

func (loc *Location) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON implements the json.Unmarshaller interface. The JSON value can be a string specifying a URL, in which case the Format field is determined by the extension of the URL's path. Otherwise, the value must be an object that matches the structure of the Location.

type UnsupportedFormatError

type UnsupportedFormatError interface {
	error
	// UnsupportedFormat returns the unsupported format.
	UnsupportedFormat() string
}

UnsupportedFormatError indicates that an unsupported format was received.

type Version

type Version = rbxdhist.Version

Version represents a Roblox version number.