Joseph Doherty
65 lines
2.4 KiB
Markdown
65 lines
2.4 KiB
Markdown
# Protobuf Style Guide
|
|
|
|
This guide defines protobuf conventions for MXAccess Gateway public gRPC and
|
|
gateway-to-worker IPC contracts.
|
|
|
|
## Baseline
|
|
|
|
- Use `proto3`.
|
|
- Keep public gateway contracts and worker IPC contracts in separate `.proto`
|
|
files.
|
|
- Treat field numbers as permanent once released.
|
|
- Do not reuse removed field numbers or enum values. Reserve them.
|
|
- Keep generated code reproducible from checked-in `.proto` files.
|
|
|
|
## Source Documentation
|
|
|
|
- Maintain the existing documentation style in the `.proto` file and
|
|
surrounding contract docs.
|
|
- Write comments that include business-specific or domain-specific context when
|
|
that context is available from the contract, surrounding docs, or naming.
|
|
- Comment fields that carry MXAccess parity details, credential-sensitive data,
|
|
raw HRESULT/status information, or compatibility constraints.
|
|
- Avoid comments that restate field types or message nesting.
|
|
|
|
## Naming
|
|
|
|
- Use `snake_case` for package names, file names, field names, and enum values.
|
|
- Use `PascalCase` for message, enum, and service names.
|
|
- Prefix enum values with the enum name or a clear abbreviation to avoid name
|
|
collisions in generated languages.
|
|
- Keep MXAccess event family and command names recognizable in enum values.
|
|
|
|
## Compatibility
|
|
|
|
- Add fields instead of changing field meaning.
|
|
- Use `oneof` for command payloads, reply payloads, value unions, and event
|
|
bodies.
|
|
- Add explicit `UNKNOWN` or `UNSPECIFIED` enum zero values.
|
|
- Preserve raw HRESULT, MXAccess status, and diagnostic metadata in replies and
|
|
events.
|
|
- Use protocol version fields in worker IPC envelopes.
|
|
|
|
## Field Rules
|
|
|
|
- Do not use required semantics in application code for newly added optional
|
|
fields unless compatibility behavior is documented.
|
|
- Prefer explicit wrapper messages for repeated structured values.
|
|
- Use signed or unsigned integer types based on the actual semantic range.
|
|
- Represent timestamps with `google.protobuf.Timestamp` unless the source value
|
|
is not a real timestamp.
|
|
- Represent durations with `google.protobuf.Duration`.
|
|
|
|
## Security
|
|
|
|
- Do not define fields that require clients or workers to log secrets.
|
|
- Mark credential-bearing request fields clearly in comments.
|
|
- Keep raw values out of diagnostics unless an explicit redacted or opt-in path
|
|
exists.
|
|
|
|
## Generated Code
|
|
|
|
- Do not hand-edit generated code.
|
|
- Keep generation commands documented near the contracts project.
|
|
- Regenerate all affected language outputs when a contract changes.
|