protocol

README

Developer Notes

Background

After experimenting with multiple approaches, the current design was chosen because it should make supporting both BSER and JSON encoding easier. It also provides mechanisms to add support for additional commands outside the module.

Watchman's protocol is documented here: https://facebook.github.io/watchman/docs/socket-interface.html

Code Organization

The focus of this package is providing low-level building blocks to interact with the Watchman server. In other words: connecting, marshaling, and unmarshaling messages. It should leave decisions about channels, goroutines, and such to other packages. Likewise, high-level interfaces and abstractions should not be included in this package.

Guidelines for this package include:

• One Watchman command per file.
• Each command file should include three items:
  • Request struct
  • Response struct
  • A ResponseTranslator to convert from raw ResponsePDU to Response struct.
• Request structs should expose their member values, and implement the Request interface,
• Response structs should hide their member values, and provide accessor methods.
• Keep the mapping from PDU to Request or Response struct as simple as possible.
• Each command file should have a matching unit test file.
• Each command should also be exercised by one or more integration tests.

Documentation

Overview

Package protocol provides primitives to communicate with the Watchman file watching service. Most Watchman clients will use the facilities of package watchman (such as Client and WatchProject) instead of this package.

Index

• type ClockRequest
  • func (req *ClockRequest) Args() []interface{}
• type ClockResponse
  • func NewClockResponse(pdu ResponsePDU) (res *ClockResponse)
  • func (res *ClockResponse) Clock() string
  • func (r *ClockResponse) PDU() ResponsePDU
  • func (r *ClockResponse) Version() string
  • func (r *ClockResponse) Warning() string
• type Connection
  • func Connect() (*Connection, error)
  • func (c *Connection) Close() error
  • func (c *Connection) HasCapability(capability string) bool
  • func (c *Connection) Recv() (ResponsePDU, error)
  • func (c *Connection) Send(req Request) (err error)
  • func (c *Connection) SockName() string
  • func (c *Connection) Version() string
• type ListCapabilitiesRequest
  • func (req *ListCapabilitiesRequest) Args() []interface{}
• type ListCapabilitiesResponse
  • func NewListCapabilitiesResponse(pdu ResponsePDU) (res *ListCapabilitiesResponse)
  • func (res *ListCapabilitiesResponse) Capabilities() []string
  • func (r *ListCapabilitiesResponse) PDU() ResponsePDU
  • func (r *ListCapabilitiesResponse) Version() string
  • func (r *ListCapabilitiesResponse) Warning() string
• type Request
• type Response
• type ResponsePDU
  • func (pdu ResponsePDU) IsUnilateral() bool
• type ResponseTranslator
• type SubscribeRequest
  • func (req *SubscribeRequest) Args() []interface{}
• type SubscribeResponse
  • func NewSubscribeResponse(pdu ResponsePDU) (res *SubscribeResponse)
  • func (res *SubscribeResponse) Clock() string
  • func (r *SubscribeResponse) PDU() ResponsePDU
  • func (res *SubscribeResponse) Subscription() string
  • func (r *SubscribeResponse) Version() string
  • func (r *SubscribeResponse) Warning() string
• type Subscription
  • func NewSubscription(pdu ResponsePDU) (s *Subscription)
  • func (s *Subscription) Clock() string
  • func (s *Subscription) Files() []interface{}
  • func (s *Subscription) IsFreshInstance() bool
  • func (r *Subscription) PDU() ResponsePDU
  • func (s *Subscription) Root() string
  • func (s *Subscription) Subscription() string
  • func (r *Subscription) Version() string
  • func (r *Subscription) Warning() string
• type UnsubscribeRequest
  • func (req *UnsubscribeRequest) Args() []interface{}
• type UnsubscribeResponse
  • func NewUnsubscribeResponse(pdu ResponsePDU) (res *UnsubscribeResponse)
  • func (res *UnsubscribeResponse) Deleted() bool
  • func (r *UnsubscribeResponse) PDU() ResponsePDU
  • func (res *UnsubscribeResponse) Subscription() string
  • func (r *UnsubscribeResponse) Version() string
  • func (r *UnsubscribeResponse) Warning() string
