ws: github.com/gobwas/ws/wsutil Index | Files

package wsutil

import "github.com/gobwas/ws/wsutil"

Package wsutil provides utilities for working with WebSocket protocol.

Overview:

  // Read masked text message from peer and check utf8 encoding.
  header, err := ws.ReadHeader(conn)
  if err != nil {
	  // handle err
  }

  // Prepare to read payload.
  r := io.LimitReader(conn, header.Length)
  r = wsutil.NewCipherReader(r, header.Mask)
  r = wsutil.NewUTF8Reader(r)

  payload, err := ioutil.ReadAll(r)
  if err != nil {
	  // handle err
  }

You could get the same behavior using just `wsutil.Reader`:

  r := wsutil.Reader{
	  Source:    conn,
	  CheckUTF8: true,
  }

  payload, err := ioutil.ReadAll(r)
  if err != nil {
	  // handle err
  }

Or even simplest:

  payload, err := wsutil.ReadClientText(conn)
  if err != nil {
	  // handle err
  }

Package is also exports tools for buffered writing:

  // Create buffered writer, that will buffer output bytes and send them as
  // 128-length fragments (with exception on large writes, see the doc).
  writer := wsutil.NewWriterSize(conn, ws.StateServerSide, ws.OpText, 128)

  _, err := io.CopyN(writer, rand.Reader, 100)
  if err == nil {
	  err = writer.Flush()
  }
  if err != nil {
	  // handle error
  }

For more utils and helpers see the documentation.

Index

Package Files

cipher.go dialer.go handler.go helper.go reader.go upgrader.go utf8.go writer.go wsutil.go

Variables

var (
    // ErrNotEmpty is returned by Writer.WriteThrough() to indicate that buffer is
    // not empty and write through could not be done. That is, caller should call
    // Writer.FlushFragment() to make buffer empty.
    ErrNotEmpty = fmt.Errorf("writer not empty")

    // ErrControlOverflow is returned by ControlWriter.Write() to indicate that
    // no more data could be written to the underlying io.Writer because
    // MaxControlFramePayloadSize limit is reached.
    ErrControlOverflow = fmt.Errorf("control frame payload overflow")
)
var DefaultWriteBuffer = 4096

DefaultWriteBuffer contains size of Writer's default buffer. It used by Writer constructor functions.

var ErrInvalidUTF8 = fmt.Errorf("invalid utf8")

ErrInvalidUTF8 is returned by UTF8 reader on invalid utf8 sequence.

var ErrNoFrameAdvance = errors.New("no frame advance")

ErrNoFrameAdvance means that Reader's Read() method was called without preceding NextFrame() call.

var ErrNotControlFrame = errors.New("not a control frame")

ErrNotControlFrame is returned by ControlHandler to indicate that given header could not be handled.

func HandleClientControlMessage Uses

func HandleClientControlMessage(conn io.Writer, msg Message) error

HandleClientControlMessage handles control frame from conn and writes response when needed.

It considers that caller represents server side.

func HandleControlMessage Uses

func HandleControlMessage(conn io.Writer, state ws.State, msg Message) error

HandleControlMessage handles message which was read by ReadMessage() functions.

That is, it is expected, that payload is already unmasked and frame header were checked by ws.CheckHeader() call.

func HandleServerControlMessage Uses

func HandleServerControlMessage(conn io.Writer, msg Message) error

HandleServerControlMessage handles control frame from conn and writes response when needed.

It considers that caller represents client side.

func NextReader Uses

func NextReader(r io.Reader, s ws.State) (ws.Header, io.Reader, error)

NextReader prepares next message read from r. It returns header that describes the message and io.Reader to read message's payload. It returns non-nil error when it is not possible to read message's initial frame.

Note that next NextReader() on the same r should be done after reading all bytes from previously returned io.Reader. For more performant way to discard message use Reader and its Discard() method.

