frame

Documentation

Overview

Package frame contains interfaces, types and functions to read and write CQL protocol frames, as defined in sections 1 and 2 of the CQL protocol specifications.

Index

• type Body
  • func (in *Body) DeepCopy() *Body
  • func (in *Body) DeepCopyInto(out *Body)
  • func (b *Body) String() string
• type BodyCompressor
• type Codec
  • func NewCodec(messageCodecs ...message.Codec) Codec
  • func NewCodecWithCompression(compressor BodyCompressor, messageCodecs ...message.Codec) Codec
• type Decoder
• type Encoder
• type Frame
  • func NewFrame(version primitive.ProtocolVersion, streamId int16, message message.Message) *Frame
  • func (in *Frame) DeepCopy() *Frame
  • func (in *Frame) DeepCopyInto(out *Frame)
  • func (f *Frame) Dump() (string, error)
  • func (f *Frame) RequestTracingId(tracing bool)
  • func (f *Frame) SetCompress(compress bool)
  • func (f *Frame) SetCustomPayload(customPayload map[string][]byte)
  • func (f *Frame) SetTracingId(tracingId *primitive.UUID)
  • func (f *Frame) SetWarnings(warnings []string)
  • func (f *Frame) String() string
• type Header
  • func (in *Header) DeepCopy() *Header
  • func (in *Header) DeepCopyInto(out *Header)
  • func (h *Header) String() string
• type ProtocolVersionErr
  • func NewProtocolVersionErr(err string, version primitive.ProtocolVersion, useBeta bool) *ProtocolVersionErr
  • func (e *ProtocolVersionErr) Error() string
• type RawCodec
  • func NewRawCodec(messageCodecs ...message.Codec) RawCodec
  • func NewRawCodecWithCompression(compressor BodyCompressor, messageCodecs ...message.Codec) RawCodec
• type RawConverter
• type RawDecoder
• type RawEncoder
• type RawFrame
  • func (in *RawFrame) DeepCopy() *RawFrame
  • func (in *RawFrame) DeepCopyInto(out *RawFrame)
  • func (f *RawFrame) Dump() (string, error)
  • func (f *RawFrame) String() string

Types

type Body

type Body struct {
	// The tracing id. Only valid for response frames, ignored otherwise.
	TracingId *primitive.UUID
	// The custom payload, or nil if no custom payload is defined.
	// Custom payloads are only valid from Protocol Version 4 onwards.
	CustomPayload map[string][]byte
	// Query warnings, if any. Query warnings are only valid for response frames, and only from Protocol Version 4 onwards.
	Warnings []string
	// The body message.
	Message message.Message
}

Body is the body of a frame. +k8s:deepcopy-gen=true

func (*Body) DeepCopy

func (in *Body) DeepCopy() *Body

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new Body.

func (*Body) DeepCopyInto

func (in *Body) DeepCopyInto(out *Body)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*Body) String

func (b *Body) String() string

type BodyCompressor

type BodyCompressor interface {

	// CompressWithLength compresses the source, reading it fully, and writes the compressed length and the compressed
	// result to dest. This is Cassandra's expected format of compressed frame bodies.
	CompressWithLength(source io.Reader, dest io.Writer) error

	// DecompressWithLength reads the compressed length then decompresses the source, reading it fully, and writes the
	// decompressed result to dest. This is Cassandra's expected format of compressed frame bodies.
	DecompressWithLength(source io.Reader, dest io.Writer) error
}

type Codec

type Codec interface {
	Encoder
	Decoder
}

Codec exposes basic encoding and decoding operations for Frame instances. It should be the preferred interface to use in typical client applications such as drivers.

func NewCodec

func NewCodec(messageCodecs ...message.Codec) Codec

func NewCodecWithCompression

func NewCodecWithCompression(compressor BodyCompressor, messageCodecs ...message.Codec) Codec

type Decoder

