protocol

README

👉 RPC Protocol

The RPC protocol used by Hemi's daemons is WebSocket-based and uses JSON-encoded requests/responses.

The JSON data sent over WebSocket connections are referred to as "messages".

📩 Message Format

An RPC message has the following format:

{
  "header": {
    "command": "command-name",
    "id": "request-id"
  },
  "payload": null
}

Header

The message header contains metadata required for processing the message:

• command: The name of the command being executed.
• id: A string used to uniquely identify each request. Responses will have the same id as the request, making it possible to match requests to responses.

Payload

The payload type depends on the command being called. Please refer to the documentation for more details on the specific API you wish to use.

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, opts *ConnOptions) (*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 ConnOptions
• type Error
  • func Errorf(msg string, args ...interface{}) *Error
  • func RequestError(err error) *Error
  • func RequestErrorf(msg string, args ...any) *Error
  • func (e Error) Error() string
  • func (e Error) String() string
• type HandshakeError
  • func (he HandshakeError) Error() string
  • func (he HandshakeError) Is(target error) bool
• type Header
• type InternalError
  • func NewInternalError(err error) *InternalError
  • func NewInternalErrorf(msg string, args ...interface{}) *InternalError
  • func (ie InternalError) Error() string
  • func (ie InternalError) ProtocolError() *Error
  • func (ie InternalError) Unwrap() error
• 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, opts *ConnOptions) (*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 closes 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 ConnOptions

type ConnOptions struct {
	// ReadLimit is the maximum number of bytes to read from the connection.
	// Defaults to defaultConnReadLimit.
	ReadLimit int64

	// Authenticator is the connection authenticator.
	Authenticator Authenticator

	// Headers are the HTTP headers included in the WebSocket handshake request.
	Headers http.Header
}

ConnOptions are options available for a Conn.

type Error

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

Error is a protocol error type that is used to provide additional error information between a server and client.

A unique "trace" string may be embedded, which can be used to trace errors between a server and client.

func Errorf

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

Errorf returns a protocol Error type with an embedded trace.

func RequestError

func RequestError(err error) *Error

RequestError wraps an error to create a protocol request error.

Request errors are usually something caused by a client, e.g. validation or input errors, and therefore should not be logged server-side and do not contain an embedded trace.

func RequestErrorf

func RequestErrorf(msg string, args ...any) *Error

RequestErrorf creates a new protocol request error.

Request errors are usually something caused by a client, e.g. validation or input errors, and therefore should not be logged server-side and do not contain an embedded trace.

func (Error) Error

func (e Error) Error() string

func (Error) String

func (e Error) String() string

String pretty prints a protocol error.

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 InternalError

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

InternalError represents an internal application error.

Internal errors are errors that occurred within the application and are not caused by a client (e.g. validation or input errors). The actual error message should not be sent to clients, as it is internal to the application, and may be server-operator specific.

func NewInternalError

func NewInternalError(err error) *InternalError

NewInternalError returns an InternalError wrapping the given error.

func NewInternalErrorf

func NewInternalErrorf(msg string, args ...interface{}) *InternalError

NewInternalErrorf returns an InternalError constructed from the passed message and arguments.

func (InternalError) Error

func (ie InternalError) Error() string

Error satisfies the error interface.

func (InternalError) ProtocolError

func (ie InternalError) ProtocolError() *Error

ProtocolError returns the protocol error representation. This error is intended to be sent to clients.

func (InternalError) Unwrap

func (ie InternalError) Unwrap() error

Unwrap returns the error wrapped by this internal error.

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