Note that it will not handle any "intermediate" frames, that possibly could be received between text/binary continuation frames. That is, if peer sent text/binary frame with fin flag "false", then it could send ping frame, and eventually remaining part of text/binary frame with fin "true" – with NextReader() the ping frame will be dropped without any notice. To handle this rare, but possible situation (and if you do not know exactly which frames peer could send), you could use Reader with OnIntermediate field set.

func PutWriter Uses

func PutWriter(w *Writer)

PutWriter puts w for future reuse by GetWriter().

func ReadClientBinary Uses

func ReadClientBinary(rw io.ReadWriter) ([]byte, error)

ReadClientBinary reads next binary message from rw, considering that caller represents server side. It is a shortcut for ReadData(rw, ws.StateServerSide). It discards received text messages.

Note this may handle and write control frames into the writer part of a given

io.ReadWriter.

func ReadClientData Uses

func ReadClientData(rw io.ReadWriter) ([]byte, ws.OpCode, error)

ReadClientData reads next data message from rw, considering that caller represents server side. It is a shortcut for ReadData(rw, ws.StateServerSide).

Note this may handle and write control frames into the writer part of a given io.ReadWriter.

func ReadClientText Uses

func ReadClientText(rw io.ReadWriter) ([]byte, error)

ReadClientText reads next text message from rw, considering that caller represents server side. It is a shortcut for ReadData(rw, ws.StateServerSide). It discards received binary messages.

Note this may handle and write control frames into the writer part of a given io.ReadWriter.

func ReadData Uses

func ReadData(rw io.ReadWriter, s ws.State) ([]byte, ws.OpCode, error)

ReadData is a helper function that reads next data (non-control) message from rw. It takes care on handling all control frames. It will write response on control frames to the write part of rw. It blocks until some data frame will be received.

Note this may handle and write control frames into the writer part of a given io.ReadWriter.

func ReadServerBinary Uses

func ReadServerBinary(rw io.ReadWriter) ([]byte, error)

ReadServerBinary reads next binary message from rw, considering that caller represents client side. It is a shortcut for ReadData(rw, ws.StateClientSide). It discards received text messages.

Note this may handle and write control frames into the writer part of a given io.ReadWriter.

func ReadServerData Uses

func ReadServerData(rw io.ReadWriter) ([]byte, ws.OpCode, error)

ReadServerData reads next data message from rw, considering that caller represents client side. It is a shortcut for ReadData(rw, ws.StateClientSide).

Note this may handle and write control frames into the writer part of a given io.ReadWriter.

func ReadServerText Uses

func ReadServerText(rw io.ReadWriter) ([]byte, error)

ReadServerText reads next text message from rw, considering that caller represents client side. It is a shortcut for ReadData(rw, ws.StateClientSide). It discards received binary messages.

Note this may handle and write control frames into the writer part of a given

io.ReadWriter.

func WriteClientBinary Uses

func WriteClientBinary(w io.Writer, p []byte) error

WriteClientBinary is the same as WriteClientMessage with ws.OpBinary.

func WriteClientMessage Uses

func WriteClientMessage(w io.Writer, op ws.OpCode, p []byte) error

WriteClientMessage writes message to w, considering that caller represents client side.

func WriteClientText Uses

func WriteClientText(w io.Writer, p []byte) error

WriteClientText is the same as WriteClientMessage with ws.OpText.

func WriteMessage Uses

func WriteMessage(w io.Writer, s ws.State, op ws.OpCode, p []byte) error

WriteMessage is a helper function that writes message to the w. It constructs single frame with given operation code and payload. It uses given state to prepare side-dependent things, like cipher payload bytes from client to server. It will not mutate p bytes if cipher must be made.

If you want to write message in fragmented frames, use Writer instead.

func WriteServerBinary Uses

func WriteServerBinary(w io.Writer, p []byte) error

WriteServerBinary is the same as WriteServerMessage with ws.OpBinary.

func WriteServerMessage Uses

func WriteServerMessage(w io.Writer, op ws.OpCode, p []byte) error

WriteServerMessage writes message to w, considering that caller represents server side.

func WriteServerText Uses

func WriteServerText(w io.Writer, p []byte) error

WriteServerText is the same as WriteServerMessage with ws.OpText.

