butlerd

package
v12.0.0+incompatible Latest Latest
Warning

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

 Go to latest Published: Mar 31, 2018 License: MIT Imports: 21 Imported by: 29

README

butlerd

butlerd (butler daemon) is a JSON-RPC 2.0 service over TCP that allows using butler for long-running tasks (called operations) or one-off requests.

Documentation

Comprehensive documentation is available at http://docs.itch.ovh/butlerd/master/

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FromDateTime 

func FromDateTime(s string) (time.Time, error)

func NewStateConsumer 

func NewStateConsumer(params *NewStateConsumerParams) (*state.Consumer, error)

func ToDateTime 

func ToDateTime(t time.Time) string

Types

type Action 

type Action struct {
	// human-readable or standard name
	Name string `json:"name"`

	// file path (relative to manifest or absolute), URL, etc.
	Path string `json:"path"`

	// icon name (see static/fonts/icomoon/demo.html, don't include `icon-` prefix)
	Icon string `json:"icon,omitempty"`

	// command-line arguments
	Args []string `json:"args,omitempty"`

	// sandbox opt-in
	Sandbox bool `json:"sandbox,omitempty"`

	// requested API scope
	Scope string `json:"scope,omitempty"`

	// don't redirect stdout/stderr, open in new console window
	Console bool `json:"console,omitempty"`

	// platform to restrict this action too
	Platform ItchPlatform `json:"platform,omitempty"`

	// localized action name
	Locales map[string]*ActionLocale `json:"locales,omitempty"`
}

An Action is a choice for the user to pick when launching a game.

see https://itch.io/docs/itch/integrating/manifest.html

type ActionLocale 

type ActionLocale struct {
	// A localized action name
	Name string `json:"name"`
}

type AllowSandboxSetupParams 

type AllowSandboxSetupParams struct{}

Ask the user to allow sandbox setup. Will be followed by a UAC prompt (on Windows) or a pkexec dialog (on Linux) if the user allows.

Sent during @@LaunchParams.

@category Launch @tags Dialogs @caller server

type AllowSandboxSetupResult 

type AllowSandboxSetupResult struct {
	// Set to true if user allowed the sandbox setup, false otherwise
	Allow bool `json:"allow"`
}

type CancelFuncs 

type CancelFuncs struct {
	Funcs map[string]context.CancelFunc
}

func (*CancelFuncs) Add 

func (cf *CancelFuncs) Add(id string, f context.CancelFunc)

func (*CancelFuncs) Call 

func (cf *CancelFuncs) Call(id string) bool

func (*CancelFuncs) Remove 

func (cf *CancelFuncs) Remove(id string)

type Cave 

type Cave struct {
	ID string `json:"id"`

	Game   *itchio.Game   `json:"game"`
	Upload *itchio.Upload `json:"upload"`
	Build  *itchio.Build  `json:"build"`

	Stats       *CaveStats       `json:"stats"`
	InstallInfo *CaveInstallInfo `json:"installInfo"`
}

type CaveInstallInfo 

type CaveInstallInfo struct {
	InstalledSize   int64  `json:"installedSize"`
	InstallLocation string `json:"installLocation"`
	InstallFolder   string `json:"installFolder"`
}

type CaveStats 

type CaveStats struct {
	InstalledAt   *time.Time `json:"installedAt"`
	LastTouchedAt *time.Time `json:"lastTouchedAt"`
	SecondsRun    int64      `json:"secondsRun"`
}

type CaveSummary 

type CaveSummary struct {
	ID string `json:"id"`

	GameID int64 `json:"gameId"`

	LastTouchedAt *time.Time `json:"lastTouchedAt"`
	SecondsRun    int64      `json:"secondsRun"`
	InstalledSize int64      `json:"installedSize"`
}

type CheckUpdateItem 

type CheckUpdateItem struct {
	// An UUID generated by the client, which allows it to map back the
	// results to its own items.
	ItemID string `json:"itemId"`
	// Timestamp of the last successful install operation
	InstalledAt time.Time `json:"installedAt"`
	// Game for which to look for an update
	Game *itchio.Game `json:"game"`
	// Currently installed upload
	Upload *itchio.Upload `json:"upload"`
	// Currently installed build
	Build *itchio.Build `json:"build,omitempty"`
}

@category Update

type CheckUpdateParams 

type CheckUpdateParams struct {
	// A list of items, each of it will be checked for updates
	Items []*CheckUpdateItem `json:"items"`
}

Looks for one or more game updates.

Updates found are regularly sent via @@GameUpdateAvailableNotification, and then all at once in the result.

@category Update @caller client

type CheckUpdateResult 

type CheckUpdateResult struct {
	// Any updates found (might be empty)
	Updates []*GameUpdate `json:"updates"`
	// Warnings messages logged while looking for updates
	Warnings []string `json:"warnings"`
}

type CleanDownloadsApplyParams 

type CleanDownloadsApplyParams struct {
	Entries []*CleanDownloadsEntry `json:"entries"`
}

Remove the specified entries from disk, freeing up disk space.

@name CleanDownloads.Apply @category Clean Downloads @caller client

type CleanDownloadsApplyResult 

type CleanDownloadsApplyResult struct{}

@category Clean Downloads

type CleanDownloadsEntry 

type CleanDownloadsEntry struct {
	// The complete path of the file or folder we intend to remove
	Path string `json:"path"`
	// The size of the folder or file, in bytes
	Size int64 `json:"size"`
}

@category Clean Downloads

type CleanDownloadsSearchParams 

type CleanDownloadsSearchParams struct {
	// A list of folders to scan for potential subfolders to clean up
	Roots []string `json:"roots"`
	// A list of subfolders to not consider when cleaning
	// (staging folders for in-progress downloads)
	Whitelist []string `json:"whitelist"`
}

Look for folders we can clean up in various download folders. This finds anything that doesn't correspond to any current downloads we know about.

@name CleanDownloads.Search @category Clean Downloads @caller client

type CleanDownloadsSearchResult 

type CleanDownloadsSearchResult struct {
	// Entries we found that could use some cleaning (with path and size information)
	Entries []*CleanDownloadsEntry `json:"entries"`
}

@category Clean Downloads

type Code 

type Code int64

butlerd JSON-RPC 2.0 error codes 

