decode_runtime.go

// Copyright 2026 The Go Language Server Authors
// SPDX-License-Identifier: BSD-3-Clause

package protocol

import (
	"errors"
	"fmt"
	"io"
	"math"
	"slices"
	"strconv"
	"unicode/utf16"
	"unicode/utf8"
	"unsafe"

	"go.lsp.dev/uri"
)

// This file implements the shared primitives for the generated byte-level
// decoders. Each primitive consumes one JSON value from a fully-resident
// []byte starting at index i (the caller has already skipped insignificant
// whitespace) and returns the index just past the value. The primitives
// mirror the go-json-experiment semantics the package's reflection fallback
// exhibits under wireOptions — most importantly: raw invalid UTF-8 inside
// strings mangles to U+FFFD (AllowInvalidUTF8) while invalid escape sequences
// and bare control characters remain hard errors; duplicate object members
// decode last-wins (AllowDuplicateNames); integer fields reject fraction and
// exponent forms as syntax errors and range-check overflow.
//
// Unknown object members and raw-value fields are skipped with the same
// syntactic validation as known fields. That preserves the reflection path's
// wire-correctness contract while keeping the hot known-field scalar paths out
// of the generic token decoder.

const dvMaxDepth = 10000

// errDecodeTrailing reports non-whitespace bytes after a complete JSON value.
var errDecodeTrailing = errors.New("protocol: invalid character after top-level value")

// dvSyntaxError returns a positioned syntax error. It is deliberately out of
// the inlined hot path; callers only reach it on malformed input.
func dvSyntaxError(i int, what string) error {
	return fmt.Errorf("protocol: invalid JSON %s at offset %d", what, i)
}

// dvEnd verifies only insignificant whitespace remains in raw at or after i.
func dvEnd(raw []byte, i int) error {
	i = skipSpace(raw, i)
	if i != len(raw) {
		return errDecodeTrailing
	}
	return nil
}

// dvNull consumes a JSON null literal if present at raw[i].
func dvNull(raw []byte, i int) (next int, ok bool) {
	if len(raw)-i >= 4 && raw[i] == 'n' && raw[i+1] == 'u' && raw[i+2] == 'l' && raw[i+3] == 'l' {
		return i + 4, true
	}
	return i, false
}

// dvBool consumes a JSON true or false literal.
func dvBool(raw []byte, i int) (v bool, next int, err error) {
	switch {
	case len(raw)-i >= 4 && raw[i] == 't' && raw[i+1] == 'r' && raw[i+2] == 'u' && raw[i+3] == 'e':
		return true, i + 4, nil
	case len(raw)-i >= 5 && raw[i] == 'f' && raw[i+1] == 'a' && raw[i+2] == 'l' && raw[i+3] == 's' && raw[i+4] == 'e':
		return false, i + 5, nil
	}
	return false, i, dvSyntaxError(i, "boolean")
}

// dvIsDelim reports whether c terminates a scalar token.
func dvIsDelim(c byte) bool {
	return c == ',' || c == '}' || c == ']' || isJSONSpace(c)
}

// dvString consumes a JSON string starting at raw[i] (which must be '"') and
// returns its decoded Go value. The fast path covers strings without escapes
// or invalid UTF-8 and aliases the owned input copy installed by Unmarshal; the
// slow path decodes escape sequences (including UTF-16 surrogate pairs) and
// mangles raw invalid UTF-8 to U+FFFD, matching jsonwire.AppendUnquote under
// AllowInvalidUTF8.
func dvString(raw []byte, i int) (s string, next int, err error) {
	if i >= len(raw) || raw[i] != '"' {
		return "", i, dvSyntaxError(i, "string")
	}
	start := i + 1
	n := dvScanStringSpecial(raw, start)
	if n >= len(raw) {
		return "", len(raw), io.ErrUnexpectedEOF
	}
	if raw[n] == '"' {
		if n == start {
			return "", n + 1, nil
		}
		// unsafe.String aliases the per-message owned copy installed by
		// Unmarshal/UnmarshalJSONFrom; .bench/phase2-after-M5-decode-amd64.txt
		// records the allocation gate that justifies this hot-path risk.
		return unsafe.String(&raw[start], n-start), n + 1, nil
	}
	return dvStringSlow(raw, i)
}

