querystring.go

// Copyright 2026 Company.info B.V.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package reqbind

import (
	"errors"
	"fmt"
	"net/url"
	"reflect"
	"regexp"
	"strconv"
	"strings"

	"golang.org/x/text/cases"
	"golang.org/x/text/language"
)

// queryStringPattern defines the regex pattern for matching bracket-notation query strings.
var queryStringPattern = regexp.MustCompile(`(?P<key>\w+)(?P<innerKeys>(\[[a-zA-Z]+])+)$`)

var (
	// ErrMalformedQueryString is returned when the query string has an invalid structure (e.g. mismatched brackets).
	ErrMalformedQueryString = errors.New("invalid query string")
	// ErrEmptyQueryParam is returned when an empty query parameter is encountered.
	ErrEmptyQueryParam = errors.New("empty query param")
)

// ParsedQueryString represents a parsed and categorized query string parameter.
type ParsedQueryString struct {
	Key       string
	InnerKeys []string
	Values    []string
}

// decodeQueryParams converts query string parameters into the given struct.
func decodeQueryParams(query url.Values, target any) error {
	for key, value := range query {
		if err := parseAndBind(key, value, target); err != nil {
			return err
		}
	}
	return nil
}

// parseAndBind parses a query string key-value pair and binds it to the target struct.
func parseAndBind(key string, value any, target any) error {
	pqs, err := parseQueryString(key, value)
	if err != nil {
		return err
	}

	return parsedQueryToStruct(pqs, target)
}

// parseQueryString parses a query string key based on bracket notation.
func parseQueryString(key string, value any) (*ParsedQueryString, error) {
	pqs := &ParsedQueryString{}
	// Check if it is a nested query string with bracket notation.
	if strings.Contains(key, "[") || strings.Contains(key, "]") {
		if !queryStringPattern.MatchString(key) {
			return nil, ErrMalformedQueryString
		}

		// Extract the key and nested path.
		parsed := make(map[string]string)
		matched := queryStringPattern.FindStringSubmatch(key)
		for index, name := range queryStringPattern.SubexpNames() {
			if index != 0 {
				parsed[name] = matched[index]
			}
		}

		// Parse the inner keys from the bracket notation.
		innerKeys, err := extractInnerKeys(parsed["innerKeys"])
		if err != nil {
			return nil, err
		}

		pqs.Key = parsed["key"]
		pqs.InnerKeys = innerKeys
	} else {
		// Simple query string without bracket notation.
		pqs.Key = key
	}

	// Parse value.
	//lint:ignore S1034 switch case is much cleaner than if/else here.
	switch value.(type) {
	case string:
		pqs.Values = strings.Split(value.(string), ",")
	case []string:
		pqs.Values = value.([]string)
	}

	return pqs, nil
}

// extractInnerKeys parses the nested part of the query string and extracts the inner keys.
// For example, it parses [company][id] and returns [company, id] as the inner keys.
func extractInnerKeys(input string) ([]string, error) {
	if len(input) == 0 {
		return nil, ErrEmptyQueryParam
	}
	result := make([]string, 0)
	fieldName := ""

	// Iterate over characters and extract field names between brackets.
	for _, c := range input {
		if string(c) == "[" {
			continue
		}

		if string(c) == "]" {
			if len(fieldName) == 0 {
				return nil, ErrMalformedQueryString
			}
			result = append(result, fieldName)
			fieldName = ""
			continue
		}

		fieldName = fieldName + string(c)
	}

	return result, nil
}

