bootjp
diff --git a/‎internal/backup/filename.go‎
Lines changed: 313 additions & 0 deletions b/‎internal/backup/filename.go‎
Lines changed: 313 additions & 0 deletions
@@ -0,0 +1,313 @@
+// Package backup implements the per-adapter logical-backup format defined in
+// docs/design/2026_04_29_proposed_snapshot_logical_decoder.md (Phase 0) and
+// reused by docs/design/2026_04_29_proposed_logical_backup.md (Phase 1).
+//
+// This file owns the filename encoding rules for non-S3 segments. S3 object
+// keys preserve their `/` separators (and so are not transformed by EncodeSegment);
+// every other adapter scope encodes user-supplied bytes through this path.
+//
+// Encoding rules (see "Filename encoding" in the Phase 0 doc):
+//
+//   - Bytes in the unreserved set [A-Za-z0-9._-] pass through.
+//   - Every other byte is rendered as %HH (uppercase hex), like
+//     application/x-www-form-urlencoded but applied to every non-allowlisted byte.
+//   - If the encoded result exceeds maxSegmentBytes (240), the segment is
+//     replaced with <sha256-hex-prefix-32>__<truncated-original> and the full
+//     original bytes must be recorded in KEYMAP.jsonl by the caller.
+//   - Binary DynamoDB partition / sort keys take a separate "b64.<base64url>"
+//     path so a binary key never collides with a string key whose hex encoding
+//     happens to look like base64. EncodeBinarySegment emits that form.
+package backup
+
+import (
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"strings"
+
+	"github.com/cockroachdb/errors"
+)
+
+const (
+	// maxSegmentBytes is the maximum length of a single encoded path segment
+	// before the SHA-fallback kicks in. Chosen to leave headroom under the
+	// common NAME_MAX of 255: two-character percent escapes can grow a 240-byte
+	// raw segment to 720 encoded bytes in the worst case, but any segment
+	// large enough to overflow NAME_MAX after expansion takes the SHA-fallback
+	// path before the encoded length is examined.
+	maxSegmentBytes = 240
+
+	// shaFallbackHexPrefixBytes is the number of hex characters of SHA-256
+	// embedded in the SHA-fallback prefix. 32 hex chars == 128 bits of
+	// hash-prefix entropy — enough to make accidental collision negligible
+	// for any single scope.
+	shaFallbackHexPrefixBytes = 32
+
+	// shaFallbackTruncatedSuffixBytes is the number of leading bytes of the
+	// raw segment retained (after percent-encoding) in the SHA-fallback
+	// rendering. Total encoded segment is then at most:
+	//
+	//   shaFallbackHexPrefixBytes + len("__") + 3*shaFallbackTruncatedSuffixBytes
+	//
+	// = 32 + 2 + 3*64 = 226 bytes  (under the 240 ceiling).
+	//
+	// The truncated suffix is purely a human-recognisability aid; it does
+	// NOT carry enough information to reverse the original bytes — that is
+	// what KEYMAP.jsonl is for.
+	shaFallbackTruncatedSuffixBytes = 64
+
+	// binaryPrefix marks a DynamoDB B-attribute segment encoded as base64url.
+	binaryPrefix = "b64."
+
+	// shaFallbackSeparator separates the SHA-256 prefix from the truncated
+	// original bytes. Two underscores rather than one because single
+	// underscores are common in user keys; doubled is much rarer and so
+	// the boundary is unambiguous.
+	shaFallbackSeparator = "__"
+)
+
+// ErrInvalidEncodedSegment is returned by DecodeSegment when its input is
+// neither a valid percent-encoded segment, a binary-prefixed segment, nor a
+// SHA-fallback segment.
+var ErrInvalidEncodedSegment = errors.New("backup: invalid encoded filename segment")
+
+// ErrShaFallbackNeedsKeymap is returned by DecodeSegment when its input is a
+// SHA-fallback segment. The segment cannot be reversed to its original bytes
+// from the filename alone — the caller must consult KEYMAP.jsonl.
+var ErrShaFallbackNeedsKeymap = errors.New("backup: filename uses SHA fallback; consult KEYMAP.jsonl")
+
+// EncodeSegment encodes a single user-supplied path segment for use as a
+// filename component. It is the inverse of DecodeSegment for non-fallback
+// inputs.
+//
+// The encoding is deterministic given the same input.
+//
+// Three structural short-circuits ensure DecodeSegment cannot
+// misclassify a legitimate key:
+//
+//   - If `raw` is longer than maxSegmentBytes, even a fully-unreserved
+//     encoding (1:1) cannot fit, so we go straight to shaFallback.
+//     This also caps the percent-encode allocation at
+//     ~maxSegmentBytes, preventing OOM on adversarial input.
+//   - If the percent-encoded form happens to match the SHA-fallback
+//     shape (32 hex chars followed by "__"), we promote it to a real
+//     SHA-fallback so DecodeSegment's structural detection cannot
+//     fabricate a wrong original.
+//   - If the percent-encoded form starts with the binary "b64."
+//     prefix, we promote to SHA-fallback for the same reason: a
+//     plain string key like "b64.foo" would otherwise be decoded as
+//     base64 and produce different bytes on round-trip.
+//
+// Both promoted-fallback paths leave the original in KEYMAP.jsonl
+// (a correctness dependency, per the package doc), so exact-byte
+// recovery is preserved.
+func EncodeSegment(raw []byte) string {
+	if len(raw) > maxSegmentBytes {
+		// 1:1 lower bound on encoded length; cannot fit.
+		return shaFallback(raw)
+	}
+	encoded, ok := percentEncodeBounded(raw, maxSegmentBytes)
+	if !ok || isShaFallback(encoded) || strings.HasPrefix(encoded, binaryPrefix) {
+		return shaFallback(raw)
+	}
+	return encoded
+}
+
+// percentEncodeBounded percent-encodes raw, bailing out as soon as the
+// in-progress output would exceed maxLen. Returns ("", false) on
+// overflow so the caller can take the SHA-fallback path without
+// having allocated the full 3*len(raw) buffer that the unbounded
+// variant would. Returns (encoded, true) on success.
+func percentEncodeBounded(raw []byte, maxLen int) (string, bool) {
+	const escapeBytes = 3 // len("%HH") -- one escape's worst-case width
+	cap := escapeBytes * len(raw)
+	if cap > maxLen+escapeBytes {
+		cap = maxLen + escapeBytes
+	}
+	var b strings.Builder
+	b.Grow(cap)
+	for _, c := range raw {
+		if isUnreserved(c) {
+			if b.Len()+1 > maxLen {
+				return "", false
+			}
+			b.WriteByte(c)
+			continue
+		}
+		if b.Len()+escapeBytes > maxLen {
+			return "", false
+		}
+		b.WriteByte('%')
+		b.WriteByte(hexUpper(c >> 4))   //nolint:mnd // 4 == nibble width
+		b.WriteByte(hexUpper(c & 0x0F)) //nolint:mnd // 0x0F == low-nibble mask
+	}
+	return b.String(), true
+}
+
+// EncodeBinarySegment encodes a DynamoDB B-attribute (binary) segment as
+// "b64.<base64url-no-padding>" so that binary keys never collide with string
+// keys whose hex-encoding happens to look like base64.
+//
+// Short-circuits the SHA-fallback for inputs whose base64 expansion (~4/3 of
+// the raw length, plus the 4-byte "b64." prefix) would always overflow
+// maxSegmentBytes. As with EncodeSegment, this avoids an unnecessary large
+// allocation when the result would have been discarded anyway.
+func EncodeBinarySegment(raw []byte) string {
+	if base64.RawURLEncoding.EncodedLen(len(raw))+len(binaryPrefix) > maxSegmentBytes {
+		return shaFallback(raw)
+	}
+	enc := binaryPrefix + base64.RawURLEncoding.EncodeToString(raw)
+	if len(enc) > maxSegmentBytes {
+		return shaFallback(raw)
+	}
+	return enc
+}
+
+// DecodeSegment is the inverse of EncodeSegment for percent-encoded and
+// binary-prefixed inputs. SHA-fallback inputs return ErrShaFallbackNeedsKeymap
+// so the caller knows to consult KEYMAP.jsonl rather than treat the partial
+// suffix as the original key.
+//
+// As a defensive measure DecodeSegment refuses inputs longer than
+// maxSegmentBytes. EncodeSegment never produces such inputs, so any caller
+// passing one is either reading a corrupted dump or has a bug; either way the
+// percentDecode allocation should not run.
+func DecodeSegment(seg string) ([]byte, error) {
+	if len(seg) > maxSegmentBytes {
+		return nil, errors.Wrapf(ErrInvalidEncodedSegment,
+			"segment length %d exceeds maximum %d", len(seg), maxSegmentBytes)
+	}
+	if isShaFallback(seg) {
+		return nil, errors.WithStack(ErrShaFallbackNeedsKeymap)
+	}
+	if strings.HasPrefix(seg, binaryPrefix) {
+		raw, err := base64.RawURLEncoding.DecodeString(seg[len(binaryPrefix):])
+		if err != nil {
+			return nil, errors.Wrap(ErrInvalidEncodedSegment, err.Error())
+		}
+		return raw, nil
+	}
+	return percentDecode(seg)
+}
+
+// IsShaFallback reports whether seg uses the SHA-prefix-and-truncated-original
+// form. Such segments cannot be reversed without KEYMAP.jsonl.
+func IsShaFallback(seg string) bool {
+	return isShaFallback(seg)
+}
+
+// IsBinarySegment reports whether seg is a base64-url encoded binary segment
+// emitted by EncodeBinarySegment.
+func IsBinarySegment(seg string) bool {
+	return strings.HasPrefix(seg, binaryPrefix)
+}
+
+func percentEncode(raw []byte) string {
+	// Worst case: every byte expands to %HH (3 bytes). Pre-allocate.
+	var b strings.Builder
+	b.Grow(len(raw) * 3) //nolint:mnd // 3 == len("%HH"), local idiom
+	for _, c := range raw {
+		if isUnreserved(c) {
+			b.WriteByte(c)
+			continue
+		}
+		b.WriteByte('%')
+		b.WriteByte(hexUpper(c >> 4))   //nolint:mnd // 4 == nibble width
+		b.WriteByte(hexUpper(c & 0x0F)) //nolint:mnd // 0x0F == low-nibble mask
+	}
+	return b.String()
+}
+
+func percentDecode(seg string) ([]byte, error) {
+	out := make([]byte, 0, len(seg))
+	for i := 0; i < len(seg); i++ {
+		c := seg[i]
+		if c != '%' {
+			if !isUnreserved(c) {
+				return nil, errors.Wrapf(ErrInvalidEncodedSegment,
+					"unexpected raw byte 0x%02x at offset %d", c, i)
+			}
+			out = append(out, c)
+			continue
+		}
+		if i+2 >= len(seg) { //nolint:mnd // 2 == hex digit count after %
+			return nil, errors.Wrapf(ErrInvalidEncodedSegment,
+				"truncated percent escape at offset %d", i)
+		}
+		const (
+			hiNibbleOff = 1
+			loNibbleOff = 2
+		)
+		hi, ok := unhex(seg[i+hiNibbleOff])
+		if !ok {
+			return nil, errors.Wrapf(ErrInvalidEncodedSegment,
+				"non-hex digit 0x%02x at offset %d", seg[i+hiNibbleOff], i+hiNibbleOff)
+		}
+		lo, ok := unhex(seg[i+loNibbleOff])
+		if !ok {
+			return nil, errors.Wrapf(ErrInvalidEncodedSegment,
+				"non-hex digit 0x%02x at offset %d", seg[i+loNibbleOff], i+loNibbleOff)
+		}
+		out = append(out, (hi<<4)|lo) //nolint:mnd // 4 == nibble width
+		i += loNibbleOff              // skip the two consumed hex digits
+	}
+	return out, nil
+}
+
+func shaFallback(raw []byte) string {
+	sum := sha256.Sum256(raw)
+	hashHex := hex.EncodeToString(sum[:])[:shaFallbackHexPrefixBytes]
+	suffix := raw
+	if len(suffix) > shaFallbackTruncatedSuffixBytes {
+		suffix = suffix[:shaFallbackTruncatedSuffixBytes]
+	}
+	return hashHex + shaFallbackSeparator + percentEncode(suffix)
+}
+
+func isShaFallback(seg string) bool {
+	if len(seg) < shaFallbackHexPrefixBytes+len(shaFallbackSeparator) {
+		return false
+	}
+	for i := 0; i < shaFallbackHexPrefixBytes; i++ {
+		if _, ok := unhex(seg[i]); !ok {
+			return false
+		}
+	}
+	return seg[shaFallbackHexPrefixBytes:shaFallbackHexPrefixBytes+len(shaFallbackSeparator)] == shaFallbackSeparator
+}
+
+// isUnreserved is the RFC3986 unreserved set: ALPHA / DIGIT / "-" / "." / "_".
+// "~" is excluded because it has caused interop problems with older shells and
+// the additional safety is not worth the rare benefit.
+func isUnreserved(c byte) bool {
+	switch {
+	case c >= 'A' && c <= 'Z':
+		return true
+	case c >= 'a' && c <= 'z':
+		return true
+	case c >= '0' && c <= '9':
+		return true
+	case c == '-', c == '.', c == '_':
+		return true
+	}
+	return false
+}
+
+func hexUpper(nibble byte) byte {
+	if nibble < 10 { //nolint:mnd // 10 == decimal/hex boundary
+		return '0' + nibble
+	}
+	return 'A' + (nibble - 10) //nolint:mnd // 10 == decimal/hex boundary
+}
+
+func unhex(c byte) (byte, bool) {
+	switch {
+	case c >= '0' && c <= '9':
+		return c - '0', true
+	case c >= 'a' && c <= 'f':
+		return c - 'a' + 10, true //nolint:mnd // 10 == decimal/hex boundary
+	case c >= 'A' && c <= 'F':
+		return c - 'A' + 10, true //nolint:mnd // 10 == decimal/hex boundary
+	}
+	return 0, false
+}