// dvStringEnd consumes and validates a JSON string without constructing its
// decoded Go value on the common ASCII/no-escape path. It falls back to
// dvString for escape, multibyte, or invalid-UTF-8 cases so all edge semantics
// stay centralized in one state machine.
func dvStringEnd(raw []byte, i int) (next int, err error) {
	if i >= len(raw) || raw[i] != '"' {
		return i, dvSyntaxError(i, "string")
	}
	n := dvScanStringSpecial(raw, i+1)
	if n >= len(raw) {
		return len(raw), io.ErrUnexpectedEOF
	}
	if raw[n] == '"' {
		return n + 1, nil
	}
	_, next, err = dvString(raw, i)
	return next, err
}

// dvURI consumes a JSON string and parses it through go.lsp.dev/uri so URI
// fields store the canonical vscode-uri representation instead of a raw cast.
func dvURI(raw []byte, i int) (uri.URI, int, error) {
	s, n, err := dvString(raw, i)
	if err != nil {
		return "", n, err
	}
	u, err := uri.Parse(s)
	if err != nil {
		return "", n, err
	}
	return u, n, nil
}

// dvStringSlow handles strings containing escapes, multibyte UTF-8, control
// characters, or invalid UTF-8. It restarts from the opening quote at raw[i].
//
//nolint:cyclop,funlen,gocognit,nestif // single-pass wire parser mirroring jsonwire.AppendUnquote; splitting the state machine adds hot-path call overhead and scatters the escape semantics it must mirror exactly.
func dvStringSlow(raw []byte, i int) (s string, next int, err error) {
	n := i + 1
	buf := make([]byte, 0, 32)
	for n < len(raw) {
		c := raw[n]
		switch {
		case c == '"':
			return string(buf), n + 1, nil
		case c == '\\':
			if len(raw)-n < 2 {
				return "", len(raw), io.ErrUnexpectedEOF
			}
			switch e := raw[n+1]; e {
			case '"', '\\', '/':
				buf = append(buf, e)
				n += 2
			case 'b':
				buf = append(buf, '\b')
				n += 2
			case 'f':
				buf = append(buf, '\f')
				n += 2
			case 'n':
				buf = append(buf, '\n')
				n += 2
			case 'r':
				buf = append(buf, '\r')
				n += 2
			case 't':
				buf = append(buf, '\t')
				n += 2
			case 'u':
				if len(raw)-n < 6 {
					return "", len(raw), io.ErrUnexpectedEOF
				}
				v1, ok := dvHexUint16(raw[n+2 : n+6])
				if !ok {
					return "", n, dvSyntaxError(n, "escape sequence")
				}
				n += 6
				r := rune(v1)
				if utf16.IsSurrogate(r) {
					// Mirror jsonwire under AllowInvalidUTF8: an unpaired
					// surrogate mangles to U+FFFD (a following escape is left
					// for the next iteration); only malformed hex is a hard
					// error.
					r = utf8.RuneError
					if len(raw)-n >= 6 && raw[n] == '\\' && raw[n+1] == 'u' {
						v2, ok2 := dvHexUint16(raw[n+2 : n+6])
						if !ok2 {
							return "", n, dvSyntaxError(n, "escape sequence")
						}
						if dr := utf16.DecodeRune(rune(v1), rune(v2)); dr != utf8.RuneError {
							r = dr
							n += 6
						}
					}
				}
				buf = utf8.AppendRune(buf, r)
			default:
				return "", n, dvSyntaxError(n, "escape sequence")
			}
		case c < ' ':
			return "", n, dvSyntaxError(n, "control character in string")
		case c < utf8.RuneSelf:
			buf = append(buf, c)
			n++
		default:
			r, rn := utf8.DecodeRune(raw[n:])
			if r == utf8.RuneError && rn == 1 {
				if !utf8.FullRune(raw[n:]) {
					return "", len(raw), io.ErrUnexpectedEOF
				}
				// AllowInvalidUTF8: mangle, do not reject.
				buf = append(buf, "�"...)
				n++
			} else {
				buf = append(buf, raw[n:n+rn]...)
				n += rn
			}
		}
	}
	return "", len(raw), io.ErrUnexpectedEOF
}

