feat: customer list filters

Author: tothandras

Makefile

@@ -22,7 +22,9 @@ down: ## Stop the dependencies via docker compose
 .PHONY: patch-oapi-templates
 patch-oapi-templates: ## Patch oapi-codegen chi-middleware template with custom filter parsing
 	$(call print-target)
+	@go mod download github.com/oapi-codegen/oapi-codegen/v2
 	@OAPI_MOD_DIR=$$(go list -m -f '{{.Dir}}' github.com/oapi-codegen/oapi-codegen/v2) && \
+		if [ -z "$$OAPI_MOD_DIR" ]; then echo "error: could not locate oapi-codegen/v2 module dir"; exit 1; fi && \
 		cp "$$OAPI_MOD_DIR/pkg/codegen/templates/chi/chi-middleware.tmpl" api/v3/templates/chi-middleware.tmpl && \
 		chmod u+w api/v3/templates/chi-middleware.tmpl && \
 		patch -p1 -d api/v3/templates < api/v3/templates/chi-middleware.tmpl.patch

api/spec/packages/aip/src/customers/operations.tsp

@@ -23,6 +23,16 @@ model ListCustomersParamsFilter {
    * Filter customers by key.
    */
   key?: Common.StringFieldFilter;
+
+  /**
+   * Filter customers by name.
+   */
+  name?: Common.StringFieldFilter;
+
+  /**
+   * Filter customers by primary email.
+   */
+  primary_email?: Common.StringFieldFilter;
 }
 
 interface CustomersOperations {

api/v3/api.gen.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"net/url"
 	"reflect"
+	"sort"
 	"strconv"
 	"strings"
 )
