blob: b6f4ed092e733764e21632683369055a4bdfbafe [file] [log] [blame]
Joey Armstrong903c69d2024-02-01 19:46:39 -05001package codec
2
3import (
4 "io"
5
6 "github.com/golang/protobuf/proto"
7 "github.com/jhump/protoreflect/internal/codec"
8)
9
10// ErrOverflow is returned when an integer is too large to be represented.
11var ErrOverflow = codec.ErrOverflow
12
13// ErrBadWireType is returned when decoding a wire-type from a buffer that
14// is not valid.
15var ErrBadWireType = codec.ErrBadWireType
16
17// NB: much of the implementation is in an internal package, to avoid an import
18// cycle between this codec package and the desc package. We export it from
19// this package, but we can't use a type alias because we also need to add
20// methods to it, to broaden the exposed API.
21
22// Buffer is a reader and a writer that wraps a slice of bytes and also
23// provides API for decoding and encoding the protobuf binary format.
24//
25// Its operation is similar to that of a bytes.Buffer: writing pushes
26// data to the end of the buffer while reading pops data from the head
27// of the buffer. So the same buffer can be used to both read and write.
28type Buffer codec.Buffer
29
30// NewBuffer creates a new buffer with the given slice of bytes as the
31// buffer's initial contents.
32func NewBuffer(buf []byte) *Buffer {
33 return (*Buffer)(codec.NewBuffer(buf))
34}
35
36// SetDeterministic sets this buffer to encode messages deterministically. This
37// is useful for tests. But the overhead is non-zero, so it should not likely be
38// used outside of tests. When true, map fields in a message must have their
39// keys sorted before serialization to ensure deterministic output. Otherwise,
40// values in a map field will be serialized in map iteration order.
41func (cb *Buffer) SetDeterministic(deterministic bool) {
42 (*codec.Buffer)(cb).SetDeterministic(deterministic)
43}
44
45// IsDeterministic returns whether or not this buffer is configured to encode
46// messages deterministically.
47func (cb *Buffer) IsDeterministic() bool {
48 return (*codec.Buffer)(cb).IsDeterministic()
49}
50
51// Reset resets this buffer back to empty. Any subsequent writes/encodes
52// to the buffer will allocate a new backing slice of bytes.
53func (cb *Buffer) Reset() {
54 (*codec.Buffer)(cb).Reset()
55}
56
57// Bytes returns the slice of bytes remaining in the buffer. Note that
58// this does not perform a copy: if the contents of the returned slice
59// are modified, the modifications will be visible to subsequent reads
60// via the buffer.
61func (cb *Buffer) Bytes() []byte {
62 return (*codec.Buffer)(cb).Bytes()
63}
64
65// String returns the remaining bytes in the buffer as a string.
66func (cb *Buffer) String() string {
67 return (*codec.Buffer)(cb).String()
68}
69
70// EOF returns true if there are no more bytes remaining to read.
71func (cb *Buffer) EOF() bool {
72 return (*codec.Buffer)(cb).EOF()
73}
74
75// Skip attempts to skip the given number of bytes in the input. If
76// the input has fewer bytes than the given count, io.ErrUnexpectedEOF
77// is returned and the buffer is unchanged. Otherwise, the given number
78// of bytes are skipped and nil is returned.
79func (cb *Buffer) Skip(count int) error {
80 return (*codec.Buffer)(cb).Skip(count)
81
82}
83
84// Len returns the remaining number of bytes in the buffer.
85func (cb *Buffer) Len() int {
86 return (*codec.Buffer)(cb).Len()
87}
88
89// Read implements the io.Reader interface. If there are no bytes
90// remaining in the buffer, it will return 0, io.EOF. Otherwise,
91// it reads max(len(dest), cb.Len()) bytes from input and copies
92// them into dest. It returns the number of bytes copied and a nil
93// error in this case.
94func (cb *Buffer) Read(dest []byte) (int, error) {
95 return (*codec.Buffer)(cb).Read(dest)
96}
97
98var _ io.Reader = (*Buffer)(nil)
99
100// Write implements the io.Writer interface. It always returns
101// len(data), nil.
102func (cb *Buffer) Write(data []byte) (int, error) {
103 return (*codec.Buffer)(cb).Write(data)
104}
105
106var _ io.Writer = (*Buffer)(nil)
107
108// DecodeVarint reads a varint-encoded integer from the Buffer.
109// This is the format for the
110// int32, int64, uint32, uint64, bool, and enum
111// protocol buffer types.
112func (cb *Buffer) DecodeVarint() (uint64, error) {
113 return (*codec.Buffer)(cb).DecodeVarint()
114}
115
116// DecodeTagAndWireType decodes a field tag and wire type from input.
117// This reads a varint and then extracts the two fields from the varint
118// value read.
119func (cb *Buffer) DecodeTagAndWireType() (tag int32, wireType int8, err error) {
120 return (*codec.Buffer)(cb).DecodeTagAndWireType()
121}
122
123// DecodeFixed64 reads a 64-bit integer from the Buffer.
124// This is the format for the
125// fixed64, sfixed64, and double protocol buffer types.
126func (cb *Buffer) DecodeFixed64() (x uint64, err error) {
127 return (*codec.Buffer)(cb).DecodeFixed64()
128}
129
130// DecodeFixed32 reads a 32-bit integer from the Buffer.
131// This is the format for the
132// fixed32, sfixed32, and float protocol buffer types.
133func (cb *Buffer) DecodeFixed32() (x uint64, err error) {
134 return (*codec.Buffer)(cb).DecodeFixed32()
135}
136
137// DecodeRawBytes reads a count-delimited byte buffer from the Buffer.
138// This is the format used for the bytes protocol buffer
139// type and for embedded messages.
140func (cb *Buffer) DecodeRawBytes(alloc bool) (buf []byte, err error) {
141 return (*codec.Buffer)(cb).DecodeRawBytes(alloc)
142}
143
144// ReadGroup reads the input until a "group end" tag is found
145// and returns the data up to that point. Subsequent reads from
146// the buffer will read data after the group end tag. If alloc
147// is true, the data is copied to a new slice before being returned.
148// Otherwise, the returned slice is a view into the buffer's
149// underlying byte slice.
150//
151// This function correctly handles nested groups: if a "group start"
152// tag is found, then that group's end tag will be included in the
153// returned data.
154func (cb *Buffer) ReadGroup(alloc bool) ([]byte, error) {
155 return (*codec.Buffer)(cb).ReadGroup(alloc)
156}
157
158// SkipGroup is like ReadGroup, except that it discards the
159// data and just advances the buffer to point to the input
160// right *after* the "group end" tag.
161func (cb *Buffer) SkipGroup() error {
162 return (*codec.Buffer)(cb).SkipGroup()
163}
164
165// SkipField attempts to skip the value of a field with the given wire
166// type. When consuming a protobuf-encoded stream, it can be called immediately
167// after DecodeTagAndWireType to discard the subsequent data for the field.
168func (cb *Buffer) SkipField(wireType int8) error {
169 return (*codec.Buffer)(cb).SkipField(wireType)
170}
171
172// EncodeVarint writes a varint-encoded integer to the Buffer.
173// This is the format for the
174// int32, int64, uint32, uint64, bool, and enum
175// protocol buffer types.
176func (cb *Buffer) EncodeVarint(x uint64) error {
177 return (*codec.Buffer)(cb).EncodeVarint(x)
178}
179
180// EncodeTagAndWireType encodes the given field tag and wire type to the
181// buffer. This combines the two values and then writes them as a varint.
182func (cb *Buffer) EncodeTagAndWireType(tag int32, wireType int8) error {
183 return (*codec.Buffer)(cb).EncodeTagAndWireType(tag, wireType)
184}
185
186// EncodeFixed64 writes a 64-bit integer to the Buffer.
187// This is the format for the
188// fixed64, sfixed64, and double protocol buffer types.
189func (cb *Buffer) EncodeFixed64(x uint64) error {
190 return (*codec.Buffer)(cb).EncodeFixed64(x)
191
192}
193
194// EncodeFixed32 writes a 32-bit integer to the Buffer.
195// This is the format for the
196// fixed32, sfixed32, and float protocol buffer types.
197func (cb *Buffer) EncodeFixed32(x uint64) error {
198 return (*codec.Buffer)(cb).EncodeFixed32(x)
199}
200
201// EncodeRawBytes writes a count-delimited byte buffer to the Buffer.
202// This is the format used for the bytes protocol buffer
203// type and for embedded messages.
204func (cb *Buffer) EncodeRawBytes(b []byte) error {
205 return (*codec.Buffer)(cb).EncodeRawBytes(b)
206}
207
208// EncodeMessage writes the given message to the buffer.
209func (cb *Buffer) EncodeMessage(pm proto.Message) error {
210 return (*codec.Buffer)(cb).EncodeMessage(pm)
211}
212
213// EncodeDelimitedMessage writes the given message to the buffer with a
214// varint-encoded length prefix (the delimiter).
215func (cb *Buffer) EncodeDelimitedMessage(pm proto.Message) error {
216 return (*codec.Buffer)(cb).EncodeDelimitedMessage(pm)
217}