1# Copyright 2015 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"""Constants and interfaces of the Beta API of gRPC Python.""" 15 16import abc 17 18import six 19 20import grpc 21 22ChannelConnectivity = grpc.ChannelConnectivity 23# FATAL_FAILURE was a Beta-API name for SHUTDOWN 24ChannelConnectivity.FATAL_FAILURE = ChannelConnectivity.SHUTDOWN 25 26StatusCode = grpc.StatusCode 27 28 29class GRPCCallOptions(object): 30 """A value encapsulating gRPC-specific options passed on RPC invocation. 31 32 This class and its instances have no supported interface - it exists to 33 define the type of its instances and its instances exist to be passed to 34 other functions. 35 """ 36 37 def __init__(self, disable_compression, subcall_of, credentials): 38 self.disable_compression = disable_compression 39 self.subcall_of = subcall_of 40 self.credentials = credentials 41 42 43def grpc_call_options(disable_compression=False, credentials=None): 44 """Creates a GRPCCallOptions value to be passed at RPC invocation. 45 46 All parameters are optional and should always be passed by keyword. 47 48 Args: 49 disable_compression: A boolean indicating whether or not compression should 50 be disabled for the request object of the RPC. Only valid for 51 request-unary RPCs. 52 credentials: A CallCredentials object to use for the invoked RPC. 53 """ 54 return GRPCCallOptions(disable_compression, None, credentials) 55 56 57GRPCAuthMetadataContext = grpc.AuthMetadataContext 58GRPCAuthMetadataPluginCallback = grpc.AuthMetadataPluginCallback 59GRPCAuthMetadataPlugin = grpc.AuthMetadataPlugin 60 61 62class GRPCServicerContext(six.with_metaclass(abc.ABCMeta)): 63 """Exposes gRPC-specific options and behaviors to code servicing RPCs.""" 64 65 @abc.abstractmethod 66 def peer(self): 67 """Identifies the peer that invoked the RPC being serviced. 68 69 Returns: 70 A string identifying the peer that invoked the RPC being serviced. 71 """ 72 raise NotImplementedError() 73 74 @abc.abstractmethod 75 def disable_next_response_compression(self): 76 """Disables compression of the next response passed by the application.""" 77 raise NotImplementedError() 78 79 80class GRPCInvocationContext(six.with_metaclass(abc.ABCMeta)): 81 """Exposes gRPC-specific options and behaviors to code invoking RPCs.""" 82 83 @abc.abstractmethod 84 def disable_next_request_compression(self): 85 """Disables compression of the next request passed by the application.""" 86 raise NotImplementedError() 87 88 89class Server(six.with_metaclass(abc.ABCMeta)): 90 """Services RPCs.""" 91 92 @abc.abstractmethod 93 def add_insecure_port(self, address): 94 """Reserves a port for insecure RPC service once this Server becomes active. 95 96 This method may only be called before calling this Server's start method is 97 called. 98 99 Args: 100 address: The address for which to open a port. 101 102 Returns: 103 An integer port on which RPCs will be serviced after this link has been 104 started. This is typically the same number as the port number contained 105 in the passed address, but will likely be different if the port number 106 contained in the passed address was zero. 107 """ 108 raise NotImplementedError() 109 110 @abc.abstractmethod 111 def add_secure_port(self, address, server_credentials): 112 """Reserves a port for secure RPC service after this Server becomes active. 113 114 This method may only be called before calling this Server's start method is 115 called. 116 117 Args: 118 address: The address for which to open a port. 119 server_credentials: A ServerCredentials. 120 121 Returns: 122 An integer port on which RPCs will be serviced after this link has been 123 started. This is typically the same number as the port number contained 124 in the passed address, but will likely be different if the port number 125 contained in the passed address was zero. 126 """ 127 raise NotImplementedError() 128 129 @abc.abstractmethod 130 def start(self): 131 """Starts this Server's service of RPCs. 132 133 This method may only be called while the server is not serving RPCs (i.e. it 134 is not idempotent). 135 """ 136 raise NotImplementedError() 137 138 @abc.abstractmethod 139 def stop(self, grace): 140 """Stops this Server's service of RPCs. 141 142 All calls to this method immediately stop service of new RPCs. When existing 143 RPCs are aborted is controlled by the grace period parameter passed to this 144 method. 145 146 This method may be called at any time and is idempotent. Passing a smaller 147 grace value than has been passed in a previous call will have the effect of 148 stopping the Server sooner. Passing a larger grace value than has been 149 passed in a previous call will not have the effect of stopping the server 150 later. 151 152 Args: 153 grace: A duration of time in seconds to allow existing RPCs to complete 154 before being aborted by this Server's stopping. May be zero for 155 immediate abortion of all in-progress RPCs. 156 157 Returns: 158 A threading.Event that will be set when this Server has completely 159 stopped. The returned event may not be set until after the full grace 160 period (if some ongoing RPC continues for the full length of the period) 161 of it may be set much sooner (such as if this Server had no RPCs underway 162 at the time it was stopped or if all RPCs that it had underway completed 163 very early in the grace period). 164 """ 165 raise NotImplementedError() 166