type CipherReader Uses

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

CipherReader implements io.Reader that applies xor-cipher to the bytes read from source. It could help to unmask WebSocket frame payload on the fly.

func NewCipherReader Uses

func NewCipherReader(r io.Reader, mask [4]byte) *CipherReader

NewCipherReader creates xor-cipher reader from r with given mask.

func (*CipherReader) Read Uses

func (c *CipherReader) Read(p []byte) (n int, err error)

Read implements io.Reader interface. It applies mask given during initialization to every read byte.

func (*CipherReader) Reset Uses

func (c *CipherReader) Reset(r io.Reader, mask [4]byte)

Reset resets CipherReader to read from r with given mask.

type CipherWriter Uses

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

CipherWriter implements io.Writer that applies xor-cipher to the bytes written to the destination writer. It does not modify the original bytes.

func NewCipherWriter Uses

func NewCipherWriter(w io.Writer, mask [4]byte) *CipherWriter

NewCipherWriter creates xor-cipher writer to w with given mask.

func (*CipherWriter) Reset Uses

func (c *CipherWriter) Reset(w io.Writer, mask [4]byte)

Reset reset CipherWriter to write to w with given mask.

func (*CipherWriter) Write Uses

func (c *CipherWriter) Write(p []byte) (n int, err error)

Write implements io.Writer interface. It applies masking during initialization to every sent byte. It does not modify original slice.

type ClosedError Uses

type ClosedError struct {
    Code   ws.StatusCode
    Reason string
}

ClosedError returned when peer has closed the connection with appropriate code and a textual reason.

func (ClosedError) Error Uses

func (err ClosedError) Error() string

Error implements error interface.

type ControlHandler Uses

type ControlHandler struct {
    Src   io.Reader
    Dst   io.Writer
    State ws.State

    // DisableSrcCiphering disables unmasking payload data read from Src.
    // It is useful when wsutil.Reader is used or when frame payload already
    // pulled and ciphered out from the connection (and introduced by
    // bytes.Reader, for example).
    DisableSrcCiphering bool
}

ControlHandler contains logic of handling control frames.

The intentional way to use it is to read the next frame header from the connection, optionally check its validity via ws.CheckHeader() and if it is not a ws.OpText of ws.OpBinary (or ws.OpContinuation) – pass it to Handle() method.

That is, passed header should be checked to get rid of unexpected errors.

The Handle() method will read out all control frame payload (if any) and write necessary bytes as a rfc compatible response.

func (ControlHandler) Handle Uses

func (c ControlHandler) Handle(h ws.Header) error

Handle handles control frames regarding to the c.State and writes responses to the c.Dst when needed.

It returns ErrNotControlFrame when given header is not of ws.OpClose, ws.OpPing or ws.OpPong operation code.

func (ControlHandler) HandleClose Uses

func (c ControlHandler) HandleClose(h ws.Header) error

HandleClose handles close frame, makes protocol validity checks and writes specification compatible response to the c.Dst.

func (ControlHandler) HandlePing Uses

func (c ControlHandler) HandlePing(h ws.Header) error

HandlePing handles ping frame and writes specification compatible response to the c.Dst.

func (ControlHandler) HandlePong Uses

func (c ControlHandler) HandlePong(h ws.Header) error

HandlePong handles pong frame by discarding it.

type ControlWriter Uses

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

ControlWriter is a wrapper around Writer that contains some guards for buffered writes of control frames.

func NewControlWriter Uses

func NewControlWriter(dest io.Writer, state ws.State, op ws.OpCode) *ControlWriter

NewControlWriter contains ControlWriter with Writer inside whose buffer size is at most ws.MaxControlFramePayloadSize + ws.MaxHeaderSize.

func NewControlWriterBuffer Uses

func NewControlWriterBuffer(dest io.Writer, state ws.State, op ws.OpCode, buf []byte) *ControlWriter

NewControlWriterBuffer returns a new ControlWriter with buf as a buffer.

