websocket

Documentation

Overview

Pine's websocket package is a websocket server that supports multiple channels This feature is experimental and may change in the future. Please use it with caution and at your own risk.

Pine's websocket package is a websocket server that supports multiple channels This feature is experimental and may change in the future. Please use it with caution and at your own risk.

Index

• Variables
• func Managed(config ...Config) pine.Handler
• func New(handler func(conn *Conn, ctx *pine.Ctx), config ...Config) pine.Handler
• func WatchFile(path string, conn *Conn) error
• type Channel
  • func (c *Channel) Broadcast()
  • func (c *Channel) MoveClientToChannel(client *Client, newChannel *Channel) error
  • func (c *Channel) RemoveClientFromChannel(clientId uuid.UUID)
• type Client
• type Config
• type Conn
• type ConnectionTree
  • func (c *ConnectionTree) RemoveClient(clientID uuid.UUID)

Variables

var (
	ReconnectTimeout = 5 * time.Second
	WriteWait        = 10 * time.Second
	PongWait         = 60 * time.Second
	PingPeriod       = (PongWait * 9) / 10
	MaxRetryAttempts = 5
)

var RunTimeTree = ConnectionTree{
	Channels: make(map[uuid.UUID]*Channel),
	Clients:  make(map[uuid.UUID]Client),
}

Functions

func Managed

func Managed(config ...Config) pine.Handler

This is the main function to use to create a new websocket connection Use this function if the Type is set to "managed" This function is experimental and may change in the future

The managed method is managed by Pine's runtime for efficiency Each connection is linked to a channel and a client You can move clients to different channels for example in a chat application Instead of managing all new connections manually, you can use the channel ID of the connection to move the client to a different channel

func New

func New(handler func(conn *Conn, ctx *pine.Ctx), config ...Config) pine.Handler

Called to open a new connection and upgrade it to a websocket connection this is the main function to use to create a new websocket connection Use this function if the Type is set to "self"

func WatchFile

func WatchFile(path string, conn *Conn) error

This is an experimental feature and may change in the future WatchFile is used to watch a file for changes and send the changes to the client This is particularly useful for live streaming of files

If you notice performance issues as you try to stream files please use a different method to stream files WatchFile is not recommended for streaming large files

WatchFile automatically handles file changes but may not be suited for fast changes and may lead to performance issues TODO: Improve performance and add support for fast changes

Types

type Channel

type Channel struct {
	ID      uuid.UUID
	Clients []*Client
	Message chan []byte
	CM      sync.Mutex
}

func (*Channel) Broadcast

func (c *Channel) Broadcast()

used to broadcast a message to all clients in the channel avoid calling this function manually as it is called automatically during the managed function runtime

func (*Channel) MoveClientToChannel

func (c *Channel) MoveClientToChannel(client *Client, newChannel *Channel) error

used to move a client to a new channel Use this function to move a client to a new channel especially when you want to when you want to manually move a client to a new channel

Example: You want to move a client to a new channel when a user joins a chat room

func (*Channel) RemoveClientFromChannel

func (c *Channel) RemoveClientFromChannel(clientId uuid.UUID)

used to remove a client from a channel avoid using this to manually remove clients

when a client disconnects, it is automatically removed from the channel no need to call this function manually

type Client

type Client struct {
	Conn    *websocket.Conn
	Channel *Channel
	Id      uuid.UUID
	IP      string
	Send    chan []byte
}

type Config

type Config struct {
	// ReadBufferSize and WriteBufferSize specify I/O buffer sizes in bytes. If a buffer
	// size is zero, then buffers allocated by the HTTP server are used. The
	// I/O buffer sizes do not limit the size of the messages that can be sent
	// or received.
	ReadBufferSize, WriteBufferSize int

	// Subprotocols specifies the server's supported protocols in order of
	// preference. If this field is not nil, then the Upgrade method negotiates a
	// subprotocol by selecting the first match in this list with a protocol
	// requested by the client. If there's no match, then no protocol is
	// negotiated (the Sec-Websocket-Protocol header is not included in the
	// handshake response).
	SubprotocolsAllowed []string

	// CheckOrigin returns true if the request Origin header is acceptable. If
	// CheckOrigin is nil, then a safe default is used: return false if the
	// Origin request header is present and the origin host is not equal to
	// request Host header.
	//
	// A CheckOrigin function should carefully validate the request origin to
	// prevent cross-site request forgery.
	CheckOrigin func(r *http.Request) bool

	// Error specifies the function for generating HTTP error responses. If Error
	// is nil, then http.Error is used to generate the HTTP response.
	Error func(w http.ResponseWriter, r *http.Request, status int, reason error)

	// EnableCompression specify if the server should attempt to negotiate per
	// message compression (RFC 7692). Setting this value to true does not
	// guarantee that compression will be supported. Currently only "no context
	// takeover" modes are supported.
	EnableCompression bool

	// HandshakeTimeout specifies the duration for the handshake to complete.
	HandshakeTimeout time.Duration

	// This defines the the type of connection you wish to create
	// it can be "self" or "managed"
	// if you set it to "self" you will need to use the New function to open a
	// new connection
	// if you set it to "managed" you will need to use the Managed function to open a
	// new connection
	//
	// default is "self"
	// Please not that "managed" is experimental and may change in the future
	Type string
}

Config is a struct that holds the configuration for the websocket server

type Conn

type Conn struct {
	*websocket.Conn
	// contains filtered or unexported fields
}

Conn is a struct that holds the websocket connection

type ConnectionTree

type ConnectionTree struct {
	Channels map[uuid.UUID]*Channel
	Clients  map[uuid.UUID]Client
	CM       sync.RWMutex
}

func (*ConnectionTree) RemoveClient

func (c *ConnectionTree) RemoveClient(clientID uuid.UUID)

used to remove a client from the connection tree avoid using this to manually remove clients use MoveClientToChannel instead