mxaccessgw/docs/style-guides/ProtobufStyleGuide.md

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.