Add @grpc_only annotation to preserve manually-maintained protobuf fields

lucy66hw · lucy66hw · commit 96bbc44ebf9d · 2026-03-16T23:14:50.000Z
Signed-off-by: xil &lt;fridalu66@gmail.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ## [Unreleased]
 ### Added
+- Add tooling_skip field option to preserve manually-maintained protobuf fields ([#378](https://github.com/opensearch-project/opensearch-protobufs/pull/378))
 
 ### Changed
  - Fix simplifySingleMapSchema to generate named wrapper schemas. ([#406](https://github.com/opensearch-project/opensearch-protobufs/pull/406))
diff --git a/protos/schemas/common.proto b/protos/schemas/common.proto
@@ -8,6 +8,13 @@ option go_package = "github.com/opensearch-project/opensearch-protobufs/go/opens
 option java_multiple_files = true;
 option java_outer_classname = "CommonProto";
 option java_package = "org.opensearch.protobufs";
+import "google/protobuf/descriptor.proto";
+
+// Custom field option for tooling
+extend google.protobuf.FieldOptions {
+  // Mark a field to be skipped by tooling. These fields are manually maintained and won't be marked as deprecated.
+  optional bool tooling_skip = 50001;
+}
 
 // The Search API operation to perform a search across all indices in the cluster or index search
 message SearchRequest {
@@ -134,7 +141,7 @@ message SearchRequestBody {
   optional TrackHits track_total_hits = 7;
 
   // [optional] Values used to boost the score of specified indexes. Specify in the format of <index> : <boost-multiplier>
-  map<string, float> indices_boost = 8;
+  map<string, float> indices_boost = 8 [deprecated = true];
 
   // [optional] The fields that OpenSearch should return using their docvalue forms. Specify a format to return results in a certain format, such as date and time.
   repeated FieldAndFormat docvalue_fields = 9;
@@ -210,6 +217,9 @@ message SearchRequestBody {
 
   // [optional]
   map<string, DerivedField> derived = 35;
+
+  // [optional] Values used to boost the score of specified indexes. Specify in the format of <index> : <boost-multiplier>
+  repeated FloatMap indices_boost_2 = 36;
 }
 
 message DerivedField {
@@ -2908,6 +2918,11 @@ message ShardSearchFailure {
   ErrorCause reason = 4;
 }
 
+message FloatMap {
+
+  map<string, float> float_map = 1;
+}
+
 enum FieldValueFactorModifier {
   FIELD_VALUE_FACTOR_MODIFIER_UNSPECIFIED = 0;
   FIELD_VALUE_FACTOR_MODIFIER_LN = 1;
diff --git a/tools/proto-convert/src/config/protobuf-schema-template/field_options.mustache b/tools/proto-convert/src/config/protobuf-schema-template/field_options.mustache
@@ -0,0 +1,8 @@
+
+import "google/protobuf/descriptor.proto";
+
+// Custom field option for tooling
+extend google.protobuf.FieldOptions {
+  // Mark a field to be skipped by tooling. These fields are manually maintained and won't be marked as deprecated.
+  optional bool tooling_skip = 50001;
+}
diff --git a/tools/proto-convert/src/postprocessing/CompatibilityMerger.ts b/tools/proto-convert/src/postprocessing/CompatibilityMerger.ts
@@ -13,6 +13,7 @@ import {
 import { CompatibilityReporter, formatField } from './CompatibilityReporter';
 
 const DEPRECATED: Annotation = { name: 'deprecated', value: 'true' };
+const TOOLING_SKIP: Annotation = { name: '(tooling_skip)', value: 'true' };
 
 /**
  * Extract base name
@@ -42,6 +43,16 @@ function isDeprecated(item: HasAnnotations): boolean {
     ) ?? false;
 }
 
+/**
+ * Check if an item has tooling_skip option set to true.
+ * Fields with this option are manually maintained and won't be deprecated.
+ */
+function hasToolingSkip(item: HasAnnotations): boolean {
+    return item.annotations?.some(a =>
+        a.name === TOOLING_SKIP.name && a.value === TOOLING_SKIP.value
+    ) ?? false;
+}
+
 /**
  * Add deprecated annotation to an item if not already deprecated.
  */
@@ -114,6 +125,9 @@ function mergeField(
             }
         }
     } else {
+        if (hasToolingSkip(sourceField)) {
+            return sourceField;
+        }
         reporter?.addFieldChange({
             messageName: msgName,
             changeType: 'DEPRECATED',
@@ -244,7 +258,7 @@ export function mergeMessage(
                     continue;
                 }
 
-                // Try 3: No match - deprecate
+                // Try 3: No match - deprecate or skip
                 mergedOneofFields.push(mergeField(sourceField, upcomingOneofByName, sourceMsg.name, reporter));
             }
 
diff --git a/tools/proto-convert/src/postprocessing/writer.ts b/tools/proto-convert/src/postprocessing/writer.ts
@@ -9,9 +9,10 @@ import { ProtoMessage, ProtoEnum } from './types';
 
 const TEMPLATE = readFileSync(join(__dirname, 'templates', 'proto.mustache'), 'utf8');
 
-const TEMPLATE_DIR = join(__dirname, '../config/protobuf-schema-template');
-const PROTO_HEADER = readFileSync(join(TEMPLATE_DIR, 'partial_header.mustache'), 'utf-8');
-const CUSTOM_MESSAGES = readFileSync(join(TEMPLATE_DIR, 'custom_message.mustache'), 'utf-8');
+const CONFIG_TEMPLATE_DIR = join(__dirname, '../config/protobuf-schema-template');
+const PROTO_HEADER = readFileSync(join(CONFIG_TEMPLATE_DIR, 'partial_header.mustache'), 'utf-8');
+const FIELD_OPTIONS = readFileSync(join(CONFIG_TEMPLATE_DIR, 'field_options.mustache'), 'utf-8');
+const CUSTOM_MESSAGES = readFileSync(join(CONFIG_TEMPLATE_DIR, 'custom_message.mustache'), 'utf-8');
 
 // Custom messages/enums defined in template - always handled separately
 export const CUSTOM_MESSAGE_NAMES = new Set(['ObjectMap', 'GeneralNumber']);
@@ -96,6 +97,9 @@ export function writeProtoFile(
 
     // Use fixed header from template
     outputParts.push(PROTO_HEADER.trim());
+    
+    // Add field options (import descriptor + extend)
+    outputParts.push(FIELD_OPTIONS.trim());
 
     // Generate messages (excluding custom ones - they're added from template)
     for (const msg of messages) {
diff --git a/tools/proto-convert/test/postprocessing/CompatibilityMerger.test.ts b/tools/proto-convert/test/postprocessing/CompatibilityMerger.test.ts
@@ -275,6 +275,125 @@ describe('mergeMessage', () => {
             );
             expect(deprecatedOptions).toHaveLength(1);
         });
+
+        it('should keep fields with tooling_skip option without deprecating', () => {
+            const source: ProtoMessage = {
+                name: 'TestMessage',
+                fields: [{
+                    name: 'skip_field',
+                    type: 'string',
+                    number: 1,
+                    annotations: [{ name: '(tooling_skip)', value: 'true' }]
+                }, {
+                    name: 'normal_field',
+                    type: 'string',
+                    number: 2
+                }]
+            };
+            const upcoming: ProtoMessage = {
+                name: 'TestMessage',
+                fields: [{
+                    name: 'normal_field',
+                    type: 'string',
+                    number: 2
+                }]
+            };
+
+            const result = mergeMessage(source, upcoming);
+
+            // skip_field should remain without deprecated annotation added
+            expect(result.fields).toHaveLength(2);
+            const skipField = result.fields.find(f => f.name === 'skip_field');
+            expect(skipField).toBeDefined();
+            // Should only have tooling_skip, not deprecated
+            expect(skipField!.annotations).not.toContainEqual({ name: 'deprecated', value: 'true' });
+        });
+
+        it('should not report tooling_skip fields as deprecated', () => {
+            const source: ProtoMessage = {
+                name: 'TestMessage',
+                fields: [{
+                    name: 'skip_field',
+                    type: 'string',
+                    number: 1,
+                    annotations: [{ name: '(tooling_skip)', value: 'true' }]
+                }]
+            };
+            const upcoming: ProtoMessage = {
+                name: 'TestMessage',
+                fields: []
+            };
+
+            const reporter = new CompatibilityReporter();
+            mergeMessage(source, upcoming, reporter);
+
+            const markdown = reporter.toMarkdown();
+            // Should not report deprecation for tooling_skip fields
+            expect(markdown).toContain('No changes detected');
+        });
+
+        it('should keep tooling_skip field if it exists in upcoming', () => {
+            const source: ProtoMessage = {
+                name: 'TestMessage',
+                fields: [{
+                    name: 'field_name',
+                    type: 'string',
+                    number: 1,
+                    annotations: [{ name: '(tooling_skip)', value: 'true' }]
+                }]
+            };
+            const upcoming: ProtoMessage = {
+                name: 'TestMessage',
+                fields: [{
+                    name: 'field_name',
+                    type: 'string',
+                    number: 1
+                }]
+            };
+
+            const result = mergeMessage(source, upcoming);
+
+            expect(result.fields).toHaveLength(1);
+            expect(result.fields[0].name).toBe('field_name');
+        });
+
+        it('should assign new field number after max including tooling_skip field', () => {
+            const source: ProtoMessage = {
+                name: 'TestMessage',
+                fields: [{
+                    name: 'existing_field',
+                    type: 'string',
+                    number: 1
+                }, {
+                    name: 'skip_field',
+                    type: 'string',
+                    number: 5,  // This is the max field number
+                    annotations: [{ name: '(tooling_skip)', value: 'true' }]
+                }]
+            };
+            const upcoming: ProtoMessage = {
+                name: 'TestMessage',
+                fields: [{
+                    name: 'existing_field',
+                    type: 'string',
+                    number: 1
+                }, {
+                    name: 'new_field',
+                    type: 'int32',
+                    number: 99  // This will be reassigned
+                }]
+            };
+
+            const result = mergeMessage(source, upcoming);
+
+            // skip_field is kept, new_field is added
+            expect(result.fields).toHaveLength(3);
+            expect(result.fields.find(f => f.name === 'skip_field')).toBeDefined();
+
+            const newField = result.fields.find(f => f.name === 'new_field');
+            expect(newField).toBeDefined();
+            expect(newField!.number).toBe(6);
+        });
     });
 
     describe('new fields', () => {
@@ -884,6 +1003,7 @@ describe('mergeEnum', () => {
             const markdown = reporter.toMarkdown();
             expect(markdown).toContain('No changes detected');
         });
+
     });
 
     describe('new values', () => {
