protocol

Documentation

Index

• Constants
• Variables
• func Write(ctx context.Context, c APIConn, api API, id string, payload interface{}) error
• type API
• type APIConn
• type Authenticator
• type Command
  • func Read(ctx context.Context, c APIConn, api API) (Command, string, interface{}, error)
• type Conn
  • func NewConn(urlStr string, authenticator Authenticator) (*Conn, error)
  • func (ac *Conn) Call(ctx context.Context, api API, payload interface{}) (Command, string, interface{}, error)
  • func (ac *Conn) Close() error
  • func (ac *Conn) CloseStatus(code websocket.StatusCode, reason string) error
  • func (ac *Conn) Connect(ctx context.Context) error
  • func (ac *Conn) IsOnline() bool
  • func (ac *Conn) Read(ctx context.Context, api API) (Command, string, interface{}, error)
  • func (ac *Conn) ReadJSON(ctx context.Context, v any) error
  • func (ac *Conn) Write(ctx context.Context, api API, id string, payload interface{}) error
  • func (ac *Conn) WriteJSON(ctx context.Context, v any) error
• type Error
  • func Errorf(msg string, args ...interface{}) *Error
  • func (e Error) String() string
• type HandshakeError
  • func (he HandshakeError) Error() string
  • func (he HandshakeError) Is(target error) bool
• type Header
• type Message
• type PingRequest
• type PingResponse
• type WSConn
  • func NewWSConn(conn *websocket.Conn) *WSConn
  • func (wsc *WSConn) Close() error
  • func (wsc *WSConn) CloseStatus(code websocket.StatusCode, reason string) error
  • func (wsc *WSConn) ReadJSON(ctx context.Context, v any) error
  • func (wsc *WSConn) WriteJSON(ctx context.Context, v any) error

Constants

const (
	WSConnectTimeout   = 20 * time.Second
	WSHandshakeTimeout = 15 * time.Second
)

const (
	StatusHandshakeErr websocket.StatusCode = 4100 // XXX can we just hijack 4100?
)

Variables

var ErrInvalidCommand = errors.New("invalid command")

var PublicKeyAuthError = websocket.CloseError{
	Code:   StatusHandshakeErr,
	Reason: HandshakeError("invalid public key").Error(),
}

Functions

func Write

func Write(ctx context.Context, c APIConn, api API, id string, payload interface{}) error

Write encodes and sends a payload over the API connection.

Types

type API

type API interface {
	Commands() map[Command]reflect.Type
}

type APIConn

type APIConn interface {
	ReadJSON(ctx context.Context, v any) error
	WriteJSON(ctx context.Context, v any) error
}

APIConn provides an API connection.

type Authenticator

type Authenticator interface {
	HandshakeClient(ctx context.Context, ac APIConn) error
	HandshakeServer(ctx context.Context, ac APIConn) error
}

Authenticator implements authentication between a client and a server.

type Command

type Command string

func Read

func Read(ctx context.Context, c APIConn, api API) (Command, string, interface{}, error)

type Conn

type Conn struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Conn is a client side connection.

func NewConn

func NewConn(urlStr string, authenticator Authenticator) (*Conn, error)

NewConn returns a client side connection object.

func (*Conn) Call

func (ac *Conn) Call(ctx context.Context, api API, payload interface{}) (Command, string, interface{}, error)

Call is a blocking call that returns the command, id and unmarshaled payload.

func (*Conn) Close

func (ac *Conn) Close() error

Close close a websocket connection with normal status.

func (*Conn) CloseStatus

func (ac *Conn) CloseStatus(code websocket.StatusCode, reason string) error

CloseStatus close the connection with the provided StatusCode.

func (*Conn) Connect

func (ac *Conn) Connect(ctx context.Context) error

func (*Conn) IsOnline

func (ac *Conn) IsOnline() bool

func (*Conn) Read

func (ac *Conn) Read(ctx context.Context, api API) (Command, string, interface{}, error)

Read reads and returns the next command from the API connection.

func (*Conn) ReadJSON

func (ac *Conn) ReadJSON(ctx context.Context, v any) error

ReadJSON returns JSON of the wire and unmarshals it into v.

func (*Conn) Write

func (ac *Conn) Write(ctx context.Context, api API, id string, payload interface{}) error

Write encodes and sends a payload over the API connection.

func (*Conn) WriteJSON

func (ac *Conn) WriteJSON(ctx context.Context, v any) error

WriteJSON writes marshals v and writes it to the wire.

type Error

type Error struct {
	Timestamp int64  `json:"timestamp"`
	Trace     string `json:"trace"`
	Message   string `json:"error"`
}

Error is a protocol Error type that can be used for additional error context. It embeds an 8 byte number that can be used to trace calls on both the client and server side.

func Errorf

func Errorf(msg string, args ...interface{}) *Error

Errorf is a client induced protocol error (e.g. "invalid height"). This is a pretty printable error on the client and server and is not fatal.

func (Error) String

func (e Error) String() string

type HandshakeError

type HandshakeError string

func (HandshakeError) Error

func (he HandshakeError) Error() string

func (HandshakeError) Is

func (he HandshakeError) Is(target error) bool

type Header

type Header struct {
	Command Command `json:"command"`      // Command to execute
	ID      string  `json:"id,omitempty"` // Command identifier
}

Header prefixes all websocket commands.

type Message

type Message struct {
	Header  Header          `json:"header"`
	Payload json.RawMessage `json:"payload"`
}

Message represents a websocket message.

type PingRequest

type PingRequest struct {
	Timestamp int64 `json:"timestamp"` // Local timestamp
}

Ping

type PingResponse

type PingResponse struct {
	OriginTimestamp int64 `json:"origintimestamp"` // Timestamp from origin
	Timestamp       int64 `json:"timestamp"`       // Local timestamp
}

PingResponse

type WSConn

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

func NewWSConn

func NewWSConn(conn *websocket.Conn) *WSConn

func (*WSConn) Close

func (wsc *WSConn) Close() error

func (*WSConn) CloseStatus

func (wsc *WSConn) CloseStatus(code websocket.StatusCode, reason string) error

func (*WSConn) ReadJSON

func (wsc *WSConn) ReadJSON(ctx context.Context, v any) error

func (*WSConn) WriteJSON

func (wsc *WSConn) WriteJSON(ctx context.Context, v any) error