websocket

type Config struct {
	// Endpoint is the path which the websocket server will listen for clients/connections
	// Default value is empty string, if you don't set it the Websocket server is disabled.
	Endpoint string
	// ClientSourcePath is is the path which the client-side
	// will be auto-served when the server adapted to an Iris station.
	// Default value is "/iris-ws.js"
	ClientSourcePath string
	Error            func(w http.ResponseWriter, r *http.Request, status int, reason error)
	CheckOrigin      func(r *http.Request) bool
	// WriteTimeout time allowed to write a message to the connection.
	// 0 means no timeout.
	// Default value is 0
	WriteTimeout time.Duration
	// ReadTimeout time allowed to read a message from the connection.
	// 0 means no timeout.
	// Default value is 0
	ReadTimeout time.Duration
	// PongTimeout allowed to read the next pong message from the connection.
	// Default value is 60 * time.Second
	PongTimeout time.Duration
	// PingPeriod send ping messages to the connection with this period. Must be less than PongTimeout.
	// Default value is 60 *time.Second
	PingPeriod time.Duration
	// MaxMessageSize max message size allowed from connection.
	// Default value is 1024
	MaxMessageSize int64
	// BinaryMessages set it to true in order to denotes binary data messages instead of utf-8 text
	// compatible if you wanna use the Connection's EmitMessage to send a custom binary data to the client, like a native server-client communication.
	// defaults to false
	BinaryMessages bool
	// ReadBufferSize is the buffer size for the underline reader
	// Default value is 4096
	ReadBufferSize int
	// WriteBufferSize is the buffer size for the underline writer
	// Default value is 4096
	WriteBufferSize int
	// IDGenerator used to create (and later on, set)
	// an ID for each incoming websocket connections (clients).
	// The request is an argument which you can use to generate the ID (from headers for example).
	// If empty then the ID is generated by DefaultIDGenerator: randomString(64)
	IDGenerator func(ctx context.Context) string

	// Subprotocols specifies the server's supported protocols in order of
	// preference. If this field is set, then the Upgrade method negotiates a
	// subprotocol by selecting the first match in this list with a protocol
	// requested by the client.
	Subprotocols []string
}

type Connection interface {
	// Emitter implements EmitMessage & Emit
	Emitter
	// ID returns the connection's identifier
	ID() string

	// Context returns the (upgraded) context.Context of this connection
	// avoid using it, you normally don't need it,
	// websocket has everything you need to authenticate the user BUT if it's necessary
	// then  you use it to receive user information, for example: from headers
	Context() context.Context

	// OnDisconnect registers a callback which fires when this connection is closed by an error or manual
	OnDisconnect(DisconnectFunc)
	// OnStatusCode registers a callback which fires when this connection occurs an error
	OnStatusCode(ErrorFunc)
	// FireStatusCode can be used to send a custom error message to the connection
	//
	// It does nothing more than firing the OnStatusCode listeners. It doesn't sends anything to the client.
	FireStatusCode(errorMessage string)
	// To defines where server should send a message
	// returns an emitter to send messages
	To(string) Emitter
	// OnMessage registers a callback which fires when native websocket message received
	OnMessage(NativeMessageFunc)
	// On registers a callback to a particular event which fires when a message to this event received
	On(string, MessageFunc)
	// Join join a connection to a room, it doesn't check if connection is already there, so care
	Join(string)
	// Leave removes a connection from a room
	// Returns true if the connection has actually left from the particular room.
	Leave(string) bool
	// OnLeave registers a callback which fires when this connection left from any joined room.
	// This callback is called automatically on Disconnected client, because websocket server automatically
	// deletes the disconnected connection from any joined rooms.
	//
	// Note: the callback(s) called right before the server deletes the connection from the room
	// so the connection theoretical can still send messages to its room right before it is being disconnected.
	OnLeave(roomLeaveCb LeaveRoomFunc)
	// Disconnect disconnects the client, close the underline websocket conn and removes it from the conn list
	// returns the error, if any, from the underline connection
	Disconnect() error
	// SetValue sets a key-value pair on the connection's mem store.
	SetValue(key string, value interface{})
	// GetValue gets a value by its key from the connection's mem store.
	GetValue(key string) interface{}
	// GetValueArrString gets a value as []string by its key from the connection's mem store.
	GetValueArrString(key string) []string
	// GetValueString gets a value as string by its key from the connection's mem store.
	GetValueString(key string) string
	// GetValueInt gets a value as integer by its key from the connection's mem store.
	GetValueInt(key string) int
}

