Documentation ¶
Overview ¶
Package websocket implements a client and server for the WebSocket protocol as specified in RFC 6455.
Index ¶
- Constants
- Variables
- func Origin(config *Config, req *http.Request) (*url.URL, error)
- type Addr
- type Codec
- type Config
- type Conn
- func (ws *Conn) Close() 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 error)
- func (ws *Conn) RemoteAddr() net.Addr
- func (ws *Conn) Request() *http.Request
- func (ws *Conn) SetDeadline(t time.Time) error
- func (ws *Conn) SetReadDeadline(t time.Time) error
- func (ws *Conn) SetWriteDeadline(t time.Time) error
- func (ws *Conn) Write(msg []byte) (n int, err error)
- type DialError
- type Handler
- type ProtocolError
- type Server
Examples ¶
Constants ¶
const ( ProtocolVersionHybi13 = 13 ProtocolVersionHybi = ProtocolVersionHybi13 SupportedProtocolVersion = "13" 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.
Trivial 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)
Functions ¶
Types ¶
type Codec ¶
type Codec struct { Marshal func(v interface{}) (data []byte, payloadType byte, err error) Unmarshal func(data []byte, payloadType byte, v interface{}) (err error) }
Codec represents a symmetric pair of functions that implement a codec.
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 // Additional header fields to be sent in WebSocket opening handshake. Header http.Header // contains filtered or unexported fields }
Config is a WebSocket configuration
type Conn ¶
type Conn struct { PayloadType byte // contains filtered or unexported fields }
Conn represents a WebSocket connection.
func Dial ¶
Dial opens a new client connection to a WebSocket.
Example ¶
This example demonstrates a trivial client.
package main import ( "fmt" "log" "github.com/abh/geodns/Godeps/_workspace/src/golang.org/x/net/websocket" ) func main() { origin := "http://localhost/" url := "ws://localhost:12345/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) var n int if n, err = ws.Read(msg); err != nil { log.Fatal(err) } fmt.Printf("Received: %s.\n", msg[:n]) }
Output:
func DialConfig ¶
DialConfig opens a new client connection to a WebSocket with a config.
func NewClient ¶
func NewClient(config *Config, rwc io.ReadWriteCloser) (ws *Conn, err error)
NewClient creates a new WebSocket client connection over rwc.
func (*Conn) IsClientConn ¶
func (*Conn) IsServerConn ¶
func (*Conn) LocalAddr ¶
LocalAddr returns the WebSocket Origin for the connection for client, or the WebSocket location for server.
func (*Conn) Read ¶
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 ¶
RemoteAddr returns the WebSocket location for the connection for client, or the Websocket Origin for server.
func (*Conn) Request ¶
Request returns the http request upgraded to the WebSocket. It is nil for client side.
func (*Conn) SetDeadline ¶
SetDeadline sets the connection's network read & write deadlines.
func (*Conn) SetReadDeadline ¶
SetReadDeadline sets the connection's network read deadline.
func (*Conn) SetWriteDeadline ¶
SetWriteDeadline sets the connection's network write deadline.
type Handler ¶
type Handler func(*Conn)
Handler is a simple interface to a WebSocket browser client. It checks if Origin header is valid URL by default. You might want to verify websocket.Conn.Config().Origin in the func. If you use Server instead of Handler, you could call websocket.Origin and check the origin in your Handshake func. So, if you want to accept non-browser clients, which do not send an Origin header, set a Server.Handshake that does not check the origin.
Example ¶
This example demonstrates a trivial echo server.
package main import ( "io" "net/http" "github.com/abh/geodns/Godeps/_workspace/src/golang.org/x/net/websocket" ) // Echo the data received on the WebSocket. func EchoServer(ws *websocket.Conn) { io.Copy(ws, ws) } // This example demonstrates a trivial echo server. func main() { http.Handle("/echo", websocket.Handler(EchoServer)) err := http.ListenAndServe(":12345", nil) if err != nil { panic("ListenAndServe: " + err.Error()) } }
Output:
type ProtocolError ¶
type ProtocolError struct {
ErrorString string
}
ProtocolError represents WebSocket protocol errors.
func (*ProtocolError) Error ¶
func (err *ProtocolError) Error() string
type Server ¶
type Server struct { // Config is a WebSocket configuration for new WebSocket connection. Config // Handshake is an optional function in WebSocket handshake. // For example, you can check, or don't check Origin header. // Another example, you can select config.Protocol. Handshake func(*Config, *http.Request) error // Handler handles a WebSocket connection. Handler }
Server represents a server of a WebSocket.