websocket

README

websocket

Package websocket provides high- and low-level bindings for the browser's WebSocket API.

The high-level bindings act like a regular net.Conn. They can be used as such. For example:

c, err := websocket.Dial("ws://localhost/socket") // Blocks until connection is established
if err != nil { panic(err) }

buf := make([]byte, 1024)
n, err = c.Read(buf) // Blocks until a WebSocket frame is received
if err != nil { panic(err) }
doSomethingWithData(buf[:n])

_, err = c.Write([]byte("Hello!"))
if err != nil { panic(err) }

err = c.Close()
if err != nil { panic(err) }

The low-level bindings use the typical JavaScript idioms.

ws, err := websocket.New("ws://localhost/socket") // Does not block.
if err != nil { panic(err) }

onOpen := func(ev *js.Object) {
	err := ws.Send([]byte("Hello!")) // Send as a binary frame
	err := ws.Send("Hello!")         // Send a text frame
}

ws.AddEventListener("open", false, onOpen)
ws.AddEventListener("message", false, onMessage)
ws.AddEventListener("close", false, onClose)
ws.AddEventListener("error", false, onError)

err = ws.Close()
if err != nil { panic(err) }

Documentation

Overview

Package websocket provides high- and low-level bindings for the browser's WebSocket API.

The high-level bindings act like a regular net.Conn. They can be used as such. For example:

c, err := websocket.Dial("ws://localhost/socket") // Blocks until connection is established
if err != nil { panic(err) }

buf := make([]byte, 1024)
n, err = c.Read(buf) // Blocks until a WebSocket frame is received
if err != nil { panic(err) }
doSomethingWithData(buf[:n])

_, err = c.Write([]byte("Hello!"))
if err != nil { panic(err) }

err = c.Close()
if err != nil { panic(err) }

The low-level bindings use the typical JavaScript idioms.

ws, err := websocket.New("ws://localhost/socket") // Does not block.
if err != nil { panic(err) }

onOpen := func(ev *js.Object) {
	err := ws.Send([]byte("Hello!")) // Send as a binary frame
	err := ws.Send("Hello!")         // Send a text frame
}

ws.AddEventListener("open", false, onOpen)
ws.AddEventListener("message", false, onMessage)
ws.AddEventListener("close", false, onClose)
ws.AddEventListener("error", false, onError)

err = ws.Close()
if err != nil { panic(err) }

Index

• func Dial(url string) (net.Conn, error)
• type ReadyState
  • func (rs ReadyState) String() string
• type WebSocket
  • func New(url string) (ws *WebSocket, err error)
  • func (ws *WebSocket) AddEventListener(typ string, useCapture bool, listener func(*js.Object))
  • func (ws *WebSocket) Close() (err error)
  • func (ws *WebSocket) RemoveEventListener(typ string, useCapture bool, listener func(*js.Object))
  • func (ws *WebSocket) Send(data interface{}) (err error)
• Bugs

Functions

func Dial

func Dial(url string) (net.Conn, error)

Dial opens a new WebSocket connection. It will block until the connection is established or fails to connect.

Types

type ReadyState

type ReadyState uint16

ReadyState represents the state that a WebSocket is in. For more information about the available states, see http://dev.w3.org/html5/websockets/#dom-websocket-readystate

const (
	// Connecting means that the connection has not yet been established.
	Connecting ReadyState = 0
	// Open means that the WebSocket connection is established and communication
	// is possible.
	Open ReadyState = 1
	// Closing means that the connection is going through the closing handshake,
	// or the Close() method has been invoked.
	Closing ReadyState = 2
	// Closed means that the connection has been closed or could not be opened.
	Closed ReadyState = 3
)

func (ReadyState) String

func (rs ReadyState) String() string

type WebSocket

type WebSocket struct {
	*js.Object

	URL string `js:"url"`

	// ready state
	ReadyState     ReadyState `js:"readyState"`
	BufferedAmount uint32     `js:"bufferedAmount"`

	// networking
	Extensions string `js:"extensions"`
	Protocol   string `js:"protocol"`

	// messaging
	BinaryType string `js:"binaryType"`
}

WebSocket is a low-level convenience wrapper around the browser's WebSocket object. For more information, see http://dev.w3.org/html5/websockets/#the-websocket-interface

For the high-level wrapper, see Conn.

func New

func New(url string) (ws *WebSocket, err error)

New creates a new low-level WebSocket. It immediately returns the new WebSocket.

func (*WebSocket) AddEventListener

func (ws *WebSocket) AddEventListener(typ string, useCapture bool, listener func(*js.Object))

AddEventListener provides the ability to bind callback functions to the following available events: open, error, close, message

func (*WebSocket) Close

func (ws *WebSocket) Close() (err error)

Close closes the underlying WebSocket.

See: http://dev.w3.org/html5/websockets/#dom-websocket-close

func (*WebSocket) RemoveEventListener

func (ws *WebSocket) RemoveEventListener(typ string, useCapture bool, listener func(*js.Object))

RemoveEventListener removes a previously bound callback function

func (*WebSocket) Send

func (ws *WebSocket) Send(data interface{}) (err error)

Send sends a message on the WebSocket. The data argument can be a string or a *js.Object fulfilling the ArrayBufferView definition.

See: http://dev.w3.org/html5/websockets/#dom-websocket-send

Notes

Bugs

• conn.LocalAddr() panics because the underlying JavaScript API has no way of figuring out the local address.

• When WebSocket.Send is called on a closed WebSocket, the thrown error doesn't seem to be caught by recover.