buf-plugin-idempotency-level

This repository contains a buf check plugin that checks that read-only RPCs (by default, methods named Get* or List*) explicitly declare their idempotency_level.

It is published to the BSR at fchimpanorg/idempotency-level.

Usage

1. Add the following to your buf.yaml's plugins: stanza:

- plugin: buf.build/fchimpanorg/idempotency-level

2. Run the following command to download the plugin to your local environment:

$ buf plugin update

3. If you have any lint.use rules specified, explicitly add the lint rule to your lint.use stanza:

lint:
  use:
    - STANDARD
+   - METHOD_IDEMPOTENCY_LEVEL

Matching methods that do not declare an idempotency_level are then reported by buf lint:

$ buf lint
pet/v1/pet.proto:7:3:Method "GetPet" looks read-only (matches prefix "Get") but does not declare an idempotency_level. Declare it side-effect-free with "option idempotency_level = NO_SIDE_EFFECTS;".

A matching method passes with any explicit level (NO_SIDE_EFFECTS or IDEMPOTENT). To skip a specific method, use a comment ignore:

// buf:lint:ignore METHOD_IDEMPOTENCY_LEVEL
rpc GetLegacyReport(GetLegacyReportRequest) returns (GetLegacyReportResponse);

Options

buf-plugin-idempotency-level supports a single option, method_prefixes. If not specified, methods whose names start with Get or List are checked. If specified, it replaces the default list.

- plugin: buf.build/fchimpanorg/idempotency-level
  options:
    method_prefixes:
      - Get
      - List
      - BatchGet

Prefix matching is case-insensitive and respects PascalCase word boundaries: Get matches GetPet and Get, but not GettyImages.

Why?

Marking a read-only method with option idempotency_level = NO_SIDE_EFFECTS; documents that it is side-effect-free ("safe" in HTTP terms) and enables features such as HTTP GET support and caching in Connect:

rpc GetPet(GetPetRequest) returns (GetPetResponse) {
  option idempotency_level = NO_SIDE_EFFECTS;
}

The default buf linter has no check for this, so it is easy to forget. This plugin makes the declaration mandatory for read-only methods.