wsconn

README

websocket-conn

📞 A dead simple WebSocket connection written in Go.

websocket-conn provides you with easy handling for WebSockets, it's based on github.com/gorilla/websocket.

Installation

$ go get -u github.com/shiwano/websocket-conn/v4

Usage

func Connect(ctx context.Context, settings Settings, url string, requestHeader http.Header) (*Conn *http.Response, error)
func UpgradeFromHTTP(ctx context.Context, settings Settings, w http.ResponseWriter, r *http.Request) (*Conn, error)

type Conn struct {
  Stream() <-chan Message
  Err() error
  SendBinaryMessage(data []byte) error
  SendTextMessage(text string) error
  SendJSONMessage(v interface{}) error
  Close() error
}

Examples

Server:

package main

import (
  "context"
  "net/http"
  wsconn "github.com/shiwano/websocket-conn/v3"
)

func main() {
  http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    c, _ := wsconn.UpgradeFromHTTP(r.Context(), wsconn.DefaultSettings(), w, r)

    m := <-c.Stream()
    c.SendTextMessage(m.Text() + " World")
    m = <-c.Stream()
    if m.Text() == "Close" {
      c.Close()
    }
  })
  http.ListenAndServe(":5000", nil)
}

Client:

package main

import (
  "context"
  "log"
  wsconn "github.com/shiwano/websocket-conn/v3"
)

func main() {
  ctx, cancel := context.WithCancel(context.Background())
  defer cancel()

  c, _, _ := wsconn.Connect(ctx, wsconn.DefaultSettings(), "ws://localhost:5000", nil)

  c.SendTextMessage("Hello")
  m := <-c.Stream()
  log.Println(m.Text()) // Hello World
  c.SendTextMessage("Close")

  for range c.Stream() {
    // wait for closing.
  }
}

See also examples directory.

License

Copyright (c) 2016 Shogo Iwano Licensed under the MIT license.

Documentation

Index

• Constants
• Variables
• type Conn
  • func Connect(ctx context.Context, settings Settings, url string, requestHeader http.Header) (*Conn, *http.Response, error)
  • func UpgradeFromHTTP(ctx context.Context, settings Settings, w http.ResponseWriter, r *http.Request) (*Conn, error)
  • func (c *Conn) Close() error
  • func (c *Conn) Err() error
  • func (c *Conn) SendBinaryMessage(data []byte) error
  • func (c *Conn) SendJSONMessage(v interface{}) error
  • func (c *Conn) SendTextMessage(text string) error
  • func (c *Conn) Stream() <-chan Message
• type DialerSettings
• type Message
  • func (m Message) IsBinaryMessage() bool
  • func (m Message) IsTextMessage() bool
  • func (m Message) Text() string
  • func (m Message) UnmarshalAsJSON(v interface{}) error
• type MessageType
• type Settings
  • func DefaultSettings() Settings
• type UpgraderSettings

Constants

const (
	TextMessageType   = websocket.TextMessage
	BinaryMessageType = websocket.BinaryMessage
)

MessageType constants. these are same websocket package's values.

Variables

var (
	// ErrCloseSent is returned when the application writes a message to the
	// connection after sending a close message.
	ErrCloseSent = websocket.ErrCloseSent
)

Types

type Conn

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

Conn represents a WebSocket connection.

func Connect

func Connect(ctx context.Context, settings Settings, url string, requestHeader http.Header) (*Conn, *http.Response, error)

Connect to the peer. the requestHeader argument may be nil.

func UpgradeFromHTTP

func UpgradeFromHTTP(ctx context.Context, settings Settings, w http.ResponseWriter, r *http.Request) (*Conn, error)

UpgradeFromHTTP upgrades HTTP to WebSocket.

func (*Conn) Close

func (c *Conn) Close() error

Close the connection.

func (*Conn) Err

func (c *Conn) Err() error

Err returns the disconnection error if the connection closed.

func (*Conn) SendBinaryMessage

func (c *Conn) SendBinaryMessage(data []byte) error

SendBinaryMessage to the peer. This method is goroutine safe.

func (*Conn) SendJSONMessage

func (c *Conn) SendJSONMessage(v interface{}) error

SendJSONMessage to the peer. This method is goroutine safe.

func (*Conn) SendTextMessage

func (c *Conn) SendTextMessage(text string) error

SendTextMessage to the peer. This method is goroutine safe.

func (*Conn) Stream

func (c *Conn) Stream() <-chan Message

Stream retrieve the peer's message data from the stream channel. If the connection closed, this channel closes too.

type DialerSettings

type DialerSettings struct {
	NetDial         func(network, addr string) (net.Conn, error)
	TLSClientConfig *tls.Config
}

DialerSettings represents websocket.Dialer settings.

type Message

type Message struct {
	MessageType MessageType
	Data        []byte
}

Message represents a message.

func (Message) IsBinaryMessage

func (m Message) IsBinaryMessage() bool

IsBinaryMessage determines whether the message is a binary message.

func (Message) IsTextMessage

func (m Message) IsTextMessage() bool

IsTextMessage determines whether the message is a text message.

func (Message) Text

func (m Message) Text() string

Text returns text message data as string.

func (Message) UnmarshalAsJSON

func (m Message) UnmarshalAsJSON(v interface{}) error

UnmarshalAsJSON unmarshals data as JSON.

type MessageType

type MessageType int

MessageType represents websocket message types.

type Settings

type Settings struct {
	WriteWait        time.Duration
	PongWait         time.Duration
	PingPeriod       time.Duration
	HandshakeTimeout time.Duration
	MaxMessageSize   int64
	ReadBufferSize   int
	WriteBufferSize  int
	Subprotocols     []string

	DialerSettings   *DialerSettings
	UpgraderSettings *UpgraderSettings
}

Settings represents connection settings.

func DefaultSettings

func DefaultSettings() Settings

DefaultSettings returns default settings.

type UpgraderSettings

type UpgraderSettings struct {
	Error       func(w http.ResponseWriter, r *http.Request, status int, reason error)
	CheckOrigin func(r *http.Request) bool
}

UpgraderSettings represents websocket.Upgrader settings.