type Decoder interface {

	// DecodeFrame decodes the entire frame, decompressing the body if needed.
	DecodeFrame(source io.Reader) (*Frame, error)
}

type Encoder

type Encoder interface {

	// EncodeFrame encodes the entire frame, compressing the body if needed.
	EncodeFrame(frame *Frame, dest io.Writer) error
}

type Frame

type Frame struct {
	Header *Header
	Body   *Body
}

Frame is a high-level representation of a frame, where the body is fully decoded. Note that frames are called "envelopes" in protocol v5 specs. +k8s:deepcopy-gen=true

func NewFrame

func NewFrame(version primitive.ProtocolVersion, streamId int16, message message.Message) *Frame

NewFrame Creates a new Frame with the given version, stream id and message.

func (*Frame) DeepCopy

func (in *Frame) DeepCopy() *Frame

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new Frame.

func (*Frame) DeepCopyInto

func (in *Frame) DeepCopyInto(out *Frame)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*Frame) Dump

func (f *Frame) Dump() (string, error)

Dump encodes and dumps the contents of this frame, for debugging purposes.

func (*Frame) RequestTracingId

func (f *Frame) RequestTracingId(tracing bool)

RequestTracingId Configures this frame to request a tracing id from the server, adjusting the header flags accordingly. Note: this method should only be used for request frames.

func (*Frame) SetCompress

func (f *Frame) SetCompress(compress bool)

SetCompress Configures this frame to use compression, adjusting the header flags accordingly. Note: this method will not enable compression on frames that cannot be compressed. Also, enabling compression on a frame does not guarantee that the frame will be properly compressed: the frame codec must also be configured to use a BodyCompressor.

func (*Frame) SetCustomPayload

func (f *Frame) SetCustomPayload(customPayload map[string][]byte)

SetCustomPayload Sets a new custom payload on this frame, adjusting the header flags accordingly. If nil, the existing payload, if any, will be removed along with the corresponding header flag. Note: custom payloads cannot be used with protocol versions lesser than 4.

func (*Frame) SetTracingId

func (f *Frame) SetTracingId(tracingId *primitive.UUID)

SetTracingId Sets a new tracing id on this frame, adjusting the header flags accordingly. If nil, the existing tracing id, if any, will be removed along with the corresponding header flag. Note: tracing ids can only be used with response frames.

func (*Frame) SetWarnings

func (f *Frame) SetWarnings(warnings []string)

SetWarnings Sets new query warnings on this frame, adjusting the header flags accordingly. If nil, the existing warnings, if any, will be removed along with the corresponding header flag. Note: query warnings cannot be used with protocol versions lesser than 4.

func (*Frame) String

func (f *Frame) String() string

type Header

type Header struct {
	IsResponse bool
	Version    primitive.ProtocolVersion
	Flags      primitive.HeaderFlag
	// The stream id. A stream id is a signed byte (protocol versions 1 and 2) or a signed 16-bit integer (protocol
	// versions 3 and higher). Note that the protocol specs refer to the stream id as a primitive [short] integer,
	// but in fact stream ids are signed integers. Indeed, server-initiated messages, such as EVENT messages, have
	// negative stream ids. For this reason, stream ids are represented as signed 16-bit integers in this library.
	StreamId int16
	// The OpCode is an unsigned byte that distinguishes the type of payload that a frame contains.
	OpCode primitive.OpCode
	// The encoded body length. This is a computed value that users should not set themselves. When encoding a frame,
	// this field is not read but is rather dynamically computed from the actual body length. When decoding a frame,
	// this field is always correctly set to the exact decoded body length.
	BodyLength int32
}

Header is the header of a frame. +k8s:deepcopy-gen=true

func (*Header) DeepCopy

func (in *Header) DeepCopy() *Header

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new Header.

func (*Header) DeepCopyInto

func (in *Header) DeepCopyInto(out *Header)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*Header) String

func (h *Header) String() string

type ProtocolVersionErr

