rpc-request-response-unique

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error

This rule checks whether every message is used as the request or the response of a single RPC.

Rule details

A message shared by several RPCs, or used both as a request and as a response, ties these RPCs together: a field added for one of them appears in all the others, and cannot be removed again without breaking them.

The rpc-request-response-unique rule goes through the RPCs of all the services of the file in order, first the request and then the response type of each. When a type was already used by an earlier RPC, or as the request of the same RPC, it reports, at the RPC that uses it again:

Message '<type>' is used more than once: as <first use> and as <this use>

where each use reads the request of '<rpc>' or the response of '<rpc>'; in files with several services, RPCs are named with their service, e.g. 'PetService.GetPet'. An RPC whose request and response are the same message is reported too. In the message, <type> is the type name as written in the RPC. Types are compared by their fully-qualified names, so GetPetResponse and acme.pets.v1.GetPetResponse are the same message.

Only the RPCs of the linted file are compared.

The rule resolves the request and response types among the declarations of the file and of the files it imports; a type that cannot be resolved is compared by its name as written, without a leading dot.

Turn the rule off if the RPCs are part of an existing API that you cannot change. To allow a single RPC, add an // apigenie-lint-disable rpc-request-response-unique comment to it.

Configuration

The configuration block is an object with boolean properties:

  • allow_google_protobuf_empty_requests: whether google.protobuf.Empty may be the request of several RPCs (default false).
  • allow_google_protobuf_empty_responses: whether google.protobuf.Empty may be the response of several RPCs (default false).

Configuration example

version: "1.0"
commands:
  lint:
    protobuf:
      rules:
        rpc-request-response-unique:
          - warning
          - allow_google_protobuf_empty_requests: true
            allow_google_protobuf_empty_responses: true

Examples

Good. With the default configuration.

syntax = "proto3";

package acme.pets.v1;

service PetService {
  rpc GetPet(GetPetRequest) returns (GetPetResponse);
  rpc UpdatePet(UpdatePetRequest) returns (UpdatePetResponse);
}

message Pet {
  string name = 1;
}

message GetPetRequest {
  string name = 1;
}

message GetPetResponse {
  Pet pet = 1;
}

message UpdatePetRequest {
  Pet pet = 1;
}

message UpdatePetResponse {
  Pet pet = 1;
}

Bad. With the default configuration, the linter reports Message 'Pet' is used more than once: as the response of 'GetPet' and as the response of 'UpdatePet'.

syntax = "proto3";

package acme.pets.v1;

service PetService {
  rpc GetPet(GetPetRequest) returns (Pet);
  rpc UpdatePet(UpdatePetRequest) returns (Pet);
}

message Pet {
  string name = 1;
}

message GetPetRequest {
  string name = 1;
}

message UpdatePetRequest {
  Pet pet = 1;
}

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.protobuf has the details.

commands:
  lint:
    protobuf:
      rules:
        rpc-request-response-unique: off

Related rules

Last updated on View as Markdown
Was this helpful?