Debian Codegraph @

lang/py3/avro/ipc.py

raw
1 #!/usr/bin/env python3
2 # -*- mode: python -*-
3 # -*- coding: utf-8 -*-
4
5 # Licensed to the Apache Software Foundation (ASF) under one
6 # or more contributor license agreements. See the NOTICE file
7 # distributed with this work for additional information
8 # regarding copyright ownership. The ASF licenses this file
9 # to you under the Apache License, Version 2.0 (the
10 # "License"); you may not use this file except in compliance
11 # with the License. You may obtain a copy of the License at
12 #
13 # http://www.apache.org/licenses/LICENSE-2.0
14 #
15 # Unless required by applicable law or agreed to in writing, software
16 # distributed under the License is distributed on an "AS IS" BASIS,
17 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 # See the License for the specific language governing permissions and
19 # limitations under the License.
20
21 """RPC/IPC support."""
22
23 import abc
24 import http.client
25 import http.server
26 import io
27 import logging
28 import os
29 import socketserver
30
31 from avro import io as avro_io
32 from avro import protocol
33 from avro import schema
34
35 logger = logging.getLogger(__name__)
36
37 # ------------------------------------------------------------------------------
38 # Constants
39
40 def LoadResource(name):
41 dir_path = os.path.dirname(__file__)
42 rsrc_path = os.path.join(dir_path, name)
43 with open(rsrc_path, 'r') as f:
44 return f.read()
45
46
47 # Handshake schema is pulled in during build
48 HANDSHAKE_REQUEST_SCHEMA_JSON = LoadResource('HandshakeRequest.avsc')
49 HANDSHAKE_RESPONSE_SCHEMA_JSON = LoadResource('HandshakeResponse.avsc')
50
51 HANDSHAKE_REQUEST_SCHEMA = schema.Parse(HANDSHAKE_REQUEST_SCHEMA_JSON)
52 HANDSHAKE_RESPONSE_SCHEMA = schema.Parse(HANDSHAKE_RESPONSE_SCHEMA_JSON)
53
54 HANDSHAKE_REQUESTOR_WRITER = avro_io.DatumWriter(HANDSHAKE_REQUEST_SCHEMA)
55 HANDSHAKE_REQUESTOR_READER = avro_io.DatumReader(HANDSHAKE_RESPONSE_SCHEMA)
56 HANDSHAKE_RESPONDER_WRITER = avro_io.DatumWriter(HANDSHAKE_RESPONSE_SCHEMA)
57 HANDSHAKE_RESPONDER_READER = avro_io.DatumReader(HANDSHAKE_REQUEST_SCHEMA)
58
59 META_SCHEMA = schema.Parse('{"type": "map", "values": "bytes"}')
60 META_WRITER = avro_io.DatumWriter(META_SCHEMA)
61 META_READER = avro_io.DatumReader(META_SCHEMA)
62
63 SYSTEM_ERROR_SCHEMA = schema.Parse('["string"]')
64
65 AVRO_RPC_MIME = 'avro/binary'
66
67 # protocol cache
68
69 # Map: remote name -> remote MD5 hash
70 _REMOTE_HASHES = {}
71
72 # Decoder/encoder for a 32 bits big-endian integer.
73 UINT32_BE = avro_io.STRUCT_INT
74
75 # Default size of the buffers use to frame messages:
76 BUFFER_SIZE = 8192
77
78
79 # ------------------------------------------------------------------------------
80 # Exceptions
81
82
83 class AvroRemoteException(schema.AvroException):
84 """
85 Raised when an error message is sent by an Avro requestor or responder.
86 """
87 def __init__(self, fail_msg=None):
88 schema.AvroException.__init__(self, fail_msg)
89
90 class ConnectionClosedException(schema.AvroException):
91 pass
92
93
94 # ------------------------------------------------------------------------------
95 # Base IPC Classes (Requestor/Responder)
96
97
98 class BaseRequestor(object, metaclass=abc.ABCMeta):
99 """Base class for the client side of a protocol interaction."""
100
101 def __init__(self, local_protocol, transceiver):
102 """Initializes a new requestor object.
103
104 Args:
105 local_protocol: Avro Protocol describing the messages sent and received.
106 transceiver: Transceiver instance to channel messages through.
107 """
108 self._local_protocol = local_protocol
109 self._transceiver = transceiver
110 self._remote_protocol = None
111 self._remote_hash = None
112 self._send_protocol = None
113
114 @property
115 def local_protocol(self):
116 """Returns: the Avro Protocol describing the messages sent and received."""
117 return self._local_protocol
118
119 @property
120 def transceiver(self):
121 """Returns: the underlying channel used by this requestor."""
122 return self._transceiver
123
124 @abc.abstractmethod
125 def _IssueRequest(self, call_request, message_name, request_datum):
126 """TODO: Document this method.
127
128 Args:
129 call_request: ???
130 message_name: Name of the message.
131 request_datum: ???
132 Returns:
133 ???
134 """
135 raise Error('Abstract method')
136
137 def Request(self, message_name, request_datum):
138 """Writes a request message and reads a response or error message.
139
140 Args:
141 message_name: Name of the IPC method.
142 request_datum: IPC request.
143 Returns:
144 The IPC response.
145 """
146 # build handshake and call request
147 buffer_writer = io.BytesIO()
148 buffer_encoder = avro_io.BinaryEncoder(buffer_writer)
149 self._WriteHandshakeRequest(buffer_encoder)
150 self._WriteCallRequest(message_name, request_datum, buffer_encoder)
151
152 # send the handshake and call request; block until call response
153 call_request = buffer_writer.getvalue()
154 return self._IssueRequest(call_request, message_name, request_datum)
155
156 def _WriteHandshakeRequest(self, encoder):
157 """Emits the handshake request.
158
159 Args:
160 encoder: Encoder to write the handshake request into.
161 """
162 local_hash = self._local_protocol.md5
163
164 # if self._remote_hash is None:
165 # remote_name = self.transceiver.remote_name
166 # self._remote_hash = _REMOTE_HASHES.get(remote_name)
167
168 if self._remote_hash is None:
169 self._remote_hash = local_hash
170 self._remote_protocol = self._local_protocol
171
172 request_datum = {
173 'clientHash': local_hash,
174 'serverHash': self._remote_hash,
175 }
176 if self._send_protocol:
177 request_datum['clientProtocol'] = str(self._local_protocol)
178
179 logger.info('Sending handshake request: %s', request_datum)
180 HANDSHAKE_REQUESTOR_WRITER.write(request_datum, encoder)
181
182 def _WriteCallRequest(self, message_name, request_datum, encoder):
183 """
184 The format of a call request is:
185 * request metadata, a map with values of type bytes
186 * the message name, an Avro string, followed by
187 * the message parameters. Parameters are serialized according to
188 the message's request declaration.
189 """
190 # request metadata (not yet implemented)
191 request_metadata = {}
192 META_WRITER.write(request_metadata, encoder)
193
194 # Identify message to send:
195 message = self.local_protocol.message_map.get(message_name)
196 if message is None:
197 raise schema.AvroException('Unknown message: %s' % message_name)
198 encoder.write_utf8(message.name)
199
200 # message parameters
201 self._WriteRequest(message.request, request_datum, encoder)
202
203 def _WriteRequest(self, request_schema, request_datum, encoder):
204 logger.info('writing request: %s', request_datum)
205 datum_writer = avro_io.DatumWriter(request_schema)
206 datum_writer.write(request_datum, encoder)
207
208 def _ReadHandshakeResponse(self, decoder):
209 """Reads and processes the handshake response message.
210
211 Args:
212 decoder: Decoder to read messages from.
213 Returns:
214 call-response exists (boolean) ???
215 Raises:
216 schema.AvroException on ???
217 """
218 handshake_response = HANDSHAKE_REQUESTOR_READER.read(decoder)
219 logger.info('Processing handshake response: %s', handshake_response)
220 match = handshake_response['match']
221 if match == 'BOTH':
222 # Both client and server protocol hashes match:
223 self._send_protocol = False
224 return True
225
226 elif match == 'CLIENT':
227 # Client's side hash mismatch:
228 self._remote_protocol = \
229 protocol.Parse(handshake_response['serverProtocol'])
230 self._remote_hash = handshake_response['serverHash']
231 self._send_protocol = False
232 return True
233
234 elif match == 'NONE':
235 # Neither client nor server match:
236 self._remote_protocol = \
237 protocol.Parse(handshake_response['serverProtocol'])
238 self._remote_hash = handshake_response['serverHash']
239 self._send_protocol = True
240 return False
241 else:
242 raise schema.AvroException('handshake_response.match=%r' % match)
243
244 def _ReadCallResponse(self, message_name, decoder):
245 """Reads and processes a method call response.
246
247 The format of a call response is:
248 - response metadata, a map with values of type bytes
249 - a one-byte error flag boolean, followed by either:
250 - if the error flag is false,
251 the message response, serialized per the message's response schema.
252 - if the error flag is true,
253 the error, serialized per the message's error union schema.
254
255 Args:
256 message_name:
257 decoder:
258 Returns:
259 ???
260 Raises:
261 schema.AvroException on ???
262 """
263 # response metadata
264 response_metadata = META_READER.read(decoder)
265
266 # remote response schema
267 remote_message_schema = self._remote_protocol.message_map.get(message_name)
268 if remote_message_schema is None:
269 raise schema.AvroException('Unknown remote message: %s' % message_name)
270
271 # local response schema
272 local_message_schema = self._local_protocol.message_map.get(message_name)
273 if local_message_schema is None:
274 raise schema.AvroException('Unknown local message: %s' % message_name)
275
276 # error flag
277 if not decoder.read_boolean():
278 writer_schema = remote_message_schema.response
279 reader_schema = local_message_schema.response
280 return self._ReadResponse(writer_schema, reader_schema, decoder)
281 else:
282 writer_schema = remote_message_schema.errors
283 reader_schema = local_message_schema.errors
284 raise self._ReadError(writer_schema, reader_schema, decoder)
285
286 def _ReadResponse(self, writer_schema, reader_schema, decoder):
287 datum_reader = avro_io.DatumReader(writer_schema, reader_schema)
288 result = datum_reader.read(decoder)
289 return result
290
291 def _ReadError(self, writer_schema, reader_schema, decoder):
292 datum_reader = avro_io.DatumReader(writer_schema, reader_schema)
293 return AvroRemoteException(datum_reader.read(decoder))
294
295
296 class Requestor(BaseRequestor):
297 """Concrete requestor implementation."""
298
299 def _IssueRequest(self, call_request, message_name, request_datum):
300 call_response = self.transceiver.Transceive(call_request)
301
302 # process the handshake and call response
303 buffer_decoder = avro_io.BinaryDecoder(io.BytesIO(call_response))
304 call_response_exists = self._ReadHandshakeResponse(buffer_decoder)
305 if call_response_exists:
306 return self._ReadCallResponse(message_name, buffer_decoder)
307 else:
308 return self.Request(message_name, request_datum)
309
310
311 # ------------------------------------------------------------------------------
312
313
314 class Responder(object, metaclass=abc.ABCMeta):
315 """Base class for the server side of a protocol interaction."""
316
317 def __init__(self, local_protocol):
318 self._local_protocol = local_protocol
319 self._local_hash = self._local_protocol.md5
320 self._protocol_cache = {}
321
322 self.set_protocol_cache(self._local_hash, self._local_protocol)
323
324 @property
325 def local_protocol(self):
326 return self._local_protocol
327
328 # utility functions to manipulate protocol cache
329 def get_protocol_cache(self, hash):
330 return self._protocol_cache.get(hash)
331
332 def set_protocol_cache(self, hash, protocol):
333 self._protocol_cache[hash] = protocol
334
335 def Respond(self, call_request):
336 """Entry point to process one procedure call.
337
338 Args:
339 call_request: Serialized procedure call request.
340 Returns:
341 Serialized procedure call response.
342 Raises:
343 ???
344 """
345 buffer_reader = io.BytesIO(call_request)
346 buffer_decoder = avro_io.BinaryDecoder(buffer_reader)
347 buffer_writer = io.BytesIO()
348 buffer_encoder = avro_io.BinaryEncoder(buffer_writer)
349 error = None
350 response_metadata = {}
351
352 try:
353 remote_protocol = self._ProcessHandshake(buffer_decoder, buffer_encoder)
354 # handshake failure
355 if remote_protocol is None:
356 return buffer_writer.getvalue()
357
358 # read request using remote protocol
359 request_metadata = META_READER.read(buffer_decoder)
360 remote_message_name = buffer_decoder.read_utf8()
361
362 # get remote and local request schemas so we can do
363 # schema resolution (one fine day)
364 remote_message = remote_protocol.message_map.get(remote_message_name)
365 if remote_message is None:
366 fail_msg = 'Unknown remote message: %s' % remote_message_name
367 raise schema.AvroException(fail_msg)
368 local_message = self.local_protocol.message_map.get(remote_message_name)
369 if local_message is None:
370 fail_msg = 'Unknown local message: %s' % remote_message_name
371 raise schema.AvroException(fail_msg)
372 writer_schema = remote_message.request
373 reader_schema = local_message.request
374 request = self._ReadRequest(writer_schema, reader_schema, buffer_decoder)
375 logger.info('Processing request: %r', request)
376
377 # perform server logic
378 try:
379 response = self.Invoke(local_message, request)
380 except AvroRemoteException as exn:
381 error = exn
382 except Exception as exn:
383 error = AvroRemoteException(str(exn))
384
385 # write response using local protocol
386 META_WRITER.write(response_metadata, buffer_encoder)
387 buffer_encoder.write_boolean(error is not None)
388 if error is None:
389 writer_schema = local_message.response
390 self._WriteResponse(writer_schema, response, buffer_encoder)
391 else:
392 writer_schema = local_message.errors
393 self._WriteError(writer_schema, error, buffer_encoder)
394 except schema.AvroException as exn:
395 error = AvroRemoteException(str(exn))
396 buffer_encoder = avro_io.BinaryEncoder(io.StringIO())
397 META_WRITER.write(response_metadata, buffer_encoder)
398 buffer_encoder.write_boolean(True)
399 self._WriteError(SYSTEM_ERROR_SCHEMA, error, buffer_encoder)
400 return buffer_writer.getvalue()
401
402 def _ProcessHandshake(self, decoder, encoder):
403 """Processes an RPC handshake.
404
405 Args:
406 decoder: Where to read from.
407 encoder: Where to write to.
408 Returns:
409 The requested Protocol.
410 """
411 handshake_request = HANDSHAKE_RESPONDER_READER.read(decoder)
412 logger.info('Processing handshake request: %s', handshake_request)
413
414 # determine the remote protocol
415 client_hash = handshake_request.get('clientHash')
416 client_protocol = handshake_request.get('clientProtocol')
417 remote_protocol = self.get_protocol_cache(client_hash)
418 if remote_protocol is None and client_protocol is not None:
419 remote_protocol = protocol.Parse(client_protocol)
420 self.set_protocol_cache(client_hash, remote_protocol)
421
422 # evaluate remote's guess of the local protocol
423 server_hash = handshake_request.get('serverHash')
424
425 handshake_response = {}
426 if self._local_hash == server_hash:
427 if remote_protocol is None:
428 handshake_response['match'] = 'NONE'
429 else:
430 handshake_response['match'] = 'BOTH'
431 else:
432 if remote_protocol is None:
433 handshake_response['match'] = 'NONE'
434 else:
435 handshake_response['match'] = 'CLIENT'
436
437 if handshake_response['match'] != 'BOTH':
438 handshake_response['serverProtocol'] = str(self.local_protocol)
439 handshake_response['serverHash'] = self._local_hash
440
441 logger.info('Handshake response: %s', handshake_response)
442 HANDSHAKE_RESPONDER_WRITER.write(handshake_response, encoder)
443 return remote_protocol
444
445 @abc.abstractmethod
446 def Invoke(self, local_message, request):
447 """Processes one procedure call.
448
449 Args:
450 local_message: Avro message specification.
451 request: Call request.
452 Returns:
453 Call response.
454 Raises:
455 ???
456 """
457 raise Error('abtract method')
458
459 def _ReadRequest(self, writer_schema, reader_schema, decoder):
460 datum_reader = avro_io.DatumReader(writer_schema, reader_schema)
461 return datum_reader.read(decoder)
462
463 def _WriteResponse(self, writer_schema, response_datum, encoder):
464 datum_writer = avro_io.DatumWriter(writer_schema)
465 datum_writer.write(response_datum, encoder)
466
467 def _WriteError(self, writer_schema, error_exception, encoder):
468 datum_writer = avro_io.DatumWriter(writer_schema)
469 datum_writer.write(str(error_exception), encoder)
470
471
472 # ------------------------------------------------------------------------------
473 # Framed message
474
475
476 class FramedReader(object):
477 """Wrapper around a file-like object to read framed data."""
478
479 def __init__(self, reader):
480 self._reader = reader
481
482 def Read(self):
483 """Reads one message from the configured reader.
484
485 Returns:
486 The message, as bytes.
487 """
488 message = io.BytesIO()
489 # Read and append frames until we encounter a 0-size frame:
490 while self._ReadFrame(message) > 0: pass
491 return message.getvalue()
492
493 def _ReadFrame(self, message):
494 """Reads and appends one frame into the given message bytes.
495
496 Args:
497 message: Message to append the frame to.
498 Returns:
499 Size of the frame that was read.
500 The empty frame (size 0) indicates the end of a message.
501 """
502 frame_size = self._ReadInt32()
503 remaining = frame_size
504 while remaining > 0:
505 data_bytes = self._reader.read(remaining)
506 if len(data_bytes) == 0:
507 raise ConnectionClosedException(
508 'FramedReader: expecting %d more bytes in frame of size %d, got 0.'
509 % (remaining, frame_size))
510 message.write(data_bytes)
511 remaining -= len(data_bytes)
512 return frame_size
513
514 def _ReadInt32(self):
515 encoded = self._reader.read(UINT32_BE.size)
516 if len(encoded) != UINT32_BE.size:
517 raise ConnectionClosedException('Invalid header: %r' % encoded)
518 return UINT32_BE.unpack(encoded)[0]
519
520
521 class FramedWriter(object):
522 """Wrapper around a file-like object to write framed data."""
523
524 def __init__(self, writer):
525 self._writer = writer
526
527 def Write(self, message):
528 """Writes a message.
529
530 Message is chunked into sequences of frames terminated by an empty frame.
531
532 Args:
533 message: Message to write, as bytes.
534 """
535 while len(message) > 0:
536 chunk_size = max(BUFFER_SIZE, len(message))
537 chunk = message[:chunk_size]
538 self._WriteBuffer(chunk)
539 message = message[chunk_size:]
540
541 # A message is always terminated by a zero-length buffer.
542 self._WriteUnsignedInt32(0)
543
544 def _WriteBuffer(self, chunk):
545 self._WriteUnsignedInt32(len(chunk))
546 self._writer.write(chunk)
547
548 def _WriteUnsignedInt32(self, uint32):
549 self._writer.write(UINT32_BE.pack(uint32))
550
551
552 # ------------------------------------------------------------------------------
553 # Transceiver (send/receive channel)
554
555
556 class Transceiver(object, metaclass=abc.ABCMeta):
557 @abc.abstractproperty
558 def remote_name(self):
559 pass
560
561 @abc.abstractmethod
562 def ReadMessage(self):
563 """Reads a single message from the channel.
564
565 Blocks until a message can be read.
566
567 Returns:
568 The message read from the channel.
569 """
570 pass
571
572 @abc.abstractmethod
573 def WriteMessage(self, message):
574 """Writes a message into the channel.
575
576 Blocks until the message has been written.
577
578 Args:
579 message: Message to write.
580 """
581 pass
582
583 def Transceive(self, request):
584 """Processes a single request-reply interaction.
585
586 Synchronous request-reply interaction.
587
588 Args:
589 request: Request message.
590 Returns:
591 The reply message.
592 """
593 self.WriteMessage(request)
594 result = self.ReadMessage()
595 return result
596
597 def Close(self):
598 """Closes this transceiver."""
599 pass
600
601
602 class HTTPTransceiver(Transceiver):
603 """HTTP-based transceiver implementation."""
604
605 def __init__(self, host, port, req_resource='/'):
606 """Initializes a new HTTP transceiver.
607
608 Args:
609 host: Name or IP address of the remote host to interact with.
610 port: Port the remote server is listening on.
611 req_resource: Optional HTTP resource path to use, '/' by default.
612 """
613 self._req_resource = req_resource
614 self._conn = http.client.HTTPConnection(host, port)
615 self._conn.connect()
616 self._remote_name = self._conn.sock.getsockname()
617
618 @property
619 def remote_name(self):
620 return self._remote_name
621
622 def ReadMessage(self):
623 response = self._conn.getresponse()
624 response_reader = FramedReader(response)
625 framed_message = response_reader.Read()
626 response.read() # ensure we're ready for subsequent requests
627 return framed_message
628
629 def WriteMessage(self, message):
630 req_method = 'POST'
631 req_headers = {'Content-Type': AVRO_RPC_MIME}
632
633 bio = io.BytesIO()
634 req_body_buffer = FramedWriter(bio)
635 req_body_buffer.Write(message)
636 req_body = bio.getvalue()
637
638 self._conn.request(req_method, self._req_resource, req_body, req_headers)
639
640 def Close(self):
641 self._conn.close()
642 self._conn = None
643
644
645 # ------------------------------------------------------------------------------
646 # Server Implementations
647
648
649 def _MakeHandlerClass(responder):
650 class AvroHTTPRequestHandler(http.server.BaseHTTPRequestHandler):
651 def do_POST(self):
652 reader = FramedReader(self.rfile)
653 call_request = reader.Read()
654 logger.info('Serialized request: %r', call_request)
655 call_response = responder.Respond(call_request)
656 logger.info('Serialized response: %r', call_response)
657
658 self.send_response(200)
659 self.send_header('Content-type', AVRO_RPC_MIME)
660 self.end_headers()
661
662 framed_writer = FramedWriter(self.wfile)
663 framed_writer.Write(call_response)
664 self.wfile.flush()
665 logger.info('Response sent')
666
667 return AvroHTTPRequestHandler
668
669
670 class MultiThreadedHTTPServer(
671 socketserver.ThreadingMixIn,
672 http.server.HTTPServer,
673 ):
674 """Multi-threaded HTTP server."""
675 pass
676
677
678 class AvroIpcHttpServer(MultiThreadedHTTPServer):
679 """Avro IPC server implemented on top of an HTTP server."""
680
681 def __init__(self, interface, port, responder):
682 """Initializes a new Avro IPC server.
683
684 Args:
685 interface: Interface the server listens on, eg. 'localhost' or '0.0.0.0'.
686 port: TCP port the server listens on, eg. 8000.
687 responder: Responder implementation to handle RPCs.
688 """
689 super(AvroIpcHttpServer, self).__init__(
690 server_address=(interface, port),
691 RequestHandlerClass=_MakeHandlerClass(responder),
692 )
693
694
695 if __name__ == '__main__':
696 raise Exception('Not a standalone module')