lotharschulz
Published in

lotharschulz

Challenge — We Need To Lint Protos Easily

Proto linting with buf findings can be surprising. This write up describes options on how to reduce your buf linting failures to zero.

What is gRPC?

gRPC is a RPC framework. It is a popular framework and available for many languages including Kotlin. gRPC uses by default protocol buffer as its interface definition language.

What are proto files?

Proto files are

  • used to define the structure for the data to serialize with protocol buffers
  • text files with the .proto extension.

Protocol buffer data in proto files contains messages. Each message is a small logical block of information containing a series of name-value pairs called fields.

With this data you define a contract between servers and clients: an API. Proto files can be and shall be linted.

Why proto file linting?

Linting helps to define APIs consistently. Buf contains a CLI that can be used for proto file linting.

Linting Failures Fixes

I started with a simple hello world kotlin grpc example (branch initialState) that produced buf linting failures about

lower snake case fields

First lint failure I worked around was lower snake case fields with adding the FIELD_LOWER_SNAKE_CASE exception (see also branch fieldLowerSnakeCase). With that edit lower snake case fields failures are gone.

service suffix

Next lint failure I fixed was service suffix with adding the SERVICE_SUFFIX exception (see also branch branch serviceSuffix).

request standard name

The request standard name failure was fixed next with adding RPC_REQUEST_STANDARD_NAME exception (see also branch rpcRequestStandardName). That leaves these failures:

response standard name

After fixing the request related failure, the response related one must be fixed afterwards. Similar to the previous fix I added the RPC_RESPONSE_STANDARD_NAME exception (see also branch rpcResponseStandardName).

request response unique

There is a combined request-response failure that is not fixed so far. I could fix that by adding yet another exception: RPC_REQUEST_RESPONSE_UNIQUE (see also branch rpcRequestResponseUnique).

package assignment

The last package version failure required a new package structure. Not only the kotlin code package structure had to be changed, also the gradle build scripts and the proto files location.

No lint failures anymore — yay.

Conclusion

Only 6 edits are required to fix all buf proto linting failures in hello world kotlin grpc sample code:

  1. add FIELD_LOWER_SNAKE_CASE exception
  2. add SERVICE_SUFFIX exception
  3. add RPC_REQUEST_STANDARD_NAME exception
  4. add RPC_RESPONSE_STANDARD_NAME exception
  5. add RPC_REQUEST_RESPONSE_UNIQUE exception
  6. adapt packages

The main branch contains the code that fixed all linting failures.

Source Code

Originally published at https://www.lotharschulz.info.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store