const (
	// An operation was cancelled gracefully
	CodeOperationCancelled Code = 499
	// An operation was aborted by the user
	CodeOperationAborted Code = 410

	// We tried to launch something, but the install folder just wasn't there
	CodeInstallFolderDisappeared Code = 404
)

type CollectionGame 

type CollectionGame struct {
	// Position in collection, use if you want to display them in the
	// canonical itch.io order
	Position int64        `json:"position"`
	Game     *itchio.Game `json:"game"`
}

Association between a @@Game and a @@Collection @category Fetch

type Conn 

type Conn interface {
	Notify(ctx context.Context, method string, params interface{}) error
	Call(ctx context.Context, method string, params interface{}, result interface{}) error
}

type DBGetter 

type DBGetter func() *gorm.DB

type Download 

type Download struct {
	ID            string         `json:"id"`
	Error         *string        `json:"error"`
	Reason        DownloadReason `json:"reason"`
	Position      int64          `json:"position"`
	CaveID        string         `json:"caveId"`
	Game          *itchio.Game   `json:"game"`
	Upload        *itchio.Upload `json:"upload"`
	Build         *itchio.Build  `json:"build"`
	StartedAt     *time.Time     `json:"startedAt"`
	FinishedAt    *time.Time     `json:"finishedAt"`
	StagingFolder string         `json:"stagingFolder"`
}

Represents a download queued, which will be performed whenever @@DownloadsDriveParams is called.

type DownloadKeySummary 

type DownloadKeySummary struct {
	// Site-wide unique identifier generated by itch.io
	ID int64 `json:"id"`

	// Identifier of the game to which this download key grants access
	GameID int64 `json:"gameId"`

	// Date this key was created at (often coincides with purchase time)
	CreatedAt time.Time `json:"createdAt"`
}

type DownloadProgress 

type DownloadProgress struct {
	Stage    string  `json:"stage"`
	Progress float64 `json:"progress"`
	ETA      float64 `json:"eta"`
	BPS      float64 `json:"bps"`
}

type DownloadReason 

type DownloadReason string
const (
	DownloadReasonInstall       DownloadReason = "install"
	DownloadReasonReinstall     DownloadReason = "reinstall"
	DownloadReasonUpdate        DownloadReason = "update"
	DownloadReasonVersionSwitch DownloadReason = "version-switch"
)

type DownloadsClearFinishedParams 

type DownloadsClearFinishedParams struct {
}

Removes all finished downloads from the queue.

@name Downloads.ClearFinished @category Downloads @caller client

type DownloadsClearFinishedResult 

type DownloadsClearFinishedResult struct {
	// The number of removed downloads
	RemovedCount int64 `json:"removedCount"`
}

type DownloadsDiscardParams 

type DownloadsDiscardParams struct {
	DownloadID string `json:"downloadId"`
}

Attempts to discard a download

@name Downloads.Discard @category Downloads @caller client

type DownloadsDiscardResult 

type DownloadsDiscardResult struct{}

type DownloadsDriveCancelParams 

type DownloadsDriveCancelParams struct{}

Stop driving downloads gracefully.

@name Downloads.Drive.Cancel @category Downloads @caller client

type DownloadsDriveCancelResult 

type DownloadsDriveCancelResult struct {
	DidCancel bool `json:"didCancel"`
}

type DownloadsDriveDiscardedNotification 

type DownloadsDriveDiscardedNotification struct {
	Download *Download `json:"download"`
}

@name Downloads.Drive.Discarded

type DownloadsDriveErroredNotification 

type DownloadsDriveErroredNotification struct {
	Download *Download `json:"download"`
	Error    string    `json:"error"`
}

@name Downloads.Drive.Errored

type DownloadsDriveFinishedNotification 

type DownloadsDriveFinishedNotification struct {
	Download *Download `json:"download"`
}

@name Downloads.Drive.Finished

type DownloadsDriveParams 

type DownloadsDriveParams struct{}

Drive downloads, which is: perform them one at a time, until they're all finished.

@name Downloads.Drive @category Downloads @caller client

type DownloadsDriveProgressNotification 

type DownloadsDriveProgressNotification struct {
	Download *Download         `json:"download"`
	Progress *DownloadProgress `json:"progress"`
	// BPS values for the last minute
	SpeedHistory []float64 `json:"speedHistory"`
}

@name Downloads.Drive.Progress

type DownloadsDriveResult 

type DownloadsDriveResult struct{}

type DownloadsDriveStartedNotification 

type DownloadsDriveStartedNotification struct {
	Download *Download `json:"download"`
}

@name Downloads.Drive.Started

type DownloadsListParams 

type DownloadsListParams struct {
}

List all known downloads.

@name Downloads.List @category Downloads @caller client

type DownloadsListResult 

type DownloadsListResult struct {
	Downloads []*Download `json:"downloads"`
}

type DownloadsPrioritizeParams 

type DownloadsPrioritizeParams struct {
	DownloadID string `json:"downloadId"`
}

Put a download on top of the queue.

@name Downloads.Prioritize @category Downloads @caller client

type DownloadsPrioritizeResult 

type DownloadsPrioritizeResult struct {
}

type DownloadsQueueParams 

type DownloadsQueueParams struct {
	Item *InstallQueueResult `json:"item"`
}

Queue a download that will be performed later by @@DownloadsDriveParams.

@name Downloads.Queue @category Downloads @caller client

type DownloadsQueueResult 

type DownloadsQueueResult struct {
}

type DownloadsRetryParams 

type DownloadsRetryParams struct {
	DownloadID string `json:"downloadId"`
}

Retries a download that has errored

@name Downloads.Retry @category Downloads @caller client

type DownloadsRetryResult 

type DownloadsRetryResult struct{}

type ErrAborted 

type ErrAborted struct{}

func (*ErrAborted) AsJsonRpc2 

func (e *ErrAborted) AsJsonRpc2() *jsonrpc2.Error

func (*ErrAborted) Error 

func (e *ErrAborted) Error() string

type ErrCancelled 

type ErrCancelled struct{}

func (*ErrCancelled) AsJsonRpc2 

func (e *ErrCancelled) AsJsonRpc2() *jsonrpc2.Error

func (*ErrCancelled) Error 

func (e *ErrCancelled) Error() string

