feat(AIP-160): Validate filter field type (#1524)

Validates that the field for filtering, called "filter," is of type string.

Author: shwoodard

docs/rules/0160/filter-field-type.md

@@ -0,0 +1,81 @@
+---
+rule:
+  aip: 160
+  name: [core, '0160', filter-field-type]
+  summary: |
+    The filtering field on List and custom method request messages,
+    "filter" must be a string.
+permalink: /160/filter-field-type
+redirect_from:
+  - /0160/filter-field-type
+---
+
+# Filtering: filter field type
+
+This rule enforces that the field used for filtering, called `filter`,
+is of type `string`, as mandated by [AIP-160][].
+
+## Details
+
+This rule looks at the request message for List methods and custom
+methods. Then, it verifes that any field called `filter` is of type
+`string`.
+
+## Examples
+
+**Incorrect** code for this rule:
+
+```proto
+// Incorrect.
+rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
+  bytes filter = 1;
+}
+```
+
+```proto
+// Incorrect.
+rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
+  BookFilters filter = 1;
+
+  message BookFilters {
+    string publisher = 1;
+    repeated string authors = 2;
+  }
+}
+```
+
+**Correct** code for this rule:
+
+```proto
+// Correct.
+rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
+  string filter = 1;
+}
+```
+
+```proto
+// Correct.
+rpc CheckoutBook(CheckoutBookRequest) returns (CheckoutBookResponse) {
+  string filter = 1;
+}
+```
+
+## Disabling
+
+If you need to violate this rule, use a leading comment above the method.
+Remember to also include an [aip.dev/not-precedent][] comment explaining why.
+
+```proto
+// (-- api-linter: core::0160::filter-field-type=disabled
+//     aip.dev/not-precedent: We need to do this because reasons. --)
+rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
+  bytes filter = 1;
+}
+```
+
+If you need to violate this rule for an entire file, place the comment at the
+top of the file.
+
+[aip-160]: https://aip.dev/160
+[aip.dev/not-precedent]: https://aip.dev/not-precedent
+

rules/aip0160/aip0160.go

@@ -24,5 +24,6 @@ func AddRules(r lint.RuleRegistry) error {
 	return r.Register(
 		160,
 		filterFieldName,
+		filterFieldType,
 	)
 }

rules/aip0160/filter_field_type.go

@@ -0,0 +1,50 @@
+// Copyright 2025 Google LLC
+//
+// 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
+//
+//     https://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 aip0160
+
+import (
+	"fmt"
+
+	"github.com/googleapis/api-linter/lint"
+	"github.com/googleapis/api-linter/locations"
+	"github.com/googleapis/api-linter/rules/internal/utils"
+	"github.com/jhump/protoreflect/desc"
+)
+
+const (
+	typeMessageFmt = `Guidance: use the field, "string filter", not "%s filter"`
+	typeSuggestion = "string"
+)
+
+var filterFieldType = &lint.MethodRule{
+	Name: lint.NewRuleName(160, "filter-field-type"),
+	OnlyIf: func(m *desc.MethodDescriptor) bool {
+		return utils.IsListMethod(m) || utils.IsCustomMethod(m)
+	},
+	LintMethod: func(m *desc.MethodDescriptor) []lint.Problem {
+		var problems []lint.Problem
+		for _, f := range m.GetInputType().GetFields() {
+			if f.GetName() == "filter" && utils.GetTypeName(f) != "string" {
+				problems = append(problems, lint.Problem{
+					Message:    fmt.Sprintf(typeMessageFmt, utils.GetTypeName(f)),
+					Descriptor: f,
+					Location:   locations.FieldType(f),
+					Suggestion: typeSuggestion,
+				})
+			}
+		}
+		return problems
+	},
+}

rules/aip0160/filter_field_type_test.go

@@ -0,0 +1,71 @@
+// Copyright 2025 Google LLC
+//
+// 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
+//
+//     https://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 aip0160
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/googleapis/api-linter/lint"
+	"github.com/googleapis/api-linter/rules/internal/testutils"
+)
+
+func TestFiltersFieldType(t *testing.T) {
+	tests := []struct {
+		testName   string
+		FieldType  string
+		FieldName  string
+		MethodName string
+		wantErr    bool
+	}{
+		{"Valid", "string", "filter", "ListBooks", false},
+		{"Skip not filters", "string", "filters", "ListBooks", false},
+		{"Invalid different native type List method", "bytes", "filter", "ListBooks", true},
+		{"Invalid different message type List method", "BookFilters", "filter", "ListBooks", true},
+		{"Invalid different native type custom method", "bytes", "filter", "SearchBooks", true},
+		{"Invalid different message type custom method", "BookFilters", "filter", "SearchBooks", true},
+	}
+	for _, test := range tests {
+		t.Run(test.testName, func(t *testing.T) {
+			file := testutils.ParseProto3Tmpl(t, `
+				service Library {
+					rpc {{.MethodName}}({{.MethodName}}Request) returns ({{.MethodName}}Response) {}
+					rpc GetBook(GetBookRequest) returns (Book) {}
+				}
+				message {{.MethodName}}Request {
+					{{.FieldType}} {{.FieldName}} = 1;
+				}
+				message {{.MethodName}}Response {}
+
+				message GetBookRequest {}
+				message Book { string filters = 1; }
+
+				message BookFilters {}
+		`, test)
+			field := file.GetMessageTypes()[0].GetFields()[0]
+			wantProblems := testutils.Problems{}
+			if test.wantErr {
+				wantProblems = append(wantProblems, lint.Problem{
+					Message:    fmt.Sprintf(`"string filter", not "%s %s`, test.FieldType, test.FieldName),
+					Suggestion: "string",
+					Descriptor: field,
+				})
+			}
+			if diff := wantProblems.Diff(filterFieldType.Lint(file)); diff != "" {
+				t.Error(diff)
+			}
+		})
+	}
+}