// dvHexUint16 parses exactly four hex digits.
func dvHexUint16(b []byte) (v uint16, ok bool) {
	for _, c := range b {
		switch {
		case c >= '0' && c <= '9':
			v = v<<4 | uint16(c-'0')
		case c >= 'a' && c <= 'f':
			v = v<<4 | uint16(c-'a'+10)
		case c >= 'A' && c <= 'F':
			v = v<<4 | uint16(c-'A'+10)
		default:
			return 0, false
		}
	}
	return v, true
}

// dvNumberEnd validates the JSON number grammar starting at raw[i] and
// returns the index just past the token plus whether the token is an integer
// (no fraction or exponent part).
//
//nolint:cyclop,gocognit,gocyclo // single-pass JSON number grammar automaton on the hot path; the branch count is the grammar itself.
func dvNumberEnd(raw []byte, i int) (next int, integer bool, err error) {
	n := i
	integer = true
	if n < len(raw) && raw[n] == '-' {
		n++
	}
	switch {
	case n < len(raw) && raw[n] == '0':
		n++
	case n < len(raw) && raw[n] >= '1' && raw[n] <= '9':
		n++
		for n < len(raw) && raw[n] >= '0' && raw[n] <= '9' {
			n++
		}
	default:
		return i, false, dvSyntaxError(i, "number")
	}
	if n < len(raw) && raw[n] == '.' {
		integer = false
		n++
		if n >= len(raw) || raw[n] < '0' || raw[n] > '9' {
			return i, false, dvSyntaxError(n, "number fraction")
		}
		for n < len(raw) && raw[n] >= '0' && raw[n] <= '9' {
			n++
		}
	}
	if n < len(raw) && (raw[n] == 'e' || raw[n] == 'E') {
		integer = false
		n++
		if n < len(raw) && (raw[n] == '+' || raw[n] == '-') {
			n++
		}
		if n >= len(raw) || raw[n] < '0' || raw[n] > '9' {
			return i, false, dvSyntaxError(n, "number exponent")
		}
		for n < len(raw) && raw[n] >= '0' && raw[n] <= '9' {
			n++
		}
	}
	if n < len(raw) && !dvIsDelim(raw[n]) {
		return i, false, dvSyntaxError(n, "number")
	}
	return n, integer, nil
}

// dvUint32 consumes a JSON number into a uint32, mirroring the reflection
// behavior: fraction, exponent, and sign forms are syntax errors; values
// beyond 32 bits are range errors.
func dvUint32(raw []byte, i int) (v uint32, next int, err error) {
	end, integer, err := dvNumberEnd(raw, i)
	if err != nil {
		return 0, i, err
	}
	if !integer || raw[i] == '-' {
		return 0, i, dvSyntaxError(i, "unsigned integer")
	}
	var u uint64
	for _, c := range raw[i:end] {
		u = u*10 + uint64(c-'0')
		if u > math.MaxUint32 {
			return 0, i, strconv.ErrRange
		}
	}
	return uint32(u), end, nil
}

// dvInt32 consumes a JSON number into an int32 with the same strictness as
// dvUint32 plus an optional leading minus.
func dvInt32(raw []byte, i int) (v int32, next int, err error) {
	end, integer, err := dvNumberEnd(raw, i)
	if err != nil {
		return 0, i, err
	}
	if !integer {
		return 0, i, dvSyntaxError(i, "integer")
	}
	d := raw[i:end]
	neg := false
	if d[0] == '-' {
		neg = true
		d = d[1:]
	}
	var u uint64
	for _, c := range d {
		u = u*10 + uint64(c-'0')
		if u > math.MaxInt32+1 {
			return 0, i, strconv.ErrRange
		}
	}
	if neg {
		if u > math.MaxInt32+1 {
			return 0, i, strconv.ErrRange
		}
		return int32(-int64(u)), end, nil
	}
	if u > math.MaxInt32 {
		return 0, i, strconv.ErrRange
	}
	return int32(u), end, nil
}

