Skip to content

Add idempotency_level check plugin - #1

Merged
fchimpan merged 3 commits into
mainfrom
add-idempotency-level-plugin
Aug 9, 2026
Merged

Add idempotency_level check plugin#1
fchimpan merged 3 commits into
mainfrom
add-idempotency-level-plugin

Conversation

@fchimpan

@fchimpan fchimpan commented Aug 9, 2026

Copy link
Copy Markdown
Owner

Summary

Adds a Buf check plugin that requires read-only RPCs (Get* / List* by default) to explicitly declare an idempotency_level such as NO_SIDE_EFFECTS, so that side-effect-free methods are marked as such (e.g. to enable HTTP GET support and caching in Connect).

Changes

  • main.go: the METHOD_IDEMPOTENCY_LEVEL lint rule built on bufplugin-go. Prefix matching is case-insensitive and respects PascalCase word boundaries (Get matches GetUser but not GettyImages). Targeted prefixes are configurable via the method_prefixes option (string list or comma-separated string; setting it replaces the defaults).
  • main_test.go / testdata/: table-driven tests — checktest-based integration tests asserting exact annotation locations and messages, plus unit tests for option parsing and prefix matching.
  • .github/workflows/ci.yaml: gofmt / go vet / go test on pushes to main and on PRs.
  • .github/workflows/release.yaml: on v* tags, a Wasm build is pushed to the BSR via buf plugin push, labeled with the tag.
  • renovate.json: keeps SHA-pinned actions and Go modules up to date.
  • README.md: consumer-facing content only — BSR usage, options, and motivation.

Notes

  • Distribution is BSR-only (buf.build/fchimpan/idempotency-level); no prebuilt binaries.
  • All GitHub Actions are pinned to commit SHAs of their latest releases (SHAs resolved and verified via the GitHub API).
  • Buf's standard ignore mechanisms (// buf:lint:ignore METHOD_IDEMPOTENCY_LEVEL, lint.ignore_only, lint.ignore) apply to this rule as-is; verified against buf CLI v1.72.0.
  • The BSR publish job requires the BUF_TOKEN repository secret (already configured).
  • A method matching a configured prefix passes with any explicit level (NO_SIDE_EFFECTS or IDEMPOTENT); only the unset default (IDEMPOTENCY_UNKNOWN) is flagged.

Test coverage

go test ./... — integration tests compare rule ID, message, and exact source spans via checktest; unit tests cover option parsing edge cases (defaults, blank entries, comma-separated form, invalid types) and prefix word-boundary matching, including compound prefixes like BatchGet.

Implement a Buf check plugin that requires read-only RPCs (Get*/List* by default) to explicitly declare an idempotency_level such as NO_SIDE_EFFECTS. The targeted method name prefixes are configurable via the method_prefixes plugin option.

Includes table-driven tests, CI (gofmt/vet/test), and a tag-driven release pipeline: GoReleaser publishes prebuilt binaries to GitHub Releases and a Wasm build is pushed to the BSR.
Check plugins are consumed through the BSR (or built locally with go install), so prebuilt release binaries add little value. The release workflow now only pushes the Wasm build to the BSR on v* tags, and the README documents the BSR usage as the single install path.
Check plugins are consumed through the BSR, so prebuilt release binaries add little value. The release workflow now only pushes the Wasm build to the BSR on v* tags. Rewrite the README to cover only consumer-facing content: BSR usage, options, and motivation.
@fchimpan
fchimpan merged commit 687ceea into main Aug 9, 2026
1 check passed
@fchimpan
fchimpan deleted the add-idempotency-level-plugin branch August 9, 2026 11:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant