codekingpro/portable-devtools

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