websocket

type CloseCode uint16

type ConnectionCloseError interface {
	net.Error
	Code() CloseCode
	Msg() []byte
}

type ConnectionState string

type Dialer struct {
	// Origin should be contained for a web browser.
	Origin string
	// Protocol contains the sub-protocols to use.
	// server may choose one or none from them.
	Protocol []string
	// Extensions are websocket extensions to use.
	// server should support all of them.
	Extensions []string

	// Header contains original headers in the handshake request.
	Header http.Header

	// NetDialer is the net dialer for the connection,
	// defaults to tls.NetDialer for "wss" scheme and net.NetDialer for "ws".
	NetDialer NetDialer
}

type Message struct {
	// Op is the Opcode of the message(the Opcode of the first frame).
	//
	// rfc 6455: section 5.2
	Op Opcode
	// Len indicates the content-length of the message(the total payload length of all frames).
	Len int64

	// Data is the message content(concatenate the payload of all frames).
	Data []byte
}

type NetDialer interface {
	Dial(network string, addr string) (net.Conn, error)
	DialContext(ctx context.Context, network string, addr string) (net.Conn, error)
}

type Opcode uint8

type ServerConfig struct {
	// Protocol contains protocols the server support.
	// May choose one of them for each connect request.
	Protocol []string
	// Extensions contains extensions the server support.
	// for each connection request, server should support all the client extensions.
	Extensions []string
}

type WebSocket interface {
	// State returns the state of the websocket connection.
	State() ConnectionState
	// Extensions returns extensions used by the websocket connection.
	Extensions() []string
	// Protocol returns the sub-protocol used by the websocket connection.
	Protocol() string

	// RecvCtx waits for a websocket message, and parses it into Message.
	// Frames with OpPing will be responded with a frame with OpPong.
	// When receiving a frame with OpConnectionClose, the close response
	// will be sent and returns ConnectionCloseError instead of Message.
	RecvCtx(ctx context.Context) (msg Message, err error)
	// Recv works like WebSocket.RecvCtx but discards the frame metadata.
	Recv() (data []byte, err error)

	// SendCtx sends a message to the connection.
	SendCtx(ctx context.Context, msg Message) (err error)
	// Send sends a message with OpBinaryFrame to the connection.
	Send(data []byte) (err error)
	// SendText sends a message with OpTextFrame to the connection.
	SendText(txt string) (err error)
	// Ping sends a frame with OpPing to the connection and waits for the next frame,
	// typically a frame with OpPong, parses it and returns its body.
	Ping() (resp []byte, err error)

	// CloseMsg sends CloseCode and msg by a frame with OpConnectionClose, waits for the response and closes the underlying
	// net.Conn. It does nothing if WebSocket is already closed or is closing.
	// The return value is nil(when it does nothing) or ConnectCloseError. Unwarp to get the error
	// occurred during closing(the close code must be AbnormalClosure in this case).
	CloseMsg(msg []byte, code CloseCode) (err error)
	// Close works like CloseMsg but with NormalClosure as CloseCode and NormalClosure.String() as msg.
	Close() (err error)
}