contrast-agent 6.7.0 → 6.8.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (221) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +0 -2
  3. data/.simplecov +0 -1
  4. data/Rakefile +0 -1
  5. data/ext/cs__assess_array/cs__assess_array.c +41 -10
  6. data/ext/cs__assess_array/cs__assess_array.h +4 -1
  7. data/lib/contrast/agent/assess/policy/trigger_method.rb +2 -2
  8. data/lib/contrast/agent/assess/policy/trigger_validation/redos_validator.rb +1 -1
  9. data/lib/contrast/agent/assess/policy/trigger_validation/ssrf_validator.rb +1 -1
  10. data/lib/contrast/agent/assess/policy/trigger_validation/xss_validator.rb +1 -1
  11. data/lib/contrast/agent/excluder.rb +52 -34
  12. data/lib/contrast/agent/exclusion_matcher.rb +21 -9
  13. data/lib/contrast/agent/middleware.rb +4 -4
  14. data/lib/contrast/agent/patching/policy/after_load_patcher.rb +6 -0
  15. data/lib/contrast/agent/protect/input_analyzer/input_analyzer.rb +146 -127
  16. data/lib/contrast/agent/protect/policy/applies_path_traversal_rule.rb +20 -0
  17. data/lib/contrast/agent/protect/policy/rule_applicator.rb +1 -1
  18. data/lib/contrast/agent/protect/rule/base.rb +45 -53
  19. data/lib/contrast/agent/protect/rule/base_service.rb +48 -24
  20. data/lib/contrast/agent/protect/rule/bot_blocker/bot_blocker_input_classification.rb +98 -0
  21. data/lib/contrast/agent/protect/rule/bot_blocker.rb +81 -0
  22. data/lib/contrast/agent/protect/rule/cmd_injection.rb +18 -1
  23. data/lib/contrast/agent/protect/rule/cmdi/cmdi_backdoors.rb +8 -5
  24. data/lib/contrast/agent/protect/rule/cmdi/cmdi_base_rule.rb +22 -22
  25. data/lib/contrast/agent/protect/rule/cmdi/cmdi_chained_command.rb +69 -0
  26. data/lib/contrast/agent/protect/rule/cmdi/cmdi_dangerous_path.rb +68 -0
  27. data/lib/contrast/agent/protect/rule/cmdi/cmdi_input_classification.rb +2 -58
  28. data/lib/contrast/agent/protect/rule/default_scanner.rb +1 -1
  29. data/lib/contrast/agent/protect/rule/deserialization.rb +3 -14
  30. data/lib/contrast/agent/protect/rule/http_method_tampering/http_method_tampering_input_classification.rb +2 -2
  31. data/lib/contrast/agent/protect/rule/http_method_tampering.rb +0 -11
  32. data/lib/contrast/agent/protect/rule/no_sqli/no_sqli_input_classification.rb +29 -34
  33. data/lib/contrast/agent/protect/rule/no_sqli.rb +25 -18
  34. data/lib/contrast/agent/protect/rule/path_traversal/path_traversal_input_classification.rb +61 -0
  35. data/lib/contrast/agent/protect/rule/path_traversal/path_traversal_semantic_security_bypass.rb +114 -0
  36. data/lib/contrast/agent/protect/rule/path_traversal.rb +38 -12
  37. data/lib/contrast/agent/protect/rule/sql_sample_builder.rb +33 -15
  38. data/lib/contrast/agent/protect/rule/sqli/sqli_base_rule.rb +0 -14
  39. data/lib/contrast/agent/protect/rule/sqli/sqli_input_classification.rb +2 -62
  40. data/lib/contrast/agent/protect/rule/sqli.rb +70 -0
  41. data/lib/contrast/agent/protect/rule/unsafe_file_upload/unsafe_file_upload_input_classification.rb +39 -63
  42. data/lib/contrast/agent/protect/rule/unsafe_file_upload.rb +6 -33
  43. data/lib/contrast/agent/protect/rule/xss/reflected_xss_input_classification.rb +58 -0
  44. data/lib/contrast/agent/protect/rule/xss.rb +14 -20
  45. data/lib/contrast/agent/protect/rule/xxe.rb +4 -24
  46. data/lib/contrast/agent/reporting/attack_result/rasp_rule_sample.rb +18 -39
  47. data/lib/contrast/agent/reporting/attack_result/response_type.rb +9 -9
  48. data/lib/contrast/agent/reporting/details/ip_denylist_details.rb +10 -2
  49. data/lib/contrast/agent/reporting/details/virtual_patch_details.rb +8 -2
  50. data/lib/contrast/agent/reporting/input_analysis/details/bot_blocker_details.rb +27 -0
  51. data/lib/contrast/agent/reporting/input_analysis/details/protect_rule_details.rb +15 -0
  52. data/lib/contrast/agent/reporting/input_analysis/input_analysis.rb +1 -2
  53. data/lib/contrast/agent/reporting/input_analysis/input_analysis_result.rb +16 -2
  54. data/lib/contrast/agent/reporting/masker/masker.rb +2 -0
  55. data/lib/contrast/agent/reporting/reporter.rb +1 -14
  56. data/lib/contrast/agent/reporting/reporting_events/application_activity.rb +15 -12
  57. data/lib/contrast/agent/reporting/reporting_events/application_defend_attack_activity.rb +3 -3
  58. data/lib/contrast/agent/reporting/reporting_events/application_defend_attack_sample.rb +1 -2
  59. data/lib/contrast/agent/reporting/reporting_events/application_update.rb +0 -2
  60. data/lib/contrast/agent/reporting/reporting_events/architecture_component.rb +0 -1
  61. data/lib/contrast/agent/reporting/reporting_events/finding.rb +4 -4
  62. data/lib/contrast/agent/reporting/reporting_events/finding_request.rb +0 -5
  63. data/lib/contrast/agent/reporting/reporting_events/library_discovery.rb +0 -1
  64. data/lib/contrast/agent/reporting/reporting_events/poll.rb +1 -11
  65. data/lib/contrast/agent/reporting/reporting_events/route_discovery.rb +0 -1
  66. data/lib/contrast/agent/reporting/reporting_events/route_discovery_observation.rb +0 -1
  67. data/lib/contrast/agent/reporting/reporting_utilities/audit.rb +2 -2
  68. data/lib/contrast/agent/reporting/reporting_utilities/response.rb +1 -1
  69. data/lib/contrast/agent/reporting/reporting_utilities/response_handler.rb +0 -3
  70. data/lib/contrast/agent/reporting/reporting_utilities/response_handler_utils.rb +1 -0
  71. data/lib/contrast/agent/reporting/settings/code_exclusion.rb +6 -1
  72. data/lib/contrast/agent/reporting/settings/exclusion_base.rb +18 -0
  73. data/lib/contrast/agent/reporting/settings/exclusions.rb +2 -1
  74. data/lib/contrast/agent/reporting/settings/input_exclusion.rb +9 -3
  75. data/lib/contrast/agent/reporting/settings/protect.rb +15 -15
  76. data/lib/contrast/agent/request.rb +2 -14
  77. data/lib/contrast/agent/request_context.rb +6 -9
  78. data/lib/contrast/agent/request_context_extend.rb +9 -148
  79. data/lib/contrast/agent/thread_watcher.rb +3 -18
  80. data/lib/contrast/agent/version.rb +1 -1
  81. data/lib/contrast/agent.rb +0 -11
  82. data/lib/contrast/agent_lib/api/command_injection.rb +46 -0
  83. data/lib/contrast/agent_lib/api/init.rb +101 -0
  84. data/lib/contrast/agent_lib/api/input_tracing.rb +267 -0
  85. data/lib/contrast/agent_lib/api/method_tempering.rb +29 -0
  86. data/lib/contrast/agent_lib/api/panic.rb +87 -0
  87. data/lib/contrast/agent_lib/api/path_semantic_file_security_bypass.rb +40 -0
  88. data/lib/contrast/agent_lib/interface.rb +260 -0
  89. data/lib/contrast/agent_lib/interface_base.rb +118 -0
  90. data/lib/contrast/agent_lib/return_types/eval_result.rb +44 -0
  91. data/lib/contrast/agent_lib/test.rb +29 -0
  92. data/lib/contrast/api/communication/connection_status.rb +5 -5
  93. data/lib/contrast/components/agent.rb +0 -14
  94. data/lib/contrast/components/app_context.rb +0 -2
  95. data/lib/contrast/components/app_context_extend.rb +0 -25
  96. data/lib/contrast/components/config.rb +1 -18
  97. data/lib/contrast/components/protect.rb +4 -1
  98. data/lib/contrast/components/ruby_component.rb +1 -1
  99. data/lib/contrast/components/settings.rb +37 -89
  100. data/lib/contrast/config/protect_rule_configuration.rb +7 -7
  101. data/lib/contrast/config/protect_rules_configuration.rb +20 -58
  102. data/lib/contrast/configuration.rb +1 -10
  103. data/lib/contrast/extension/assess/array.rb +9 -0
  104. data/lib/contrast/extension/delegator.rb +2 -0
  105. data/lib/contrast/framework/manager.rb +3 -1
  106. data/lib/contrast/framework/rails/railtie.rb +0 -1
  107. data/lib/contrast/framework/rails/support.rb +0 -1
  108. data/lib/contrast/tasks/config.rb +1 -8
  109. data/lib/contrast/utils/duck_utils.rb +1 -0
  110. data/lib/contrast/utils/input_classification_base.rb +156 -0
  111. data/lib/contrast/utils/os.rb +0 -20
  112. data/lib/contrast/utils/response_utils.rb +0 -16
  113. data/lib/contrast/utils/stack_trace_utils.rb +3 -15
  114. data/lib/contrast/utils/string_utils.rb +10 -7
  115. data/lib/contrast.rb +2 -3
  116. data/resources/protect/policy.json +1 -2
  117. data/ruby-agent.gemspec +2 -5
  118. metadata +42 -112
  119. data/exe/contrast_service +0 -23
  120. data/lib/contrast/agent/protect/rule/cmdi/cmdi_worth_watching.rb +0 -64
  121. data/lib/contrast/agent/protect/rule/sqli/sqli_worth_watching.rb +0 -118
  122. data/lib/contrast/agent/protect/rule/unsafe_file_upload/unsafe_file_upload_matcher.rb +0 -45
  123. data/lib/contrast/agent/reaction_processor.rb +0 -47
  124. data/lib/contrast/agent/service_heartbeat.rb +0 -35
  125. data/lib/contrast/api/communication/messaging_queue.rb +0 -128
  126. data/lib/contrast/api/communication/response_processor.rb +0 -90
  127. data/lib/contrast/api/communication/service_lifecycle.rb +0 -77
  128. data/lib/contrast/api/communication/socket.rb +0 -44
  129. data/lib/contrast/api/communication/socket_client.rb +0 -130
  130. data/lib/contrast/api/communication/speedracer.rb +0 -138
  131. data/lib/contrast/api/communication/tcp_socket.rb +0 -32
  132. data/lib/contrast/api/communication/unix_socket.rb +0 -28
  133. data/lib/contrast/api/communication.rb +0 -20
  134. data/lib/contrast/api/decorators/address.rb +0 -59
  135. data/lib/contrast/api/decorators/agent_startup.rb +0 -56
  136. data/lib/contrast/api/decorators/application_settings.rb +0 -43
  137. data/lib/contrast/api/decorators/application_startup.rb +0 -56
  138. data/lib/contrast/api/decorators/bot_blocker.rb +0 -37
  139. data/lib/contrast/api/decorators/http_request.rb +0 -137
  140. data/lib/contrast/api/decorators/input_analysis.rb +0 -18
  141. data/lib/contrast/api/decorators/instrumentation_mode.rb +0 -35
  142. data/lib/contrast/api/decorators/ip_denylist.rb +0 -37
  143. data/lib/contrast/api/decorators/message.rb +0 -67
  144. data/lib/contrast/api/decorators/rasp_rule_sample.rb +0 -52
  145. data/lib/contrast/api/decorators/response_type.rb +0 -17
  146. data/lib/contrast/api/decorators/server_features.rb +0 -25
  147. data/lib/contrast/api/decorators/user_input.rb +0 -51
  148. data/lib/contrast/api/decorators/virtual_patch.rb +0 -34
  149. data/lib/contrast/api/decorators.rb +0 -22
  150. data/lib/contrast/api/dtm.pb.rb +0 -363
  151. data/lib/contrast/api/settings.pb.rb +0 -500
  152. data/lib/contrast/api.rb +0 -16
  153. data/lib/contrast/components/contrast_service.rb +0 -88
  154. data/lib/contrast/components/service.rb +0 -55
  155. data/lib/contrast/tasks/service.rb +0 -84
  156. data/lib/contrast/utils/input_classification.rb +0 -73
  157. data/lib/protobuf/code_generator.rb +0 -129
  158. data/lib/protobuf/decoder.rb +0 -28
  159. data/lib/protobuf/deprecation.rb +0 -117
  160. data/lib/protobuf/descriptors/google/protobuf/compiler/plugin.pb.rb +0 -79
  161. data/lib/protobuf/descriptors/google/protobuf/descriptor.pb.rb +0 -360
  162. data/lib/protobuf/descriptors.rb +0 -3
  163. data/lib/protobuf/encoder.rb +0 -11
  164. data/lib/protobuf/enum.rb +0 -365
  165. data/lib/protobuf/exceptions.rb +0 -9
  166. data/lib/protobuf/field/base_field.rb +0 -380
  167. data/lib/protobuf/field/base_field_object_definitions.rb +0 -504
  168. data/lib/protobuf/field/bool_field.rb +0 -64
  169. data/lib/protobuf/field/bytes_field.rb +0 -67
  170. data/lib/protobuf/field/double_field.rb +0 -25
  171. data/lib/protobuf/field/enum_field.rb +0 -56
  172. data/lib/protobuf/field/field_array.rb +0 -102
  173. data/lib/protobuf/field/field_hash.rb +0 -122
  174. data/lib/protobuf/field/fixed32_field.rb +0 -25
  175. data/lib/protobuf/field/fixed64_field.rb +0 -28
  176. data/lib/protobuf/field/float_field.rb +0 -43
  177. data/lib/protobuf/field/int32_field.rb +0 -21
  178. data/lib/protobuf/field/int64_field.rb +0 -34
  179. data/lib/protobuf/field/integer_field.rb +0 -23
  180. data/lib/protobuf/field/message_field.rb +0 -51
  181. data/lib/protobuf/field/sfixed32_field.rb +0 -27
  182. data/lib/protobuf/field/sfixed64_field.rb +0 -28
  183. data/lib/protobuf/field/signed_integer_field.rb +0 -29
  184. data/lib/protobuf/field/sint32_field.rb +0 -21
  185. data/lib/protobuf/field/sint64_field.rb +0 -21
  186. data/lib/protobuf/field/string_field.rb +0 -51
  187. data/lib/protobuf/field/uint32_field.rb +0 -21
  188. data/lib/protobuf/field/uint64_field.rb +0 -21
  189. data/lib/protobuf/field/varint_field.rb +0 -77
  190. data/lib/protobuf/field.rb +0 -74
  191. data/lib/protobuf/generators/base.rb +0 -85
  192. data/lib/protobuf/generators/enum_generator.rb +0 -39
  193. data/lib/protobuf/generators/extension_generator.rb +0 -27
  194. data/lib/protobuf/generators/field_generator.rb +0 -193
  195. data/lib/protobuf/generators/file_generator.rb +0 -262
  196. data/lib/protobuf/generators/group_generator.rb +0 -122
  197. data/lib/protobuf/generators/message_generator.rb +0 -104
  198. data/lib/protobuf/generators/option_generator.rb +0 -17
  199. data/lib/protobuf/generators/printable.rb +0 -160
  200. data/lib/protobuf/generators/service_generator.rb +0 -50
  201. data/lib/protobuf/lifecycle.rb +0 -33
  202. data/lib/protobuf/logging.rb +0 -39
  203. data/lib/protobuf/message/fields.rb +0 -233
  204. data/lib/protobuf/message/serialization.rb +0 -85
  205. data/lib/protobuf/message.rb +0 -241
  206. data/lib/protobuf/optionable.rb +0 -72
  207. data/lib/protobuf/tasks/compile.rake +0 -80
  208. data/lib/protobuf/tasks.rb +0 -1
  209. data/lib/protobuf/varint.rb +0 -20
  210. data/lib/protobuf/varint_pure.rb +0 -31
  211. data/lib/protobuf/version.rb +0 -3
  212. data/lib/protobuf/wire_type.rb +0 -10
  213. data/lib/protobuf.rb +0 -91
  214. data/proto/dynamic_discovery.proto +0 -46
  215. data/proto/google/protobuf/compiler/plugin.proto +0 -183
  216. data/proto/google/protobuf/descriptor.proto +0 -911
  217. data/proto/rpc.proto +0 -71
  218. data/service_executables/.gitkeep +0 -0
  219. data/service_executables/VERSION +0 -1
  220. data/service_executables/linux/contrast-service +0 -0
  221. data/service_executables/mac/contrast-service +0 -0
