bring

README

Bring

Go client library for Apache Guacamole Protocol.

Quick start (tl;dr)

1. Install the library in your project:

   go get github.com/deluan/bring
   

2. Create a Client with the NewClient() function. This creates a session with the specified guacd server

3. Start the client with go client.Start()

4. Get screen updates with client.Screen()

5. Send keystrokes with client.SendKey()

6. Send mouse updates with client.SendMouse()

See the sample app for a working example

Documentation

The API is provided by the Client struct. The documentation is a work in progress, but the API is very simple and you can take a look at all features available in the sample app provided. Here are the steps to run the app:

1. You'll need a working guacd server in your machine. The easiest way is using docker and docker-compose. Just call docker-compose up -d in the root of this project. It starts the guacd server and a sample headless linux with a VNC server

2. Run the sample app with make run. It will connect to the linux container started by docker.

Take a look at the Makefile to learn how to run it in different scenarios.

Why?

Apache Guacamole was created with the goal of making a dedicated client unnecessary. So why create a client?!

The idea is that if you need to control a remote machine from your Go code, you can leverage the Guacamole protocol and the guacd server as a bridge. This way you can use any protocol supported by Guacamole (currently RDP and VNC, with X11 coming in the future) to do screen capture and remote control of networked servers/desktop machines from within your Go app.

My use case was to automate some tasks in a VirtualBox VM, but there was no Go support for the VirtualBox XPCOM API on Macs (my host platform), nor a working RDP client implementation in Go. Instead of writing a new RDP client, why not leverage the awesome Guacamole project and get support for multiple protocols?

References:

• The Guacamole protocol
• Guacamole protocol reference
• Apache Guacamole Client implementation

Documentation

Overview

Package bring implements a Guacamole client, with full remote control capabilities.

Index

• Variables
• type Client
  • func NewClient(addr string, remoteProtocol string, config map[string]string, logger ...Logger) (*Client, error)
  • func (c *Client) OnSync(f OnSyncFunc)
  • func (c *Client) Screen() (image image.Image, lastUpdate int64)
  • func (c *Client) SendKey(key KeyCode, pressed bool) error
  • func (c *Client) SendMouse(p image.Point, pressedButtons ...MouseButton) error
  • func (c *Client) SendText(sequence string) error
  • func (c *Client) Start()
  • func (c *Client) State() SessionState
• type DefaultLogger
  • func (l *DefaultLogger) Debugf(format string, args ...interface{})
  • func (l *DefaultLogger) Errorf(format string, args ...interface{})
  • func (l *DefaultLogger) Infof(format string, args ...interface{})
  • func (l *DefaultLogger) Tracef(format string, args ...interface{})
  • func (l *DefaultLogger) Warnf(format string, args ...interface{})
• type KeyCode
• type Logger
• type MouseButton
• type OnSyncFunc
• type SessionState

Variables

var ErrInvalidKeyCode = errors.New("invalid key code")

ErrInvalidKeyCode is returned by SendKey if an invalid code is passed

var ErrNotConnected = errors.New("not connected")

Types

type Client

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

Client is the main struct in this library, it represents the Guacamole protocol client. Automatically handles incoming and outgoing Guacamole instructions, updating its display using one or more graphic primitives.

func NewClient

func NewClient(addr string, remoteProtocol string, config map[string]string, logger ...Logger) (*Client, error)

NewClient creates a Client and connects it to the guacd server with the provided configuration. Logger is optional

func (*Client) OnSync

func (c *Client) OnSync(f OnSyncFunc)

OnSync sets a function that will be called on every sync instruction received. This event usually happens after a batch of updates are received from the guacd server, making it a perfect way to get the current screenshot without having to poll with Screen(). The handler is expected to be called frequently, so avoid adding any blocking behaviour. If your handler is slow, consider using a concurrent pattern (using goroutines)

func (*Client) Screen

func (c *Client) Screen() (image image.Image, lastUpdate int64)

Screen returns a snapshot of the current screen, together with the last updated timestamp

func (*Client) SendKey

func (c *Client) SendKey(key KeyCode, pressed bool) error

SendKey sends key presses and releases.

func (*Client) SendMouse

func (c *Client) SendMouse(p image.Point, pressedButtons ...MouseButton) error

SendMouse sends mouse events to the server. An event is composed by position of the cursor, and a list of any currently pressed MouseButtons

func (*Client) SendText

func (c *Client) SendText(sequence string) error

SendText sends the sequence of characters as they were typed. Only works with simple chars (no combination with control keys)

