frame

Documentation

Overview

Package frame provides the ability to encode and decode to and from Pulsar's custom binary protocol. The protocol is a light wrapper around protobuf messages.

Index

• Constants
• type Frame
  • func (f *Frame) Decode(r io.Reader) error
  • func (f *Frame) Encode(w io.Writer) error
  • func (f *Frame) Equal(other Frame) bool

Constants

const MaxFrameSize = 5 * 1024 * 1024 // 5mb

MaxFrameSize is defined by the Pulsar spec with a single sentence: "The maximum allowable size of a single frame is 5 MB."

https://pulsar.incubator.apache.org/docs/latest/project/BinaryProtocol/#Framing-5l6bym

Types

type Frame

type Frame struct {
	// BaseCmd is a required field
	BaseCmd *api.BaseCommand

	// The following fields are optional.
	// If present, the frame is a "Payload"
	// command, as opposed to a "Simple" command
	// if there's only the BaseCmd.
	Metadata *api.MessageMetadata
	Payload  []byte
}

Frame represents a pulsar message frame. It can be used to encode and decode messages to and from the Pulsar binary wire format.

The binary protocol is outlined here: https://pulsar.incubator.apache.org/docs/latest/project/BinaryProtocol/ But the Java source should be considered the canonical format.

All sizes are passed as 4-byte unsigned big endian integers.

"Simple" command frame format:

+------------------------------------------------------------------------+
| totalSize (uint32) | commandSize (uint32) | message (protobuf encoded) |
|       4 bytes      |       4 bytes        |         var length         |
|====================|======================|============================|
| size of everything | size of the message  |                            |
| following these 4  |                      |                            |
| bytes              |                      |                            |
+------------------------------------------------------------------------+

"Payload" command frame format (It has the same 3 fields as a "simple" command, plus the following):

+-------------------------------------------------------------------------------------------------------------------------------------------------+
| "Simple" fields | magicNumber (0x0e01) | checksum (CRC32-C) | metadataSize (uint32) | metadata (protobuf encoded) |       payload (bytes)       |
|   var length    |        2 bytes       |       4 bytes      |       4 bytes         |          var length         |   totalSize - (SUM others)  |
|=================|======================|====================|=======================|=============================|=============================|
|                 | OPTIONAL If present, | OPTIONAL Checksum  | size of the metadata  |                             | Any sequence of bytes,      |
|                 | indicates following  | of the following   |                       |                             | possibly compressed and     |
|                 | 4 bytes are checksum | bytes              |                       |                             | or encrypted (see metadata) |
+-------------------------------------------------------------------------------------------------------------------------------------------------+

func (*Frame) Decode

func (f *Frame) Decode(r io.Reader) error

Decode the pulsar binary protocol from r into the receiver frame. Returns any errors encountered.

func (*Frame) Encode

func (f *Frame) Encode(w io.Writer) error

Encode writes the pulsar binary protocol encoded frame into w.

func (*Frame) Equal

func (f *Frame) Equal(other Frame) bool

Equal returns true if the other Frame is equal to the receiver frame, false otherwise.