1# package drpcwire 2 3`import "storj.io/drpc/drpcwire"` 4 5Package drpcwire provides low level helpers for the drpc wire protocol. 6 7## Usage 8 9#### func AppendFrame 10 11```go 12func AppendFrame(buf []byte, fr Frame) []byte 13``` 14AppendFrame appends a marshaled form of the frame to the provided buffer. 15 16#### func AppendVarint 17 18```go 19func AppendVarint(buf []byte, x uint64) []byte 20``` 21AppendVarint appends the varint encoding of x to the buffer and returns it. 22 23#### func MarshalError 24 25```go 26func MarshalError(err error) []byte 27``` 28MarshalError returns a byte form of the error with any error code incorporated. 29 30#### func ReadVarint 31 32```go 33func ReadVarint(buf []byte) (rem []byte, out uint64, ok bool, err error) 34``` 35ReadVarint reads a varint encoded integer from the front of buf, returning the 36remaining bytes, the value, and if there was a success. if ok is false, the 37returned buffer is the same as the passed in buffer. 38 39#### func SplitData 40 41```go 42func SplitData(buf []byte, n int) (prefix, suffix []byte) 43``` 44SplitData is used to split a buffer if it is larger than n bytes. If n is zero, 45a reasonable default is used. If n is less than zero then it does not split. 46 47#### func SplitN 48 49```go 50func SplitN(pkt Packet, n int, cb func(fr Frame) error) error 51``` 52SplitN splits the marshaled form of the Packet into a number of frames such that 53each frame is at most n bytes. It calls the callback with every such frame. If n 54is zero, a reasonable default is used. 55 56#### func UnmarshalError 57 58```go 59func UnmarshalError(data []byte) error 60``` 61UnmarshalError unmarshals the marshaled error to one with a code. 62 63#### type Frame 64 65```go 66type Frame struct { 67 // Data is the payload of bytes. 68 Data []byte 69 70 // ID is used so that the frame can be reconstructed. 71 ID ID 72 73 // Kind is the kind of the payload. 74 Kind Kind 75 76 // Done is true if this is the last frame for the ID. 77 Done bool 78 79 // Control is true if the frame has the control bit set. 80 Control bool 81} 82``` 83 84Frame is a split data frame on the wire. 85 86#### func ParseFrame 87 88```go 89func ParseFrame(buf []byte) (rem []byte, fr Frame, ok bool, err error) 90``` 91ParseFrame attempts to parse a frame at the beginning of buf. If successful then 92rem contains the unparsed data, fr contains the parsed frame, ok will be true, 93and err will be nil. If there is not enough data for a frame, ok will be false 94and err will be nil. If the data in the buf is malformed, then an error is 95returned. 96 97#### func (Frame) String 98 99```go 100func (fr Frame) String() string 101``` 102String returns a human readable form of the packet. 103 104#### type ID 105 106```go 107type ID struct { 108 // Stream is the stream identifier. 109 Stream uint64 110 111 // Message is the message identifier. 112 Message uint64 113} 114``` 115 116ID represents a packet id. 117 118#### func (ID) Less 119 120```go 121func (i ID) Less(j ID) bool 122``` 123Less returns true if the id is less than the provided one. An ID is less than 124another if the Stream is less, and if the stream is equal, if the Message is 125less. 126 127#### func (ID) String 128 129```go 130func (i ID) String() string 131``` 132String returns a human readable form of the ID. 133 134#### type Kind 135 136```go 137type Kind uint8 138``` 139 140Kind is the enumeration of all the different kinds of messages drpc sends. 141 142```go 143const ( 144 145 // KindInvoke is used to invoke an rpc. The body is the name of the rpc. 146 KindInvoke Kind = 1 147 148 // KindMessage is used to send messages. The body is an encoded message. 149 KindMessage Kind = 2 150 151 // KindError is used to inform that an error happened. The body is an error 152 // with a code attached. 153 KindError Kind = 3 154 155 // KindClose is used to inform that the rpc is dead. It has no body. 156 KindClose Kind = 5 157 158 // KindCloseSend is used to inform that no more messages will be sent. 159 // It has no body. 160 KindCloseSend Kind = 6 // body must be empty 161 162 // KindInvokeMetadata includes metadata about the next Invoke packet. 163 KindInvokeMetadata Kind = 7 164) 165``` 166 167#### func (Kind) String 168 169```go 170func (i Kind) String() string 171``` 172 173#### type Packet 174 175```go 176type Packet struct { 177 // Data is the payload of the packet. 178 Data []byte 179 180 // ID is the identifier for the packet. 181 ID ID 182 183 // Kind is the kind of the packet. 184 Kind Kind 185} 186``` 187 188Packet is a single message sent by drpc. 189 190#### func (Packet) String 191 192```go 193func (p Packet) String() string 194``` 195String returns a human readable form of the packet. 196 197#### type Reader 198 199```go 200type Reader struct { 201} 202``` 203 204Reader reconstructs packets from frames read from an io.Reader. 205 206#### func NewReader 207 208```go 209func NewReader(r io.Reader) *Reader 210``` 211NewReader constructs a Reader to read Packets from the io.Reader. 212 213#### func (*Reader) ReadPacket 214 215```go 216func (r *Reader) ReadPacket() (pkt Packet, err error) 217``` 218ReadPacket reads a packet from the io.Reader. It is equivalent to calling 219ReadPacketUsing(nil). 220 221#### func (*Reader) ReadPacketUsing 222 223```go 224func (r *Reader) ReadPacketUsing(buf []byte) (pkt Packet, err error) 225``` 226ReadPacketUsing reads a packet from the io.Reader. IDs read from frames must be 227monotonically increasing. When a new ID is read, the old data is discarded. This 228allows for easier asynchronous interrupts. If the amount of data in the Packet 229becomes too large, an error is returned. The returned packet's Data field is 230constructed by appending to the provided buf after it has been resliced to be 231zero length. 232 233#### type Writer 234 235```go 236type Writer struct { 237} 238``` 239 240Writer is a helper to buffer and write packets and frames to an io.Writer. 241 242#### func NewWriter 243 244```go 245func NewWriter(w io.Writer, size int) *Writer 246``` 247NewWriter returns a Writer that will attempt to buffer size data before sending 248it to the io.Writer. 249 250#### func (*Writer) Empty 251 252```go 253func (b *Writer) Empty() bool 254``` 255Empty returns true if there are no bytes buffered in the writer. 256 257#### func (*Writer) Flush 258 259```go 260func (b *Writer) Flush() (err error) 261``` 262Flush forces a flush of any buffered data to the io.Writer. It is a no-op if 263there is no data in the buffer. 264 265#### func (*Writer) Reset 266 267```go 268func (b *Writer) Reset() *Writer 269``` 270Reset clears any pending data in the buffer. 271 272#### func (*Writer) WriteFrame 273 274```go 275func (b *Writer) WriteFrame(fr Frame) (err error) 276``` 277WriteFrame appends the frame into the buffer, and if the buffer is larger than 278the configured size, flushes it. 279 280#### func (*Writer) WritePacket 281 282```go 283func (b *Writer) WritePacket(pkt Packet) (err error) 284``` 285WritePacket writes the packet as a single frame, ignoring any size constraints. 286