ww/lib/encoding/base64/base64.ww

// encoding/base64 — RFC 4648 base64 / base64url over the io-streaming
// surface. Port of ref/hare/encoding/base64/base64.ha.
//
// The streaming DECODER (newdecoder/decode_reader, ref base64.ha:363,
// 375) is DEFERRED — project #247-sibling, blocked on #199b. Hare's
// decode_reader returns errors::invalid on malformed input, which fits
// Hare's io::error (it spreads ...errors::error). ww's io.error
// (lib/io/types.ww:55) does NOT carry errors.invalid (the #199b
// deferral) and io.read's (size | eof | error) can't propagate it
// either, so a base64 decoder *stream* cannot faithfully report invalid
// through io.read until #199b lands. decodestr ships as a direct
// transform meanwhile (its own return union carries errors.invalid; it
// is not io.error-constrained) — the same divergence
// lib/encoding/hex/hex.ww:105-141 took for its direct path.
package base64;

import bytes;
import errors;
import io;
import memio;
import strings;

// ref/hare/encoding/base64/base64.ha:12.
def PADDING: u8 = '=';

// ref/hare/encoding/base64/base64.ha:14-17.
export type encoding = struct {
	encmap: [64]u8,
	decmap: [128]u8,
};

// std_encoding — the standard RFC 4648 §4 alphabet.
// ref/hare/encoding/base64/base64.ha:20-44. Module-level `def` (ww has
// no `const`; same shape as math.f64info), addressed as
// &base64.std_encoding by callers (cross-module address-of-def, #149).
// encmap char-lits and decmap int-lits narrow to u8 via #251. The
// decmap trailing 0xff run (Hare's `0xff...` at :42) is SPELLED OUT (no
// `...`): Hare's explicit entries run to index 122 (0x33), then 0xff
// fills 123-127 — written here verbatim to stay byte-identical to
// base64.ha:42 while avoiding the un-implemented #250 repeat-fill sugar.
export def std_encoding: encoding = encoding {
	encmap = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L',
		'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y',
		'Z', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l',
		'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y',
		'z', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '+', '/'],
	decmap = [
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0x3e, 0xff, 0xff, 0xff, 0x3f,
		0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3a, 0x3b,
		0x3c, 0x3d, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06,
		0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e,
		0x0f, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16,
		0x17, 0x18, 0x19, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20,
		0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28,
		0x29, 0x2a, 0x2b, 0x2c, 0x2d, 0x2e, 0x2f, 0x30,
		0x31, 0x32, 0x33, 0xff, 0xff, 0xff, 0xff, 0xff,
	],
};

// url_encoding — the RFC 4648 §5 "base64url" alphabet ('-'/'_' for
// 62/63), suitable for URLs and file paths.
// ref/hare/encoding/base64/base64.ha:48-72. decmap trailing 0xff run
// spelled out (no '...', #250) — byte-identical to base64.ha:70.
export def url_encoding: encoding = encoding {
	encmap = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L',
		'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y',
		'Z', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l',
		'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y',
		'z', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '-', '_'],
	decmap = [
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0x3e, 0xff, 0xff,
		0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3a, 0x3b,
		0x3c, 0x3d, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06,
		0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e,
		0x0f, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16,
		0x17, 0x18, 0x19, 0xff, 0xff, 0xff, 0xff, 0x3f,
		0xff, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20,
		0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28,
		0x29, 0x2a, 0x2b, 0x2c, 0x2d, 0x2e, 0x2f, 0x30,
		0x31, 0x32, 0x33, 0xff, 0xff, 0xff, 0xff, 0xff,
	],
};