// parsedQueryToStruct converts a parsed query string into the target struct fields.
func parsedQueryToStruct(pqs *ParsedQueryString, target any) error {
	var field reflect.Value
	targetFieldValues := target.(reflect.Value)

	// Locate the top-level field in the struct.
	field, err := findField(targetFieldValues, pqs.Key)
	if err != nil {
		return err
	}

	var mapKey string
	if len(pqs.InnerKeys) != 0 {
		// Traverse the nested struct fields to find the target element.
		for _, p := range pqs.InnerKeys {
			mapKey = p
			field, err = findField(field, p)
			if err != nil {
				return err
			}
		}
	}

	// Validate that the target field can be set.
	if !field.IsValid() || !field.CanSet() {
		return fmt.Errorf("cannot set value to the attribute %s", field.String())
	}
	if field.Kind() == reflect.Struct {
		return fmt.Errorf("cannot set value to the struct attribute %s", field.String())

	} else if field.Kind() == reflect.Slice {
		field.Set(reflect.ValueOf(splitValues(pqs.Values[0])))

	} else if field.Kind() == reflect.Int || field.Kind() == reflect.Int8 || field.Kind() == reflect.Int16 ||
		field.Kind() == reflect.Int32 || field.Kind() == reflect.Int64 {
		i, err := strconv.ParseInt(strings.Join(pqs.Values, ","), 10, 64)
		if err != nil {
			return fmt.Errorf("cannot parse int for the attribute %s", field.String())
		}
		field.SetInt(i)

	} else if field.Kind() == reflect.Uint || field.Kind() == reflect.Uint8 ||
		field.Kind() == reflect.Uint16 || field.Kind() == reflect.Uint32 || field.Kind() == reflect.Uint64 {
		ui, err := strconv.ParseUint(strings.Join(pqs.Values, ","), 10, 64)
		if err != nil {
			return fmt.Errorf("cannot parse int for the attribute %s", field.String())
		}
		field.SetUint(ui)

	} else if field.Kind() == reflect.Float64 || field.Kind() == reflect.Float32 {
		f, _ := strconv.ParseFloat(strings.Join(pqs.Values, ","), 64)
		field.SetFloat(f)

	} else if field.Kind() == reflect.Ptr && field.Type().Elem().Kind() == reflect.Int {
		// Handle pointers to integers.
		i, err := strconv.ParseInt(strings.Join(pqs.Values, ","), 10, 64)
		if err != nil {
			return fmt.Errorf("cannot parse int for the attribute %s", field.String())
		}
		// Allocate memory for the pointer if nil.
		if field.IsNil() {
			field.Set(reflect.New(field.Type().Elem()))
		}
		// Set the value of the integer.
		field.Elem().SetInt(i)

	} else if field.Kind() == reflect.Map {
		// Ensure the map is initialized before setting values.
		if field.IsNil() {
			field.Set(reflect.MakeMap(field.Type()))
		}
		field.SetMapIndex(reflect.ValueOf(mapKey), reflect.ValueOf(strings.Join(pqs.Values, ",")))
	} else {
		field.SetString(strings.Join(pqs.Values, ","))
	}

	return nil
}

// splitValues splits a comma-separated string into a slice of strings.
func splitValues(input string) []string {
	input = strings.TrimSpace(input)

	// Handle special cases where the input is empty or just a comma.
	if input == "" || input == "," {
		return nil
	}

	separatedValues := strings.Split(input, ",")

	return separatedValues
}

// findField locates a struct field by its name or goReq tag value.
func findField(fieldValues reflect.Value, fieldName string) (reflect.Value, error) {
	caser := cases.Title(language.English, cases.NoLower)

	// Check the struct tags first; if no tag matches, fall back to the field name.
	switch fieldValues.Kind() {
	case reflect.Struct:
		for i := 0; i < fieldValues.NumField(); i++ {
			f := fieldValues.Type().Field(i)

			// Check if the tag matches.
			tagValue := f.Tag.Get(GoReqTag)
			if tagValue == fieldName {
				return fieldValues.Field(i), nil
			}

			// Check if the field name matches.
			if f.Name == caser.String(fieldName) {
				return fieldValues.Field(i), nil
			}
		}
	case reflect.Map:
		// Ensure the map keys are strings.
		if fieldValues.Type().Key().Kind() != reflect.String {
			return reflect.Value{}, fmt.Errorf("map keys must be strings, found %s",
				fieldValues.Type().Key().Kind())
		}
		return fieldValues, nil

	default:
		return reflect.Value{}, fmt.Errorf("unsupported type: %s", fieldValues.Kind())
	}

	return reflect.Value{}, fmt.Errorf("field %q not found", fieldName)
}