Linter rulesProtobufrpc-request-response-unique

rpc-request-response-unique

Since 0.9.0

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.

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;
}

When Not to Use It

You may disable this rule 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.

Compatibility

This rule is compatible with proto3 files. proto2 and editions files are rejected by the reader and are not linted. 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.

Related rules