// encoder — a write-only io stream that base64-encodes writes before
// forwarding them to `out`. ref/hare/encoding/base64/base64.ha:110-118.
// `vt` at offset 0 for the intrusive stream→io.stream cast (&e.vt) and
// the callbacks' reverse `s: *encoder` cast — same shape as memio.stream
// / hex.encoder. Hare keeps a shared const encoder_vtable (base64.ha:120)
// + a `stream` field; ww embeds the vtable INLINE and wires the
// writer/closer slots post-construction (memio/hex convention). ibuf
// buffers the in-progress 3-byte group across writes; obuf holds the
// 4-char encoded group still to be flushed.
export type encoder = struct {
	vt:     io.vtable,
	out:    io.handle,
	enc:    *encoding,
	ibuf:   [3]u8,
	obuf:   [4]u8,
	iavail: u8,
	oavail: u8,
};

// newencoder — wire an encoder over `out`. After writing, [[encode]] /
// [[io.close]] must run to flush the final partial group with '='
// padding. ref/hare/encoding/base64/base64.ha:131-141. Returns BY VALUE
// (memio/hex constructor convention); the caller passes &enc.vt to the
// io dispatchers.
export fn newencoder(enc: *encoding, out: io.handle) encoder = {
	let r: encoder;
	r.vt.writer = (&encode_writer): *io.writer;
	r.vt.closer = (&encode_closer): *io.closer;
	r.out = out;
	r.enc = enc;
	r.iavail = 0u8;
	r.oavail = 0u8;
	return r;
};

// encode_writer — the encoder's io.writer slot.
// ref/hare/encoding/base64/base64.ha:143-175. Fills ibuf to a full
// 3-byte group, encodes it into obuf, and drains obuf to `out`; a
// trailing partial group stays buffered in ibuf for the next write (or
// the closer). Returns the count of *input* bytes consumed (= len(in)
// on success, since the partial tail is buffered, mirroring Hare).
fn encode_writer(s: io.stream, in: []u8) (size | io.error) = {
	let e: *encoder = s: *encoder;
	let i: i32 = 0;
	for (i < in.len) {
		for (e.iavail < 3u8 && i < in.len) {
			e.ibuf[e.iavail] = in[i];
			i += 1;
			e.iavail += 1u8;
		};
		if (e.iavail != 3u8) {
			return i: size;
		};
		fillobuf(e);
		match (writeavail(e)) {
		case let er: io.error => {
			if (i == 0) { return er; };
			return i: size;
		};
		case void => void;
		};
	};
	return i: size;
};

// fillobuf — encode the full 3-byte ibuf group into the 4-char obuf.
// ref/hare/encoding/base64/base64.ha:177-187.
fn fillobuf(e: *encoder) void = {
	let b0: u8 = e.ibuf[0];
	let b1: u8 = e.ibuf[1];
	let b2: u8 = e.ibuf[2];
	e.obuf[0] = e.enc.encmap[b0 >> 2u8];
	e.obuf[1] = e.enc.encmap[((b0 & 0x3u8) << 4u8) | (b1 >> 4u8)];
	e.obuf[2] = e.enc.encmap[((b1 & 0xfu8) << 2u8) | (b2 >> 6u8)];
	e.obuf[3] = e.enc.encmap[b2 & 0x3fu8];
	e.oavail = 4u8;
};

// writeavail — drain the encoded obuf tail to `out`.
// ref/hare/encoding/base64/base64.ha:189-202. Loops over io.write to
// absorb partial writes; clears iavail once obuf is fully drained.
fn writeavail(e: *encoder) (void | io.error) = {
	if (e.oavail == 0u8) {
		return;
	};
	let olen: i32 = len(e.obuf): i32;
	for (e.oavail > 0u8) {
		let start: i32 = olen - (e.oavail: i32);
		match (io.write(e.out, e.obuf[start : olen])) {
		case let n: size => e.oavail -= n: u8;
		case let er: io.error => return er;
		};
	};
	if (e.oavail == 0u8) {
		e.iavail = 0u8;
	};
};

