feat(nats): define micro proto contract

[yordis]

• Prevent generator implementations from inventing incompatible NATS service annotations.
• Avoid ambiguity between service discovery identity and endpoint request subjects.

[cursor]

PR Summary

Medium Risk
Adds new protobuf descriptor extensions that will be consumed by generators; mistakes in option semantics or field numbering could create long-lived compatibility constraints for downstream tooling.

Overview
Introduces a new protobuf options contract trogon.nats.micro.v1alpha1 for documenting NATS microservice metadata directly on service and rpc definitions, including a ContentType enum and ServiceOptions/MethodOptions wrappers.

Updates the extension-number registry docs to reserve 870014/870015, and adds a new how-to guide describing recommended usage and boundaries (discovery metadata vs per-message Content-Type, and what runtime concerns to avoid encoding in proto).

^{Reviewed by Cursor Bugbot for commit 2976537. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Warning

Rate limit exceeded

@yordis has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 23 minutes and 6 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 59ca0886-32ed-4170-9adb-66e541f60fee

📥 Commits

Reviewing files that changed from the base of the PR and between 199b63a and 2976537.

📒 Files selected for processing (4)

• docs/README.md
• docs/explanation/protobuf-extension-naming.md
• docs/how-to/document-nats-micro-services.md
• proto/trogon/nats/micro/v1alpha1/options.proto

Walkthrough

This PR introduces a new protobuf schema for NATS micro service configuration options and comprehensive documentation on using these annotations to document microservice contracts. The schema defines ServiceOptions and MethodOptions messages with extension numbers 870014 and 870015, supported by updated extension naming documentation and a complete how-to guide covering subject derivation, identity overrides, error contracts, and runtime boundaries.

Changes

NATS Micro Service Options Schema and Documentation

Layer / File(s)	Summary
Proto Schema: Service and Method Options proto/trogon/nats/micro/v1alpha1/options.proto	New PayloadEncoding enum with PROTOBUF, JSON modes. New ServiceOptions message: endpoint_prefix, name, version, description, metadata map, request_timeout, skip, payload_encoding. New MethodOptions message: endpoint_name, endpoint_subject, request_timeout, metadata map. Extends google.protobuf.ServiceOptions with field 870014 and google.protobuf.MethodOptions with field 870015. File-level Elixir module prefix configured.
Extension Number Registration docs/explanation/protobuf-extension-naming.md	Registers extension numbers 870014 and 870015 for trogon.nats.micro.v1alpha1 ServiceOptions and MethodOptions. Adds trogon/nats/micro/v1alpha1/options.proto to "Examples in This Repo" section.
How-to: Document NATS Micro Services docs/how-to/document-nats-micro-services.md	New guide explains purpose of annotations as proto-contract metadata, default endpoint subject derivation rules and precedence order, service and method-level discovery identity overrides (name, version, description, metadata), endpoint naming convention via endpoint_name, explicit full subject override via endpoint_subject, structured error contract approach using trogon.error.v1alpha1, and runtime boundary definitions excluding deployment concerns.
Documentation Index Update docs/README.md	Adds link entry "Document NATS Micro Services" pointing to how-to/document-nats-micro-services.md.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• TrogonStack/trogon-proto#37: Adds protobuf option extensions and updates docs/explanation/protobuf-extension-naming.md to register nearby extension numbers.
• TrogonStack/trogon-proto#9: Earlier PR that established the protobuf-extension naming documentation framework that this PR extends.

Suggested labels

buf:skip:breaking

Poem

A rabbit hops through proto files with glee, 🐰
Where ServiceOptions now dance so free,
Extensions registered, two-seventy-oh-one-four,
Documentation blooming—there's ever more!
NATS microservices, now clearly defined,
A guide to contracts, so thoughtfully designed. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: defining a protobuf contract for NATS microservices with new options proto and supporting documentation.
Description check	✅ Passed	The description directly relates to the changeset by explaining the purpose—preventing incompatible annotations and removing ambiguity in NATS service contracts.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch yordis/feat-nats-micro-proto-contract

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf CI / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	May 11, 2026, 9:31 PM

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/how-to/document-nats-micro-services.md (1)

3-113: ⚡ Quick win

Document service.skip and service.payload_encoding in this how-to.

The new contract includes both fields, but this guide doesn’t describe intended semantics. Adding them here would better prevent generator interpretation drift.

📝 Suggested addition

+## Skip Generation
+
+Set `service.skip: true` when a protobuf service should be excluded from NATS micro code generation.
+
+## Select Payload Encoding
+
+Use `service.payload_encoding` to declare the default payload format for generated clients/handlers:
+
+- `PAYLOAD_ENCODING_PROTOBUF`
+- `PAYLOAD_ENCODING_JSON`
+
+If unset, generators use their configured default (typically protobuf).

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/how-to/document-nats-micro-services.md` around lines 3 - 113, Add
documentation for the new service fields: explain
(trogon.nats.micro.v1alpha1.service).skip as a boolean that tells generators to
omit service discovery registration and subject generation for that service
(i.e., endpoints may still exist but are not advertised), and document
(trogon.nats.micro.v1alpha1.service).payload_encoding as the service-level
default encoding (e.g., "proto", "json", "jsonpb", or "binary") that generators
should apply to request/response payloads unless a method-level override exists
(method.payload_encoding), how it interacts with transport metadata and error
payloads, and that it is purely a descriptor hint (no runtime enforcement) so
generators must emit metadata/serialization code accordingly.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/explanation/protobuf-extension-naming.md`:
- Line 117: The ServiceOptions example in the docs is missing fields and should
match the actual proto schema; update the ServiceOptions entry (the line showing
"ServiceOptions { endpoint_prefix, name, version, metadata } → service") so its
field list exactly mirrors the fields defined in
proto/trogon/nats/micro/v1alpha1/options.proto (use the same field names and
order), and ensure the example maps to "service" consistently with the proto
definition.

---

Nitpick comments:
In `@docs/how-to/document-nats-micro-services.md`:
- Around line 3-113: Add documentation for the new service fields: explain
(trogon.nats.micro.v1alpha1.service).skip as a boolean that tells generators to
omit service discovery registration and subject generation for that service
(i.e., endpoints may still exist but are not advertised), and document
(trogon.nats.micro.v1alpha1.service).payload_encoding as the service-level
default encoding (e.g., "proto", "json", "jsonpb", or "binary") that generators
should apply to request/response payloads unless a method-level override exists
(method.payload_encoding), how it interacts with transport metadata and error
payloads, and that it is purely a descriptor hint (no runtime enforcement) so
generators must emit metadata/serialization code accordingly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 31be75b3-14c9-41d9-ab70-a4be875f25d6

📥 Commits

Reviewing files that changed from the base of the PR and between d447415 and 199b63a.

📒 Files selected for processing (4)

• docs/README.md
• docs/explanation/protobuf-extension-naming.md
• docs/how-to/document-nats-micro-services.md
• proto/trogon/nats/micro/v1alpha1/options.proto

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2976537. Configure here.}