aahframe.work: aahframe.work/ws Index | Files

package ws

import "aahframe.work/ws"

Package ws is a WebSocket library for aah framework (RFC 6455 compliant).

aah ws internally it uses tiny, efficient WebSocket library (http://github.com/gobwas/ws) developed by Sergey Kamardin (https://github.com/gobwas).

Index

Package Files

context.go engine.go request.go util.go ws.go

Constants

const (
    // EventOnPreConnect event published before connection gets upgraded to WebSocket.
    // It provides a control of accepting incoming request or reject it
    // using ctx.Abort(errorCode).
    EventOnPreConnect = "OnPreConnect"

    // EventOnPostConnect event published right after the successful WebSocket
    // connection which is established with the aah server.
    EventOnPostConnect = "OnPostConnect"

    // EventOnPostDisconnect event published right after the WebSocket client
    // got disconnected. It could have occurred due to graceful disconnect,
    // network related error, etc.
    EventOnPostDisconnect = "OnPostDisconnect"

    // EventOnError event published whenever error occurs in the lifecycle
    // such as Origin Check failed, WebSocket/WebSocket Action not found,
    // WebSocket Action parameter parse error, and WebSocket upgrade fails.
    //
    //`ctx.ErrorReason()` method can be called to know the reason for the error.
    EventOnError = "OnError"
)

Variables

var (
    ErrOriginMismatch        = errors.New("aahws: origin mismatch")
    ErrParameterParseFailed  = errors.New("aahws: parameter parse failed")
    ErrNotFound              = errors.New("aahws: not found")
    ErrConnectFailed         = errors.New("aahws: connect failed")
    ErrAbortRequest          = errors.New("aahws: abort request")
    ErrConnectionClosed      = errors.New("aahws: connection closed")
    ErrUseOfClosedConnection = errors.New("aahws: use of closed ws connection")
)

WebSocket errors

func IsDisconnected Uses

func IsDisconnected(err error) bool

IsDisconnected method is helper to identify error is disconnect related. If it is returns true otherwise false.

type Context Uses

type Context struct {
    Req    *Request
    Conn   net.Conn
    Header http.Header // These headers are sent to WS client during Connection upgrade
    // contains filtered or unexported fields
}

Context struct holds friendly WebSocket implementation for aah framework.

func (*Context) Abort Uses

func (ctx *Context) Abort(httpErroCode int)

Abort method is useful for `OnPreConnect` event, aah user could make a choice of proceed or abort.

For e.g.:

ctx.Abort(http.StatusUnauthorized)
ctx.Abort(http.StatusForbidden)

func (*Context) Disconnect Uses

func (ctx *Context) Disconnect() error

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 Uses

func (ctx *Context) ErrorReason() error

ErrorReason method returns error info if error was occurred otherwise nil.

func (*Context) Log Uses

func (ctx *Context) Log() log.Loggerer

Log method adds field WebSocket `Request ID` into current log context and returns the logger.

func (*Context) ReadBinary Uses

func (ctx *Context) ReadBinary() ([]byte, error)

ReadBinary method reads a binary data from WebSocket client.

func (*Context) ReadJSON Uses

func (ctx *Context) ReadJSON(t interface{}) error

ReadJSON method reads JSON data from WebSocket client and does unmarshal into given object.

func (*Context) ReadText Uses

func (ctx *Context) ReadText() (string, error)

ReadText method reads a text value from WebSocket client.

Note: Method does HTML sanatize internally. Refer to `html.EscapeString`.

func (*Context) ReadXML Uses

func (ctx *Context) ReadXML(t interface{}) error

ReadXML method reads XML data from WebSocket client and does unmarshal into given object.

func (*Context) ReplyBinary Uses

func (ctx *Context) ReplyBinary(v []byte) error

ReplyBinary method sends Binary data to the WebSocket client returns error if client is gone, network error, etc.

func (*Context) ReplyJSON Uses

func (ctx *Context) ReplyJSON(v interface{}) error

ReplyJSON method sends JSON data to the WebSocket client returns error if json marshal issue, client is gone, network issue, etc.

func (*Context) ReplyText Uses

func (ctx *Context) ReplyText(v string) error

ReplyText method sends Text data to the WebSocket client returns error if client is gone, network error, etc.

func (*Context) ReplyXML Uses

func (ctx *Context) ReplyXML(v interface{}) error

ReplyXML method sends XML data to the WebSocket client returns error if XML marshal issue, client is gone, network issue, etc.

type Engine Uses

type Engine struct {
    // contains filtered or unexported fields
}

Engine struct holds the implementation of WebSocket for aah framework.

func New Uses

func New(app interface{}) (*Engine, error)

New method creates aah WebSocket engine with given aah application instance :)

func (*Engine) AddWebSocket Uses

func (e *Engine) AddWebSocket(t interface{}, methods []*ainsp.Method)

AddWebSocket method adds the given WebSocket implementation into engine.

func (*Engine) Handle Uses

func (e *Engine) Handle(w http.ResponseWriter, r *http.Request)

Handle method primarily does upgrades HTTP connection into WebSocket connection.

Along with Check Origin, aah WebSocket events such as `OnPreConnect`, `OnPostConnect`, `OnPostDisconnect` and `OnError`.

func (*Engine) Log Uses

func (e *Engine) Log() log.Loggerer

Log method provides logging methods at WebSocket engine.

func (*Engine) OnError Uses

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 Uses

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 Uses

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 the aah server.

func (*Engine) OnPreConnect Uses

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) SetIDGenerator Uses

func (e *Engine) SetIDGenerator(g IDGenerator)

SetIDGenerator method used to set Custom ID generator func for WebSocket connection.

type EventCallbackFunc Uses

type EventCallbackFunc func(eventName string, ctx *Context)

EventCallbackFunc func type used for all WebSocket event callback.

type IDGenerator Uses

type IDGenerator func(ctx *Context) string

IDGenerator func type used to implement custom WebSocket connection ID. By default aah generates GUID using MongoDB Object ID algorithm.

type Request Uses

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 Uses

func (r *Request) ClientIP() string

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 Uses

func (r *Request) PathValue(key string) string

PathValue method returns value for given Path param key otherwise empty string. For eg.: `/discussion/:roomName` => `PathValue("roomName")`.

func (*Request) QueryArrayValue Uses

func (r *Request) QueryArrayValue(key string) []string

QueryArrayValue method returns array value for given URL query param key otherwise empty string slice.

func (*Request) QueryValue Uses

func (r *Request) QueryValue(key string) string

QueryValue method returns value for given URL query param key otherwise empty string.

func (Request) String Uses

func (r Request) String() string

String request stringer interface.

func (*Request) URL Uses

func (r *Request) URL() *url.URL

URL method returns HTTP request URL instance.

Package ws imports 21 packages (graph) and is imported by 3 packages. Updated 2018-12-31. Refresh now. Tools for package owners.