• type WatchListRequest
  • func (req *WatchListRequest) Args() []interface{}
• type WatchListResponse
  • func NewWatchListResponse(pdu ResponsePDU) (res *WatchListResponse)
  • func (r *WatchListResponse) PDU() ResponsePDU
  • func (res *WatchListResponse) Roots() []string
  • func (r *WatchListResponse) Version() string
  • func (r *WatchListResponse) Warning() string
• type WatchProjectRequest
  • func (req *WatchProjectRequest) Args() []interface{}
• type WatchProjectResponse
  • func NewWatchProjectResponse(pdu ResponsePDU) (res *WatchProjectResponse)
  • func (r *WatchProjectResponse) PDU() ResponsePDU
  • func (res *WatchProjectResponse) RelativePath() string
  • func (r *WatchProjectResponse) Version() string
  • func (r *WatchProjectResponse) Warning() string
  • func (res *WatchProjectResponse) Watch() string
• type WatchmanError
  • func (e *WatchmanError) Error() string

Types

type ClockRequest

type ClockRequest struct {
	Path        string
	SyncTimeout int
}

A ClockRequest represents the Watchman clock command.

See also: https://facebook.github.io/watchman/docs/cmd/clock.html

func (*ClockRequest) Args

func (req *ClockRequest) Args() []interface{}

Args returns values used to encode a request PDU.

type ClockResponse

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

A ClockResponse represents a response to the Watchman clock command.

func NewClockResponse

func NewClockResponse(pdu ResponsePDU) (res *ClockResponse)

NewClockResponse converts a ResponsePDU to ClockResponse

func (*ClockResponse) Clock

func (res *ClockResponse) Clock() string

Clock returns the result of the Watchman clock command.

func (*ClockResponse) PDU

func (r *ClockResponse) PDU() ResponsePDU

func (*ClockResponse) Version

func (r *ClockResponse) Version() string

Version returns the Watchman server version.

func (*ClockResponse) Warning

func (r *ClockResponse) Warning() string

Warning returns a notice from the Watchman server that, if non-empty, should be shown to the user as an advisory so that the system can operate more effectively

type Connection

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

Connection provides a low-level interface to the Watchman service.

func Connect

func Connect() (*Connection, error)

Connect connects to or starts the Watchman server and returns a new Connection.

func (*Connection) Close

func (c *Connection) Close() error

Close closes the connection to the Watchman server.

func (*Connection) HasCapability

func (c *Connection) HasCapability(capability string) bool

HasCapability checks if the Watchman server supports a specific feature.

func (*Connection) Recv

func (c *Connection) Recv() (ResponsePDU, error)

Recv reads and decodes a response PDU from the Watchman server.

func (*Connection) Send

func (c *Connection) Send(req Request) (err error)

Send encodes and sends a request PDU to the Watchman server.

func (*Connection) SockName

func (c *Connection) SockName() string

SockName returns the UNIX domain socket used to communicate with the Watchman server.

func (*Connection) Version

func (c *Connection) Version() string

Version returns the version of the Watchman server.

type ListCapabilitiesRequest

type ListCapabilitiesRequest struct{}

A ListCapabilitiesRequest represents the Watchman list-capabilities command.

See also: https://facebook.github.io/watchman/docs/cmd/list-capabilities.html

func (*ListCapabilitiesRequest) Args

func (req *ListCapabilitiesRequest) Args() []interface{}

Args returns values used to encode a request PDU.

type ListCapabilitiesResponse

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

A ListCapabilitiesResponse represents a response to the Watchman list-capabilities command.

func NewListCapabilitiesResponse

func NewListCapabilitiesResponse(pdu ResponsePDU) (res *ListCapabilitiesResponse)

NewListCapabilitiesResponse converts a ResponsePDU to ListCapabilitiesResponse

func (*ListCapabilitiesResponse) Capabilities

func (res *ListCapabilitiesResponse) Capabilities() []string

Capabilities returns the result of the Watchman list-capabilities command.

