wsstat

README

go-wsstat

Use the go-wsstat Golang package to trace WebSocket connection and latency in your Go applications. It wraps the gorilla/websocket package for the WebSocket protocol implementation, and measures the duration of the different phases of the connection cycle. The program takes inspiration from the go-httpstat package, which is useful for tracing HTTP requests.

Install

The package is built on Go 1.21 but it has been tested to work with Go 1.18, in case that is of interest. Install to use in your project with go get:

go get github.com/jakobilobi/go-wsstat

Usage

The _example/main.go program demonstrates how to use the go-wsstat package to trace a WebSocket connection.

Run the example:

go run _example/main.go <a WebSocket URL>

Run the tests:

make test

Documentation

Overview

Package wsstat measures the latency of WebSocket connections. It wraps the gorilla/websocket package and includes latency measurements in the Result struct.

Index

• func SetCustomTLSConfig(config *tls.Config)
• func SetDialTimeout(timeout time.Duration)
• func SetLogLevel(level zerolog.Level)
• func SetLogger(l zerolog.Logger)
• type CertificateDetails
• type Result
  • func MeasureLatency(url *url.URL, msg string, customHeaders http.Header) (Result, []byte, error)
  • func MeasureLatencyJSON(url *url.URL, v interface{}, customHeaders http.Header) (Result, interface{}, error)
  • func MeasureLatencyPing(url *url.URL, customHeaders http.Header) (Result, error)
  • func (r *Result) CertificateDetails() []CertificateDetails
  • func (r Result) Format(s fmt.State, verb rune)
• type WSStat
  • func NewWSStat() *WSStat
  • func (ws *WSStat) CloseConn() error
  • func (ws *WSStat) Dial(url *url.URL, customHeaders http.Header) error
  • func (ws *WSStat) ReadMessage(writeStart time.Time) (int, []byte, error)
  • func (ws *WSStat) SendMessage(messageType int, data []byte) ([]byte, error)
  • func (ws *WSStat) SendMessageBasic() error
  • func (ws *WSStat) SendMessageJSON(v interface{}) (interface{}, error)
  • func (ws *WSStat) SendPing() error
  • func (ws *WSStat) WriteMessage(messageType int, data []byte) (time.Time, error)

Functions

func SetCustomTLSConfig

func SetCustomTLSConfig(config *tls.Config)

SetCustomTLSConfig allows users to provide their own TLS configuration. Pass nil to use default settings.

func SetDialTimeout

func SetDialTimeout(timeout time.Duration)

SetDialTimeout sets the dial timeout for WSStat.

func SetLogLevel

func SetLogLevel(level zerolog.Level)

SetLogLevel sets the log level for WSStat.

func SetLogger

func SetLogger(l zerolog.Logger)

SetLogger sets the logger for WSStat.

Types

type CertificateDetails

type CertificateDetails struct {
	CommonName         string
	Issuer             string
	NotBefore          time.Time
	NotAfter           time.Time
	PublicKeyAlgorithm x509.PublicKeyAlgorithm
	SignatureAlgorithm x509.SignatureAlgorithm
	DNSNames           []string
	IPAddresses        []net.IP
	URIs               []*url.URL
}

CertificateDetails holds details regarding a certificate.

type Result

type Result struct {
	IPs []string // IP addresses of the WebSocket connection
	URL url.URL  // URL of the WebSocket connection

	// Duration of each phase of the connection
	DNSLookup        time.Duration // Time to resolve DNS
	TCPConnection    time.Duration // TCP connection establishment time
	TLSHandshake     time.Duration // Time to perform TLS handshake
	WSHandshake      time.Duration // Time to perform WebSocket handshake
	MessageRoundTrip time.Duration // Time to send message and receive response
	ConnectionClose  time.Duration // Time to close the connection (complete the connection lifecycle)

	// Cumulative durations over the connection timeline
	DNSLookupDone        time.Duration // Time to resolve DNS (might be redundant with DNSLookup)
	TCPConnected         time.Duration // Time until the TCP connection is established
	TLSHandshakeDone     time.Duration // Time until the TLS handshake is completed
	WSHandshakeDone      time.Duration // Time until the WS handshake is completed
	FirstMessageResponse time.Duration // Time until the first message is received
	TotalTime            time.Duration // Total time from opening to closing the connection

	// Other connection details
	RequestHeaders  http.Header          // Headers of the initial request
	ResponseHeaders http.Header          // Headers of the response
	TLSState        *tls.ConnectionState // State of the TLS connection
}