// encode_closer — flush pending writes, padding the final partial group
// with '='. ref/hare/encoding/base64/base64.ha:205-242. Hare guards the
// final clear() behind a `defer if (finished)`; ww has no defer, so
// clear() is called explicitly on each success path and SKIPPED on the
// error returns (matching Hare's finished-only semantics).
fn encode_closer(s: io.stream) (void | io.error) = {
	let e: *encoder = s: *encoder;

	if (e.oavail > 0u8) {
		for (e.oavail > 0u8) {
			match (writeavail(e)) {
			case let er: io.error => return er;
			case void => void;
			};
		};
		clear(e);
		return;
	};

	if (e.iavail == 0u8) {
		clear(e);
		return;
	};

	// input length was not a multiple of 3 — pad the group.
	//                       0    1    2
	let npa: [3]u8 = [0u8, 2u8, 1u8];
	let np: u8 = npa[e.iavail];

	for (e.iavail < 3u8) {
		e.ibuf[e.iavail] = 0u8;
		e.iavail += 1u8;
	};

	fillobuf(e);
	let olast: i32 = (len(e.obuf): i32) - 1;
	let npi: i32 = np: i32;
	let k: i32 = 0;
	for (k < npi) {
		e.obuf[olast - k] = PADDING;
		k += 1;
	};

	for (e.oavail > 0u8) {
		match (writeavail(e)) {
		case let er: io.error => return er;
		case void => void;
		};
	};
	clear(e);
	return;
};

// clear — zero the work buffers after a flush.
// ref/hare/encoding/base64/base64.ha:244-247.
fn clear(e: *encoder) void = {
	bytes.zero(e.ibuf);
	bytes.zero(e.obuf);
};

// encodeslice — encode `in` and return a fresh byte slice of base64
// ASCII. ref/hare/encoding/base64/base64.ha:271-289. Hare returns
// ([]u8 | nomem) and the caller frees; ww drops nomem per the memio
// rule-9 carve-out (memio.dynamic has no nomem path) and leaks the
// backing buffer (no-GC, process-exit reclaims) — same carve-out as
// hex.encodestr.
export fn encodeslice(enc: *encoding, in: []u8) []u8 = {
	let out: memio.stream = memio.dynamic();
	let e: encoder = newencoder(enc, &out.vt);
	match (io.write(&e.vt, in)) {
	case let n: size => void;
	case let er: io.error => abort("base64.encodeslice: dynamic memio write failed");
	};
	match (io.close(&e.vt)) {
	case void => void;
	case let er: io.error => abort("base64.encodeslice: encoder close failed");
	};
	return memio.buffer(&out);
};

// encode — encode `buf` and write it to `out`, returning the number of
// input bytes encoded (i.e. len(buf)).
// ref/hare/encoding/base64/base64.ha:293-307. encode_writer consumes the
// whole slice in one call (the partial tail is buffered), so a single
// io.write replaces Hare's io::writeall (ww has no io.writeall —
// cf hex.ww:80-88); io.close then flushes the padded tail.
export fn encode(out: io.handle, enc: *encoding, buf: []u8) (size | io.error) = {
	let e: encoder = newencoder(enc, out);
	match (io.write(&e.vt, buf)) {
	case let z: size => {
		match (io.close(&e.vt)) {
		case void => return z;
		case let er: io.error => return er;
		};
	};
	case let er: io.error => {
		clear(&e);
		return er;
	};
	};
};

// encodestr — encode `in` and return it as a base64 string.
// ref/hare/encoding/base64/base64.ha:311-313. Hare uses the validating
// strings::fromutf8; ww uses strings.frombytes (pure reinterpret) per
// the CLAUDE.md rule-9 carve-out — base64 output is ASCII by
// construction. Leaks the backing buffer as encodeslice does.
export fn encodestr(enc: *encoding, in: []u8) str = {
	return strings.frombytes(encodeslice(enc, in));
};

