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 { handleError() }

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

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

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

The low-level bindings use the typical JavaScript idioms.

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

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 { handleError() }

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 { handleError() }

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

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

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

The low-level bindings use the typical JavaScript idioms.

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

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 { handleError() }

Index

• type Conn
  • func Dial(url string) (*Conn, error)
  • func (c *Conn) GetReadBufLength() int
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) Read(b []byte) (n int, err error)
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) Write(b []byte) (n int, err error)
  • func (c *Conn) WriteString(s string) (n int, err error)
• type ReadyState
  • func (rs ReadyState) String() string
• type WebSocket
  • func New(url string) (ws *WebSocket, err error)
  • func (ws *WebSocket) Close() (err error)
  • func (ws *WebSocket) Send(data interface{}) (err error)
• Bugs

Types

type Conn

type Conn struct {
	*WebSocket
	// contains filtered or unexported fields
}

Conn is a high-level wrapper around WebSocket. It is intended to satisfy the net.Conn interface.

To create a Conn, use Dial. Instantiating Conn without Dial will not work.

func Dial

func Dial(url string) (*Conn, error)

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

func (*Conn) GetReadBufLength

func (c *Conn) GetReadBufLength() int

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

LocalAddr would typically return the local network address, but due to limitations in the JavaScript API, it is unable to. Calling this method will cause a panic.

func (*Conn) Read

func (c *Conn) Read(b []byte) (n int, err error)

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr returns the remote network address, based on websocket.WebSocket.URL.

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated with the connection. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.

A zero value for t means that I/O operations will not time out.

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline sets the deadline for future Read calls. A zero value for t means Read will not time out.

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the deadline for future Write calls. Because our writes do not block, this function is a no-op.

func (*Conn) Write

func (c *Conn) Write(b []byte) (n int, err error)

Write writes the contents of b to the WebSocket using a binary opcode.

func (*Conn) WriteString

func (c *Conn) WriteString(s string) (n int, err error)

WriteString writes the contents of s to the WebSocket using a text frame opcode.

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

	// Available events:
	// open, error, close, message
	util.EventTarget

	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) Close

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

Close closes the underlying WebSocket.

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

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.