func (*Client) Start

func (c *Client) Start()

Start the Client's main loop. It is a blocking call, so it should be called in its on goroutine

func (*Client) State

func (c *Client) State() SessionState

State returns the current session state

type DefaultLogger

type DefaultLogger struct {
	Quiet bool
}

Simple console logger

func (*DefaultLogger) Debugf

func (l *DefaultLogger) Debugf(format string, args ...interface{})

func (*DefaultLogger) Errorf

func (l *DefaultLogger) Errorf(format string, args ...interface{})

func (*DefaultLogger) Infof

func (l *DefaultLogger) Infof(format string, args ...interface{})

func (*DefaultLogger) Tracef

func (l *DefaultLogger) Tracef(format string, args ...interface{})

func (*DefaultLogger) Warnf

func (l *DefaultLogger) Warnf(format string, args ...interface{})

type KeyCode

type KeyCode int32

Keys recognized by guacd. ASCII symbols from 32 to 126 do not need mapping.

const (
	KeyAgain KeyCode = 1024 + iota
	KeyAllCandidates
	KeyAlphanumeric
	KeyLeftAlt
	KeyRightAlt
	KeyAttn
	KeyAltGraph
	KeyArrowDown
	KeyArrowLeft
	KeyArrowRight
	KeyArrowUp
	KeyBackspace
	KeyCapsLock
	KeyCancel
	KeyClear
	KeyConvert
	KeyCopy
	KeyCrsel
	KeyCrSel
	KeyCodeInput
	KeyCompose
	KeyLeftControl
	KeyRightControl
	KeyContextMenu
	KeyDelete
	KeyDown
	KeyEnd
	KeyEnter
	KeyEraseEof
	KeyEscape
	KeyExecute
	KeyExsel
	KeyExSel
	KeyF1
	KeyF2
	KeyF3
	KeyF4
	KeyF5
	KeyF6
	KeyF7
	KeyF8
	KeyF9
	KeyF10
	KeyF11
	KeyF12
	KeyF13
	KeyF14
	KeyF15
	KeyF16
	KeyF17
	KeyF18
	KeyF19
	KeyF20
	KeyF21
	KeyF22
	KeyF23
	KeyF24
	KeyFind
	KeyGroupFirst
	KeyGroupLast
	KeyGroupNext
	KeyGroupPrevious
	KeyFullWidth
	KeyHalfWidth
	KeyHangulMode
	KeyHankaku
	KeyHanjaMode
	KeyHelp
	KeyHiragana
	KeyHiraganaKatakana
	KeyHome
	KeyHyper
	KeyInsert
	KeyJapaneseHiragana
	KeyJapaneseKatakana
	KeyJapaneseRomaji
	KeyJunjaMode
	KeyKanaMode
	KeyKanjiMode
	KeyKatakana
	KeyLeft
	KeyMeta
	KeyModeChange
	KeyNumLock
	KeyPageDown
	KeyPageUp
	KeyPause
	KeyPlay
	KeyPreviousCandidate
	KeyPrintScreen
	KeyRedo
	KeyRight
	KeyRomanCharacters
	KeyScroll
	KeySelect
	KeySeparator
	KeyLeftShift
	KeyRightShift
	KeySingleCandidate
	KeySuper
	KeyTab
	KeyUIKeyInputDownArrow
	KeyUIKeyInputEscape
	KeyUIKeyInputLeftArrow
	KeyUIKeyInputRightArrow
	KeyUIKeyInputUpArrow
	KeyUp
	KeyUndo
	KeyWin
	KeyZenkaku
	KeyZenkakuHankaku
)

type Logger

type Logger interface {
	Tracef(format string, args ...interface{})
	Debugf(format string, args ...interface{})
	Infof(format string, args ...interface{})
	Warnf(format string, args ...interface{})
	Errorf(format string, args ...interface{})
}

Logger interface used by this package. It is compatible with Logrus, but anything implementing this interface can be used

type MouseButton

type MouseButton int

Mouse buttons recognized by guacd

const (
	MouseLeft MouseButton = 1 << iota
	MouseMiddle
	MouseRight
	MouseUp
	MouseDown
)

type OnSyncFunc

type OnSyncFunc = func(image image.Image, lastUpdate int64)

OnSyncFunc is the signature for OnSync event handlers. It will receive the current screen image and the timestamp of the last update.

type SessionState

type SessionState int

const (
	SessionClosed SessionState = iota
	SessionHandshake
	SessionActive
)