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
• type CleanDownloadsApplyParams
• type CleanDownloadsApplyResult
• type CleanDownloadsEntry
• type CleanDownloadsSearchParams
• type CleanDownloadsSearchResult
• type GameCredentials
• type GameFindUploadsParams
• type GameFindUploadsResult
• type GetReceiptParams
• type GetReceiptResult
• 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 LogNotification
• type Operation
• type OperationCancelParams
• type OperationCancelResult
• type OperationProgressNotification
• type OperationResult
• type OperationStartParams
• type PickUploadParams
• type PickUploadResult
• type Server
  • func NewServer() *Server
  • func (s *Server) Serve(ctx context.Context, lis net.Listener, h jsonrpc2.Handler, ...) error
• type TaskReason
• type TaskStartedNotification
• type TaskSucceededNotification
• type TaskType
• type TestDoubleRequest
• type TestDoubleResult
• type TestDoubleTwiceRequest
• type TestDoubleTwiceResult
• type UninstallParams
• type VersionGetParams
• type VersionGetResult

Constants

const (
	CodeOperationCancelled = 499
	CodeOperationAborted   = 410
)

Types

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 GetReceiptParams

type GetReceiptParams struct {
}

type GetReceiptResult

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

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

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 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 PickUploadParams

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

type PickUploadResult

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

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