type ProtocolVersionErr struct {
	Err     string
	Version primitive.ProtocolVersion
	UseBeta bool
}

func NewProtocolVersionErr

func NewProtocolVersionErr(err string, version primitive.ProtocolVersion, useBeta bool) *ProtocolVersionErr

func (*ProtocolVersionErr) Error

func (e *ProtocolVersionErr) Error() string

type RawCodec

type RawCodec interface {
	Codec
	RawEncoder
	RawDecoder
	RawConverter
}

RawCodec exposes advanced encoding and decoding operations for both Frame and RawFrame instances. It should be used only by applications that need to access the frame header without necessarily accessing the frame body, such as proxies or gateways.

func NewRawCodec

func NewRawCodec(messageCodecs ...message.Codec) RawCodec

func NewRawCodecWithCompression

func NewRawCodecWithCompression(compressor BodyCompressor, messageCodecs ...message.Codec) RawCodec

type RawConverter

type RawConverter interface {

	// ConvertToRawFrame converts a Frame to a RawFrame, encoding the body and compressing it if necessary. The
	// returned RawFrame will share the same header with the initial Frame.
	ConvertToRawFrame(frame *Frame) (*RawFrame, error)

	// ConvertFromRawFrame converts a RawFrame to a Frame, decoding the body and decompressing it if necessary. The
	// returned Frame will share the same header with the initial RawFrame.
	ConvertFromRawFrame(frame *RawFrame) (*Frame, error)
}

type RawDecoder

type RawDecoder interface {

	// DecodeRawFrame decodes a RawFrame from the given source.
	DecodeRawFrame(source io.Reader) (*RawFrame, error)

	// DecodeHeader decodes a frame Header from the given source, leaving the body contents unread. This is a partial
	// operation; after calling this method, one must either call DecodeBody, DecodeRawBody or DiscardBody to fully
	// read or discard the body contents.
	DecodeHeader(source io.Reader) (*Header, error)

	// DecodeBody decodes a frame Body from the given source, decompressing it if required. This is a partial
	// operation; It is illegal to call this method before calling DecodeHeader.
	DecodeBody(header *Header, source io.Reader) (*Body, error)

	// DecodeRawBody decodes a frame RawBody from the given source. This is a partial operation; it is illegal to call
	// this method before calling DecodeHeader.
	DecodeRawBody(header *Header, source io.Reader) ([]byte, error)

	// DiscardBody discards the contents of a frame body read from the given source. This is a partial operation; it is
	// illegal to call this method before calling DecodeHeader.
	DiscardBody(header *Header, source io.Reader) error
}

type RawEncoder

type RawEncoder interface {

	// EncodeRawFrame encodes the given RawFrame.
	EncodeRawFrame(frame *RawFrame, dest io.Writer) error

	// EncodeHeader encodes the given frame Header. This is a partial operation; after calling this method, one must
	// call EncodeBody to fully encode the entire frame.
	EncodeHeader(header *Header, dest io.Writer) error

	// EncodeBody encodes the given frame Body. The body will be compressed depending on whether the Compressed flag is
	// set in the given Header. This is a partial operation; it is illegal to call this method before calling
	// EncodeHeader.
	EncodeBody(header *Header, body *Body, dest io.Writer) error
}

type RawFrame

type RawFrame struct {
	Header *Header
	Body   []byte
}

RawFrame is a low-level representation of a frame, where the body is not decoded. Note that frames are called "envelopes" in protocol v5 specs. +k8s:deepcopy-gen=true

func (*RawFrame) DeepCopy

func (in *RawFrame) DeepCopy() *RawFrame

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new RawFrame.

func (*RawFrame) DeepCopyInto

func (in *RawFrame) DeepCopyInto(out *RawFrame)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*RawFrame) Dump

func (f *RawFrame) Dump() (string, error)

Dump encodes and dumps the contents of this frame, for debugging purposes.

func (*RawFrame) String

func (f *RawFrame) String() string