diff --git a/docs/rules/0165/http-parent-variable.md b/docs/rules/0165/http-parent-variable.md new file mode 100644 index 000000000..f8b4f7424 --- /dev/null +++ b/docs/rules/0165/http-parent-variable.md @@ -0,0 +1,80 @@ +--- +rule: + aip: 165 + name: [core, '0165', http-parent-variable] + summary: Purge methods must map the parent field to the URI. +permalink: /165/http-parent-variable +redirect_from: + - /0165/http-parent-variable +--- + +# Purge methods: HTTP URI parent variable + +This rule enforces that all `Purge` RPCs map the `parent` field to the HTTP +URI, as mandated in [AIP-165][]. + +## Details + +This rule looks at any message beginning with `Purge`, and complains +if the `parent` variable is not included in the URI. It _does_ check additional +bindings if they are present. + +## Examples + +**Incorrect** code for this rule: + +```proto +// Incorrect. +rpc PurgeBooks(PurgeBooksRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/publishers/*/books:purge" // The `parent` field should be extracted. + body: "*" + }; + option (google.longrunning.operation_info) = { + response_type: "PurgeBooksResponse" + metadata_type: "PurgeBooksMetadata" + }; +} +``` + +**Correct** code for this rule: + +```proto +// Correct. +rpc PurgeBooks(PurgeBooksRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/{parent=publishers/*}/books:purge" + body: "*" + }; + option (google.longrunning.operation_info) = { + response_type: "PurgeBooksResponse" + metadata_type: "PurgeBooksMetadata" + }; +} +``` + +## 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::0165::http-parent-variable=disabled +// aip.dev/not-precedent: We need to do this because reasons. --) +rpc PurgeBooks(PurgeBooksRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/publishers/*/books:purge" + body: "*"" + }; + option (google.longrunning.operation_info) = { + response_type: "PurgeBooksResponse" + metadata_type: "PurgeBooksMetadata" + }; +} +``` + +If you need to violate this rule for an entire file, place the comment at the +top of the file. + +[aip-165]: https://aip.dev/165 +[aip.dev/not-precedent]: https://aip.dev/not-precedent diff --git a/rules/aip0165/aip0165.go b/rules/aip0165/aip0165.go index 0177c53cf..15525e241 100644 --- a/rules/aip0165/aip0165.go +++ b/rules/aip0165/aip0165.go @@ -28,6 +28,7 @@ func AddRules(r lint.RuleRegistry) error { 165, httpBody, httpMethod, + httpParentVariable, httpURISuffix, requestFilterBehavior, requestFilterField, diff --git a/rules/aip0165/http_parent_variable.go b/rules/aip0165/http_parent_variable.go new file mode 100644 index 000000000..cc6d2730c --- /dev/null +++ b/rules/aip0165/http_parent_variable.go @@ -0,0 +1,43 @@ +// Copyright 2021 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 aip0165 + +import ( + "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" +) + +// Purge methods should have a parent variable in the URI unless the resource is top-level. +var httpParentVariable = &lint.MethodRule{ + Name: lint.NewRuleName(165, "http-parent-variable"), + OnlyIf: func(m *desc.MethodDescriptor) bool { + return isPurgeMethod(m) && m.GetInputType().FindFieldByName("parent") != nil + }, + LintMethod: func(m *desc.MethodDescriptor) []lint.Problem { + for _, httpRule := range utils.GetHTTPRules(m) { + if _, ok := httpRule.GetVariables()["parent"]; !ok { + return []lint.Problem{{ + Message: "Purge methods should include the `parent` field in the URI.", + Descriptor: m, + Location: locations.MethodHTTPRule(m), + }} + } + } + + return nil + }, +} diff --git a/rules/aip0165/http_parent_variable_test.go b/rules/aip0165/http_parent_variable_test.go new file mode 100644 index 000000000..e3cb596ac --- /dev/null +++ b/rules/aip0165/http_parent_variable_test.go @@ -0,0 +1,60 @@ +// Copyright 2019 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 aip0165 + +import ( + "testing" + + "github.com/googleapis/api-linter/rules/internal/testutils" +) + +func TestHTTPParentVariable(t *testing.T) { + tests := []struct { + testName string + URI string + MethodName string + Field string + problems testutils.Problems + }{ + {"Valid", "/v1/{parent=publishers/*/books/*}", "PurgeBooks", "string parent = 1;", nil}, + {"InvalidVarParent", "/v1/{book=publishers/*/books/*}", "PurgeBooks", "string parent = 1;", testutils.Problems{{Message: "`parent` field"}}}, + {"NoVarParent", "/v1/publishers/*/books/*", "PurgeBooks", "string parent = 1;", testutils.Problems{{Message: "`parent` field"}}}, + {"NoParent", "/v1/books/*", "PurgeBooks", "", nil}, + {"Irrelevant", "/v1/{book=publishers/*/books/*}", "BuildBook", "string parent = 1;", nil}, + } + + for _, test := range tests { + t.Run(test.testName, func(t *testing.T) { + f := testutils.ParseProto3Tmpl(t, ` + import "google/api/annotations.proto"; + service Library { + rpc {{.MethodName}}({{.MethodName}}Request) returns ({{.MethodName}}Response) { + option (google.api.http) = { + post: "{{.URI}}" + }; + } + } + message {{.MethodName}}Request { + {{.Field}} + } + message {{.MethodName}}Response {} + `, test) + method := f.GetServices()[0].GetMethods()[0] + if diff := test.problems.SetDescriptor(method).Diff(httpParentVariable.Lint(f)); diff != "" { + t.Error(diff) + } + }) + } +}