@@ -1,911 +0,0 @@
1
- // Protocol Buffers - Google's data interchange format
2
- // Copyright 2008 Google Inc. All rights reserved.
3
- // https://developers.google.com/protocol-buffers/
4
- //
5
- // Redistribution and use in source and binary forms, with or without
6
- // modification, are permitted provided that the following conditions are
7
- // met:
8
- //
9
- // * Redistributions of source code must retain the above copyright
10
- // notice, this list of conditions and the following disclaimer.
11
- // * Redistributions in binary form must reproduce the above
12
- // copyright notice, this list of conditions and the following disclaimer
13
- // in the documentation and/or other materials provided with the
14
- // distribution.
15
- // * Neither the name of Google Inc. nor the names of its
16
- // contributors may be used to endorse or promote products derived from
17
- // this software without specific prior written permission.
18
- //
19
- // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20
- // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21
- // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22
- // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23
- // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24
- // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25
- // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26
- // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27
- // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28
- // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29
- // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
-
31
- // Author: kenton@google.com (Kenton Varda)
32
- // Based on original Protocol Buffers design by
33
- // Sanjay Ghemawat, Jeff Dean, and others.
34
- //
35
- // The messages in this file describe the definitions found in .proto files.
36
- // A valid .proto file can be translated directly to a FileDescriptorProto
37
- // without any other information (e.g. without reading its imports).
38
-
39
-
40
- syntax = "proto2";
41
-
42
- package google.protobuf;
43
-
44
- option go_package = "google.golang.org/protobuf/types/descriptorpb";
45
- option java_package = "com.google.protobuf";
46
- option java_outer_classname = "DescriptorProtos";
47
- option csharp_namespace = "Google.Protobuf.Reflection";
48
- option objc_class_prefix = "GPB";
49
- option cc_enable_arenas = true;
50
-
51
- // descriptor.proto must be optimized for speed because reflection-based
52
- // algorithms don't work during bootstrapping.
53
- option optimize_for = SPEED;
54
-
55
- // The protocol compiler can output a FileDescriptorSet containing the .proto
56
- // files it parses.
57
- message FileDescriptorSet {
58
- repeated FileDescriptorProto file = 1;
59
- }
60
-
61
- // Describes a complete .proto file.
62
- message FileDescriptorProto {
63
- optional string name = 1; // file name, relative to root of source tree
64
- optional string package = 2; // e.g. "foo", "foo.bar", etc.
65
-
66
- // Names of files imported by this file.
67
- repeated string dependency = 3;
68
- // Indexes of the public imported files in the dependency list above.
69
- repeated int32 public_dependency = 10;
70
- // Indexes of the weak imported files in the dependency list.
71
- // For Google-internal migration only. Do not use.
72
- repeated int32 weak_dependency = 11;
73
-
74
- // All top-level definitions in this file.
75
- repeated DescriptorProto message_type = 4;
76
- repeated EnumDescriptorProto enum_type = 5;
77
- repeated ServiceDescriptorProto service = 6;
78
- repeated FieldDescriptorProto extension = 7;
79
-
80
- optional FileOptions options = 8;
81
-
82
- // This field contains optional information about the original source code.
83
- // You may safely remove this entire field without harming runtime
84
- // functionality of the descriptors -- the information is needed only by
85
- // development tools.
86
- optional SourceCodeInfo source_code_info = 9;
87
-
88
- // The syntax of the proto file.
89
- // The supported values are "proto2" and "proto3".
90
- optional string syntax = 12;
91
- }
92
-
93
- // Describes a message type.
94
- message DescriptorProto {
95
- optional string name = 1;
96
-
97
- repeated FieldDescriptorProto field = 2;
98
- repeated FieldDescriptorProto extension = 6;
99
-
100
- repeated DescriptorProto nested_type = 3;
101
- repeated EnumDescriptorProto enum_type = 4;
102
-
103
- message ExtensionRange {
104
- optional int32 start = 1; // Inclusive.
105
- optional int32 end = 2; // Exclusive.
106
-
107
- optional ExtensionRangeOptions options = 3;
108
- }
109
- repeated ExtensionRange extension_range = 5;
110
-
111
- repeated OneofDescriptorProto oneof_decl = 8;
112
-
113
- optional MessageOptions options = 7;
114
-
115
- // Range of reserved tag numbers. Reserved tag numbers may not be used by
116
- // fields or extension ranges in the same message. Reserved ranges may
117
- // not overlap.
118
- message ReservedRange {
119
- optional int32 start = 1; // Inclusive.
120
- optional int32 end = 2; // Exclusive.
121
- }
122
- repeated ReservedRange reserved_range = 9;
123
- // Reserved field names, which may not be used by fields in the same message.
124
- // A given name may only be reserved once.
125
- repeated string reserved_name = 10;
126
- }
127
-
128
- message ExtensionRangeOptions {
129
- // The parser stores options it doesn't recognize here. See above.
130
- repeated UninterpretedOption uninterpreted_option = 999;
131
-
132
-
133
- // Clients can define custom options in extensions of this message. See above.
134
- extensions 1000 to max;
135
- }
136
-
137
- // Describes a field within a message.
138
- message FieldDescriptorProto {
139
- enum Type {
140
- // 0 is reserved for errors.
141
- // Order is weird for historical reasons.
142
- TYPE_DOUBLE = 1;
143
- TYPE_FLOAT = 2;
144
- // Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT64 if
145
- // negative values are likely.
146
- TYPE_INT64 = 3;
147
- TYPE_UINT64 = 4;
148
- // Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT32 if
149
- // negative values are likely.
150
- TYPE_INT32 = 5;
151
- TYPE_FIXED64 = 6;
152
- TYPE_FIXED32 = 7;
153
- TYPE_BOOL = 8;
154
- TYPE_STRING = 9;
155
- // Tag-delimited aggregate.
156
- // Group type is deprecated and not supported in proto3. However, Proto3
157
- // implementations should still be able to parse the group wire format and
158
- // treat group fields as unknown fields.
159
- TYPE_GROUP = 10;
160
- TYPE_MESSAGE = 11; // Length-delimited aggregate.
161
-
162
- // New in version 2.
163
- TYPE_BYTES = 12;
164
- TYPE_UINT32 = 13;
165
- TYPE_ENUM = 14;
166
- TYPE_SFIXED32 = 15;
167
- TYPE_SFIXED64 = 16;
168
- TYPE_SINT32 = 17; // Uses ZigZag encoding.
169
- TYPE_SINT64 = 18; // Uses ZigZag encoding.
170
- }
171
-
172
- enum Label {
173
- // 0 is reserved for errors
174
- LABEL_OPTIONAL = 1;
175
- LABEL_REQUIRED = 2;
176
- LABEL_REPEATED = 3;
177
- }
178
-
179
- optional string name = 1;
180
- optional int32 number = 3;
181
- optional Label label = 4;
182
-
183
- // If type_name is set, this need not be set. If both this and type_name
184
- // are set, this must be one of TYPE_ENUM, TYPE_MESSAGE or TYPE_GROUP.
185
- optional Type type = 5;
186
-
187
- // For message and enum types, this is the name of the type. If the name
188
- // starts with a '.', it is fully-qualified. Otherwise, C++-like scoping
189
- // rules are used to find the type (i.e. first the nested types within this
190
- // message are searched, then within the parent, on up to the root
191
- // namespace).
192
- optional string type_name = 6;
193
-
194
- // For extensions, this is the name of the type being extended. It is
195
- // resolved in the same manner as type_name.
196
- optional string extendee = 2;
197
-
198
- // For numeric types, contains the original text representation of the value.
199
- // For booleans, "true" or "false".
200
- // For strings, contains the default text contents (not escaped in any way).
201
- // For bytes, contains the C escaped value. All bytes >= 128 are escaped.
202
- // TODO(kenton): Base-64 encode?
203
- optional string default_value = 7;
204
-
205
- // If set, gives the index of a oneof in the containing type's oneof_decl
206
- // list. This field is a member of that oneof.
207
- optional int32 oneof_index = 9;
208
-
209
- // JSON name of this field. The value is set by protocol compiler. If the
210
- // user has set a "json_name" option on this field, that option's value
211
- // will be used. Otherwise, it's deduced from the field's name by converting
212
- // it to camelCase.
213
- optional string json_name = 10;
214
-
215
- optional FieldOptions options = 8;
216
-
217
- // If true, this is a proto3 "optional". When a proto3 field is optional, it
218
- // tracks presence regardless of field type.
219
- //
220
- // When proto3_optional is true, this field must be belong to a oneof to
221
- // signal to old proto3 clients that presence is tracked for this field. This
222
- // oneof is known as a "synthetic" oneof, and this field must be its sole
223
- // member (each proto3 optional field gets its own synthetic oneof). Synthetic
224
- // oneofs exist in the descriptor only, and do not generate any API. Synthetic
225
- // oneofs must be ordered after all "real" oneofs.
226
- //
227
- // For message fields, proto3_optional doesn't create any semantic change,
228
- // since non-repeated message fields always track presence. However it still
229
- // indicates the semantic detail of whether the user wrote "optional" or not.
230
- // This can be useful for round-tripping the .proto file. For consistency we
231
- // give message fields a synthetic oneof also, even though it is not required
232
- // to track presence. This is especially important because the parser can't
233
- // tell if a field is a message or an enum, so it must always create a
234
- // synthetic oneof.
235
- //
236
- // Proto2 optional fields do not set this flag, because they already indicate
237
- // optional with `LABEL_OPTIONAL`.
238
- optional bool proto3_optional = 17;
239
- }
240
-
241
- // Describes a oneof.
242
- message OneofDescriptorProto {
243
- optional string name = 1;
244
- optional OneofOptions options = 2;
245
- }
246
-
247
- // Describes an enum type.
248
- message EnumDescriptorProto {
249
- optional string name = 1;
250
-
251
- repeated EnumValueDescriptorProto value = 2;
252
-
253
- optional EnumOptions options = 3;
254
-
255
- // Range of reserved numeric values. Reserved values may not be used by
256
- // entries in the same enum. Reserved ranges may not overlap.
257
- //
258
- // Note that this is distinct from DescriptorProto.ReservedRange in that it
259
- // is inclusive such that it can appropriately represent the entire int32
260
- // domain.
261
- message EnumReservedRange {
262
- optional int32 start = 1; // Inclusive.
263
- optional int32 end = 2; // Inclusive.
264
- }
265
-
266
- // Range of reserved numeric values. Reserved numeric values may not be used
267
- // by enum values in the same enum declaration. Reserved ranges may not
268
- // overlap.
269
- repeated EnumReservedRange reserved_range = 4;
270
-
271
- // Reserved enum value names, which may not be reused. A given name may only
272
- // be reserved once.
273
- repeated string reserved_name = 5;
274
- }
275
-
276
- // Describes a value within an enum.
277
- message EnumValueDescriptorProto {
278
- optional string name = 1;
279
- optional int32 number = 2;
280
-
281
- optional EnumValueOptions options = 3;
282
- }
283
-
284
- // Describes a service.
285
- message ServiceDescriptorProto {
286
- optional string name = 1;
287
- repeated MethodDescriptorProto method = 2;
288
-
289
- optional ServiceOptions options = 3;
290
- }
291
-
292
- // Describes a method of a service.
293
- message MethodDescriptorProto {
294
- optional string name = 1;
295
-
296
- // Input and output type names. These are resolved in the same way as
297
- // FieldDescriptorProto.type_name, but must refer to a message type.
298
- optional string input_type = 2;
299
- optional string output_type = 3;
300
-
301
- optional MethodOptions options = 4;
302
-
303
- // Identifies if client streams multiple client messages
304
- optional bool client_streaming = 5 [default = false];
305
- // Identifies if server streams multiple server messages
306
- optional bool server_streaming = 6 [default = false];
307
- }
308
-
309
-
310
- // ===================================================================
311
- // Options
312
-
313
- // Each of the definitions above may have "options" attached. These are
314
- // just annotations which may cause code to be generated slightly differently
315
- // or may contain hints for code that manipulates protocol messages.
316
- //
317
- // Clients may define custom options as extensions of the *Options messages.
318
- // These extensions may not yet be known at parsing time, so the parser cannot
319
- // store the values in them. Instead it stores them in a field in the *Options
320
- // message called uninterpreted_option. This field must have the same name
321
- // across all *Options messages. We then use this field to populate the
322
- // extensions when we build a descriptor, at which point all protos have been
323
- // parsed and so all extensions are known.
324
- //
325
- // Extension numbers for custom options may be chosen as follows:
326
- // * For options which will only be used within a single application or
327
- // organization, or for experimental options, use field numbers 50000
328
- // through 99999. It is up to you to ensure that you do not use the
329
- // same number for multiple options.
330
- // * For options which will be published and used publicly by multiple
331
- // independent entities, e-mail protobuf-global-extension-registry@google.com
332
- // to reserve extension numbers. Simply provide your project name (e.g.
333
- // Objective-C plugin) and your project website (if available) -- there's no
334
- // need to explain how you intend to use them. Usually you only need one
335
- // extension number. You can declare multiple options with only one extension
336
- // number by putting them in a sub-message. See the Custom Options section of
337
- // the docs for examples:
338
- // https://developers.google.com/protocol-buffers/docs/proto#options
339
- // If this turns out to be popular, a web service will be set up
340
- // to automatically assign option numbers.
341
-
342
- message FileOptions {
343
-
344
- // Sets the Java package where classes generated from this .proto will be
345
- // placed. By default, the proto package is used, but this is often
346
- // inappropriate because proto packages do not normally start with backwards
347
- // domain names.
348
- optional string java_package = 1;
349
-
350
-
351
- // Controls the name of the wrapper Java class generated for the .proto file.
352
- // That class will always contain the .proto file's getDescriptor() method as
353
- // well as any top-level extensions defined in the .proto file.
354
- // If java_multiple_files is disabled, then all the other classes from the
355
- // .proto file will be nested inside the single wrapper outer class.
356
- optional string java_outer_classname = 8;
357
-
358
- // If enabled, then the Java code generator will generate a separate .java
359
- // file for each top-level message, enum, and service defined in the .proto
360
- // file. Thus, these types will *not* be nested inside the wrapper class
361
- // named by java_outer_classname. However, the wrapper class will still be
362
- // generated to contain the file's getDescriptor() method as well as any
363
- // top-level extensions defined in the file.
364
- optional bool java_multiple_files = 10 [default = false];
365
-
366
- // This option does nothing.
367
- optional bool java_generate_equals_and_hash = 20 [deprecated=true];
368
-
369
- // If set true, then the Java2 code generator will generate code that
370
- // throws an exception whenever an attempt is made to assign a non-UTF-8
371
- // byte sequence to a string field.
372
- // Message reflection will do the same.
373
- // However, an extension field still accepts non-UTF-8 byte sequences.
374
- // This option has no effect on when used with the lite runtime.
375
- optional bool java_string_check_utf8 = 27 [default = false];
376
-
377
-
378
- // Generated classes can be optimized for speed or code size.
379
- enum OptimizeMode {
380
- SPEED = 1; // Generate complete code for parsing, serialization,
381
- // etc.
382
- CODE_SIZE = 2; // Use ReflectionOps to implement these methods.
383
- LITE_RUNTIME = 3; // Generate code using MessageLite and the lite runtime.
384
- }
385
- optional OptimizeMode optimize_for = 9 [default = SPEED];
386
-
387
- // Sets the Go package where structs generated from this .proto will be
388
- // placed. If omitted, the Go package will be derived from the following:
389
- // - The basename of the package import path, if provided.
390
- // - Otherwise, the package statement in the .proto file, if present.
391
- // - Otherwise, the basename of the .proto file, without extension.
392
- optional string go_package = 11;
393
-
394
-
395
-
396
-
397
- // Should generic services be generated in each language? "Generic" services
398
- // are not specific to any particular RPC system. They are generated by the
399
- // main code generators in each language (without additional plugins).
400
- // Generic services were the only kind of service generation supported by
401
- // early versions of google.protobuf.
402
- //
403
- // Generic services are now considered deprecated in favor of using plugins
404
- // that generate code specific to your particular RPC system. Therefore,
405
- // these default to false. Old code which depends on generic services should
406
- // explicitly set them to true.
407
- optional bool cc_generic_services = 16 [default = false];
408
- optional bool java_generic_services = 17 [default = false];
409
- optional bool py_generic_services = 18 [default = false];
410
- optional bool php_generic_services = 42 [default = false];
411
-
412
- // Is this file deprecated?
413
- // Depending on the target platform, this can emit Deprecated annotations
414
- // for everything in the file, or it will be completely ignored; in the very
415
- // least, this is a formalization for deprecating files.
416
- optional bool deprecated = 23 [default = false];
417
-
418
- // Enables the use of arenas for the proto messages in this file. This applies
419
- // only to generated classes for C++.
420
- optional bool cc_enable_arenas = 31 [default = true];
421
-
422
-
423
- // Sets the objective c class prefix which is prepended to all objective c
424
- // generated classes from this .proto. There is no default.
425
- optional string objc_class_prefix = 36;
426
-
427
- // Namespace for generated classes; defaults to the package.
428
- optional string csharp_namespace = 37;
429
-
430
- // By default Swift generators will take the proto package and CamelCase it
431
- // replacing '.' with underscore and use that to prefix the types/symbols
432
- // defined. When this options is provided, they will use this value instead
433
- // to prefix the types/symbols defined.
434
- optional string swift_prefix = 39;
435
-
436
- // Sets the php class prefix which is prepended to all php generated classes
437
- // from this .proto. Default is empty.
438
- optional string php_class_prefix = 40;
439
-
440
- // Use this option to change the namespace of php generated classes. Default
441
- // is empty. When this option is empty, the package name will be used for
442
- // determining the namespace.
443
- optional string php_namespace = 41;
444
-
445
- // Use this option to change the namespace of php generated metadata classes.
446
- // Default is empty. When this option is empty, the proto file name will be
447
- // used for determining the namespace.
448
- optional string php_metadata_namespace = 44;
449
-
450
- // Use this option to change the package of ruby generated classes. Default
451
- // is empty. When this option is not set, the package name will be used for
452
- // determining the ruby package.
453
- optional string ruby_package = 45;
454
-
455
-
456
- // The parser stores options it doesn't recognize here.
457
- // See the documentation for the "Options" section above.
458
- repeated UninterpretedOption uninterpreted_option = 999;
459
-
460
- // Clients can define custom options in extensions of this message.
461
- // See the documentation for the "Options" section above.
462
- extensions 1000 to max;
463
-
464
- reserved 38;
465
- }
466
-
467
- message MessageOptions {
468
- // Set true to use the old proto1 MessageSet wire format for extensions.
469
- // This is provided for backwards-compatibility with the MessageSet wire
470
- // format. You should not use this for any other reason: It's less
471
- // efficient, has fewer features, and is more complicated.
472
- //
473
- // The message must be defined exactly as follows:
474
- // message Foo {
475
- // option message_set_wire_format = true;
476
- // extensions 4 to max;
477
- // }
478
- // Note that the message cannot have any defined fields; MessageSets only
479
- // have extensions.
480
- //
481
- // All extensions of your type must be singular messages; e.g. they cannot
482
- // be int32s, enums, or repeated messages.
483
- //
484
- // Because this is an option, the above two restrictions are not enforced by
485
- // the protocol compiler.
486
- optional bool message_set_wire_format = 1 [default = false];
487
-
488
- // Disables the generation of the standard "descriptor()" accessor, which can
489
- // conflict with a field of the same name. This is meant to make migration
490
- // from proto1 easier; new code should avoid fields named "descriptor".
491
- optional bool no_standard_descriptor_accessor = 2 [default = false];
492
-
493
- // Is this message deprecated?
494
- // Depending on the target platform, this can emit Deprecated annotations
495
- // for the message, or it will be completely ignored; in the very least,
496
- // this is a formalization for deprecating messages.
497
- optional bool deprecated = 3 [default = false];
498
-
499
- reserved 4, 5, 6;
500
-
501
- // Whether the message is an automatically generated map entry type for the
502
- // maps field.
503
- //
504
- // For maps fields:
505
- // map<KeyType, ValueType> map_field = 1;
506
- // The parsed descriptor looks like:
507
- // message MapFieldEntry {
508
- // option map_entry = true;
509
- // optional KeyType key = 1;
510
- // optional ValueType value = 2;
511
- // }
512
- // repeated MapFieldEntry map_field = 1;
513
- //
514
- // Implementations may choose not to generate the map_entry=true message, but
515
- // use a native map in the target language to hold the keys and values.
516
- // The reflection APIs in such implementations still need to work as
517
- // if the field is a repeated message field.
518
- //
519
- // NOTE: Do not set the option in .proto files. Always use the maps syntax
520
- // instead. The option should only be implicitly set by the proto compiler
521
- // parser.
522
- optional bool map_entry = 7;
523
-
524
- reserved 8; // javalite_serializable
525
- reserved 9; // javanano_as_lite
526
-
527
-
528
- // The parser stores options it doesn't recognize here. See above.
529
- repeated UninterpretedOption uninterpreted_option = 999;
530
-
531
- // Clients can define custom options in extensions of this message. See above.
532
- extensions 1000 to max;
533
- }
534
-
535
- message FieldOptions {
536
- // The ctype option instructs the C++ code generator to use a different
537
- // representation of the field than it normally would. See the specific
538
- // options below. This option is not yet implemented in the open source
539
- // release -- sorry, we'll try to include it in a future version!
540
- optional CType ctype = 1 [default = STRING];
541
- enum CType {
542
- // Default mode.
543
- STRING = 0;
544
-
545
- CORD = 1;
546
-
547
- STRING_PIECE = 2;
548
- }
549
- // The packed option can be enabled for repeated primitive fields to enable
550
- // a more efficient representation on the wire. Rather than repeatedly
551
- // writing the tag and type for each element, the entire array is encoded as
552
- // a single length-delimited blob. In proto3, only explicit setting it to
553
- // false will avoid using packed encoding.
554
- optional bool packed = 2;
555
-
556
- // The jstype option determines the JavaScript type used for values of the
557
- // field. The option is permitted only for 64 bit integral and fixed types
558
- // (int64, uint64, sint64, fixed64, sfixed64). A field with jstype JS_STRING
559
- // is represented as JavaScript string, which avoids loss of precision that
560
- // can happen when a large value is converted to a floating point JavaScript.
561
- // Specifying JS_NUMBER for the jstype causes the generated JavaScript code to
562
- // use the JavaScript "number" type. The behavior of the default option
563
- // JS_NORMAL is implementation dependent.
564
- //
565
- // This option is an enum to permit additional types to be added, e.g.
566
- // goog.math.Integer.
567
- optional JSType jstype = 6 [default = JS_NORMAL];
568
- enum JSType {
569
- // Use the default type.
570
- JS_NORMAL = 0;
571
-
572
- // Use JavaScript strings.
573
- JS_STRING = 1;
574
-
575
- // Use JavaScript numbers.
576
- JS_NUMBER = 2;
577
- }
578
-
579
- // Should this field be parsed lazily? Lazy applies only to message-type
580
- // fields. It means that when the outer message is initially parsed, the
581
- // inner message's contents will not be parsed but instead stored in encoded
582
- // form. The inner message will actually be parsed when it is first accessed.
583
- //
584
- // This is only a hint. Implementations are free to choose whether to use
585
- // eager or lazy parsing regardless of the value of this option. However,
586
- // setting this option true suggests that the protocol author believes that
587
- // using lazy parsing on this field is worth the additional bookkeeping
588
- // overhead typically needed to implement it.
589
- //
590
- // This option does not affect the public interface of any generated code;
591
- // all method signatures remain the same. Furthermore, thread-safety of the
592
- // interface is not affected by this option; const methods remain safe to
593
- // call from multiple threads concurrently, while non-const methods continue
594
- // to require exclusive access.
595
- //
596
- //
597
- // Note that implementations may choose not to check required fields within
598
- // a lazy sub-message. That is, calling IsInitialized() on the outer message
599
- // may return true even if the inner message has missing required fields.
600
- // This is necessary because otherwise the inner message would have to be
601
- // parsed in order to perform the check, defeating the purpose of lazy
602
- // parsing. An implementation which chooses not to check required fields
603
- // must be consistent about it. That is, for any particular sub-message, the
604
- // implementation must either *always* check its required fields, or *never*
605
- // check its required fields, regardless of whether or not the message has
606
- // been parsed.
607
- optional bool lazy = 5 [default = false];
608
-
609
- // Is this field deprecated?
610
- // Depending on the target platform, this can emit Deprecated annotations
611
- // for accessors, or it will be completely ignored; in the very least, this
612
- // is a formalization for deprecating fields.
613
- optional bool deprecated = 3 [default = false];
614
-
615
- // For Google-internal migration only. Do not use.
616
- optional bool weak = 10 [default = false];
617
-
618
-
619
- // The parser stores options it doesn't recognize here. See above.
620
- repeated UninterpretedOption uninterpreted_option = 999;
621
-
622
- // Clients can define custom options in extensions of this message. See above.
623
- extensions 1000 to max;
624
-
625
- reserved 4; // removed jtype
626
- }
627
-
628
- message OneofOptions {
629
- // The parser stores options it doesn't recognize here. See above.
630
- repeated UninterpretedOption uninterpreted_option = 999;
631
-
632
- // Clients can define custom options in extensions of this message. See above.
633
- extensions 1000 to max;
634
- }
635
-
636
- message EnumOptions {
637
-
638
- // Set this option to true to allow mapping different tag names to the same
639
- // value.
640
- optional bool allow_alias = 2;
641
-
642
- // Is this enum deprecated?
643
- // Depending on the target platform, this can emit Deprecated annotations
644
- // for the enum, or it will be completely ignored; in the very least, this
645
- // is a formalization for deprecating enums.
646
- optional bool deprecated = 3 [default = false];
647
-
648
- reserved 5; // javanano_as_lite
649
-
650
- // The parser stores options it doesn't recognize here. See above.
651
- repeated UninterpretedOption uninterpreted_option = 999;
652
-
653
- // Clients can define custom options in extensions of this message. See above.
654
- extensions 1000 to max;
655
- }
656
-
657
- message EnumValueOptions {
658
- // Is this enum value deprecated?
659
- // Depending on the target platform, this can emit Deprecated annotations
660
- // for the enum value, or it will be completely ignored; in the very least,
661
- // this is a formalization for deprecating enum values.
662
- optional bool deprecated = 1 [default = false];
663
-
664
- // The parser stores options it doesn't recognize here. See above.
665
- repeated UninterpretedOption uninterpreted_option = 999;
666
-
667
- // Clients can define custom options in extensions of this message. See above.
668
- extensions 1000 to max;
669
- }
670
-
671
- message ServiceOptions {
672
-
673
- // Note: Field numbers 1 through 32 are reserved for Google's internal RPC
674
- // framework. We apologize for hoarding these numbers to ourselves, but
675
- // we were already using them long before we decided to release Protocol
676
- // Buffers.
677
-
678
- // Is this service deprecated?
679
- // Depending on the target platform, this can emit Deprecated annotations
680
- // for the service, or it will be completely ignored; in the very least,
681
- // this is a formalization for deprecating services.
682
- optional bool deprecated = 33 [default = false];
683
-
684
- // The parser stores options it doesn't recognize here. See above.
685
- repeated UninterpretedOption uninterpreted_option = 999;
686
-
687
- // Clients can define custom options in extensions of this message. See above.
688
- extensions 1000 to max;
689
- }
690
-
691
- message MethodOptions {
692
-
693
- // Note: Field numbers 1 through 32 are reserved for Google's internal RPC
694
- // framework. We apologize for hoarding these numbers to ourselves, but
695
- // we were already using them long before we decided to release Protocol
696
- // Buffers.
697
-
698
- // Is this method deprecated?
699
- // Depending on the target platform, this can emit Deprecated annotations
700
- // for the method, or it will be completely ignored; in the very least,
701
- // this is a formalization for deprecating methods.
702
- optional bool deprecated = 33 [default = false];
703
-
704
- // Is this method side-effect-free (or safe in HTTP parlance), or idempotent,
705
- // or neither? HTTP based RPC implementation may choose GET verb for safe
706
- // methods, and PUT verb for idempotent methods instead of the default POST.
707
- enum IdempotencyLevel {
708
- IDEMPOTENCY_UNKNOWN = 0;
709
- NO_SIDE_EFFECTS = 1; // implies idempotent
710
- IDEMPOTENT = 2; // idempotent, but may have side effects
711
- }
712
- optional IdempotencyLevel idempotency_level = 34
713
- [default = IDEMPOTENCY_UNKNOWN];
714
-
715
- // The parser stores options it doesn't recognize here. See above.
716
- repeated UninterpretedOption uninterpreted_option = 999;
717
-
718
- // Clients can define custom options in extensions of this message. See above.
719
- extensions 1000 to max;
720
- }
721
-
722
-
723
- // A message representing a option the parser does not recognize. This only
724
- // appears in options protos created by the compiler::Parser class.
725
- // DescriptorPool resolves these when building Descriptor objects. Therefore,
726
- // options protos in descriptor objects (e.g. returned by Descriptor::options(),
727
- // or produced by Descriptor::CopyTo()) will never have UninterpretedOptions
728
- // in them.
729
- message UninterpretedOption {
730
- // The name of the uninterpreted option. Each string represents a segment in
731
- // a dot-separated name. is_extension is true iff a segment represents an
732
- // extension (denoted with parentheses in options specs in .proto files).
733
- // E.g.,{ ["foo", false], ["bar.baz", true], ["qux", false] } represents
734
- // "foo.(bar.baz).qux".
735
- message NamePart {
736
- required string name_part = 1;
737
- required bool is_extension = 2;
738
- }
739
- repeated NamePart name = 2;
740
-
741
- // The value of the uninterpreted option, in whatever type the tokenizer
742
- // identified it as during parsing. Exactly one of these should be set.
743
- optional string identifier_value = 3;
744
- optional uint64 positive_int_value = 4;
745
- optional int64 negative_int_value = 5;
746
- optional double double_value = 6;
747
- optional bytes string_value = 7;
748
- optional string aggregate_value = 8;
749
- }
750
-
751
- // ===================================================================
752
- // Optional source code info
753
-
754
- // Encapsulates information about the original source file from which a
755
- // FileDescriptorProto was generated.
756
- message SourceCodeInfo {
757
- // A Location identifies a piece of source code in a .proto file which
758
- // corresponds to a particular definition. This information is intended
759
- // to be useful to IDEs, code indexers, documentation generators, and similar
760
- // tools.
761
- //
762
- // For example, say we have a file like:
763
- // message Foo {
764
- // optional string foo = 1;
765
- // }
766
- // Let's look at just the field definition:
767
- // optional string foo = 1;
768
- // ^ ^^ ^^ ^ ^^^
769
- // a bc de f ghi
770
- // We have the following locations:
771
- // span path represents
772
- // [a,i) [ 4, 0, 2, 0 ] The whole field definition.
773
- // [a,b) [ 4, 0, 2, 0, 4 ] The label (optional).
774
- // [c,d) [ 4, 0, 2, 0, 5 ] The type (string).
775
- // [e,f) [ 4, 0, 2, 0, 1 ] The name (foo).
776
- // [g,h) [ 4, 0, 2, 0, 3 ] The number (1).
777
- //
778
- // Notes:
779
- // - A location may refer to a repeated field itself (i.e. not to any
780
- // particular index within it). This is used whenever a set of elements are
781
- // logically enclosed in a single code segment. For example, an entire
782
- // extend block (possibly containing multiple extension definitions) will
783
- // have an outer location whose path refers to the "extensions" repeated
784
- // field without an index.
785
- // - Multiple locations may have the same path. This happens when a single
786
- // logical declaration is spread out across multiple places. The most
787
- // obvious example is the "extend" block again -- there may be multiple
788
- // extend blocks in the same scope, each of which will have the same path.
789
- // - A location's span is not always a subset of its parent's span. For
790
- // example, the "extendee" of an extension declaration appears at the
791
- // beginning of the "extend" block and is shared by all extensions within
792
- // the block.
793
- // - Just because a location's span is a subset of some other location's span
794
- // does not mean that it is a descendant. For example, a "group" defines
795
- // both a type and a field in a single declaration. Thus, the locations
796
- // corresponding to the type and field and their components will overlap.
797
- // - Code which tries to interpret locations should probably be designed to
798
- // ignore those that it doesn't understand, as more types of locations could
799
- // be recorded in the future.
800
- repeated Location location = 1;
801
- message Location {
802
- // Identifies which part of the FileDescriptorProto was defined at this
803
- // location.
804
- //
805
- // Each element is a field number or an index. They form a path from
806
- // the root FileDescriptorProto to the place where the definition. For
807
- // example, this path:
808
- // [ 4, 3, 2, 7, 1 ]
809
- // refers to:
810
- // file.message_type(3) // 4, 3
811
- // .field(7) // 2, 7
812
- // .name() // 1
813
- // This is because FileDescriptorProto.message_type has field number 4:
814
- // repeated DescriptorProto message_type = 4;
815
- // and DescriptorProto.field has field number 2:
816
- // repeated FieldDescriptorProto field = 2;
817
- // and FieldDescriptorProto.name has field number 1:
818
- // optional string name = 1;
819
- //
820
- // Thus, the above path gives the location of a field name. If we removed
821
- // the last element:
822
- // [ 4, 3, 2, 7 ]
823
- // this path refers to the whole field declaration (from the beginning
824
- // of the label to the terminating semicolon).
825
- repeated int32 path = 1 [packed = true];
826
-
827
- // Always has exactly three or four elements: start line, start column,
828
- // end line (optional, otherwise assumed same as start line), end column.
829
- // These are packed into a single field for efficiency. Note that line
830
- // and column numbers are zero-based -- typically you will want to add
831
- // 1 to each before displaying to a user.
832
- repeated int32 span = 2 [packed = true];
833
-
834
- // If this SourceCodeInfo represents a complete declaration, these are any
835
- // comments appearing before and after the declaration which appear to be
836
- // attached to the declaration.
837
- //
838
- // A series of line comments appearing on consecutive lines, with no other
839
- // tokens appearing on those lines, will be treated as a single comment.
840
- //
841
- // leading_detached_comments will keep paragraphs of comments that appear
842
- // before (but not connected to) the current element. Each paragraph,
843
- // separated by empty lines, will be one comment element in the repeated
844
- // field.
845
- //
846
- // Only the comment content is provided; comment markers (e.g. //) are
847
- // stripped out. For block comments, leading whitespace and an asterisk
848
- // will be stripped from the beginning of each line other than the first.
849
- // Newlines are included in the output.
850
- //
851
- // Examples:
852
- //
853
- // optional int32 foo = 1; // Comment attached to foo.
854
- // // Comment attached to bar.
855
- // optional int32 bar = 2;
856
- //
857
- // optional string baz = 3;
858
- // // Comment attached to baz.
859
- // // Another line attached to baz.
860
- //
861
- // // Comment attached to qux.
862
- // //
863
- // // Another line attached to qux.
864
- // optional double qux = 4;
865
- //
866
- // // Detached comment for corge. This is not leading or trailing comments
867
- // // to qux or corge because there are blank lines separating it from
868
- // // both.
869
- //
870
- // // Detached comment for corge paragraph 2.
871
- //
872
- // optional string corge = 5;
873
- // /* Block comment attached
874
- // * to corge. Leading asterisks
875
- // * will be removed. */
876
- // /* Block comment attached to
877
- // * grault. */
878
- // optional int32 grault = 6;
879
- //
880
- // // ignored detached comments.
881
- optional string leading_comments = 3;
882
- optional string trailing_comments = 4;
883
- repeated string leading_detached_comments = 6;
884
- }
885
- }
886
-
887
- // Describes the relationship between generated code and its original source
888
- // file. A GeneratedCodeInfo message is associated with only one generated
889
- // source file, but may contain references to different source .proto files.
890
- message GeneratedCodeInfo {
891
- // An Annotation connects some span of text in generated code to an element
892
- // of its generating .proto file.
893
- repeated Annotation annotation = 1;
894
- message Annotation {
895
- // Identifies the element in the original source .proto file. This field
896
- // is formatted the same as SourceCodeInfo.Location.path.
897
- repeated int32 path = 1 [packed = true];
898
-
899
- // Identifies the filesystem path to the original source .proto.
900
- optional string source_file = 2;
901
-
902
- // Identifies the starting offset in bytes in the generated code
903
- // that relates to the identified object.
904
- optional int32 begin = 3;
905
-
906
- // Identifies the ending offset in bytes in the generated code that
907
- // relates to the identified offset. The end offset should be one past
908
- // the last relevant byte (so the length of the text = end - begin).
909
- optional int32 end = 4;
910
- }
911
- }