Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-09-21 13:54:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add Protobuf and gRPC API review skill 🤖🤖🤖 (#3085)

Browse Source 
* feat: add protobuf and gRPC API review skill

* fix: use accepted spelling in review skill

* docs: clarify per-method authorization guidance
This commit is contained in:
Mnimiy
2026-09-21 10:22:29 +10:00
committed by GitHub
parent 9bf465b455
commit 5ffd821817
4 changed files with 329 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/protobuf-grpc-api-review/references/grpc-contract-review.md
+104
View File
@@ -0,0 +1,104 @@
# gRPC Contract Review
Use this reference when a change affects a service, method, request/response behavior, or client/server policy. Apply only the checks relevant to the change.
## Method Identity and Shape
The fully qualified package, service, and method form the RPC identity. Renaming or moving any of them changes the method path and breaks existing clients, routing, authorization policies, observability, and service configuration.
Treat these as breaking contract changes:
- removing or renaming a service or method
- changing request or response message type
- changing unary, client-streaming, server-streaming, or bidirectional-streaming mode
- moving a service to another protobuf package
Prefer adding a new method, migrating callers, deprecating the old method, and removing it only after the compatibility window closes. Review request and response message changes with the protobuf compatibility rules.
## Deadlines and Cancellation
- Clients should set a realistic deadline; gRPC does not set one by default.
- The deadline must cover expected network and processing latency and be validated against production or load-test evidence.
- Servers must stop spawned work when the call is cancelled or its deadline expires.
- Downstream calls should receive the remaining deadline rather than starting a fresh full timeout. Confirm whether propagation is automatic or must be enabled in the implementation language.
- Do not convert a deadline or cancellation into a misleading application status.
Flag new unbounded calls, swallowed cancellation, or downstream work that can outlive the originating request when they create resource or correctness risk.
## Retries and Idempotency
Before recommending or approving a retry policy, answer:
1. Can the operation be repeated without duplicating a state change?
2. If the result is ambiguous, is there an idempotency key or server-side deduplication window?
3. Which status codes are retryable for this method?
4. Are attempts bounded by max attempts, exponential backoff, jitter, throttling, and the overall deadline?
5. Are retry attempts and final call outcomes observable?
Retries are enabled in gRPC implementations, but there is no default general retry policy; transparent retries can still occur in limited cases. A response header commits the RPC and ends gRPC retry attempts. Never treat a mutating RPC as retry-safe merely because it returns `UNAVAILABLE` or `DEADLINE_EXCEEDED`: the server may already have applied the change.
## Status Codes Are Part of the API
Review status changes as observable behavior. Prefer the most specific stable code and keep error details free of secrets.
- `INVALID_ARGUMENT`: invalid regardless of system state
- `FAILED_PRECONDITION`: retry only after state is explicitly fixed
- `ABORTED`: retry the larger transaction or read-modify-write sequence
- `UNAVAILABLE`: transient failure where retrying this call may be appropriate
- `RESOURCE_EXHAUSTED`: quota or capacity exhausted
- `UNAUTHENTICATED`: credentials are missing or invalid
- `PERMISSION_DENIED`: authenticated caller lacks permission
- `NOT_FOUND`: resource does not exist, or deliberate existence hiding is part of the authorization contract
Avoid replacing domain failures with `UNKNOWN` or `INTERNAL`. Check client logic, retry policies, metrics, and alerts before changing an established code.
## Streaming Contracts
For streaming methods, establish and test:
- message ordering and whether duplicates are possible
- half-close and completion semantics
- backpressure and bounded buffering
- per-message and total stream size limits
- cancellation and cleanup on both peers
- authentication lifetime for long-lived streams
- resume, replay, or checkpoint behavior after interruption
Do not add streaming as a default improvement; require a concrete need and an explicit lifecycle contract.
## Security and Resource Boundaries
- Enforce authentication and authorization per method; update policy maps that enumerate paths whenever a method is added.
- Use transport security appropriate to the deployment, and avoid logging credentials or sensitive metadata.
- Bound request size, response size, concurrency, fan-out, and expensive repeated fields where input is untrusted.
- Validate before starting irreversible or costly work.
- Check that reflection, health services, and debug endpoints are exposed only as intended.
## Behavioral Evolution
Schema compatibility does not protect semantic contracts. Review changes to:
- required business fields represented as optional protobuf fields
- pagination tokens, ordering, filters, and consistency guarantees
- idempotency and deduplication keys
- partial success and batch error semantics
- default limits, quotas, and server-side timeouts
- error details and redaction
For a behavioral change, require documentation and tests that cover old clients during rollout and rollback.
## Targeted Verification
- invoke old generated clients against the new server and new clients against the old server when mixed versions are supported
- test the exact method path through proxies, gateways, and authorization middleware
- exercise deadlines, cancellation, and downstream propagation
- inject retryable and non-retryable failures, including an ambiguous failure after a state change
- test streaming cancellation, slow consumers, large messages, and interrupted streams where applicable
- verify metrics distinguish attempts from logical calls
## Primary References
- [gRPC deadlines](https://grpc.io/docs/guides/deadlines/)
- [gRPC retry](https://grpc.io/docs/guides/retry/)
- [gRPC status codes](https://grpc.io/docs/guides/status-codes/)
- [gRPC authentication](https://grpc.io/docs/guides/auth/)
skills/protobuf-grpc-api-review/references/protobuf-compatibility.md
+106
View File
@@ -0,0 +1,106 @@
# Protobuf Compatibility Rules
Use this reference when a review changes messages, fields, enums, serialization, or generated APIs. Apply it to the actual encoding and runtimes in scope.
## Classify the Change
### Binary wire-unsafe
Treat these as breaking unless all serialized data and every reader/writer can be migrated atomically:
- changing an existing field number
- reusing a deleted or previously shipped field number
- reusing a deleted enum number
- moving fields into an existing `oneof`
- changing between types with different wire encodings, such as `string` and an integer
Never rely on an apparently unused tag having no historical data. Old binaries, logs, queues, and rollback artifacts may still contain it.
### Binary wire-safe, with other dimensions still to review
- adding a field with a new number
- removing a field while permanently reserving its number; reserve its name when name reuse is also unsafe
- adding an enum value with a new number
- moving one explicit-presence field into a new `oneof`
- changing a single-field `oneof` to an explicit-presence field
- changing a field to an extension with the same number and type
These can still break source code, business logic, JSON consumers, validation, or exhaustive enum handling.
### Binary-compatible but rollout-dependent
These pairs can parse the same wire representation but may change values or lose data. Prefer adding a new field. If a migration is unavoidable, keep writers within the old domain until every reader has upgraded and rollback is closed.
| Change | Required constraint or risk |
| --- | --- |
| `int32`, `uint32`, `int64`, `uint64`, `bool` | Old readers may truncate or reinterpret values; boolean semantics are especially risky. |
| `sint32` <-> `sint64` | Values outside the narrower range change when read as `sint32`. These are not compatible with ordinary integer encodings. |
| `fixed32` <-> `sfixed32`; `fixed64` <-> `sfixed64` | Signedness changes application meaning. |
| `string` <-> `bytes` | Bytes must remain valid UTF-8 for `string` readers. Generated APIs change. |
| embedded message <-> `bytes` | Bytes must always contain that message encoding; generated APIs change. |
| enum <-> integer types | Unknown-enum representation and generated behavior vary by language. |
| singular <-> repeated for strings, bytes, or messages | A singular reader keeps the last primitive value or merges messages; information can be lost. |
| map <-> its repeated entry message | Map readers may reorder entries and discard duplicate keys. |
Numeric repeated fields are normally packed and are not safely interchangeable with singular fields. Treat any cardinality change as a data migration rather than a cleanup.
## Deletion and Replacement Pattern
For a shipped field that must change type or meaning:
1. Add a new field with a new number and a distinct name.
2. Deploy readers that understand both fields.
3. Deploy writers that populate the new field, and dual-write if rollback requires it.
4. Backfill persisted data where needed.
5. Stop reading and writing the old field only after old binaries and rollback are gone.
6. Remove the old field and reserve its number and name.
Do not reserve the old number while the field is still declared. Do not reuse the old number for the replacement.
## Presence, Defaults, and `oneof`
- Changing implicit scalar presence to explicit `optional` presence is wire-compatible but changes generated APIs and the meaning of default values. Check merge, patch, equality, and serialization behavior.
- An implicit-presence scalar cannot distinguish "unset" from its default value. If zero, empty, or false is meaningful in an update API, use explicit presence or a field mask.
- Adding a field to a `oneof` is generally parseable, but old clients can clear an unknown member when they set a known member and reserialize. Review read-modify-write paths.
- Removing a `oneof` member makes it impossible for a new reader to know which removed member had been set. Preserve the number and plan the migration.
- Never add a required field. Older writers cannot populate it, and partial rollout or rollback becomes unsafe.
- Do not change explicit defaults in proto2; version-skewed readers can interpret the same absent field differently.
## Enums
- Keep a zero-valued `*_UNSPECIFIED` first value unless the established contract deliberately uses another zero value.
- Adding a value is binary-safe but may break exhaustive switches or older business logic. Search generated-language consumers.
- When deleting a value, reserve both its number and, where names are part of the contract, its name.
- For aliases, add the new alias after the old one. A safe rename requires staged parser and serializer rollout before removing the old name.
## ProtoJSON and Other Named Formats
Review name-based formats separately from the binary wire format:
- field and enum names can be serialized contract data, so renaming may break readers
- ProtoJSON does not preserve unknown fields, narrowing forward compatibility
- adding fields or enum values can fail older parsers that reject unknown names
- changing `json_name`, integer/string representation, bytes encoding, or `oneof` shape can alter the public JSON schema
- HTTP transcoding can expose message fields and enum names even when the internal transport is binary gRPC
Ask whether stored JSON exists. If it does, include historical payloads in compatibility tests.
## Verification Matrix
Use real generated runtimes where behavior can vary by language:
| Writer | Reader | What to assert |
| --- | --- | --- |
| old | new | Values, presence, enum handling, and validation remain correct. |
| new | old | Unknown data is tolerated and known values are not reinterpreted. |
| old | new -> modify -> serialize -> old | Unknown fields survive and known fields are not cleared. |
| new | old -> modify -> serialize -> new | New fields or `oneof` members are not silently lost. |
Also compile descriptors, run the repository's breaking-change checker, test boundary values for widened/narrowed numeric domains, and round-trip any supported JSON representation.
## Primary References
- [Proto3: Updating a Message Type](https://protobuf.dev/programming-guides/proto3/#updating)
- [Proto Best Practices](https://protobuf.dev/best-practices/dos-donts/)
- [ProtoJSON wire safety](https://protobuf.dev/programming-guides/json/#json-wire-safety)
- [Field presence](https://protobuf.dev/programming-guides/field_presence/)