// dvFloat64 consumes any JSON number into a float64.
func dvFloat64(raw []byte, i int) (v float64, next int, err error) {
	end, _, err := dvNumberEnd(raw, i)
	if err != nil {
		return 0, i, err
	}
	f, err := strconv.ParseFloat(string(raw[i:end]), 64)
	if err != nil {
		return 0, i, dvSyntaxError(i, "number")
	}
	return f, end, nil
}

// dvUint32Slice consumes a JSON array of unsigned integers into dst, reusing
// its backing storage. A null yields a nil slice, matching the reflection
// path.
//
//nolint:cyclop // single-pass semantic-token array parser; splitting the hot numeric state machine adds per-element call overhead.
func dvUint32Slice[T ~uint32](raw []byte, i int, dst []T) (v []T, next int, err error) {
	if n, ok := dvNull(raw, i); ok {
		return nil, n, nil
	}
	if i >= len(raw) || raw[i] != '[' {
		return dst, i, dvSyntaxError(i, "array")
	}
	i = skipSpace(raw, i+1)
	out := dst[:0]
	if i < len(raw) && raw[i] == ']' {
		// jsonv2 decodes [] into an empty non-nil slice.
		if out == nil {
			out = []T{}
		}
		return out, i + 1, nil
	}
	// Bytes-remaining heuristic instead of an exact comma pre-scan: the
	// pre-scan was 3.4% of decode CPU on the amd64 spine for at most one
	// saved growth step. Two bytes per element ("N,") upper-bounds the count
	// so the result still lands in a single allocation.
	out = slices.Grow(out, dvSliceCapHint(raw, i, 2))
	for {
		var u uint64
		i = skipSpace(raw, i)
		if i >= len(raw) {
			return dst, len(raw), io.ErrUnexpectedEOF
		}
		switch {
		case raw[i] == '0':
			i++
		case raw[i] >= '1' && raw[i] <= '9':
			for i < len(raw) && raw[i] >= '0' && raw[i] <= '9' {
				u = u*10 + uint64(raw[i]-'0')
				if u > math.MaxUint32 {
					return dst, i, strconv.ErrRange
				}
				i++
			}
		case raw[i] == '-':
			return dst, i, dvSyntaxError(i, "unsigned integer")
		default:
			return dst, i, dvSyntaxError(i, "number")
		}
		if i < len(raw) && raw[i] >= '0' && raw[i] <= '9' {
			return dst, i, dvSyntaxError(i, "number")
		}
		out = append(out, T(u))
		i = skipSpace(raw, i)
		if i >= len(raw) {
			return dst, len(raw), io.ErrUnexpectedEOF
		}
		switch raw[i] {
		case ',':
			i++
		case ']':
			return out, i + 1, nil
		default:
			return dst, i, dvSyntaxError(i, "array")
		}
	}
}

// dvStringSliceLenHint counts the elements of a string array by scanning for
// closing quotes outside escape sequences, so dvStringSlice can size its
// result in one allocation. String arrays cannot nest, which makes the count
// exact for valid input; malformed input merely yields a harmless hint.
func dvStringSliceLenHint(raw []byte, i int) int {
	n := 0
	inStr := false
	for ; i < len(raw); i++ {
		switch c := raw[i]; {
		case inStr && c == '\\':
			i++
		case inStr && c == '"':
			inStr = false
			n++
		case !inStr && c == '"':
			inStr = true
		case !inStr && c == ']':
			return max(n, 1)
		}
	}
	return max(n, 1)
}

// dvSliceCapHint bounds an element-count guess for pre-sizing slice and slab
// capacity from the bytes remaining after i. Arrays dominate the tail of LSP
// payloads, so remaining-length divided by a per-element wire estimate lands
// within one growth step of the true count without a structural pre-scan.
// The bound exists only to cap pathological pre-allocation; semantic-token
// arrays legitimately reach several thousand elements.
func dvSliceCapHint(raw []byte, i, perElem int) int {
	return min((len(raw)-i)/perElem+1, 4096)
}

