1// Copyright 2016 gRPC authors.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15// Service exported by server reflection
16
17syntax = "proto3";
18
19package grpc.reflection.v1alpha;
20
21service ServerReflection {
22  // The reflection service is structured as a bidirectional stream, ensuring
23  // all related requests go to a single server.
24  rpc ServerReflectionInfo(stream ServerReflectionRequest)
25      returns (stream ServerReflectionResponse);
26}
27
28// The message sent by the client when calling ServerReflectionInfo method.
29message ServerReflectionRequest {
30  string host = 1;
31  // To use reflection service, the client should set one of the following
32  // fields in message_request. The server distinguishes requests by their
33  // defined field and then handles them using corresponding methods.
34  oneof message_request {
35    // Find a proto file by the file name.
36    string file_by_filename = 3;
37
38    // Find the proto file that declares the given fully-qualified symbol name.
39    // This field should be a fully-qualified symbol name
40    // (e.g. <package>.<service>[.<method>] or <package>.<type>).
41    string file_containing_symbol = 4;
42
43    // Find the proto file which defines an extension extending the given
44    // message type with the given field number.
45    ExtensionRequest file_containing_extension = 5;
46
47    // Finds the tag numbers used by all known extensions of the given message
48    // type, and appends them to ExtensionNumberResponse in an undefined order.
49    // Its corresponding method is best-effort: it's not guaranteed that the
50    // reflection service will implement this method, and it's not guaranteed
51    // that this method will provide all extensions. Returns
52    // StatusCode::UNIMPLEMENTED if it's not implemented.
53    // This field should be a fully-qualified type name. The format is
54    // <package>.<type>
55    string all_extension_numbers_of_type = 6;
56
57    // List the full names of registered services. The content will not be
58    // checked.
59    string list_services = 7;
60  }
61}
62
63// The type name and extension number sent by the client when requesting
64// file_containing_extension.
65message ExtensionRequest {
66  // Fully-qualified type name. The format should be <package>.<type>
67  string containing_type = 1;
68  int32 extension_number = 2;
69}
70
71// The message sent by the server to answer ServerReflectionInfo method.
72message ServerReflectionResponse {
73  string valid_host = 1;
74  ServerReflectionRequest original_request = 2;
75  // The server set one of the following fields accroding to the message_request
76  // in the request.
77  oneof message_response {
78    // This message is used to answer file_by_filename, file_containing_symbol,
79    // file_containing_extension requests with transitive dependencies. As
80    // the repeated label is not allowed in oneof fields, we use a
81    // FileDescriptorResponse message to encapsulate the repeated fields.
82    // The reflection service is allowed to avoid sending FileDescriptorProtos
83    // that were previously sent in response to earlier requests in the stream.
84    FileDescriptorResponse file_descriptor_response = 4;
85
86    // This message is used to answer all_extension_numbers_of_type requst.
87    ExtensionNumberResponse all_extension_numbers_response = 5;
88
89    // This message is used to answer list_services request.
90    ListServiceResponse list_services_response = 6;
91
92    // This message is used when an error occurs.
93    ErrorResponse error_response = 7;
94  }
95}
96
97// Serialized FileDescriptorProto messages sent by the server answering
98// a file_by_filename, file_containing_symbol, or file_containing_extension
99// request.
100message FileDescriptorResponse {
101  // Serialized FileDescriptorProto messages. We avoid taking a dependency on
102  // descriptor.proto, which uses proto2 only features, by making them opaque
103  // bytes instead.
104  repeated bytes file_descriptor_proto = 1;
105}
106
107// A list of extension numbers sent by the server answering
108// all_extension_numbers_of_type request.
109message ExtensionNumberResponse {
110  // Full name of the base type, including the package name. The format
111  // is <package>.<type>
112  string base_type_name = 1;
113  repeated int32 extension_number = 2;
114}
115
116// A list of ServiceResponse sent by the server answering list_services request.
117message ListServiceResponse {
118  // The information of each service may be expanded in the future, so we use
119  // ServiceResponse message to encapsulate it.
120  repeated ServiceResponse service = 1;
121}
122
123// The information of a single service used by ListServiceResponse to answer
124// list_services request.
125message ServiceResponse {
126  // Full name of a registered service, including its package name. The format
127  // is <package>.<service>
128  string name = 1;
129}
130
131// The error code and error message sent by the server when an error occurs.
132message ErrorResponse {
133  // This field uses the error codes defined in grpc::StatusCode.
134  int32 error_code = 1;
135  string error_message = 2;
136}
137