buse

README

buse

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

Usage

Start butler in service mode:

butler service --json

It'll output a line of JSON similar to this one:

{"time":1509722356,"type":"result","value":{"address":"127.0.0.1:50890","type":"server-listening"}}

Dial the address to establish a connection, then send \n-separated valid JSON-RPC 2.0 requests or notifications. The connection is bidirectional, so butler may send requests and notifications the other way.

Note: most JSON-RPC 2.0 implementations assume a unidirectional use-case, ie. client/server. These won't work with buse.

When you're done, just kill the butler process.

Methods

There is no human documentation for buse, save for this README.

All requests, notifications and results can be found in the types.go file.

Client libraries

While JSON-RPC 2.0 and TCP are simple (unlike, say, grpc), it's sometimes more convenient to use client libraries and get straight to the point.

node.js client library

node-buse is used by the itch.io app to access buse from the node.js runtime. It has very few dependencies and ships with TypeScript typings so that all requests/notifications/results are type-checked by the compiler.

Documentation

Index

• Constants
• func FromDateTime(s string) (time.Time, error)
• func ToDateTime(t time.Time) string
• type AllowSandboxSetupParams
• type AllowSandboxSetupResponse
• type CheckUpdateItem
• type CheckUpdateParams
• type CheckUpdateResult
• type CleanDownloadsApplyParams
• type CleanDownloadsApplyResult
• type CleanDownloadsEntry
• type CleanDownloadsSearchParams
• type CleanDownloadsSearchResult
• type GameCredentials
• type GameFindUploadsParams
• type GameFindUploadsResult
• type GameUpdate
• type GameUpdateAvailableNotification
• type GetReceiptParams
• type GetReceiptResult
• type HTMLLaunchParams
• type HTMLLaunchResult
• type InstallParams
• type InstallResult
• type LFObjectCodec
  • func (LFObjectCodec) ReadObject(stream *bufio.Reader, v interface{}) error
  • func (LFObjectCodec) WriteObject(stream io.Writer, obj interface{}) error
• type LaunchExitedNotification
• type LaunchParams
• type LaunchResult
• type LaunchRunningNotification
• type LogNotification
• type Operation
• type OperationCancelParams
• type OperationCancelResult
• type OperationProgressNotification
• type OperationResult
• type OperationStartParams
• type PickManifestActionParams
• type PickManifestActionResult
• type PickUploadParams
• type PickUploadResult
• type PrereqStatus
• type PrereqTask
• type PrereqsEndedNotification
• type PrereqsFailedParams
• type PrereqsFailedResult
• type PrereqsStartedNotification
• type PrereqsTaskStateNotification
• type SaveVerdictParams
• type SaveVerdictResult
• type Server
  • func NewServer() *Server
  • func (s *Server) Serve(ctx context.Context, lis net.Listener, h jsonrpc2.Handler, ...) error
• type ShellLaunchParams
• type ShellLaunchResult
• type TaskReason
• type TaskStartedNotification
• type TaskSucceededNotification
• type TaskType
• type TestDoubleRequest
• type TestDoubleResult
• type TestDoubleTwiceRequest
• type TestDoubleTwiceResult
• type URLLaunchParams
• type URLLaunchResult
• type UninstallParams
• type VersionGetParams
• type VersionGetResult

Constants

const (
	CodeOperationCancelled = 499
	CodeOperationAborted   = 410
)

Functions

func FromDateTime

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

func ToDateTime

func ToDateTime(t time.Time) string

Types

type AllowSandboxSetupParams

type AllowSandboxSetupParams struct{}

type AllowSandboxSetupResponse

type AllowSandboxSetupResponse struct {
	Allow bool `json:"allow"`
}

type CheckUpdateItem

type CheckUpdateItem struct {
	ItemID      string           `json:"itemId"`
	InstalledAt string           `json:"installedAt"`
	Game        *itchio.Game     `json:"game"`
	Upload      *itchio.Upload   `json:"upload"`
	Build       *itchio.Build    `json:"build,omitempty"`
	Credentials *GameCredentials `json:"credentials"`
}

type CheckUpdateParams

type CheckUpdateParams struct {
	Items []*CheckUpdateItem `json:"items"`
}