type Error 

type Error interface {
	error
	AsJsonRpc2() *jsonrpc2.Error
}

func AsButlerdError 

func AsButlerdError(err error) (Error, bool)

func StandardRpcError 

func StandardRpcError(Code int64) Error

type ExternalUploadsAreBadParams 

type ExternalUploadsAreBadParams struct {
	Upload *itchio.Upload `json:"upload"`
}

Sent during @@InstallQueueParams.

@name ExternalUploadsAreBad @category Install @caller server

type ExternalUploadsAreBadResult 

type ExternalUploadsAreBadResult struct {
	// If true, will proceed with install anyway. Otherwise aborts.
	Whatever bool `json:"whatever"`
}

type FetchCaveParams 

type FetchCaveParams struct {
	CaveID string `json:"caveId"`
}

Retrieve info on a cave by ID.

@name Fetch.Cave @category Fetch @caller client

type FetchCaveResult 

type FetchCaveResult struct {
	Cave *Cave `json:"cave"`
}

type FetchCavesByGameIDParams 

type FetchCavesByGameIDParams struct {
	GameID int64 `json:"gameId"`
}

Retrieve all caves for a given game.

@name Fetch.CavesByGameID @category Fetch @caller client

type FetchCavesByGameIDResult 

type FetchCavesByGameIDResult struct {
	Caves []*Cave `json:"caves"`
}

type FetchCavesByInstallLocationIDParams 

type FetchCavesByInstallLocationIDParams struct {
	InstallLocationID string `json:"installLocationId"`
}

Retrieve all caves installed to a given location.

@name Fetch.CavesByInstallLocationID @category Fetch @caller client

type FetchCavesByInstallLocationIDResult 

type FetchCavesByInstallLocationIDResult struct {
	InstallLocationPath string  `json:"installLocationPath"`
	InstallLocationSize int64   `json:"installLocationSize"`
	Caves               []*Cave `json:"caves"`
}

type FetchCavesParams 

type FetchCavesParams struct {
}

Retrieve info for all caves.

@name Fetch.Caves @category Fetch @caller client

type FetchCavesResult 

type FetchCavesResult struct {
	Caves []*Cave `json:"caves"`
}

type FetchCollectionParams 

type FetchCollectionParams struct {
	// Profile to use to fetch collection
	ProfileID int64 `json:"profileId"`
	// Identifier of the collection to look for
	CollectionID int64 `json:"collectionId"`
}

Fetches information about a collection and the games it contains.

Sends @@FetchCollectionYieldNotification.

@name Fetch.Collection @category Fetch @caller client

type FetchCollectionResult 

type FetchCollectionResult struct {
}

type FetchCollectionYieldNotification 

type FetchCollectionYieldNotification struct {
	Collection *itchio.Collection `json:"collection"`
}

Contains general info about a collection

@name Fetch.Collection.Yield @category Fetch

type FetchCommonsParams 

type FetchCommonsParams struct{}

@name Fetch.Commons @category Fetch @caller client

type FetchCommonsResult 

type FetchCommonsResult struct {
	DownloadKeys     []*DownloadKeySummary     `json:"downloadKeys"`
	Caves            []*CaveSummary            `json:"caves"`
	InstallLocations []*InstallLocationSummary `json:"installLocations"`
}

type FetchGameParams 

type FetchGameParams struct {
	// Identifier of game to look for
	GameID int64 `json:"gameId"`
}

Fetches information for an itch.io game.

Sends @@FetchGameYieldNotification twice at most: first from cache, second from API if we're online.

@name Fetch.Game @category Fetch @caller client

type FetchGameResult 

type FetchGameResult struct {
}

type FetchGameYieldNotification 

type FetchGameYieldNotification struct {
	// Current result for game fetching (from local DB, or API, etc.)
	Game *itchio.Game `json:"game"`
}

Sent during @@FetchGameParams whenever a result is available.

@name Fetch.Game.Yield @category Fetch

type FetchProfileCollectionsParams 

type FetchProfileCollectionsParams struct {
	// Profile to use to fetch game
	ProfileID int64 `json:"profileId"`
}

@name Fetch.ProfileCollections @category Fetch @caller client

type FetchProfileCollectionsResult 

type FetchProfileCollectionsResult struct {
}

type FetchProfileCollectionsYieldNotification 

type FetchProfileCollectionsYieldNotification struct {
	Offset int64                `json:"offset"`
	Total  int64                `json:"total"`
	Items  []*itchio.Collection `json:"items"`
}

Sent during @@FetchProfileCollectionsParams whenever new info is available.

@name Fetch.ProfileCollections.Yield @category Fetch

type FetchProfileGamesParams 

type FetchProfileGamesParams struct {
	// Profile to use to fetch game
	ProfileID int64 `json:"profileId"`
}

@name Fetch.ProfileGames @category Fetch @caller client

type FetchProfileGamesResult 

type FetchProfileGamesResult struct {
}

type FetchProfileGamesYieldNotification 

type FetchProfileGamesYieldNotification struct {
	Offset int64          `json:"offset"`
	Total  int64          `json:"total"`
	Items  []*ProfileGame `json:"items"`
}

@name Fetch.ProfileGames.Yield @category Fetch

type FetchProfileOwnedKeysParams 

type FetchProfileOwnedKeysParams struct {
	// Profile to use to fetch game
	ProfileID int64 `json:"profileId"`
}

@name Fetch.ProfileOwnedKeys @category Fetch @caller client

type FetchProfileOwnedKeysResult 

type FetchProfileOwnedKeysResult struct {
}

type FetchProfileOwnedKeysYieldNotification 

type FetchProfileOwnedKeysYieldNotification struct {
	Offset int64                 `json:"offset"`
	Total  int64                 `json:"total"`
	Items  []*itchio.DownloadKey `json:"items"`
}

@name Fetch.ProfileOwnedKeys.Yield @category Fetch

type GameCredentials 

type GameCredentials struct {
	// Defaults to `https://itch.io`
	// @optional
	Server string `json:"server"`
	// A valid itch.io API key
	APIKey string `json:"apiKey"`
	// A download key identifier, or 0 if no download key is available
	// @optional
	DownloadKey int64 `json:"downloadKey"`
}