type ConnectionFunc func(Connection)

type ConnectionValues []connectionValue

type DisconnectFunc func()

type Emitter interface {
	// EmitMessage sends a native websocket message
	EmitMessage([]byte) error
	// Emit sends a message on a particular event
	Emit(string, interface{}) error
}

type ErrorFunc (func(string))

type LeaveRoomFunc func(roomName string)

type MessageFunc interface{}

type NativeMessageFunc func([]byte)

type Server interface {
	// Attach adapts the websocket server to an Iris instance.
	// see websocket.go
	Attach(app *iris.Application)

	// Handler returns the iris.Handler
	// which is setted to the 'Websocket Endpoint path',
	// the client should target to this handler's developer's custom path
	// ex: app.Any("/myendpoint", mywebsocket.Handler())
	Handler() context.Handler

	// OnConnection this is the main event you, as developer, will work with each of the websocket connections
	OnConnection(cb ConnectionFunc)

	// IsConnected returns true if the connection with that ID is connected to the server
	// useful when you have defined a custom connection id generator (based on a database)
	// and you want to check if that connection is already connected (on multiple tabs)
	IsConnected(connID string) bool

	// Join joins a websocket client to a room,
	// first parameter is the room name and the second the connection.ID()
	//
	// You can use connection.Join("room name") instead.
	Join(roomName string, connID string)

	// LeaveAll kicks out a connection from ALL of its joined rooms
	LeaveAll(connID string)

	// Leave leaves a websocket client from a room,
	// first parameter is the room name and the second the connection.ID()
	//
	// You can use connection.Leave("room name") instead.
	// Returns true if the connection has actually left from the particular room.
	Leave(roomName string, connID string) bool

	// GetConnectionsByRoom returns a list of Connection
	// are joined to this room.
	GetConnectionsByRoom(roomName string) []Connection

	// Disconnect force-disconnects a websocket connection
	// based on its connection.ID()
	// What it does?
	// 1. remove the connection from the list
	// 2. leave from all joined rooms
	// 3. fire the disconnect callbacks, if any
	// 4. close the underline connection and return its error, if any.
	//
	// You can use the connection.Disconnect() instead.
	Disconnect(connID string) error
}

type UnderlineConnection interface {
	// SetWriteDeadline sets the write deadline on the underlying network
	// connection. After a write has timed out, the websocket state is corrupt and
	// all future writes will return an error. A zero value for t means writes will
	// not time out.
	SetWriteDeadline(t time.Time) error
	// SetReadDeadline sets the read deadline on the underlying network connection.
	// After a read has timed out, the websocket connection state is corrupt and
	// all future reads will return an error. A zero value for t means reads will
	// not time out.
	SetReadDeadline(t time.Time) error
	// SetReadLimit sets the maximum size for a message read from the peer. If a
	// message exceeds the limit, the connection sends a close frame to the peer
	// and returns ErrReadLimit to the application.
	SetReadLimit(limit int64)
	// SetPongHandler sets the handler for pong messages received from the peer.
	// The appData argument to h is the PONG frame application data. The default
	// pong handler does nothing.
	SetPongHandler(h func(appData string) error)
	// SetPingHandler sets the handler for ping messages received from the peer.
	// The appData argument to h is the PING frame application data. The default
	// ping handler sends a pong to the peer.
	SetPingHandler(h func(appData string) error)
	// WriteControl writes a control message with the given deadline. The allowed
	// message types are CloseMessage, PingMessage and PongMessage.
	WriteControl(messageType int, data []byte, deadline time.Time) error
	// WriteMessage is a helper method for getting a writer using NextWriter,
	// writing the message and closing the writer.
	WriteMessage(messageType int, data []byte) error
	// ReadMessage is a helper method for getting a reader using NextReader and
	// reading from that reader to a buffer.
	ReadMessage() (messageType int, p []byte, err error)
	// NextWriter returns a writer for the next message to send. The writer's Close
	// method flushes the complete message to the network.
	//
	// There can be at most one open writer on a connection. NextWriter closes the
	// previous writer if the application has not already done so.
	NextWriter(messageType int) (io.WriteCloser, error)
	// Close closes the underlying network connection without sending or waiting for a close frame.
	Close() error
}