websocket

Documentation

Overview

Package websocket implements a client and server for the WebSocket protocol. The protocol is defined at http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol

Index

• Constants
• Variables
• type Codec
  • func (cd Codec) Receive(ws *Conn, v interface{}) (err os.Error)
  • func (cd Codec) Send(ws *Conn, v interface{}) (err os.Error)
• type Config
  • func NewConfig(server, origin string) (config *Config, err os.Error)
• type Conn
  • func Dial(url_, protocol, origin string) (ws *Conn, err os.Error)
  • func DialConfig(config *Config) (ws *Conn, err os.Error)
  • func NewClient(config *Config, rwc io.ReadWriteCloser) (ws *Conn, err os.Error)
  • func (ws *Conn) Close() os.Error
  • func (ws *Conn) Config() *Config
  • func (ws *Conn) IsClientConn() bool
  • func (ws *Conn) IsServerConn() bool
  • func (ws *Conn) LocalAddr() net.Addr
  • func (ws *Conn) Read(msg []byte) (n int, err os.Error)
  • func (ws *Conn) RemoteAddr() net.Addr
  • func (ws *Conn) Request() *http.Request
  • func (ws *Conn) SetReadTimeout(nsec int64) os.Error
  • func (ws *Conn) SetTimeout(nsec int64) os.Error
  • func (ws *Conn) SetWriteTimeout(nsec int64) os.Error
  • func (ws *Conn) Write(msg []byte) (n int, err os.Error)
• type DialError
  • func (e *DialError) String() string
• type Handler
  • func (h Handler) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type ProtocolError
  • func (err ProtocolError) String() string
• type WebSocketAddr
  • func (addr WebSocketAddr) Network() string
  • func (addr WebSocketAddr) String() string

Constants

const (
	ProtocolVersionHixie75 = -75
	ProtocolVersionHixie76 = -76
	ProtocolVersionHybi00  = 0
	ProtocolVersionHybi    = 8

	ContinuationFrame = 0
	TextFrame         = 1
	BinaryFrame       = 2
	CloseFrame        = 8
	PingFrame         = 9
	PongFrame         = 10
	UnknownFrame      = 255
)

Variables

var (
	ErrBadMaskingKey         = &ProtocolError{"bad masking key"}
	ErrBadPongMessage        = &ProtocolError{"bad pong message"}
	ErrBadClosingStatus      = &ProtocolError{"bad closing status"}
	ErrUnsupportedExtensions = &ProtocolError{"unsupported extensions"}
	ErrNotImplemented        = &ProtocolError{"not implemented"}
)

var (
	ErrBadProtocolVersion   = ProtocolError{"bad protocol version"}
	ErrBadScheme            = ProtocolError{"bad scheme"}
	ErrBadStatus            = ProtocolError{"bad status"}
	ErrBadUpgrade           = ProtocolError{"missing or bad upgrade"}
	ErrBadWebSocketOrigin   = ProtocolError{"missing or bad WebSocket-Origin"}
	ErrBadWebSocketLocation = ProtocolError{"missing or bad WebSocket-Location"}
	ErrBadWebSocketProtocol = ProtocolError{"missing or bad WebSocket-Protocol"}
	ErrBadWebSocketVersion  = ProtocolError{"missing or bad WebSocket Version"}
	ErrChallengeResponse    = ProtocolError{"mismatch challenge/response"}
	ErrBadFrame             = ProtocolError{"bad frame"}
	ErrBadFrameBoundary     = ProtocolError{"not on frame boundary"}
	ErrNotWebSocket         = ProtocolError{"not websocket protocol"}
	ErrBadRequestMethod     = ProtocolError{"bad method"}
	ErrNotSupported         = ProtocolError{"not supported"}
)

var JSON = Codec{jsonMarshal, jsonUnmarshal}

JSON is a codec to send/receive JSON data in a frame from a WebSocket connection.

Trival usage:

import "websocket"

type T struct {
	Msg string
	Count int
}

// receive JSON type T
var data T
websocket.JSON.Receive(ws, &data)

// send JSON type T
websocket.JSON.Send(ws, data)

var Message = Codec{marshal, unmarshal}

Message is a codec to send/receive text/binary data in a frame on WebSocket connection. To send/receive text frame, use string type. To send/receive binary frame, use []byte type.

Trivial usage:

import "websocket"

// receive text frame
var message string
websocket.Message.Receive(ws, &message)

// send text frame
message = "hello"
websocket.Message.Send(ws, message)

// receive binary frame
var data []byte
websocket.Message.Receive(ws, &data)

// send binary frame
data = []byte{0, 1, 2}
websocket.Message.Send(ws, data)

Types

type Codec

type Codec struct {
	Marshal   func(v interface{}) (data []byte, payloadType byte, err os.Error)
	Unmarshal func(data []byte, payloadType byte, v interface{}) (err os.Error)
}

Codec represents a symmetric pair of functions that implement a codec.

func (Codec) Receive

func (cd Codec) Receive(ws *Conn, v interface{}) (err os.Error)