GameCredentials contains all the credentials required to make API requests including the download key if any.

type GameFindUploadsParams 

type GameFindUploadsParams struct {
	// Which game to find uploads for
	Game *itchio.Game `json:"game"`
}

Finds uploads compatible with the current runtime, for a given game.

@name Game.FindUploads @category Install @caller client

type GameFindUploadsResult 

type GameFindUploadsResult struct {
	// A list of uploads that were found to be compatible.
	Uploads []*itchio.Upload `json:"uploads"`
}

type GameUpdate 

type GameUpdate struct {
	// Identifier originally passed in CheckUpdateItem
	ItemID string `json:"itemId"`
	// Game we found an update for
	Game *itchio.Game `json:"game"`
	// Upload to be installed
	Upload *itchio.Upload `json:"upload"`
	// Build to be installed (may be nil)
	Build *itchio.Build `json:"build"`
}

Describes an available update for a particular game install.

@category Update

type GameUpdateAvailableNotification 

type GameUpdateAvailableNotification struct {
	Update *GameUpdate `json:"update"`
}

Sent during @@CheckUpdateParams, every time butler finds an update for a game. Can be safely ignored if displaying updates as they are found is not a requirement for the client.

@category Update @tags Optional

type HTMLLaunchParams 

type HTMLLaunchParams struct {
	// Absolute path on disk to serve
	RootFolder string `json:"rootFolder"`
	// Path of index file, relative to root folder
	IndexPath string `json:"indexPath"`

	// Command-line arguments, to pass as `global.Itch.args`
	Args []string `json:"args"`
	// Environment variables, to pass as `global.Itch.env`
	Env map[string]string `json:"env"`
}

Ask the client to perform an HTML launch, ie. open an HTML5 game, ideally in an embedded browser.

Sent during @@LaunchParams.

@category Launch @caller server

type HTMLLaunchResult 

type HTMLLaunchResult struct {
}

type HandshakeParams 

type HandshakeParams struct {
	Message string `json:"message"`
}

@name Handshake @category Protocol @caller server

type HandshakeResult 

type HandshakeResult struct {
	Signature string `json:"signature"`
}

type Harness 

type Harness interface {
	ClientFromCredentials(credentials *GameCredentials) (*itchio.Client, error)
}

func NewProductionHarness 

func NewProductionHarness() Harness

type InstallCancelParams 

type InstallCancelParams struct {
	// The UUID of the task to cancel, as passed to @@OperationStartParams
	ID string `json:"id"`
}

Attempt to gracefully cancel an ongoing operation.

@name Install.Cancel @category Install @caller client

type InstallCancelResult 

type InstallCancelResult struct {
	DidCancel bool `json:"didCancel"`
}

type InstallLocationSizeInfo 

type InstallLocationSizeInfo struct {
	// Number of bytes used by caves installed in this location
	InstalledSize int64 `json:"installedSize"`
	// Free space at this location (depends on the partition/disk on which
	// it is), or a negative value if we can't find it
	FreeSize int64 `json:"freeSize"`
	// Total space of this location (depends on the partition/disk on which
	// it is), or a negative value if we can't find it
	TotalSize int64 `json:"totalSize"`
}

type InstallLocationSummary 

type InstallLocationSummary struct {
	ID       string                   `json:"id"`
	Path     string                   `json:"path"`
	SizeInfo *InstallLocationSizeInfo `json:"sizeInfo,omitempty"`
}

type InstallLocationsAddParams 

type InstallLocationsAddParams struct {
	// identifier of the new install location.
	// if not specified, will be generated.
	// @optional
	ID string `json:"id"`

	// path of the new install location
	Path string `json:"path"`
}

@name Install.Locations.Add @category Install @caller client

type InstallLocationsAddResult 

type InstallLocationsAddResult struct {
}

type InstallLocationsGetByIDParams 

type InstallLocationsGetByIDParams struct {
	// identifier of the install location to remove
	ID string `json:"id"`
}

@name Install.Locations.GetByID @category Install @caller client

type InstallLocationsGetByIDResult 

type InstallLocationsGetByIDResult struct {
	InstallLocation *InstallLocationSummary `json:"installLocation"`
}

type InstallLocationsListParams 

type InstallLocationsListParams struct {
}

@name Install.Locations.List @category Install @caller client

type InstallLocationsListResult 

type InstallLocationsListResult struct {
	InstallLocations []*InstallLocationSummary `json:"installLocations"`
}

type InstallLocationsRemoveParams 

type InstallLocationsRemoveParams struct {
	// identifier of the install location to remove
	ID string `json:"id"`
}

@name Install.Locations.Remove @category Install @caller client

type InstallLocationsRemoveResult 

type InstallLocationsRemoveResult struct {
}

type InstallLocationsScanConfirmImportParams 

type InstallLocationsScanConfirmImportParams struct {
	// number of items that will be imported
	NumItems int64 `json:"numItems"`
}

Sent at the end of @@InstallLocationsScanParams

@name Install.Locations.Scan.ConfirmImport @category Install @caller server

type InstallLocationsScanConfirmImportResult 

type InstallLocationsScanConfirmImportResult struct {
	Confirm bool `json:"confirm"`
}

type InstallLocationsScanParams 

type InstallLocationsScanParams struct {
	// path to a legacy marketDB
	// @optional
	LegacyMarketPath string `json:"legacyMarketPath"`
}

@name Install.Locations.Scan @category Install @caller client

type InstallLocationsScanResult 

type InstallLocationsScanResult struct {
	NumFoundItems    int64 `json:"numFoundItems"`
	NumImportedItems int64 `json:"numImportedItems"`
}

type InstallLocationsScanYieldNotification 

type InstallLocationsScanYieldNotification struct {
	Game *itchio.Game `json:"game"`
}

Sent during @@InstallLocationsScanParams whenever a game is found.

@name Install.Locations.Scan.Yield @category Install

type InstallPerformParams 

type InstallPerformParams struct {
	// ID that can be later used in @@InstallCancelParams
	ID string `json:"id"`

	// The folder turned by @@InstallQueueParams
	StagingFolder string `json:"stagingFolder"`
}

Perform an install that was previously queued via @@InstallQueueParams.

Can be cancelled by passing the same `ID` to @@InstallCancelParams.

