Documentation
¶
Index ¶
- Constants
- Variables
- func CompressFrame(f ws.Frame) (ws.Frame, error)
- func CompressFrameBuffer(buf Buffer, f ws.Frame) (ws.Frame, error)
- func DecompressFrame(f ws.Frame) (ws.Frame, error)
- func DecompressFrameBuffer(buf Buffer, f ws.Frame) (ws.Frame, error)
- func IsCompressed(h ws.Header) (bool, error)
- func SetBit(h ws.Header) (_ ws.Header, err error)
- func UnsetBit(h ws.Header) (_ ws.Header, wasSet bool, err error)
- type Buffer
- type Compressor
- type Decompressor
- type Extension
- type Helper
- func (h *Helper) Compress(p []byte) ([]byte, error)
- func (h *Helper) CompressFrame(in ws.Frame) (f ws.Frame, err error)
- func (h *Helper) CompressFrameBuffer(buf Buffer, f ws.Frame) (ws.Frame, error)
- func (h *Helper) CompressTo(w io.Writer, p []byte) (err error)
- func (h *Helper) Decompress(p []byte) ([]byte, error)
- func (h *Helper) DecompressFrame(in ws.Frame) (f ws.Frame, err error)
- func (h *Helper) DecompressFrameBuffer(buf Buffer, f ws.Frame) (ws.Frame, error)
- func (h *Helper) DecompressTo(w io.Writer, p []byte) (err error)
- type MessageState
- type Parameters
- type ReadResetter
- type Reader
- type WindowBits
- type WriteResetter
- type Writer
Constants ¶
const (
ExtensionName = "permessage-deflate"
)
const (
MaxLZ77WindowSize = 32768 // 2^15
)
Variables ¶
var DefaultHelper = Helper{ Compressor: func(w io.Writer) Compressor { f, _ := flate.NewWriter(w, 9) return f }, Decompressor: func(r io.Reader) Decompressor { return flate.NewReader(r) }, }
DefaultHelper is a default helper instance holding standard library's `compress/flate` compressor and decompressor under the hood.
Note that use of DefaultHelper methods assumes that DefaultParameters were used for extension negotiation during WebSocket handshake.
var DefaultParameters = Parameters{ ServerNoContextTakeover: true, ClientNoContextTakeover: true, }
DefaultParameters holds deflate extension parameters which are assumed by DefaultHelper to be used during WebSocket handshake.
var ErrUnexpectedCompressionBit = ws.ProtocolError(
"control frame or non-first fragment of data contains compression bit set",
)
var (
ExtensionNameBytes = []byte(ExtensionName)
)
Functions ¶
func CompressFrame ¶
CompressFrame is a shortcut for DefaultHelper.CompressFrame().
Note that use of DefaultHelper methods assumes that DefaultParameters were used for extension negotiation during WebSocket handshake.
func CompressFrameBuffer ¶
CompressFrameBuffer is a shortcut for DefaultHelper.CompressFrameBuffer().
Note that use of DefaultHelper methods assumes that DefaultParameters were used for extension negotiation during WebSocket handshake.
func DecompressFrame ¶
DecompressFrame is a shortcut for DefaultHelper.DecompressFrame().
Note that use of DefaultHelper methods assumes that DefaultParameters were used for extension negotiation during WebSocket handshake.
func DecompressFrameBuffer ¶
DecompressFrameBuffer is a shortcut for DefaultHelper.DecompressFrameBuffer().
Note that use of DefaultHelper methods assumes that DefaultParameters were used for extension negotiation during WebSocket handshake.
func IsCompressed ¶
IsCompressed reports whether the Per-Message Compression bit is set in header h. It returns non-nil error if compression bit has unexpected value.
If you need to be fully compatible with Compression Extensions for WebSocket RFC and work with chains of extensions, take a look at the UnsetBit() instead. That is, IsCompressed() is a shortcut for UnsetBit() with reduced number of return values.
func SetBit ¶
SetBit sets the Per-Message Compression bit in header h and returns its modified copy. It returns non-nil error if compression bit has unexpected value.
func UnsetBit ¶
UnsetBit clears the Per-Message Compression bit in header h and returns its modified copy. It reports whether compression bit was set in header h. It returns non-nil error if compression bit has unexpected value.
This function's main purpose is to be compatible with "Framing" section of the Compression Extensions for WebSocket RFC. If you don't need to work with chains of extensions then IsCompressed() could be enough to check if message is compressed. See https://tools.ietf.org/html/rfc7692#section-6.2
Types ¶
type Compressor ¶
Compressor is an interface holding deflate compression implementation.
type Decompressor ¶
Decompressor is an interface holding deflate decompression implementation.
type Extension ¶
type Extension struct {
// Parameters is specification of extension parameters server is going to
// accept.
Parameters Parameters
// contains filtered or unexported fields
}
Extension contains logic of compression extension parameters negotiation made during HTTP WebSocket handshake. It might be reused between different upgrades (but not concurrently) with Reset() being called after each.
func (*Extension) Accepted ¶
func (n *Extension) Accepted() (_ Parameters, accepted bool)
Accepted returns parameters parsed during last negotiation and a flag that reports whether they were accepted.
type Helper ¶
type Helper struct {
Compressor func(w io.Writer) Compressor
Decompressor func(r io.Reader) Decompressor
}
Helper is a helper struct that holds common code for compression and decompression bytes or WebSocket frames.
Its purpose is to reduce boilerplate code in WebSocket applications.
func (*Helper) Compress ¶
Compress compresses given bytes. Note that it does memory allocations internally. To control those allocations consider using CompressTo().
func (*Helper) CompressFrame ¶
CompressFrame returns compressed version of a frame. Note that it does memory allocations internally. To control those allocations consider using CompressFrameBuffer().
func (*Helper) CompressFrameBuffer ¶
CompressFrameBuffer compresses a frame using given buffer. Returned frame's payload holds bytes returned by buf.Bytes().
func (*Helper) CompressTo ¶
CompressTo compresses bytes into given buffer.
func (*Helper) Decompress ¶
Decompress decompresses given bytes. Note that it does memory allocations internally. To control those allocations consider using DecompressTo().
func (*Helper) DecompressFrame ¶
DecompressFrame returns decompressed version of a frame. Note that it does memory allocations internally. To control those allocations consider using DecompressFrameBuffer().
func (*Helper) DecompressFrameBuffer ¶
DecompressFrameBuffer decompresses a frame using given buffer. Returned frame's payload holds bytes returned by buf.Bytes().
type MessageState ¶
type MessageState struct {
// contains filtered or unexported fields
}
MessageState holds message compression state.
It is consulted during SetBits(h) call to make a decision whether we must set the Per-Message Compression bit for given header h argument. It is updated during UnsetBits(h) to reflect compression state of a message represented by header h argument. It can also be consulted/updated directly by calling IsCompressed()/SetCompressed().
In general MessageState should be used when there is no direct access to connection to read frame from, but it is still needed to know if message being read is compressed. For other cases SetBit() and UnsetBit() should be used instead.
NOTE: the compression state is updated during UnsetBits(h) only when header h argument represents data (text or binary) frame.
func (*MessageState) IsCompressed ¶
func (s *MessageState) IsCompressed() bool
IsCompressed reports whether message is "compressed". See https://tools.ietf.org/html/rfc7692#section-6
func (*MessageState) SetBits ¶
SetBits changes RSV bits of the frame header h which is being send as if compression extension was negotiated. It returns modified copy of h and error if header is malformed from the RFC perspective.
func (*MessageState) SetCompressed ¶
func (s *MessageState) SetCompressed(v bool)
SetCompressed marks message as "compressed" or "uncompressed". See https://tools.ietf.org/html/rfc7692#section-6
type Parameters ¶
type Parameters struct {
ServerNoContextTakeover bool
ClientNoContextTakeover bool
ServerMaxWindowBits WindowBits
ClientMaxWindowBits WindowBits
}
Parameters contains compression extension options.
func (Parameters) Option ¶
func (p Parameters) Option() httphead.Option
Option encodes parameters into HTTP header option.
func (*Parameters) Parse ¶
func (p *Parameters) Parse(opt httphead.Option) (err error)
Parse reads parameters from given HTTP header option accordingly to RFC.
It returns non-nil error at least in these cases:
- The negotiation offer contains an extension parameter not defined for use in an offer/response.
- The negotiation offer/response contains an extension parameter with an invalid value.
- The negotiation offer/response contains multiple extension parameters with the same name.
type ReadResetter ¶
ReadResetter is an optional interface that Decompressor can implement.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader implements decompression from an io.Reader object using Decompressor. Essentially Reader is a thin wrapper around Decompressor interface to meet PMCE specs.
After all data has been written client should call Flush() method. If any error occurs after reading from Reader, all subsequent calls to Read() or Close() will return the error.
Reader might be reused for different io.Reader objects after its Reset() method has been called.
func (*Reader) Close ¶
Close closes Reader and a Decompressor instance used under the hood (if it implements io.Closer interface).
type WindowBits ¶
type WindowBits byte
WindowBits specifies window size accordingly to RFC. Use its Bytes() method to obtain actual size of window in bytes.
func (WindowBits) Bytes ¶
func (b WindowBits) Bytes() int
Bytes returns window size in number of bytes.
func (WindowBits) Defined ¶
func (b WindowBits) Defined() bool
Defined reports whether window bits were specified.
type WriteResetter ¶
WriteResetter is an optional interface that Compressor can implement.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer implements compression for an io.Writer object using Compressor. Essentially Writer is a thin wrapper around Compressor interface to meet PMCE specs.
After all data has been written client should call Flush() method. If any error occurs after writing to or flushing a Writer, all subsequent calls to Write(), Flush() or Close() will return the error.
Writer might be reused for different io.Writer objects after its Reset() method has been called.
func (*Writer) Close ¶
Close closes Writer and a Compressor instance used under the hood (if it implements io.Closer interface).
Source Files