Receive receives single frame from ws, unmarshaled by cd.Unmarshal and stores in v.

func (Codec) Send

func (cd Codec) Send(ws *Conn, v interface{}) (err os.Error)

Send sends v marshaled by cd.Marshal as single frame to ws.

type Config

type Config struct {
	// A WebSocket server address.
	Location *url.URL

	// A Websocket client origin.
	Origin *url.URL

	// WebSocket subprotocols.
	Protocol []string

	// WebSocket protocol version.
	Version int

	// TLS config for secure WebSocket (wss).
	TlsConfig *tls.Config
	// contains filtered or unexported fields
}

Config is a WebSocket configuration

func NewConfig

func NewConfig(server, origin string) (config *Config, err os.Error)

NewConfig creates a new WebSocket config for client connection.

type Conn

type Conn struct {
	PayloadType byte
	// contains filtered or unexported fields
}

Conn represents a WebSocket connection.

func Dial

func Dial(url_, protocol, origin string) (ws *Conn, err os.Error)

Dial opens a new client connection to a WebSocket.

A trivial example client:

package main

import (
	"http"
	"log"
	"strings"
	"websocket"
)

func main() {
	origin := "http://localhost/"
	url := "ws://localhost/ws"
	ws, err := websocket.Dial(url, "", origin)
	if err != nil {
		log.Fatal(err)
	}
	if _, err := ws.Write([]byte("hello, world!\n")); err != nil {
		log.Fatal(err)
	}
	var msg = make([]byte, 512);
	if n, err := ws.Read(msg); err != nil {
		log.Fatal(err)
	}
	// use msg[0:n]
}

func DialConfig

func DialConfig(config *Config) (ws *Conn, err os.Error)

DialConfig opens a new client connection to a WebSocket with a config.

func NewClient

func NewClient(config *Config, rwc io.ReadWriteCloser) (ws *Conn, err os.Error)

NewClient creates a new WebSocket client connection over rwc.

func (*Conn) Close

func (ws *Conn) Close() os.Error

Close implements the io.Closer interface.

func (*Conn) Config

func (ws *Conn) Config() *Config

Config returns the WebSocket config.

func (*Conn) IsClientConn

func (ws *Conn) IsClientConn() bool

func (*Conn) IsServerConn

func (ws *Conn) IsServerConn() bool

func (*Conn) LocalAddr

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

LocalAddr returns the WebSocket Origin for the connection for client, or the WebSocket location for server.

func (*Conn) Read

func (ws *Conn) Read(msg []byte) (n int, err os.Error)

Read implements the io.Reader interface: it reads data of a frame from the WebSocket connection. if msg is not large enough for the frame data, it fills the msg and next Read will read the rest of the frame data. it reads Text frame or Binary frame.

func (*Conn) RemoteAddr

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

RemoteAddr returns the WebSocket location for the connection for client, or the Websocket Origin for server.

func (*Conn) Request

func (ws *Conn) Request() *http.Request

Request returns the http request upgraded to the WebSocket. It is nil for client side.

func (*Conn) SetReadTimeout

func (ws *Conn) SetReadTimeout(nsec int64) os.Error

SetReadTimeout sets the connection's network read timeout in nanoseconds.

func (*Conn) SetTimeout

func (ws *Conn) SetTimeout(nsec int64) os.Error

SetTimeout sets the connection's network timeout in nanoseconds.

func (*Conn) SetWriteTimeout

func (ws *Conn) SetWriteTimeout(nsec int64) os.Error

SetWriteTimeout sets the connection's network write timeout in nanoseconds.

func (*Conn) Write

func (ws *Conn) Write(msg []byte) (n int, err os.Error)

Write implements the io.Writer interface: it writes data as a frame to the WebSocket connection.

type DialError

type DialError struct {
	*Config
	Error os.Error
}

DialError is an error that occurs while dialling a websocket server.

func (*DialError) String

func (e *DialError) String() string

type Handler

type Handler func(*Conn)

Handler is an interface to a WebSocket.

A trivial example server:

package main

import (
	"http"
	"io"
	"websocket"
)

// Echo the data received on the WebSocket.
func EchoServer(ws *websocket.Conn) {
	io.Copy(ws, ws);
}

func main() {
	http.Handle("/echo", websocket.Handler(EchoServer));
	err := http.ListenAndServe(":12345", nil);
	if err != nil {
		panic("ListenAndServe: " + err.String())
	}
}

func (Handler) ServeHTTP

func (h Handler) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements the http.Handler interface for a Web Socket

type ProtocolError

type ProtocolError struct {
	ErrorString string
}

WebSocket protocol errors.

func (ProtocolError) String

func (err ProtocolError) String() string

type WebSocketAddr

type WebSocketAddr struct {
	*url.URL
}

WebSocketAddr is an implementation of net.Addr for WebSocket.

func (WebSocketAddr) Network

func (addr WebSocketAddr) Network() string

Network returns the network type for a WebSocket, "websocket".

func (WebSocketAddr) String

func (addr WebSocketAddr) String() string

String returns the network address for a WebSocket.