@@ -14,12 +15,12 @@ import (
 // whose fields are filter types. Field names are resolved from json struct tags.
 //
 // Supported field types:
-//   - *FilterString: parsed via ParseFilterString
-//   - *FilterStringExact: parsed via ParseFilterStringExact
-//   - *StringFilter: parsed via ParseFilterStringSimple
-//   - *FilterNumeric: parsed via ParseFilterNumeric
-//   - *FilterDateTime: parsed via ParseFilterDateTime
-//   - *FilterBoolean: parsed via ParseFilterBoolean
+//   - *FilterString: parsed via parseFilterString
+//   - *FilterStringExact: parsed via parseFilterStringExact
+//   - *StringFilter: parsed via parseFilterStringSimple
+//   - *FilterNumeric: parsed via parseFilterNumeric
+//   - *FilterDateTime: parsed via parseFilterDateTime
+//   - *FilterBoolean: parsed via parseFilterBoolean
 //   - *string: parsed as shorthand eq (filter[field]=value)
 //   - any type implementing json.Unmarshaler: marshals filter ops to JSON, then unmarshals
 func Parse(qs url.Values, target any) error {
@@ -50,19 +51,82 @@ func hasFilterKeys(qs url.Values) bool {
 	return false
 }
 
+// checkUnknownFilterKeys returns an error if any filter[<name>]... key in qs
+// refers to a <name> that is not in the knownFields set. Label-style
+// dot-notation keys (e.g. "filter[labels.env]") are matched against their
+// base segment before the first dot, since label map fields use that shape.
+// Unknown field names are reported as a deterministic, comma-separated list
+// so the error can be surfaced to API clients (e.g. as a 400 response).
+func checkUnknownFilterKeys(qs url.Values, knownFields map[string]struct{}) error {
+	var unknown []string
+	seen := make(map[string]struct{})
+	for key := range qs {
+		name, ok := filterFieldName(key)
+		if !ok {
+			continue
+		}
+		// Allow dot-notation for labels-style map filters: the known field is
+		// the base segment ("labels" in "labels.env").
+		base := name
+		if dot := strings.IndexByte(name, '.'); dot > 0 {
+			base = name[:dot]
+		}
+		if _, known := knownFields[base]; known {
+			continue
+		}
+		if _, already := seen[name]; already {
+			continue
+		}
+		seen[name] = struct{}{}
+		unknown = append(unknown, name)
+	}
+	if len(unknown) == 0 {
+		return nil
+	}
+	sort.Strings(unknown)
+	return fmt.Errorf("unknown filter field(s): %s", strings.Join(unknown, ", "))
+}
+
+// filterFieldName extracts the <name> portion from a URL query key shaped like
+// "filter[<name>]" or "filter[<name>][op]". It returns false for keys that do
+// not match the filter[...] prefix or that are malformed (e.g. "filter[" with
+// no closing bracket or an empty name).
+func filterFieldName(key string) (string, bool) {
+	const prefix = "filter["
+	if !strings.HasPrefix(key, prefix) {
+		return "", false
+	}
+	rest := key[len(prefix):]
+	end := strings.IndexByte(rest, ']')
+	if end <= 0 {
+		return "", false
+	}
+	return rest[:end], true
+}
+
 var (
-	filterStringType      = reflect.TypeOf((*FilterString)(nil))
-	filterStringExactType = reflect.TypeOf((*FilterStringExact)(nil))
-	filterNumericType     = reflect.TypeOf((*FilterNumeric)(nil))
-	filterDateTimeType    = reflect.TypeOf((*FilterDateTime)(nil))
-	filterBooleanType     = reflect.TypeOf((*FilterBoolean)(nil))
-	stringFilterType      = reflect.TypeOf((*StringFilter)(nil))
-	stringPtrType         = reflect.TypeOf((*string)(nil))
+	filterStringType      = reflect.TypeFor[*FilterString]()
+	filterStringExactType = reflect.TypeFor[*FilterStringExact]()
+	filterNumericType     = reflect.TypeFor[*FilterNumeric]()
+	filterDateTimeType    = reflect.TypeFor[*FilterDateTime]()
+	filterBooleanType     = reflect.TypeFor[*FilterBoolean]()
+	stringFilterType      = reflect.TypeFor[*StringFilter]()
+	stringPtrType         = reflect.TypeFor[*string]()
 )
 
 func parseFiltersValue(qs url.Values, v reflect.Value) error {
 	t := v.Type()
 
+	knownFields := make(map[string]struct{}, t.NumField())
+	for i := range t.NumField() {
+		if name := jsonFieldName(t.Field(i)); name != "" && name != "-" {
+			knownFields[name] = struct{}{}
+		}
+	}
+	if err := checkUnknownFilterKeys(qs, knownFields); err != nil {
+		return err
+	}
+
 	for i := range t.NumField() {
 		field := t.Field(i)
 		fieldVal := v.Field(i)
@@ -74,7 +138,7 @@ func parseFiltersValue(qs url.Values, v reflect.Value) error {
 
 		switch fieldVal.Type() {
 		case filterStringType:
-			parsed, err := ParseFilterString(qs, name)
+			parsed, err := parseFilterString(qs, name)
 			if err != nil {
 				return err
 			}
@@ -83,7 +147,7 @@ func parseFiltersValue(qs url.Values, v reflect.Value) error {
 			}
 
 		case filterStringExactType:
-			parsed, err := ParseFilterStringExact(qs, name)
+			parsed, err := parseFilterStringExact(qs, name)
 			if err != nil {
 				return err
 			}
@@ -92,7 +156,7 @@ func parseFiltersValue(qs url.Values, v reflect.Value) error {
 			}
 
 		case stringFilterType:
-			parsed, err := ParseFilterStringSimple(qs, name)
+			parsed, err := parseFilterStringSimple(qs, name)
 			if err != nil {
 				return err
 			}
@@ -101,7 +165,7 @@ func parseFiltersValue(qs url.Values, v reflect.Value) error {
 			}
 
 		case filterNumericType:
-			parsed, err := ParseFilterNumeric(qs, name)
+			parsed, err := parseFilterNumeric(qs, name)
 			if err != nil {
 				return err
 			}
@@ -110,7 +174,7 @@ func parseFiltersValue(qs url.Values, v reflect.Value) error {
 			}
 
 		case filterDateTimeType:
-			parsed, err := ParseFilterDateTime(qs, name)
+			parsed, err := parseFilterDateTime(qs, name)
 			if err != nil {
 				return err
 			}
@@ -119,7 +183,7 @@ func parseFiltersValue(qs url.Values, v reflect.Value) error {
 			}
 
 		case filterBooleanType:
-			parsed, err := ParseFilterBoolean(qs, name)
+			parsed, err := parseFilterBoolean(qs, name)
 			if err != nil {
 				return err
 			}
@@ -228,7 +292,7 @@ func jsonFieldName(f reflect.StructField) string {
 	return name
 }
 
-// ParseFilterString extracts a FilterString from URL query values for
+// parseFilterString extracts a FilterString from URL query values for
 // the given field name.  It understands the deepObject encoding used by our API:
 //
 //	filter[field]=value          → eq (shorthand)
@@ -243,7 +307,7 @@ func jsonFieldName(f reflect.StructField) string {
 //	filter[field][lte]=value     → lte
 //	filter[field][exists]        → exists (true)
 //	filter[field][nexists]       → exists (false)
-func ParseFilterString(qs url.Values, field string) (FilterString, error) {
+func parseFilterString(qs url.Values, field string) (FilterString, error) {
 	var f FilterString
 
 	prefix := fmt.Sprintf("filter[%s]", field)
@@ -303,9 +367,9 @@ func ParseFilterString(qs url.Values, field string) (FilterString, error) {
 	return f, nil
 }
 
-// ParseFilterStringExact extracts a FilterStringExact from URL query values.
+// parseFilterStringExact extracts a FilterStringExact from URL query values.
 // Supports eq, neq, and oeq operators.
-func ParseFilterStringExact(qs url.Values, field string) (FilterStringExact, error) {
+func parseFilterStringExact(qs url.Values, field string) (FilterStringExact, error) {
 	var f FilterStringExact
 
 	prefix := fmt.Sprintf("filter[%s]", field)
@@ -342,8 +406,8 @@ func ParseFilterStringExact(qs url.Values, field string) (FilterStringExact, err
 	return f, nil
 }
 
-// ParseFilterStringSimple extracts a StringFilter (simple eq/neq/contains) from URL query values.
-func ParseFilterStringSimple(qs url.Values, field string) (StringFilter, error) {
+// parseFilterStringSimple extracts a StringFilter (simple eq/neq/contains) from URL query values.
+func parseFilterStringSimple(qs url.Values, field string) (StringFilter, error) {
 	var f StringFilter
 
 	prefix := fmt.Sprintf("filter[%s]", field)
@@ -380,8 +444,8 @@ func ParseFilterStringSimple(qs url.Values, field string) (StringFilter, error)
 	return f, nil
 }
 
-// ParseFilterNumeric extracts a FilterNumeric from URL query values.
-func ParseFilterNumeric(qs url.Values, field string) (FilterNumeric, error) {
+// parseFilterNumeric extracts a FilterNumeric from URL query values.
+func parseFilterNumeric(qs url.Values, field string) (FilterNumeric, error) {
 	var f FilterNumeric
 
 	prefix := fmt.Sprintf("filter[%s]", field)
@@ -460,9 +524,9 @@ func ParseFilterNumeric(qs url.Values, field string) (FilterNumeric, error) {
 	return f, nil
 }
 
-// ParseFilterDateTime extracts a FilterDateTime from URL query values.
+// parseFilterDateTime extracts a FilterDateTime from URL query values.
 // Values are kept as strings (expected to be RFC-3339 timestamps).
-func ParseFilterDateTime(qs url.Values, field string) (FilterDateTime, error) {
+func parseFilterDateTime(qs url.Values, field string) (FilterDateTime, error) {
 	var f FilterDateTime
 
 	prefix := fmt.Sprintf("filter[%s]", field)
@@ -507,8 +571,8 @@ func ParseFilterDateTime(qs url.Values, field string) (FilterDateTime, error) {
 	return f, nil
 }
 
-// ParseFilterBoolean extracts a FilterBoolean from URL query values.
-func ParseFilterBoolean(qs url.Values, field string) (FilterBoolean, error) {
+// parseFilterBoolean extracts a FilterBoolean from URL query values.
+func parseFilterBoolean(qs url.Values, field string) (FilterBoolean, error) {
 	var f FilterBoolean
 
 	prefix := fmt.Sprintf("filter[%s]", field)