Note that it reserves x bytes of buf for header data, where x could be ws.MinHeaderSize or ws.MinHeaderSize+4 (depending on state). At most (ws.MaxControlFramePayloadSize + x) bytes of buf will be used.

It panics if len(buf) <= ws.MinHeaderSize + x.

func (*ControlWriter) Flush Uses

func (c *ControlWriter) Flush() error

Flush flushes all buffered data to the underlying io.Writer.

func (*ControlWriter) Write Uses

func (c *ControlWriter) Write(p []byte) (n int, err error)

Write implements io.Writer. It writes to the underlying Writer until it returns error or until ControlWriter write limit will be exceeded.

type DebugDialer Uses

type DebugDialer struct {
    // Dialer contains WebSocket connection establishment options.
    Dialer ws.Dialer

    // OnRequest and OnResponse are the callbacks that will be called with the
    // HTTP request and response respectively.
    OnRequest, OnResponse func([]byte)
}

DebugDialer is a wrapper around ws.Dialer. It tracks i/o of WebSocket handshake. That is, it gives ability to receive copied HTTP request and response bytes that made inside Dialer.Dial().

Note that it must not be used in production applications that requires Dial() to be efficient.

func (*DebugDialer) Dial Uses

func (d *DebugDialer) Dial(ctx context.Context, urlstr string) (conn net.Conn, br *bufio.Reader, hs ws.Handshake, err error)

Dial connects to the url host and upgrades connection to WebSocket. It makes it by calling d.Dialer.Dial().

type DebugUpgrader Uses

type DebugUpgrader struct {
    // Upgrader contains upgrade to WebSocket options.
    Upgrader ws.Upgrader

    // OnRequest and OnResponse are the callbacks that will be called with the
    // HTTP request and response respectively.
    OnRequest, OnResponse func([]byte)
}

DebugUpgrader is a wrapper around ws.Upgrader. It tracks I/O of a WebSocket handshake.

Note that it must not be used in production applications that requires Upgrade() to be efficient.

func (*DebugUpgrader) Upgrade Uses

func (d *DebugUpgrader) Upgrade(conn io.ReadWriter) (hs ws.Handshake, err error)

Upgrade calls Upgrade() on underlying ws.Upgrader and tracks I/O on conn.

type FrameHandlerFunc Uses

type FrameHandlerFunc func(ws.Header, io.Reader) error

FrameHandlerFunc handles parsed frame header and its body represented by io.Reader.

Note that reader represents already unmasked body.

func ControlFrameHandler Uses

func ControlFrameHandler(w io.Writer, state ws.State) FrameHandlerFunc

ControlFrameHandler returns FrameHandlerFunc for handling control frames. For more info see ControlHandler docs.

type Message Uses

type Message struct {
    OpCode  ws.OpCode
    Payload []byte
}

Message represents a message from peer, that could be presented in one or more frames. That is, it contains payload of all message fragments and operation code of initial frame for this message.

func ReadClientMessage Uses

func ReadClientMessage(r io.Reader, m []Message) ([]Message, error)

ReadClientMessage reads next message from r, considering that caller represents server side. It is a shortcut for ReadMessage(r, ws.StateServerSide, m)

func ReadMessage Uses

func ReadMessage(r io.Reader, s ws.State, m []Message) ([]Message, error)

ReadMessage is a helper function that reads next message from r. It appends received message(s) to the third argument and returns the result of it and an error if some failure happened. That is, it probably could receive more than one message when peer sending fragmented message in multiple frames and want to send some control frame between fragments. Then returned slice will contain those control frames at first, and then result of gluing fragments.

TODO(gobwas): add DefaultReader with buffer size options.

func ReadServerMessage Uses

func ReadServerMessage(r io.Reader, m []Message) ([]Message, error)

ReadServerMessage reads next message from r, considering that caller represents client side. It is a shortcut for ReadMessage(r, ws.StateClientSide, m)

type Reader Uses

