Debian Codegraph @

coding/base32/base32.go

raw
1 // Package base32 implements base32 encoding and decoding with streaming support.
2 // It provides both standard and hexadecimal base32 alphabets, along with
3 // streaming capabilities for efficient processing of large data.
4 package base32
5
6 import (
7 "encoding/base32"
8 "io"
9 )
10
11 // StdAlphabet is the standard base32 alphabet as defined in RFC 4648.
12 // It uses uppercase letters A-Z and digits 2-7, excluding 0, 1, 8, and 9
13 // to avoid confusion with similar-looking characters.
14 var StdAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"
15
16 // HexAlphabet is the hexadecimal base32 alphabet as defined in RFC 4648.
17 // It uses digits 0-9 and uppercase letters A-V, providing a more
18 // compact representation for hexadecimal data.
19 var HexAlphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUV"
20
21 // StdEncoder represents a base32 encoder for standard encoding operations.
22 // It wraps the standard library's base32.Encoding to provide a consistent
23 // interface with error handling capabilities.
24 type StdEncoder struct {
25 encoding *base32.Encoding // Underlying base32 encoding implementation
26 alphabet string // The alphabet used for encoding
27 Error error // Error field for storing encoding errors
28 }
29
30 // NewStdEncoder creates a new base32 encoder with the specified alphabet.
31 // The alphabet must be a valid base32 alphabet string (exactly 32 characters).
32 // Returns a pointer to the newly created StdEncoder.
33 func NewStdEncoder(alphabet string) *StdEncoder {
34 if len(alphabet) != 32 {
35 return &StdEncoder{Error: AlphabetSizeError(len(alphabet))}
36 }
37 return &StdEncoder{encoding: base32.NewEncoding(alphabet), alphabet: alphabet}
38 }
39
40 // Encode encodes the given byte slice using base32 encoding.
41 // Returns an empty byte slice if the input is empty.
42 // The encoded result uses the alphabet specified when creating the encoder.
43 func (e *StdEncoder) Encode(src []byte) (dst []byte) {
44 if e.Error != nil {
45 return
46 }
47 if len(src) == 0 {
48 return
49 }
50
51 dst = make([]byte, e.encoding.EncodedLen(len(src)))
52 e.encoding.Encode(dst, src)
53 return
54 }
55
56 // StdDecoder represents a base32 decoder for standard decoding operations.
57 // It wraps the standard library's base32.Encoding to provide a consistent
58 // interface with error handling capabilities.
59 type StdDecoder struct {
60 encoding *base32.Encoding // Underlying base32 encoding implementation
61 alphabet string // The alphabet used for decoding
62 Error error // Error field for storing decoding errors
63 }
64
65 // NewStdDecoder creates a new base32 decoder with the specified alphabet.
66 // The alphabet must be a valid base32 alphabet string (exactly 32 characters).
67 // Returns a pointer to the newly created StdDecoder.
68 func NewStdDecoder(alphabet string) *StdDecoder {
69 if len(alphabet) != 32 {
70 return &StdDecoder{Error: AlphabetSizeError(len(alphabet))}
71 }
72 return &StdDecoder{encoding: base32.NewEncoding(alphabet), alphabet: alphabet}
73 }
74
75 // Decode decodes the given base32-encoded byte slice.
76 // Returns the decoded data and any error encountered during decoding.
77 // Returns an empty byte slice and nil error if the input is empty.
78 // The decoded result is truncated to the actual decoded length.
79 func (d *StdDecoder) Decode(src []byte) (dst []byte, err error) {
80 if d.Error != nil {
81 err = d.Error
82 return
83 }
84 if len(src) == 0 {
85 return
86 }
87
88 buf := make([]byte, d.encoding.DecodedLen(len(src)))
89 n, err := d.encoding.Decode(buf, src)
90 if err != nil {
91 d.Error = CorruptInputError(0)
92 return nil, d.Error
93 }
94 return buf[:n], nil
95 }
96
97 // StreamEncoder represents a streaming base32 encoder that implements io.WriteCloser.
98 // It provides efficient encoding for large data streams by processing data
99 // in chunks and writing encoded output immediately.
100 type StreamEncoder struct {
101 writer io.Writer // Underlying writer for encoded output
102 encoder *base32.Encoding // Base32 encoding implementation
103 buffer []byte // Buffer for accumulating partial bytes (0-4 bytes)
104 alphabet string // The alphabet used for encoding
105 encodeBuf [8]byte // Reusable buffer for encoding output (5 bytes -> 8 chars)
106 Error error // Error field for storing encoding errors
107 }
108
109 // NewStreamEncoder creates a new streaming base32 encoder that writes encoded data
110 // to the provided io.Writer. The encoder uses the specified alphabet for encoding.
111 // Returns an io.WriteCloser that can be used for streaming base32 encoding.
112 func NewStreamEncoder(w io.Writer, alphabet string) io.WriteCloser {
113 if len(alphabet) != 32 {
114 return &StreamEncoder{Error: AlphabetSizeError(len(alphabet))}
115 }
116 return &StreamEncoder{
117 writer: w,
118 encoder: base32.NewEncoding(alphabet),
119 alphabet: alphabet,
120 }
121 }
122
123 // Write implements the io.Writer interface for streaming base32 encoding.
124 // Processes data in chunks while maintaining minimal state for cross-Write calls.
125 // This is true streaming - processes data immediately without accumulating large buffers.
126 func (e *StreamEncoder) Write(p []byte) (n int, err error) {
127 if e.Error != nil {
128 return 0, e.Error
129 }
130
131 if len(p) == 0 {
132 return 0, nil
133 }
134
135 // Combine any leftover bytes from previous write with new data
136 // This is necessary for true streaming across multiple Write calls
137 data := append(e.buffer, p...)
138 e.buffer = nil // Clear buffer after combining
139
140 // Process complete 5-byte blocks (5 bytes = 8 characters)
141 blocks := len(data) / 5
142 for i := 0; i < blocks*5; i += 5 {
143 // Encode 5 bytes to 8 characters using reusable buffer
144 e.encoder.Encode(e.encodeBuf[:], data[i:i+5])
145 if _, err = e.writer.Write(e.encodeBuf[:]); err != nil {
146 return len(p), err
147 }
148 }
149
150 // Buffer remaining 0-4 bytes for next write or close
151 remainder := len(data) % 5
152 if remainder > 0 {
153 e.buffer = data[len(data)-remainder:]
154 }
155
156 return len(p), nil
157 }
158
159 // Close implements the io.Closer interface for streaming base32 encoding.
160 // Encodes any remaining buffered bytes from the last Write call.
161 // This is the only place where we handle cross-Write state.
162 func (e *StreamEncoder) Close() error {
163 if e.Error != nil {
164 return e.Error
165 }
166
167 // Encode any remaining bytes (1-4 bytes) with proper padding
168 if len(e.buffer) > 0 {
169 // Create a padded buffer for encoding
170 padded := make([]byte, 5)
171 copy(padded, e.buffer)
172
173 // Encode the padded data
174 encoded := make([]byte, 8)
175 e.encoder.Encode(encoded, padded)
176
177 // Apply proper padding based on the number of remaining bytes
178 switch len(e.buffer) {
179 case 1: // 1 byte = 2 characters + 6 padding
180 encoded = encoded[:2]
181 encoded = append(encoded, []byte("======")...)
182 case 2: // 2 bytes = 4 characters + 4 padding
183 encoded = encoded[:4]
184 encoded = append(encoded, []byte("====")...)
185 case 3: // 3 bytes = 5 characters + 3 padding
186 encoded = encoded[:5]
187 encoded = append(encoded, []byte("===")...)
188 case 4: // 4 bytes = 7 characters + 1 padding
189 encoded = encoded[:7]
190 encoded = append(encoded, []byte("=")...)
191 }
192 if _, err := e.writer.Write(encoded); err != nil {
193 return err
194 }
195 e.buffer = nil
196 }
197
198 return nil
199 }
200
201 // StreamDecoder represents a streaming base32 decoder that implements io.Reader.
202 // It provides efficient decoding for large data streams by processing data
203 // in chunks and maintaining an internal buffer for partial reads.
204 type StreamDecoder struct {
205 reader io.Reader // Underlying reader for encoded input
206 decoder *base32.Encoding // Base32 encoding implementation
207 buffer []byte // Buffer for decoded data not yet read
208 pos int // Current position in the decoded buffer
209 alphabet string // The alphabet used for decoding
210 readBuf [1024]byte // Reusable buffer for reading encoded data
211 decodeBuf [640]byte // Reusable buffer for decoding (base32 decodes to 5/8 size)
212 Error error // Error field for storing decoding errors
213 }
214
215 // NewStreamDecoder creates a new streaming base32 decoder that reads encoded data
216 // from the provided io.Reader. The decoder uses the specified alphabet for decoding.
217 func NewStreamDecoder(r io.Reader, alphabet string) io.Reader {
218 if len(alphabet) != 32 {
219 return &StreamDecoder{Error: AlphabetSizeError(len(alphabet))}
220 }
221 return &StreamDecoder{
222 reader: r,
223 decoder: base32.NewEncoding(alphabet),
224 alphabet: alphabet,
225 }
226 }
227
228 // Read implements the io.Reader interface for streaming base32 decoding.
229 // Reads and decodes base32 data from the underlying reader in chunks.
230 // Maintains an internal buffer to handle partial reads efficiently.
231 func (d *StreamDecoder) Read(p []byte) (n int, err error) {
232 if d.Error != nil {
233 return 0, d.Error
234 }
235
236 // Return buffered data if available
237 if d.pos < len(d.buffer) {
238 n = copy(p, d.buffer[d.pos:])
239 d.pos += n
240 return n, nil
241 }
242
243 // Read encoded data in chunks using reusable buffer
244 rn, err := d.reader.Read(d.readBuf[:])
245 if err != nil && err != io.EOF {
246 return 0, err
247 }
248
249 if rn == 0 {
250 return 0, io.EOF
251 }
252
253 // Decode the data using the configured decoder with reusable buffer
254 n, err = d.decoder.Decode(d.decodeBuf[:], d.readBuf[:rn])
255 if err != nil {
256 return 0, err
257 }
258
259 // Copy decoded data to the provided buffer
260 copied := copy(p, d.decodeBuf[:n])
261 if copied < n {
262 // Buffer remaining data for next read
263 d.buffer = d.decodeBuf[copied:n]
264 d.pos = 0
265 }
266
267 return copied, nil
268 }