func (*ListCapabilitiesResponse) PDU

func (r *ListCapabilitiesResponse) PDU() ResponsePDU

func (*ListCapabilitiesResponse) Version

func (r *ListCapabilitiesResponse) Version() string

Version returns the Watchman server version.

func (*ListCapabilitiesResponse) Warning

func (r *ListCapabilitiesResponse) Warning() string

Warning returns a notice from the Watchman server that, if non-empty, should be shown to the user as an advisory so that the system can operate more effectively

type Request

type Request interface {
	Args() []interface{}
}

Request is the interface used to encode a request PDU.

type Response

type Response interface {
	PDU() ResponsePDU
	Version() string
	Warning() string
}

Response is the interface common to all response PDUs.

type ResponsePDU

type ResponsePDU map[string]interface{}

ResponsePDU provides access to response data decoded to primitive Go values.

func (ResponsePDU) IsUnilateral

func (pdu ResponsePDU) IsUnilateral() bool

IsUnilateral indicates if the ResponsePDU was sent in response to the immediately previous request, or an older request such as the subscribe command.

type ResponseTranslator

type ResponseTranslator func(ResponsePDU) Response

The ResponseTranslator type is an adapter that converts a ResponsePDU to a more exact Response.

type SubscribeRequest

type SubscribeRequest struct {
	Root  string
	Name  string
	Query *query.Query
}

A SubscribeRequest represents the Watchman subscribe command.

See also: https://facebook.github.io/watchman/docs/cmd/subscribe.html

func (*SubscribeRequest) Args

func (req *SubscribeRequest) Args() []interface{}

Args returns values used to encode a request PDU.

type SubscribeResponse

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

A SubscribeResponse represents a response to the Watchman subscribe command.

func NewSubscribeResponse

func NewSubscribeResponse(pdu ResponsePDU) (res *SubscribeResponse)

NewSubscribeResponse converts a ResponsePDU to SubscribeResponse

func (*SubscribeResponse) Clock

func (res *SubscribeResponse) Clock() string

Clock returns a value representing when the subscription started.

func (*SubscribeResponse) PDU

func (r *SubscribeResponse) PDU() ResponsePDU

func (*SubscribeResponse) Subscription

func (res *SubscribeResponse) Subscription() string

Subscription returns the name registered to the subscription.

func (*SubscribeResponse) Version

func (r *SubscribeResponse) Version() string

Version returns the Watchman server version.

func (*SubscribeResponse) Warning

func (r *SubscribeResponse) Warning() string

Warning returns a notice from the Watchman server that, if non-empty, should be shown to the user as an advisory so that the system can operate more effectively

type Subscription

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

A Subscription represents notifications generated as a result of the Watchman subscribe command.

func NewSubscription

func NewSubscription(pdu ResponsePDU) (s *Subscription)

NewSubscription converts a ResponsePDU to Subscription

func (*Subscription) Clock

func (s *Subscription) Clock() string

Clock returns a value representing when the notification was generated.

func (*Subscription) Files

func (s *Subscription) Files() []interface{}

Files returns a list of of relative filepaths.

func (*Subscription) IsFreshInstance

func (s *Subscription) IsFreshInstance() bool

IsFreshInstance indicates if the notification was sent because of a newly established subscription, or observed changes.

func (*Subscription) PDU

func (r *Subscription) PDU() ResponsePDU

func (*Subscription) Root

func (s *Subscription) Root() string

Root returns the directory registered to the subscription.

func (*Subscription) Subscription

func (s *Subscription) Subscription() string

Subscription returns the name registered to the subscription.

func (*Subscription) Version

func (r *Subscription) Version() string

Version returns the Watchman server version.

func (*Subscription) Warning

func (r *Subscription) Warning() string

Warning returns a notice from the Watchman server that, if non-empty, should be shown to the user as an advisory so that the system can operate more effectively

type UnsubscribeRequest

type UnsubscribeRequest struct {
	Root string
	Name string
}

An UnsubscribeRequest represents the Watchman unsubscribe command.