// dvStringSlice consumes a JSON array of strings into dst, reusing its
// backing storage.
func dvStringSlice[T ~string](raw []byte, i int, dst []T) (v []T, next int, err error) {
	if n, ok := dvNull(raw, i); ok {
		return nil, n, nil
	}
	if i >= len(raw) || raw[i] != '[' {
		return dst, i, dvSyntaxError(i, "array")
	}
	i = skipSpace(raw, i+1)
	out := dst[:0]
	if i < len(raw) && raw[i] == ']' {
		if out == nil {
			out = []T{}
		}
		return out, i + 1, nil
	}
	out = slices.Grow(out, dvStringSliceLenHint(raw, i))
	for {
		var s string
		s, i, err = dvString(raw, skipSpace(raw, i))
		if err != nil {
			return dst, i, err
		}
		out = append(out, T(s))
		i = skipSpace(raw, i)
		if i >= len(raw) {
			return dst, len(raw), io.ErrUnexpectedEOF
		}
		switch raw[i] {
		case ',':
			i++
		case ']':
			return out, i + 1, nil
		default:
			return dst, i, dvSyntaxError(i, "array")
		}
	}
}

// dvNullValue verifies raw is exactly a JSON null (plus whitespace), used by
// the generated union decoders so a root-level "null trailing-garbage" input
// is rejected like the reflection path rejects it.
func dvNullValue(raw []byte) error {
	i := skipSpace(raw, 0)
	n, ok := dvNull(raw, i)
	if !ok {
		return dvSyntaxError(i, "null")
	}
	return dvEnd(raw, n)
}

// dvScalarString decodes a complete JSON value that must be a string.
func dvScalarString(raw []byte) (string, error) {
	s, i, err := dvString(raw, skipSpace(raw, 0))
	if err != nil {
		return "", err
	}
	return s, dvEnd(raw, i)
}

// dvScalarURI decodes a complete JSON string value as a canonical URI.
func dvScalarURI(raw []byte) (uri.URI, error) {
	u, i, err := dvURI(raw, skipSpace(raw, 0))
	if err != nil {
		return "", err
	}
	return u, dvEnd(raw, i)
}

// dvScalarInt32 decodes a complete JSON value that must be an integer.
func dvScalarInt32(raw []byte) (int32, error) {
	v, i, err := dvInt32(raw, skipSpace(raw, 0))
	if err != nil {
		return 0, err
	}
	return v, dvEnd(raw, i)
}

// dvScalarBool decodes a complete JSON value that must be a boolean.
func dvScalarBool(raw []byte) (bool, error) {
	v, i, err := dvBool(raw, skipSpace(raw, 0))
	if err != nil {
		return false, err
	}
	return v, dvEnd(raw, i)
}

// dvDiagnosticTags consumes a JSON array of diagnostic tags (or null) into
// out.
func dvDiagnosticTags(raw []byte, i int, out *DiagnosticTags) (next int, err error) {
	if n, ok := dvNull(raw, i); ok {
		out.Clear()
		return n, nil
	}
	if i >= len(raw) || raw[i] != '[' {
		return i, dvSyntaxError(i, "array")
	}
	out.Clear()
	i = skipSpace(raw, i+1)
	if i < len(raw) && raw[i] == ']' {
		return i + 1, nil
	}
	for {
		var u uint32
		u, i, err = dvUint32(raw, skipSpace(raw, i))
		if err != nil {
			return i, err
		}
		out.append(DiagnosticTag(u))
		var done bool
		i, done, err = dvArrayNext(raw, i)
		if err != nil {
			return i, err
		}
		if done {
			return i, nil
		}
	}
}