@name Install.Perform @category Install @tags Cancellable @caller client

type InstallPerformResult 

type InstallPerformResult struct{}

type InstallQueueParams 

type InstallQueueParams struct {
	// ID of the cave to perform the install for.
	// If not specified, will create a new cave.
	// @optional
	CaveID string `json:"caveId"`

	// If unspecified, will default to 'install'
	// @optional
	Reason DownloadReason `json:"reason"`

	// If CaveID is not specified, ID of an install location
	// to install to.
	// @optional
	InstallLocationID string `json:"installLocationId"`

	// If set, InstallFolder can be set and no cave
	// record will be read or modified
	// @optional
	NoCave bool `json:"noCave"`

	// When NoCave is set, exactly where to install
	// @optional
	InstallFolder string `json:"installFolder"`

	// Which game to install.
	//
	// If unspecified and caveId is specified, the same game will be used.
	// @optional
	Game *itchio.Game `json:"game"`

	// Which upload to install.
	//
	// If unspecified and caveId is specified, the same upload will be used.
	// @optional
	Upload *itchio.Upload `json:"upload"`

	// Which build to install
	//
	// If unspecified and caveId is specified, the same build will be used.
	// @optional
	Build *itchio.Build `json:"build"`

	// If true, do not run windows installers, just extract
	// whatever to the install folder.
	// @optional
	IgnoreInstallers bool `json:"ignoreInstallers,omitempty"`

	// A folder that butler can use to store temporary files, like
	// partial downloads, checkpoint files, etc.
	// @optional
	StagingFolder string `json:"stagingFolder"`

	// If set, and the install operation is successfully disambiguated,
	// will queue it as a download for butler to drive.
	// See @@DownloadsDriveParams.
	// @optional
	QueueDownload bool `json:"queueDownload"`
}

Queues an install operation to be later performed via @@InstallPerformParams.

@name Install.Queue @category Install @caller client

type InstallQueueResult 

type InstallQueueResult struct {
	ID            string         `json:"id"`
	Reason        DownloadReason `json:"reason"`
	CaveID        string         `json:"caveId"`
	Game          *itchio.Game   `json:"game"`
	Upload        *itchio.Upload `json:"upload"`
	Build         *itchio.Build  `json:"build"`
	InstallFolder string         `json:"installFolder"`
	StagingFolder string         `json:"stagingFolder"`
}

type InstallResult 

type InstallResult struct {
	// The game we installed
	Game *itchio.Game `json:"game"`
	// The upload we installed
	Upload *itchio.Upload `json:"upload"`
	// The build we installed
	// @optional
	Build *itchio.Build `json:"build"`
}

What was installed by a subtask of @@OperationStartParams.

See @@TaskSucceededNotification.

@category Install @kind type

type InstallVersionSwitchPickParams 

type InstallVersionSwitchPickParams struct {
	Cave   *Cave           `json:"cave"`
	Upload *itchio.Upload  `json:"upload"`
	Builds []*itchio.Build `json:"builds"`
}

Let the user pick which version to switch to.

@category Install @caller server

type InstallVersionSwitchPickResult 

type InstallVersionSwitchPickResult struct {
	// A negative index aborts the version switch
	Index int64 `json:"index"`
}

type InstallVersionSwitchQueueParams 

type InstallVersionSwitchQueueParams struct {
	// The cave to switch to a different version
	CaveID string `json:"caveId"`
}

Prepare to queue a version switch. The client will receive an @@InstallVersionSwitchPickParams.

@name Install.VersionSwitch.Queue @category Install @caller client

type InstallVersionSwitchQueueResult 

type InstallVersionSwitchQueueResult struct {
}

type ItchPlatform 

type ItchPlatform string
const (
	ItchPlatformOSX     ItchPlatform = "osx"
	ItchPlatformWindows ItchPlatform = "windows"
	ItchPlatformLinux   ItchPlatform = "linux"
	ItchPlatformUnknown ItchPlatform = "unknown"
)

type LFObjectCodec 

type LFObjectCodec struct{}

func (LFObjectCodec) ReadObject 

func (LFObjectCodec) ReadObject(stream *bufio.Reader, v interface{}) error

func (LFObjectCodec) WriteObject 

func (LFObjectCodec) WriteObject(stream io.Writer, obj interface{}) error

type LaunchCancelParams 

type LaunchCancelParams struct {
}

Close a running game or cancel launching it

@name Launch.Cancel @category Launch @caller client

type LaunchCancelResult 

type LaunchCancelResult struct {
	DidCancel bool `json:"didCancel"`
}

type LaunchExitedNotification 

type LaunchExitedNotification struct{}

Sent during @@LaunchParams, when the game has actually exited.

@category Launch

type LaunchParams 

type LaunchParams struct {
	// The ID of the cave to launch
	CaveID string `json:"caveId"`

	// The directory to use to store installer files for prerequisites
	PrereqsDir string `json:"prereqsDir"`
	// Force installing all prerequisites, even if they're already marked as installed
	// @optional
	ForcePrereqs bool `json:"forcePrereqs,omitempty"`

	// Enable sandbox (regardless of manifest opt-in)
	Sandbox bool `json:"sandbox,omitempty"`
}

Attempt to launch an installed game.

@name Launch @category Launch @caller client

type LaunchResult 

type LaunchResult struct {
}

type LaunchRunningNotification 

type LaunchRunningNotification struct{}

Sent during @@LaunchParams, when the game is configured, prerequisites are installed sandbox is set up (if enabled), and the game is actually running.

@category Launch

type LogLevel 

type LogLevel string
const (
	// Hidden from logs by default, noisy
	LogLevelDebug LogLevel = "debug"
	// Just thinking out loud
	LogLevelInfo LogLevel = "info"
	// We're continuing, but we're not thrilled about it
	LogLevelWarning LogLevel = "warning"
	// We're eventually going to fail loudly
	LogLevelError LogLevel = "error"
)

type LogNotification 

type LogNotification struct {
	// Level of the message (`info`, `warn`, etc.)
	Level LogLevel `json:"level"`
	// Contents of the message.
	//
	// Note: logs may contain non-ASCII characters, or even emojis.
	Message string `json:"message"`
}

Sent any time butler needs to send a log message. The client should relay them in their own stdout / stderr, and collect them so they can be part of an issue report if something goes wrong.