// decodestr — decode a string of ASCII base64 into a byte slice.
// ref/hare/encoding/base64/base64.ha:499-501. Hare's decodestr defers to
// decodeslice (base64.ha:470), which decodes by copying through a
// newdecoder stream + io::copy; ww decodes DIRECTLY via enc.decmap — the
// streaming decoder is deferred to #247 (see file header), so there is
// no newdecoder to route through, and decodestr's own return union
// carries errors.invalid (it is not io.error-constrained). Same
// documented divergence as hex.ww:105-141. Hare also returns nomem;
// ww drops it (the alloc `!` aborts on OOM, as hex.decodestr).
//
// The decode mirrors Hare's decode_reader validation
// (base64.ha:424-441): length must be a multiple of 4; '=' padding is
// permitted only as the final 1-2 chars of the last quad (np>2 or
// embedded '=' → invalid); every data char must be ASCII with a non-0xff
// decmap entry.
export fn decodestr(enc: *encoding, in: str) ([]u8 | errors.invalid) = {
	let b: []u8 = strings.toutf8(in);
	let n: i32 = b.len;
	if (n == 0) {
		let empty: []u8;
		empty.ptr = nil;
		empty.len = 0;
		return empty;
	};
	if ((n & 3) != 0) {
		let er: errors.invalid;
		return er;
	};

	// trailing '=' padding: at most 2, only in the final quad.
	let np: i32 = 0;
	if (b[n - 1] == PADDING) {
		np = 1;
		if (b[n - 2] == PADDING) {
			np = 2;
		};
	};

	// validate the data region (everything before the trailing pad):
	// ascii alphabet only, no embedded '='.
	let datalen: i32 = n - np;
	let vi: i32 = 0;
	for (vi < datalen) {
		let c: u8 = b[vi];
		if (c >= 128u8) {
			let er: errors.invalid;
			return er;
		};
		if (c == PADDING) {
			let er: errors.invalid;
			return er;
		};
		if (enc.decmap[c] == 0xffu8) {
			let er: errors.invalid;
			return er;
		};
		vi += 1;
	};

	let outlen: i32 = (n / 4) * 3 - np;
	if (outlen == 0) {
		let empty: []u8;
		empty.ptr = nil;
		empty.len = 0;
		return empty;
	};
	let out: []u8 = alloc([], outlen: u64)!;

	let nquads: i32 = n / 4;
	let q: i32 = 0;
	let di: i32 = 0;
	for (q < nquads) {
		let base: i32 = q * 4;
		let v0: u8 = enc.decmap[b[base]];
		let v1: u8 = enc.decmap[b[base + 1]];
		if (q == nquads - 1 && np > 0) {
			out[di] = (v0 << 2u8) | (v1 >> 4u8);
			di += 1;
			if (np == 1) {
				let v2: u8 = enc.decmap[b[base + 2]];
				out[di] = (v1 << 4u8) | (v2 >> 2u8);
				di += 1;
			};
		} else {
			let v2: u8 = enc.decmap[b[base + 2]];
			let v3: u8 = enc.decmap[b[base + 3]];
			out[di]     = (v0 << 2u8) | (v1 >> 4u8);
			out[di + 1] = (v1 << 4u8) | (v2 >> 2u8);
			out[di + 2] = (v2 << 6u8) | v3;
			di += 3;
		};
		q += 1;
	};
	out.len = di;
	return out;
};

// encodedsize — bytes required to base64-encode `sz` source bytes,
// including '=' padding. ref/hare/encoding/base64/base64.ha:591.
export fn encodedsize(sz: i32) i32 = {
	if (sz == 0) {
		return 0;
	};
	return ((sz - 1) / 3 + 1) * 4;
};

// decodedsize — maximal decoded length for `sz` encoded bytes (the true
// length is up to 2 bytes shorter, depending on padding). `sz` must be a
// multiple of 4. ref/hare/encoding/base64/base64.ha:596-599.
export fn decodedsize(sz: i32) i32 = {
	assert(sz % 4i32 == 0i32);	// ref/hare/encoding/base64/base64.ha:597
	return sz / 4 * 3;
};