// dvValue consumes one syntactically valid JSON value and returns its raw
// bytes. The bytes alias raw.
func dvValue(raw []byte, i int) (val []byte, next int, err error) {
	i = skipSpace(raw, i)
	if i >= len(raw) {
		return nil, len(raw), io.ErrUnexpectedEOF
	}
	end, err := dvValueEnd(raw, i, 0)
	if err != nil {
		return nil, end, err
	}
	return raw[i:end], end, nil
}

// dvValueEnd validates one complete JSON value and returns the first byte
// after it. It intentionally does not consume following delimiter whitespace;
// the caller's object/array separator logic owns that.
func dvValueEnd(raw []byte, i, depth int) (int, error) {
	if depth > dvMaxDepth {
		return i, dvSyntaxError(i, "maximum nesting depth")
	}
	i = skipSpace(raw, i)
	if i >= len(raw) {
		return len(raw), io.ErrUnexpectedEOF
	}
	switch raw[i] {
	case 'n':
		n, ok := dvNull(raw, i)
		if !ok {
			return i, dvSyntaxError(i, "null")
		}
		return n, nil
	case 't', 'f':
		_, n, err := dvBool(raw, i)
		return n, err
	case '"':
		return dvStringEnd(raw, i)
	case '[':
		return dvArrayEnd(raw, i, depth)
	case '{':
		return dvObjectEnd(raw, i, depth)
	default:
		n, _, err := dvNumberEnd(raw, i)
		return n, err
	}
}

func dvArrayEnd(raw []byte, i, depth int) (int, error) {
	i = skipSpace(raw, i+1)
	if i < len(raw) && raw[i] == ']' {
		return i + 1, nil
	}
	for {
		var err error
		i, err = dvValueEnd(raw, i, depth+1)
		if err != nil {
			return i, err
		}
		var done bool
		i, done, err = dvArrayNext(raw, i)
		if err != nil {
			return i, err
		}
		if done {
			return i, nil
		}
	}
}

func dvObjectEnd(raw []byte, i, depth int) (int, error) {
	i = skipSpace(raw, i+1)
	if i < len(raw) && raw[i] == '}' {
		return i + 1, nil
	}
	for {
		var err error
		_, i, err = dvMemberKey(raw, i)
		if err != nil {
			return i, err
		}
		i, err = dvValueEnd(raw, i, depth+1)
		if err != nil {
			return i, err
		}
		var done bool
		i, done, err = dvObjectNext(raw, i)
		if err != nil {
			return i, err
		}
		if done {
			return i, nil
		}
	}
}

// dvMemberKey consumes an object member key plus the following colon and
// returns the raw (still escaped) key bytes, which alias raw. The caller
// compares them with keyEquals so escaped spellings of member names match.
func dvMemberKey(raw []byte, i int) (key []byte, next int, err error) {
	ke, err := dvStringEnd(raw, i)
	if err != nil {
		return nil, ke, err
	}
	key = raw[i+1 : ke-1]
	i = skipSpace(raw, ke)
	if i >= len(raw) || raw[i] != ':' {
		return nil, i, dvSyntaxError(i, "object member separator")
	}
	return key, skipSpace(raw, i+1), nil
}

// dvObjectNext advances past the separator following an object member.
// It reports done=true when the closing brace was consumed.
func dvObjectNext(raw []byte, i int) (next int, done bool, err error) {
	i = skipSpace(raw, i)
	if i >= len(raw) {
		return len(raw), false, io.ErrUnexpectedEOF
	}
	switch raw[i] {
	case ',':
		return skipSpace(raw, i+1), false, nil
	case '}':
		return i + 1, true, nil
	}
	return i, false, dvSyntaxError(i, "object")
}

// dvArrayNext advances past the separator following an array element.
// It reports done=true when the closing bracket was consumed.
func dvArrayNext(raw []byte, i int) (next int, done bool, err error) {
	i = skipSpace(raw, i)
	if i >= len(raw) {
		return len(raw), false, io.ErrUnexpectedEOF
	}
	switch raw[i] {
	case ',':
		return skipSpace(raw, i+1), false, nil
	case ']':
		return i + 1, true, nil
	}
	return i, false, dvSyntaxError(i, "array")
}