See also: https://facebook.github.io/watchman/docs/cmd/unsubscribe.html

func (*UnsubscribeRequest) Args

func (req *UnsubscribeRequest) Args() []interface{}

Args returns values used to encode a request PDU.

type UnsubscribeResponse

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

An UnsubscribeResponse represents a response to the Watchman unsubscribe command.

func NewUnsubscribeResponse

func NewUnsubscribeResponse(pdu ResponsePDU) (res *UnsubscribeResponse)

NewUnsubscribeResponse converts a ResponsePDU to UnsubscribeResponse

func (*UnsubscribeResponse) Deleted

func (res *UnsubscribeResponse) Deleted() bool

Deleted returns the status of the cancelled subscription.

func (*UnsubscribeResponse) PDU

func (r *UnsubscribeResponse) PDU() ResponsePDU

func (*UnsubscribeResponse) Subscription

func (res *UnsubscribeResponse) Subscription() string

Subscription returns the name registered to the cancelled subscription.

func (*UnsubscribeResponse) Version

func (r *UnsubscribeResponse) Version() string

Version returns the Watchman server version.

func (*UnsubscribeResponse) Warning

func (r *UnsubscribeResponse) Warning() string

Warning returns a notice from the Watchman server that, if non-empty, should be shown to the user as an advisory so that the system can operate more effectively

type WatchListRequest

type WatchListRequest struct{}

A WatchListRequest represents the Watchman watch-list command.

See also: https://facebook.github.io/watchman/docs/cmd/watch-list.html

func (*WatchListRequest) Args

func (req *WatchListRequest) Args() []interface{}

Args returns values used to encode a request PDU.

type WatchListResponse

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

A WatchListResponse represents a response to the Watchman watch-list command.

func NewWatchListResponse

func NewWatchListResponse(pdu ResponsePDU) (res *WatchListResponse)

NewWatchListResponse converts a ResponsePDU to WatchListResponse

func (*WatchListResponse) PDU

func (r *WatchListResponse) PDU() ResponsePDU

func (*WatchListResponse) Roots

func (res *WatchListResponse) Roots() []string

Roots returns the result of the Watchman watch-list command.

func (*WatchListResponse) Version

func (r *WatchListResponse) Version() string

Version returns the Watchman server version.

func (*WatchListResponse) Warning

func (r *WatchListResponse) Warning() string

Warning returns a notice from the Watchman server that, if non-empty, should be shown to the user as an advisory so that the system can operate more effectively

type WatchProjectRequest

type WatchProjectRequest struct {
	Path string
}

A WatchProjectRequest represents the Watchman watch-project command.

See also: https://facebook.github.io/watchman/docs/cmd/watch-project.html

func (*WatchProjectRequest) Args

func (req *WatchProjectRequest) Args() []interface{}

Args returns values used to encode a request PDU.

type WatchProjectResponse

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

A WatchProjectResponse represents a response to the Watchman watch-project command.

func NewWatchProjectResponse

func NewWatchProjectResponse(pdu ResponsePDU) (res *WatchProjectResponse)

NewWatchProjectResponse converts a ResponsePDU to WatchProjectResponse

func (*WatchProjectResponse) PDU

func (r *WatchProjectResponse) PDU() ResponsePDU

func (*WatchProjectResponse) RelativePath

func (res *WatchProjectResponse) RelativePath() string

RelativePath returns the difference between the requested directory and the watched directory actually chosen by the watch-project command.

func (*WatchProjectResponse) Version

func (r *WatchProjectResponse) Version() string

Version returns the Watchman server version.

func (*WatchProjectResponse) Warning

func (r *WatchProjectResponse) Warning() string

Warning returns a notice from the Watchman server that, if non-empty, should be shown to the user as an advisory so that the system can operate more effectively

func (*WatchProjectResponse) Watch

func (res *WatchProjectResponse) Watch() string

Watch returns the watched directory chosen by the watch-project command.

type WatchmanError

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

WatchmanError is returned when the Watchman server responds to a request with an error instead of a normal response.

func (*WatchmanError) Error

func (e *WatchmanError) Error() string