Result holds durations of each phase of a WebSocket connection, cumulative durations over the connection timeline, and other relevant connection details.

func MeasureLatency

func MeasureLatency(url *url.URL, msg string, customHeaders http.Header) (Result, []byte, error)

MeasureLatency establishes a WebSocket connection, sends a message, reads the response, and closes the connection. Returns the Result and the response message. Sets all times in the Result object.

func MeasureLatencyJSON

func MeasureLatencyJSON(url *url.URL, v interface{}, customHeaders http.Header) (Result, interface{}, error)

MeasureLatencyJSON establishes a WebSocket connection, sends a JSON message, reads the response, and closes the connection. Returns the Result and the response message. Sets all times in the Result object.

func MeasureLatencyPing

func MeasureLatencyPing(url *url.URL, customHeaders http.Header) (Result, error)

MeasureLatencyPing establishes a WebSocket connection, sends a ping message, awaits the pong response, and closes the connection. Returns the Result. Sets all times in the Result object.

func (*Result) CertificateDetails

func (r *Result) CertificateDetails() []CertificateDetails

CertificateDetails returns a slice of CertificateDetails for each certificate in the TLS connection.

func (Result) Format

func (r Result) Format(s fmt.State, verb rune)

Format formats the time.Duration members of Result.

type WSStat

type WSStat struct {
	Result *Result
	// contains filtered or unexported fields
}

WSStat wraps the gorilla/websocket package and includes latency measurements in Result.

func NewWSStat

func NewWSStat() *WSStat

NewWSStat creates and returns a new WSStat instance.

func (*WSStat) CloseConn

func (ws *WSStat) CloseConn() error

CloseConn closes the WebSocket connection and measures the time taken to close the connection. Sets result times: ConnectionClose, TotalTime

func (*WSStat) Dial

func (ws *WSStat) Dial(url *url.URL, customHeaders http.Header) error

Dial establishes a new WebSocket connection using the custom dialer defined in this package. If required, specify custom headers to merge with the default headers. Sets result times: WSHandshake, WSHandshakeDone

func (*WSStat) ReadMessage

func (ws *WSStat) ReadMessage(writeStart time.Time) (int, []byte, error)

ReadMessage reads a message from the WebSocket connection and measures the round-trip time. Wraps the gorilla/websocket ReadMessage method. Sets result times: MessageRoundTrip, FirstMessageResponse Requires that a timer has been started with WriteMessage to measure the round-trip time.

func (*WSStat) SendMessage

func (ws *WSStat) SendMessage(messageType int, data []byte) ([]byte, error)

SendMessage sends a message through the WebSocket connection and measures the round-trip time. Wraps the gorilla/websocket WriteMessage and ReadMessage methods. Sets result times: MessageRoundTrip, FirstMessageResponse

func (*WSStat) SendMessageBasic

func (ws *WSStat) SendMessageBasic() error

SendMessageBasic sends a basic message through the WebSocket connection and measures the round-trip time. Wraps the gorilla/websocket WriteMessage and ReadMessage methods. Sets result times: MessageRoundTrip, FirstMessageResponse

func (*WSStat) SendMessageJSON

func (ws *WSStat) SendMessageJSON(v interface{}) (interface{}, error)

SendMessageJSON sends a message through the WebSocket connection and measures the round-trip time. Wraps the gorilla/websocket WriteJSON and ReadJSON methods. Sets result times: MessageRoundTrip, FirstMessageResponse

func (*WSStat) SendPing

func (ws *WSStat) SendPing() error

SendPing sends a ping message through the WebSocket connection and measures the round-trip time until the pong response. Wraps the gorilla/websocket SetPongHandler and WriteMessage methods. Sets result times: MessageRoundTrip, FirstMessageResponse

func (*WSStat) WriteMessage

func (ws *WSStat) WriteMessage(messageType int, data []byte) (time.Time, error)

WriteMessage sends a message through the WebSocket connection and starts a timer to measure the round-trip time. Wraps the gorilla/websocket WriteMessage method.