type Reader struct {
    Source io.Reader
    State  ws.State

    // SkipHeaderCheck disables checking header bits to be RFC6455 compliant.
    SkipHeaderCheck bool

    // CheckUTF8 enables UTF-8 checks for text frames payload. If incoming
    // bytes are not valid UTF-8 sequence, ErrInvalidUTF8 returned.
    CheckUTF8 bool

    OnContinuation FrameHandlerFunc
    OnIntermediate FrameHandlerFunc
    // contains filtered or unexported fields
}

Reader is a wrapper around source io.Reader which represents WebSocket connection. It contains options for reading messages from source.

Reader implements io.Reader, which Read() method reads payload of incoming WebSocket frames. It also takes care on fragmented frames and possibly intermediate control frames between them.

Note that Reader's methods are not goroutine safe.

func NewClientSideReader Uses

func NewClientSideReader(r io.Reader) *Reader

NewClientSideReader is a helper function that calls NewReader with r and ws.StateClientSide.

func NewReader Uses

func NewReader(r io.Reader, s ws.State) *Reader

NewReader creates new frame reader that reads from r keeping given state to make some protocol validity checks when it needed.

func NewServerSideReader Uses

func NewServerSideReader(r io.Reader) *Reader

NewServerSideReader is a helper function that calls NewReader with r and ws.StateServerSide.

func (*Reader) Discard Uses

func (r *Reader) Discard() (err error)

Discard discards current message unread bytes. It discards all frames of fragmented message.

func (*Reader) NextFrame Uses

func (r *Reader) NextFrame() (hdr ws.Header, err error)

NextFrame prepares r to read next message. It returns received frame header and non-nil error on failure.

Note that next NextFrame() call must be done after receiving or discarding all current message bytes.

func (*Reader) Read Uses

func (r *Reader) Read(p []byte) (n int, err error)

Read implements io.Reader. It reads the next message payload into p. It takes care on fragmented messages.

The error is io.EOF only if all of message bytes were read. If an io.EOF happens during reading some but not all the message bytes Read() returns io.ErrUnexpectedEOF.

The error is ErrNoFrameAdvance if no NextFrame() call was made before reading next message bytes.

type UTF8Reader Uses

type UTF8Reader struct {
    Source io.Reader
    // contains filtered or unexported fields
}

UTF8Reader implements io.Reader that calculates utf8 validity state after every read byte from Source.

Note that in some cases client must call r.Valid() after all bytes are read to ensure that all of them are valid utf8 sequences. That is, some io helper functions such io.ReadAtLeast or io.ReadFull could discard the error information returned by the reader when they receive all of requested bytes. For example, the last read sequence is invalid and UTF8Reader returns number of bytes read and an error. But helper function decides to discard received error due to all requested bytes are completely read from the source.

Another possible case is when some valid sequence become split by the read bound. Then UTF8Reader can not make decision about validity of the last sequence cause it is not fully read yet. And if the read stops, Valid() will return false, even if Read() by itself dit not.

func NewUTF8Reader Uses

func NewUTF8Reader(r io.Reader) *UTF8Reader

NewUTF8Reader creates utf8 reader that reads from r.

func (*UTF8Reader) Accepted Uses

func (u *UTF8Reader) Accepted() int

Accepted returns number of valid bytes in last Read().

func (*UTF8Reader) Read Uses

func (u *UTF8Reader) Read(p []byte) (n int, err error)

Read implements io.Reader.

func (*UTF8Reader) Reset Uses

func (u *UTF8Reader) Reset(r io.Reader)

Reset resets utf8 reader to read from r.

func (*UTF8Reader) Valid Uses

func (u *UTF8Reader) Valid() bool

Valid checks current reader state. It returns true if all read bytes are valid UTF-8 sequences, and false if not.

type Writer Uses

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

Writer contains logic of buffering output data into a WebSocket fragments. It is much the same as bufio.Writer, except the thing that it works with WebSocket frames, not the raw data.

Writer writes frames with specified OpCode. It uses ws.State to decide whether the output frames must be masked.

Note that it does not check control frame size or other RFC rules. That is, it must be used with special care to write control frames without violation of RFC. You could use ControlWriter that wraps Writer and contains some guards for writing control frames.

