README
¶
WebSocket Library by aah framework
v0.1.0 released and tagged on TBD
It uses tiny, efficient WebSocket library github.com/gobwas/ws, RFC 6455 implementation.
Installation
# install the library
go get -u aahframework.org/ws.v0
Visit official website https://aahframework.org to learn more.
Documentation
¶
Overview ¶
Package ws is a WebSocket library for aah framework.
It uses tiny, efficient WebSocket library `github.com/gobwas/ws`, RFC 6455 implementation.
Index ¶
- Constants
- Variables
- func IsDisconnected(err error) bool
- type AuthCallbackFunc
- type Context
- func (ctx *Context) Disconnect() error
- func (ctx *Context) ErrorReason() error
- func (ctx *Context) Log() log.Loggerer
- func (ctx *Context) ReadBinary() ([]byte, error)
- func (ctx *Context) ReadJSON(t interface{}) error
- func (ctx *Context) ReadText() (string, error)
- func (ctx *Context) ReadXML(t interface{}) error
- func (ctx *Context) ReplyBinary(v []byte) error
- func (ctx *Context) ReplyJSON(v interface{}) error
- func (ctx *Context) ReplyText(v string) error
- func (ctx *Context) ReplyXML(v interface{}) error
- type Engine
- func (e *Engine) AddWebSocket(t interface{}, methods []*ainsp.Method)
- func (e *Engine) CallAction(ctx *Context)
- func (e *Engine) Connect(w http.ResponseWriter, r *http.Request, route *router.Route, ...) (*Context, error)
- func (e *Engine) Log() log.Loggerer
- func (e *Engine) OnError(ecf EventCallbackFunc)
- func (e *Engine) OnPostConnect(ecf EventCallbackFunc)
- func (e *Engine) OnPostDisconnect(ecf EventCallbackFunc)
- func (e *Engine) OnPreConnect(ecf EventCallbackFunc)
- func (e *Engine) ReplyError(w http.ResponseWriter, errCode int)
- func (e *Engine) SetAuthCallback(ac AuthCallbackFunc)
- type EventCallbackFunc
- type Request
Constants ¶
const ( // EventOnPreConnect event published right before the aah tries establish a // WebSocket connection with client. EventOnPreConnect = "OnPreConnect" // EventOnPostConnect event published right after the successful WebSocket // connection have been established with aah server. EventOnPostConnect = "OnPostConnect" // EventOnPostDisconnect event published when client disconnects either // gracefully, gone, network connection error, etc. EventOnPostDisconnect = "OnPostDisconnect" // EventOnError event published when any errors, auth error, failures while // establishing WebSocket connection, etc. EventOnError = "OnError" )
const Version = "0.1.0"
Version no. of WebSocket library by aah framework
Variables ¶
var ( ErrOriginMismatch = errors.New("aahws: origin mismatch") ErrParameterParseFailed = errors.New("aahws: parameter parse failed") ErrAuthenticationFailed = errors.New("aahws: authentication failed") ErrWebSocketNotFound = errors.New("aahws: not found") ErrWebSocketConnectFailed = errors.New("aahws: connect failed") ErrConnectionClosed = errors.New("aahws: connection closed") ErrUseOfClosedConnection = errors.New("aahws: use of closed ws connection") )
WebSocket errors
Functions ¶
func IsDisconnected ¶
Types ¶
type AuthCallbackFunc ¶
AuthCallbackFunc func type used for WebSocket authentication.
type Context ¶
type Context struct {
Req *Request
Conn net.Conn
Header http.Header
// contains filtered or unexported fields
}
Context struct holds friendly WebSocket implementation for aah framework.
func (*Context) Disconnect ¶
Disconnect method disconnects the WebSocket connection immediately. Could be used for force disconnect client from server-side.
Note: After this call, any read/reply will result in error. Since connection already closed from server side.
func (*Context) ErrorReason ¶
ErrorReason method returns error info if error was occurred otherwise nil.
func (*Context) Log ¶
func (ctx *Context) Log() log.Loggerer
Log method adds field WebSocket `Request ID` into current log context and returns the logger.
func (*Context) ReadBinary ¶
ReadBinary method reads a binary data from WebSocket client.
func (*Context) ReadJSON ¶
ReadJSON method reads JSON data from WebSocket client and does unmarshal into given object.
func (*Context) ReadXML ¶
ReadXML method reads XML data from WebSocket client and does unmarshal into given object.
func (*Context) ReplyBinary ¶
ReplyBinary method sends Binary data to the WebSocket client returns error if client is gone, network error, etc.
func (*Context) ReplyJSON ¶
ReplyJSON method sends JSON data to the WebSocket client returns error if json marshal issue, client is gone, network issue, etc.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine struct holds the implementation of managing WebSocket for aah framework.
func (*Engine) AddWebSocket ¶
func (e *Engine) AddWebSocket(t interface{}, methods []*ainsp.Method)
AddWebSocket method adds the given WebSocket implementation into engine.
func (*Engine) CallAction ¶
CallAction method calls the defined action for the WebSocket.
func (*Engine) Connect ¶
func (e *Engine) Connect(w http.ResponseWriter, r *http.Request, route *router.Route, pathParams ahttp.PathParams) (*Context, error)
Connect method primarily does upgrades HTTP connection into WebSocket connection.
Along with Check Origin, Authentication Callback and aah WebSocket events such as `OnPreConnect`, `OnPostConnect`, `OnPostDisconnect` and `OnError`.
func (*Engine) Log ¶
func (e *Engine) Log() log.Loggerer
Log method provides logging methods at WebSocket engine.
func (*Engine) OnError ¶
func (e *Engine) OnError(ecf EventCallbackFunc)
OnError method sets WebSocket `OnError` event callback into WebSocket engine.
Event published for mismatch origin, action parameter parse error, authentication failure, websocket initial connection failure, websocket not found.
func (*Engine) OnPostConnect ¶
func (e *Engine) OnPostConnect(ecf EventCallbackFunc)
OnPostConnect method sets WebSocket `OnPostConnect` event callback into WebSocket engine.
Event published after each WebSocket connection successfully established.
func (*Engine) OnPostDisconnect ¶
func (e *Engine) OnPostDisconnect(ecf EventCallbackFunc)
OnPostDisconnect method sets WebSocket `OnPostDisconnect` event callback into WebSocket engine.
Event published after each WebSocket connection is disconncted from aah server such as client disconnct, connection interrupted, etc.
func (*Engine) OnPreConnect ¶
func (e *Engine) OnPreConnect(ecf EventCallbackFunc)
OnPreConnect method sets WebSocket `OnPreConnect` event callback into WebSocket engine.
Event published before each WebSocket connection been established.
func (*Engine) ReplyError ¶
func (e *Engine) ReplyError(w http.ResponseWriter, errCode int)
ReplyError method writes HTTP error response.
func (*Engine) SetAuthCallback ¶
func (e *Engine) SetAuthCallback(ac AuthCallbackFunc)
SetAuthCallback method sets the WebSocket authentication callback. It gets called for every WebSocket connection.
Authentication callback function should return true for success otherwise false.
type EventCallbackFunc ¶
EventCallbackFunc func type used for all WebSocket event callback.
type Request ¶
type Request struct {
// ID aah assigns Globally Unique Identifier (GUID) using Mongo Object ID
// algorithm for every WebSocket connection made to aah server.
//
// You may use it for tracking, tracing or identifying WebSocket client.
ID string
// Host value of the HTTP 'Host' header (e.g. 'example.com:8080').
Host string
// Path the request URL Path e.g. `/chatroom/aahframework`.
Path string
// Header holds the values of HTTP headers when WebSocket connection made.
Header http.Header
// contains filtered or unexported fields
}
Request struct holds information for successful WebSocket connection made.
func (*Request) ClientIP ¶
ClientIP method returns remote Client IP address aka Remote IP. It parses in the order of given set of headers otherwise it uses default default header set `X-Forwarded-For`, `X-Real-IP`, "X-Appengine-Remote-Addr" and finally `http.Request.RemoteAddr`.
func (*Request) PathValue ¶
PathValue method returns value for given Path param key otherwise empty string. For eg.: `/discussion/:roomName` => `PathValue("roomName")`.
func (*Request) QueryArrayValue ¶
QueryArrayValue method returns array value for given URL query param key otherwise empty string slice.
func (*Request) QueryValue ¶
QueryValue method returns value for given URL query param key otherwise empty string.
Source Files