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