| 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 |
} |