If an error occurs writing to a Writer, no more data will be accepted and all subsequent writes will return the error. After all data has been written, the client should call the Flush() method to guarantee all data has been forwarded to the underlying io.Writer.

func GetWriter Uses

func GetWriter(dest io.Writer, state ws.State, op ws.OpCode, n int) *Writer

GetWriter tries to reuse Writer getting it from the pool.

This function is intended for memory consumption optimizations, because NewWriter*() functions make allocations for inner buffer.

Note the it ceils n to the power of two.

If you have your own bytes buffer pool you could use NewWriterBuffer to use pooled bytes in writer.

func NewWriter Uses

func NewWriter(dest io.Writer, state ws.State, op ws.OpCode) *Writer

NewWriter returns a new Writer whose buffer has the DefaultWriteBuffer size.

func NewWriterBuffer Uses

func NewWriterBuffer(dest io.Writer, state ws.State, op ws.OpCode, buf []byte) *Writer

NewWriterBuffer returns a new Writer with buf as a buffer.

Note that it reserves x bytes of buf for header data, where x is in range [ws.MinHeaderSize,ws.MaxHeaderSize] (depending on state and buf size).

You could use ws.HeaderSize() to calculate number of bytes needed to store header data.

It panics if len(buf) is too small to fit header and payload data.

func NewWriterBufferSize Uses

func NewWriterBufferSize(dest io.Writer, state ws.State, op ws.OpCode, n int) *Writer

NewWriterBufferSize returns a new Writer whose buffer size is equal to n. If n <= ws.MinHeaderSize then the default buffer size is used.

Note that Writer will reserve x bytes for header data, where x is in range [ws.MinHeaderSize,ws.MaxHeaderSize]. That is, frames flushed by Writer will not have payload length equal to n, except the case when Write() is called on empty Writer with len(p) > n.

func NewWriterSize Uses

func NewWriterSize(dest io.Writer, state ws.State, op ws.OpCode, n int) *Writer

NewWriterSize returns a new Writer whose buffer size is at most n + ws.MaxHeaderSize. That is, output frames payload length could be up to n, except the case when Write() is called on empty Writer with len(p) > n.

If n <= 0 then the default buffer size is used as Writer's buffer size.

func (*Writer) Available Uses

func (w *Writer) Available() int

Available returns how many bytes are unused in the buffer.

func (*Writer) Buffered Uses

func (w *Writer) Buffered() int

Buffered returns the number of bytes that have been written into the current buffer.

func (*Writer) Flush Uses

func (w *Writer) Flush() error

Flush writes any buffered data to the underlying io.Writer. It sends the frame with "fin" flag set to true.

If no Write() or ReadFrom() was made, then Flush() does nothing.

func (*Writer) FlushFragment Uses

func (w *Writer) FlushFragment() error

FlushFragment writes any buffered data to the underlying io.Writer. It sends the frame with "fin" flag set to false.

func (*Writer) ReadFrom Uses

func (w *Writer) ReadFrom(src io.Reader) (n int64, err error)

ReadFrom implements io.ReaderFrom.

func (*Writer) Reset Uses

func (w *Writer) Reset(dest io.Writer, state ws.State, op ws.OpCode)

Reset discards any buffered data, clears error, and resets w to have given state and write frames with given OpCode to dest.

func (*Writer) Size Uses

func (w *Writer) Size() int

Size returns the size of the underlying buffer in bytes.

func (*Writer) Write Uses

func (w *Writer) Write(p []byte) (n int, err error)

Write implements io.Writer.

Note that even if the Writer was created to have N-sized buffer, Write() with payload of N bytes will not fit into that buffer. Writer reserves some space to fit WebSocket header data.

func (*Writer) WriteThrough Uses

func (w *Writer) WriteThrough(p []byte) (n int, err error)

WriteThrough writes data bypassing the buffer. Note that Writer's buffer must be empty before calling WriteThrough().

Package wsutil imports 13 packages (graph) and is imported by 30 packages. Updated 2019-10-08. Refresh now. Tools for package owners.