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 extendee_type, and
48        // 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 sets one of the following fields according to the
76    // message_request 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.
80        // As 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 requests.
87        ExtensionNumberResponse all_extension_numbers_response = 5;
88
89        // This message is used to answer list_services requests.
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}