type CheckUpdateResult

type CheckUpdateResult struct {
	Updates  []*GameUpdate `json:"updates"`
	Warnings []string      `json:"warnings"`
}

type CleanDownloadsApplyParams

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

type CleanDownloadsApplyResult

type CleanDownloadsApplyResult struct{}

type CleanDownloadsEntry

type CleanDownloadsEntry struct {
	Path string `json:"path"`
	Size int64  `json:"size"`
}

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"`
}

CleanDownloads.Search

type CleanDownloadsSearchResult

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

type GameCredentials

type GameCredentials struct {
	Server      string `json:"server"`
	APIKey      string `json:"apiKey"`
	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 {
	Game        *itchio.Game     `json:"game"`
	Credentials *GameCredentials `json:"credentials"`
}

Game.FindUploads

type GameFindUploadsResult

type GameFindUploadsResult struct {
	Uploads []*itchio.Upload `json:"uploads"`
}

type GameUpdate

type GameUpdate struct {
	ItemID string         `json:"itemId"`
	Game   *itchio.Game   `json:"game"`
	Upload *itchio.Upload `json:"upload"`
	Build  *itchio.Build  `json:"build"`
}

type GameUpdateAvailableNotification

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

type GetReceiptParams

type GetReceiptParams struct {
}

type GetReceiptResult

type GetReceiptResult struct {
	Receipt *bfs.Receipt `json:"receipt"`
}

type HTMLLaunchParams

type HTMLLaunchParams struct {
	RootFolder string `json:"rootFolder"`
	IndexPath  string `json:"indexPath"`

	Args []string          `json:"args"`
	Env  map[string]string `json:"env"`
}

type HTMLLaunchResult

type HTMLLaunchResult struct {
}

type InstallParams

type InstallParams struct {
	Game          *itchio.Game     `json:"game"`
	InstallFolder string           `json:"installFolder"`
	Upload        *itchio.Upload   `json:"upload"`
	Build         *itchio.Build    `json:"build"`
	Credentials   *GameCredentials `json:"credentials"`

	IgnoreInstallers bool `json:"ignoreInstallers,omitempty"`
}

InstallParams contains all the parameters needed to perform an installation for a game

type InstallResult

type InstallResult struct {
	Game   *itchio.Game   `json:"game"`
	Upload *itchio.Upload `json:"upload"`
	Build  *itchio.Build  `json:"build"`
}

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 LaunchExitedNotification

type LaunchExitedNotification struct{}

type LaunchParams

type LaunchParams struct {
	InstallFolder string                `json:"installFolder"`
	Game          *itchio.Game          `json:"game"`
	Upload        *itchio.Upload        `json:"upload"`
	Build         *itchio.Build         `json:"build"`
	Verdict       *configurator.Verdict `json:"verdict"`

	PrereqsDir   string `json:"prereqsDir"`
	ForcePrereqs bool   `json:"forcePrereqs,omitempty"`

	Sandbox bool `json:"sandbox,omitempty"`

	// Used for subkeying
	Credentials *GameCredentials `json:"credentials"`
}

type LaunchResult

type LaunchResult struct {
}

type LaunchRunningNotification

type LaunchRunningNotification struct{}

type LogNotification

type LogNotification struct {
	Level   string `json:"level"`
	Message string `json:"message"`
}

Log

type Operation

type Operation string

var (
	OperationInstall   Operation = "install"
	OperationUninstall Operation = "uninstall"
)

type OperationCancelParams

type OperationCancelParams struct {
	ID string `json:"id"`
}

Operation.Cancel

type OperationCancelResult

type OperationCancelResult struct{}

type OperationProgressNotification

type OperationProgressNotification struct {
	Progress float64 `json:"progress"`
	ETA      float64 `json:"eta"`
	BPS      float64 `json:"bps"`
}

Operation.Progress Sent periodically to inform on the current state an operation

type OperationResult

type OperationResult struct{}

Result for

• Operation.Start

type OperationStartParams

type OperationStartParams struct {
	ID            string    `json:"id"`
	StagingFolder string    `json:"stagingFolder"`
	Operation     Operation `json:"operation"`

	// this is more or less a union, the relevant field
	// should be set depending on the 'Operation' type
	InstallParams   *InstallParams   `json:"installParams,omitempty"`
	UninstallParams *UninstallParams `json:"uninstallParams,omitempty"`
}

Operation.Start

type PickManifestActionParams

type PickManifestActionParams struct {
	Actions []*manifest.Action `json:"actions"`
}

type PickManifestActionResult

type PickManifestActionResult struct {
	Name string `json:"name"`
}

type PickUploadParams

type PickUploadParams struct {
	Uploads []*itchio.Upload `json:"uploads"`
}

type PickUploadResult

type PickUploadResult struct {
	Index int64 `json:"index"`
}

type PrereqStatus

type PrereqStatus string

const (
	PrereqStatusPending     PrereqStatus = "pending"
	PrereqStatusDownloading PrereqStatus = "downloading"
	PrereqStatusReady       PrereqStatus = "ready"
	PrereqStatusInstalling  PrereqStatus = "installing"
	PrereqStatusDone        PrereqStatus = "done"
)

type PrereqTask

type PrereqTask struct {
	FullName string `json:"fullName"`
	Order    int    `json:"order"`
}

type PrereqsEndedNotification

type PrereqsEndedNotification struct {
}

type PrereqsFailedParams

type PrereqsFailedParams struct {
	Error      string `json:"error"`
	ErrorStack string `json:"errorStack"`
}

type PrereqsFailedResult

type PrereqsFailedResult struct {
	Continue bool `json:"continue"`
}

type PrereqsStartedNotification

type PrereqsStartedNotification struct {
	Tasks map[string]*PrereqTask `json:"tasks"`
}

type PrereqsTaskStateNotification

type PrereqsTaskStateNotification struct {
	Name     string       `json:"name"`
	Status   PrereqStatus `json:"status"`
	Progress float64      `json:"progress"`
	ETA      float64      `json:"eta"`
	BPS      float64      `json:"bps"`
}

type SaveVerdictParams

type SaveVerdictParams struct {
	Verdict *configurator.Verdict `json:"verdict"`
}

type SaveVerdictResult

type SaveVerdictResult struct{}

type Server

type Server struct {
}

func NewServer

func NewServer() *Server

func (*Server) Serve

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

type ShellLaunchParams

type ShellLaunchParams struct {
	ItemPath string `json:"itemPath"`
}

type ShellLaunchResult

type ShellLaunchResult struct {
}

type TaskReason

type TaskReason string

const (
	TaskReasonInstall   TaskReason = "install"
	TaskReasonUninstall TaskReason = "uninstall"
)

type TaskStartedNotification

type TaskStartedNotification struct {
	Reason    TaskReason     `json:"reason"`
	Type      TaskType       `json:"type"`
	Game      *itchio.Game   `json:"game"`
	Upload    *itchio.Upload `json:"upload"`
	Build     *itchio.Build  `json:"build,omitempty"`
	TotalSize int64          `json:"totalSize,omitempty"`
}

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"`
}

type TaskType

type TaskType string

const (
	TaskTypeDownload  TaskType = "download"
	TaskTypeInstall   TaskType = "install"
	TaskTypeUninstall TaskType = "uninstall"
	TaskTypeUpdate    TaskType = "update"
	TaskTypeHeal      TaskType = "heal"
)

type TestDoubleRequest

type TestDoubleRequest struct {
	Number int64 `json:"number"`
}

Test.Double

type TestDoubleResult

type TestDoubleResult struct {
	Number int64 `json:"number"`
}

Result for Test.Double

type TestDoubleTwiceRequest

type TestDoubleTwiceRequest struct {
	Number int64 `json:"number"`
}

Test.DoubleTwice

type TestDoubleTwiceResult

type TestDoubleTwiceResult struct {
	Number int64 `json:"number"`
}

Result for Test.DoubleTwice

type URLLaunchParams

type URLLaunchParams struct {
	URL string `json:"url"`
}

type URLLaunchResult

type URLLaunchResult struct{}

type UninstallParams

type UninstallParams struct {
	InstallFolder string `json:"installFolder"`
}

type VersionGetParams

type VersionGetParams struct{}

Version.Get

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"`
}

Result for Version.Get