type Manifest 

type Manifest struct {
	// Actions are a list of options to give the user when launching a game.
	Actions []*Action `json:"actions"`

	// Prereqs describe libraries or frameworks that must be installed
	// prior to launching a game
	Prereqs []*Prereq `json:"prereqs,omitempty"`
}

A Manifest describes prerequisites (dependencies) and actions that can be taken while launching a game.

type NewStateConsumerParams 

type NewStateConsumerParams struct {
	// Mandatory
	Conn Conn
	Ctx  context.Context

	// Optional
	LogFile *os.File
}

type NotificationInterceptor 

type NotificationInterceptor func(method string, params interface{}) error

type OpenDBFunc 

type OpenDBFunc func() (*gorm.DB, error)

type PickManifestActionParams 

type PickManifestActionParams struct {
	// A list of actions to pick from. Must be shown to the user in the order they're passed.
	Actions []*Action `json:"actions"`
}

Sent during @@LaunchParams, ask the user to pick a manifest action to launch.

See [itch app manifests](https://itch.io/docs/itch/integrating/manifest.html).

@tags Dialogs @category Launch @caller server

type PickManifestActionResult 

type PickManifestActionResult struct {
	// Index of action picked by user, or negative if aborting
	Index int `json:"index"`
}

type PickUploadParams 

type PickUploadParams struct {
	// An array of upload objects to choose from
	Uploads []*itchio.Upload `json:"uploads"`
}

Asks the user to pick between multiple available uploads

@category Install @tags Dialog @caller server

type PickUploadResult 

type PickUploadResult struct {
	// The index (in the original array) of the upload that was picked,
	// or a negative value to cancel.
	Index int64 `json:"index"`
}

type Prereq 

type Prereq struct {
	// A prerequisite to be installed, see <https://itch.io/docs/itch/integrating/prereqs/> for the full list.
	Name string `json:"name"`
}

type PrereqStatus 

type PrereqStatus string

@category Launch 

const (
	// Prerequisite has not started downloading yet
	PrereqStatusPending PrereqStatus = "pending"
	// Prerequisite is currently being downloaded
	PrereqStatusDownloading PrereqStatus = "downloading"
	// Prerequisite has been downloaded and is pending installation
	PrereqStatusReady PrereqStatus = "ready"
	// Prerequisite is currently installing
	PrereqStatusInstalling PrereqStatus = "installing"
	// Prerequisite was installed (successfully or not)
	PrereqStatusDone PrereqStatus = "done"
)

type PrereqTask 

type PrereqTask struct {
	// Full name of the prerequisite, for example: `Microsoft .NET Framework 4.6.2`
	FullName string `json:"fullName"`
	// Order of task in the list. Respect this order in the UI if you want consistent progress indicators.
	Order int `json:"order"`
}

Information about a prerequisite task.

@category Launch

type PrereqsEndedNotification 

type PrereqsEndedNotification struct {
}

Sent during @@LaunchParams, when all prereqs have finished installing (successfully or not)

After this is received, it's safe to close any UI element showing prereq task state.

@category Launch

type PrereqsFailedParams 

type PrereqsFailedParams struct {
	// Short error
	Error string `json:"error"`
	// Longer error (to include in logs)
	ErrorStack string `json:"errorStack"`
}

Sent during @@LaunchParams, when one or more prerequisites have failed to install. The user may choose to proceed with the launch anyway.

@category Launch @caller server

type PrereqsFailedResult 

type PrereqsFailedResult struct {
	// Set to true if the user wants to proceed with the launch in spite of the prerequisites failure
	Continue bool `json:"continue"`
}

type PrereqsStartedNotification 

type PrereqsStartedNotification struct {
	// A list of prereqs that need to be tended to
	Tasks map[string]*PrereqTask `json:"tasks"`
}

Sent during @@LaunchParams, when some prerequisites are about to be installed.

This is a good time to start showing a UI element with the state of prereq tasks.

Updates are regularly provided via @@PrereqsTaskStateNotification.

@category Launch

type PrereqsTaskStateNotification 

type PrereqsTaskStateNotification struct {
	// Short name of the prerequisite task (e.g. `xna-4.0`)
	Name string `json:"name"`
	// Current status of the prereq
	Status PrereqStatus `json:"status"`
	// Value between 0 and 1 (floating)
	Progress float64 `json:"progress"`
	// ETA in seconds (floating)
	ETA float64 `json:"eta"`
	// Network bandwidth used in bytes per second (floating)
	BPS float64 `json:"bps"`
}

Current status of a prerequisite task

Sent during @@LaunchParams, after @@PrereqsStartedNotification, repeatedly until all prereq tasks are done.

@category Launch

type Profile 

type Profile struct {
	// itch.io user ID, doubling as profile ID
	ID int64 `json:"id"`

	// Timestamp the user last connected at (to the client)
	LastConnected time.Time `json:"lastConnected"`

	// User information
	User *itchio.User `json:"user"`
}

Represents a user for which we have profile information, ie. that we can connect as, etc.

type ProfileDataGetParams 

type ProfileDataGetParams struct {
	ProfileID int64  `json:"profileId"`
	Key       string `json:"key"`
}

Retrieves some data associated to a profile, by key.

@name Profile.Data.Get @category Profile @caller client

type ProfileDataGetResult 

type ProfileDataGetResult struct {
	// True if the value existed
	OK    bool   `json:"ok"`
	Value string `json:"value"`
}

type ProfileDataPutParams 

type ProfileDataPutParams struct {
	ProfileID int64  `json:"profileId"`
	Key       string `json:"key"`
	Value     string `json:"value"`
}

Stores some data associated to a profile, by key.

@name Profile.Data.Put @category Profile @caller client

type ProfileDataPutResult 

type ProfileDataPutResult struct {
}

type ProfileForgetParams 

type ProfileForgetParams struct {
	ProfileID int64 `json:"profileId"`
}

Forgets a remembered profile - it won't appear in the @@ProfileListParams results anymore.

@name Profile.Forget @category Profile @caller client

type ProfileForgetResult 

type ProfileForgetResult struct {
	// True if the profile did exist (and was successfully forgotten)
	Success bool `json:"success"`
}

type ProfileGame 

type ProfileGame struct {
	Game *itchio.Game `json:"game,omitempty"`
	User *itchio.User `json:"user,omitempty"`

	// Position on profile, from 0 to N
	Position int64 `json:"position"`

	ViewsCount     int64 `json:"viewsCount"`
	DownloadsCount int64 `json:"downloadsCount"`
	PurchasesCount int64 `json:"purchasesCount"`

	Published bool `json:"published"`
}

type ProfileListParams 

type ProfileListParams struct {
}

Lists remembered profiles

@name Profile.List @category Profile @caller client

type ProfileListResult 

type ProfileListResult struct {
	// A list of remembered profiles
	Profiles []*Profile `json:"profiles"`
}

type ProfileLoginWithAPIKeyParams 

type ProfileLoginWithAPIKeyParams struct {
	// The API token to use
	APIKey string `json:"apiKey"`
}

Add a new profile by API key login. This can be used for integration tests, for example. Note that no cookies are returned for this kind of login.

@name Profile.LoginWithAPIKey @category Profile @caller client

type ProfileLoginWithAPIKeyResult 

type ProfileLoginWithAPIKeyResult struct {
	// Information for the new profile, now remembered
	Profile *Profile `json:"profile"`
}

type ProfileLoginWithPasswordParams 

type ProfileLoginWithPasswordParams struct {
	// The username (or e-mail) to use for login
	Username string `json:"username"`

	// The password to use
	Password string `json:"password"`
}

Add a new profile by password login

@name Profile.LoginWithPassword @category Profile @caller client

type ProfileLoginWithPasswordResult 

type ProfileLoginWithPasswordResult struct {
	// Information for the new profile, now remembered
	Profile *Profile `json:"profile"`

	// Profile cookie for website
	Cookie map[string]string `json:"cookie"`
}

type ProfileRequestCaptchaParams 

type ProfileRequestCaptchaParams struct {
	// Address of page containing a recaptcha widget
	RecaptchaURL string `json:"recaptchaUrl"`
}

Ask the user to solve a captcha challenge Sent during @@ProfileLoginWithPasswordParams if certain conditions are met.

@name Profile.RequestCaptcha @category Profile @caller server

type ProfileRequestCaptchaResult 

type ProfileRequestCaptchaResult struct {
	// The response given by recaptcha after it's been filled
	RecaptchaResponse string `json:"recaptchaResponse"`
}

type ProfileRequestTOTPParams 

type ProfileRequestTOTPParams struct {
}

Ask the user to provide a TOTP token. Sent during @@ProfileLoginWithPasswordParams if the user has two-factor authentication enabled.

@name Profile.RequestTOTP @category Profile @caller server

type ProfileRequestTOTPResult 

type ProfileRequestTOTPResult struct {
	// The TOTP code entered by the user
	Code string `json:"code"`
}

type ProfileUseSavedLoginParams 

type ProfileUseSavedLoginParams struct {
	ProfileID int64 `json:"profileId"`
}

Use saved login credentials to validate a profile.

@name Profile.UseSavedLogin @category Profile @caller client

type ProfileUseSavedLoginResult 

type ProfileUseSavedLoginResult struct {
	// Information for the now validated profile
	Profile *Profile `json:"profile"`
}

type ProgressNotification 

type ProgressNotification struct {
	// An overall progress value between 0 and 1
	Progress float64 `json:"progress"`
	// Estimated completion time for the operation, in seconds (floating)
	ETA float64 `json:"eta"`
	// Network bandwidth used, in bytes per second (floating)
	BPS float64 `json:"bps"`
}

Sent periodically during @@InstallPerformParams to inform on the current state of an install

@name Progress @category Install

type RequestContext 

type RequestContext struct {
	Ctx            context.Context
	Harness        Harness
	Consumer       *state.Consumer
	Params         *json.RawMessage
	Conn           Conn
	MansionContext *mansion.Context
	CancelFuncs    *CancelFuncs
	DB             DBGetter
	Router         *Router
	// contains filtered or unexported fields
}

func (*RequestContext) Call 

func (rc *RequestContext) Call(method string, params interface{}, res interface{}) error

func (*RequestContext) EndProgress 

func (rc *RequestContext) EndProgress()

func (*RequestContext) InterceptNotification 

func (rc *RequestContext) InterceptNotification(method string, interceptor NotificationInterceptor)

func (*RequestContext) KeyClient 

func (rc *RequestContext) KeyClient(key string) (*itchio.Client, error)

func (*RequestContext) Notify 

func (rc *RequestContext) Notify(method string, params interface{}) error

func (*RequestContext) ProfileClient 

func (rc *RequestContext) ProfileClient(profileID int64) (*models.Profile, *itchio.Client)

func (*RequestContext) RootClient 

func (rc *RequestContext) RootClient() (*itchio.Client, error)

func (*RequestContext) StartProgress 

func (rc *RequestContext) StartProgress()

func (*RequestContext) StartProgressWithInitialAndTotal 

func (rc *RequestContext) StartProgressWithInitialAndTotal(initialProgress float64, totalBytes int64)

func (*RequestContext) StartProgressWithTotalBytes 

func (rc *RequestContext) StartProgressWithTotalBytes(totalBytes int64)

func (*RequestContext) StopInterceptingNotification 

func (rc *RequestContext) StopInterceptingNotification(method string)

type RequestHandler 

type RequestHandler func(rc *RequestContext) (interface{}, error)

type Router 

type Router struct {
	Handlers       map[string]RequestHandler
	MansionContext *mansion.Context
	CancelFuncs    *CancelFuncs
	// contains filtered or unexported fields
}

func NewRouter 

func NewRouter(mansionContext *mansion.Context, openDB OpenDBFunc) *Router

func (*Router) Dispatch 

func (r *Router) Dispatch(ctx context.Context, origConn *jsonrpc2.Conn, req *jsonrpc2.Request)

func (*Router) Register 

func (r *Router) Register(method string, rh RequestHandler)

type RpcError 

type RpcError struct {
	Code    int64
	Message string
}

func (*RpcError) AsJsonRpc2 

func (re *RpcError) AsJsonRpc2() *jsonrpc2.Error

func (*RpcError) Error 

func (re *RpcError) Error() string

type SearchGamesParams 

type SearchGamesParams struct {
	ProfileID int64 `json:"profileId"`

	Query string `json:"query"`
}

Searches for games. Returns data from the local database and the API, via @@SearchGamesYieldNotification.

@name Search.Games @category Search @caller client

type SearchGamesResult 

type SearchGamesResult struct {
}

type SearchGamesYieldNotification 

type SearchGamesYieldNotification struct {
	Games []*itchio.Game `json:"games"`
}

Sent during @@SearchGamesParams

@category Search

type SearchUsersParams 

type SearchUsersParams struct {
	ProfileID int64 `json:"profileId"`

	Query string `json:"query"`
}

Searches for users. Returns data from the local database and the API, via @@SearchUsersYieldNotification.

@name Search.Users @category Search @caller client

type SearchUsersResult 

type SearchUsersResult struct {
}

type SearchUsersYieldNotification 

type SearchUsersYieldNotification struct {
	Users []*itchio.User `json:"users"`
}

Sent during @@SearchUsersParams when results are available

@category Search

type Server 

type Server struct {
	// contains filtered or unexported fields
}

func NewServer 

func NewServer(secret string) *Server

func (*Server) Serve 

func (s *Server) Serve(ctx context.Context, lis net.Listener, h jsonrpc2.Handler, consumer *state.Consumer, opt ...jsonrpc2.ConnOpt) error

type ShellLaunchParams 

type ShellLaunchParams struct {
	// Absolute path of item to open, e.g. `D:\\Games\\Itch\\garden\\README.txt`
	ItemPath string `json:"itemPath"`
}

Ask the client to perform a shell launch, ie. open an item with the operating system's default handler (File explorer).

Sent during @@LaunchParams.

@category Launch @caller server

type ShellLaunchResult 

type ShellLaunchResult struct {
}

type SystemStatFSParams 

type SystemStatFSParams struct {
	Path string `json:"path"`
}

Get information on a filesystem.

@name System.StatFS @category System @caller client

type SystemStatFSResult 

type SystemStatFSResult struct {
	FreeSize  int64 `json:"freeSize"`
	TotalSize int64 `json:"totalSize"`
}

type TaskReason 

type TaskReason string

@category Install 

const (
	// Task was started for an install operation
	TaskReasonInstall TaskReason = "install"
	// Task was started for an uninstall operation
	TaskReasonUninstall TaskReason = "uninstall"
)

type TaskStartedNotification 

type TaskStartedNotification struct {
	// Why this task was started
	Reason TaskReason `json:"reason"`
	// Is this task a download? An install?
	Type TaskType `json:"type"`
	// The game this task is dealing with
	Game *itchio.Game `json:"game"`
	// The upload this task is dealing with
	Upload *itchio.Upload `json:"upload"`
	// The build this task is dealing with (if any)
	Build *itchio.Build `json:"build,omitempty"`
	// Total size in bytes
	TotalSize int64 `json:"totalSize,omitempty"`
}

Each operation is made up of one or more tasks. This notification is sent during @@OperationStartParams whenever a specific task starts.

@category Install

type TaskSucceededNotification 

type TaskSucceededNotification struct {
	Type TaskType `json:"type"`
	// If the task installed something, then this contains
	// info about the game, upload, build that were installed
	InstallResult *InstallResult `json:"installResult,omitempty"`
}

Sent during @@OperationStartParams whenever a task succeeds for an operation.

@category Install

type TaskType 

type TaskType string

@category Install 

const (
	// We're fetching files from a remote server
	TaskTypeDownload TaskType = "download"
	// We're running an installer
	TaskTypeInstall TaskType = "install"
	// We're running an uninstaller
	TaskTypeUninstall TaskType = "uninstall"
	// We're applying some patches
	TaskTypeUpdate TaskType = "update"
	// We're healing from a signature and heal source
	TaskTypeHeal TaskType = "heal"
)

type TestDoubleParams 

type TestDoubleParams struct {
	// The number to double
	Number int64 `json:"number"`
}

Test request: return a number, doubled. Implement that to use @@TestDoubleTwiceParams in your testing.

@name Test.Double @category Test @caller server

type TestDoubleResult 

type TestDoubleResult struct {
	// The number, doubled
	Number int64 `json:"number"`
}

Result for Test.Double

type TestDoubleTwiceParams 

type TestDoubleTwiceParams struct {
	// The number to quadruple
	Number int64 `json:"number"`
}

Test request: asks butler to double a number twice. First by calling @@TestDoubleParams, then by returning the result of that call doubled.

Use that to try out your JSON-RPC 2.0 over TCP implementation.

@name Test.DoubleTwice @category Test @caller client

type TestDoubleTwiceResult 

type TestDoubleTwiceResult struct {
	// The input, quadrupled
	Number int64 `json:"number"`
}

@category Test

type URLLaunchParams 

type URLLaunchParams struct {
	// URL to open, e.g. `https://itch.io/community`
	URL string `json:"url"`
}

Ask the client to perform an URL launch, ie. open an address with the system browser or appropriate.

Sent during @@LaunchParams.

@category Launch @caller server

type URLLaunchResult 

type URLLaunchResult struct{}

type UninstallPerformParams 

type UninstallPerformParams struct {
	// The cave to uninstall
	CaveID string `json:"caveId"`
}

UninstallParams contains all the parameters needed to perform an uninstallation for a game via @@OperationStartParams.

@name Uninstall.Perform @category Install @caller client

type UninstallPerformResult 

type UninstallPerformResult struct{}

type VersionGetParams 

type VersionGetParams struct{}

Retrieves the version of the butler instance the client is connected to.

This endpoint is meant to gather information when reporting issues, rather than feature sniffing. Conforming clients should automatically download new versions of butler, see the **Updating** section.

@name Version.Get @category Utilities @tags Offline @caller client

type VersionGetResult 

type VersionGetResult struct {
	// Something short, like `v8.0.0`
	Version string `json:"version"`

	// Something long, like `v8.0.0, built on Aug 27 2017 @ 01:13:55, ref d833cc0aeea81c236c81dffb27bc18b2b8d8b290`
	VersionString string `json:"versionString"`
}

type WithParamsFunc 

type WithParamsFunc func() (interface{}, error)

Source Files

View all Source files

Directories

Path Synopsis
spec

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.