# Copyright 2012, Google Inc. # All rights reserved. # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of Google Inc. nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. """Dispatch WebSocket request. """ import logging import os import re from mod_pywebsocket import common from mod_pywebsocket import handshake from mod_pywebsocket import msgutil from mod_pywebsocket import mux from mod_pywebsocket import stream from mod_pywebsocket import util _SOURCE_PATH_PATTERN = re.compile(r'(?i)_wsh\.py$') _SOURCE_SUFFIX = '_wsh.py' _DO_EXTRA_HANDSHAKE_HANDLER_NAME = 'web_socket_do_extra_handshake' _TRANSFER_DATA_HANDLER_NAME = 'web_socket_transfer_data' _PASSIVE_CLOSING_HANDSHAKE_HANDLER_NAME = ( 'web_socket_passive_closing_handshake') class DispatchException(Exception): """Exception in dispatching WebSocket request.""" def __init__(self, name, status=common.HTTP_STATUS_NOT_FOUND): super(DispatchException, self).__init__(name) self.status = status def _default_passive_closing_handshake_handler(request): """Default web_socket_passive_closing_handshake handler.""" return common.STATUS_NORMAL_CLOSURE, '' def _normalize_path(path): """Normalize path. Args: path: the path to normalize. Path is converted to the absolute path. The input path can use either '\\' or '/' as the separator. The normalized path always uses '/' regardless of the platform. """ path = path.replace('\\', os.path.sep) path = os.path.realpath(path) path = path.replace('\\', '/') return path def _create_path_to_resource_converter(base_dir): """Returns a function that converts the path of a WebSocket handler source file to a resource string by removing the path to the base directory from its head, removing _SOURCE_SUFFIX from its tail, and replacing path separators in it with '/'. Args: base_dir: the path to the base directory. """ base_dir = _normalize_path(base_dir) base_len = len(base_dir) suffix_len = len(_SOURCE_SUFFIX) def converter(path): if not path.endswith(_SOURCE_SUFFIX): return None # _normalize_path must not be used because resolving symlink breaks # following path check. path = path.replace('\\', '/') if not path.startswith(base_dir): return None return path[base_len:-suffix_len] return converter def _enumerate_handler_file_paths(directory): """Returns a generator that enumerates WebSocket Handler source file names in the given directory. """ for root, unused_dirs, files in os.walk(directory): for base in files: path = os.path.join(root, base) if _SOURCE_PATH_PATTERN.search(path): yield path class _HandlerSuite(object): """A handler suite holder class.""" def __init__(self, do_extra_handshake, transfer_data, passive_closing_handshake): self.do_extra_handshake = do_extra_handshake self.transfer_data = transfer_data self.passive_closing_handshake = passive_closing_handshake def _source_handler_file(handler_definition): """Source a handler definition string. Args: handler_definition: a string containing Python statements that define handler functions. """ global_dic = {} try: exec handler_definition in global_dic except Exception: raise DispatchException('Error in sourcing handler:' + util.get_stack_trace()) passive_closing_handshake_handler = None try: passive_closing_handshake_handler = _extract_handler( global_dic, _PASSIVE_CLOSING_HANDSHAKE_HANDLER_NAME) except Exception: passive_closing_handshake_handler = ( _default_passive_closing_handshake_handler) return _HandlerSuite( _extract_handler(global_dic, _DO_EXTRA_HANDSHAKE_HANDLER_NAME), _extract_handler(global_dic, _TRANSFER_DATA_HANDLER_NAME), passive_closing_handshake_handler) def _extract_handler(dic, name): """Extracts a callable with the specified name from the given dictionary dic. """ if name not in dic: raise DispatchException('%s is not defined.' % name) handler = dic[name] if not callable(handler): raise DispatchException('%s is not callable.' % name) return handler class Dispatcher(object): """Dispatches WebSocket requests. This class maintains a map from resource name to handlers. """ def __init__( self, root_dir, scan_dir=None, allow_handlers_outside_root_dir=True): """Construct an instance. Args: root_dir: The directory where handler definition files are placed. scan_dir: The directory where handler definition files are searched. scan_dir must be a directory under root_dir, including root_dir itself. If scan_dir is None, root_dir is used as scan_dir. scan_dir can be useful in saving scan time when root_dir contains many subdirectories. allow_handlers_outside_root_dir: Scans handler files even if their canonical path is not under root_dir. """ self._logger = util.get_class_logger(self) self._handler_suite_map = {} self._source_warnings = [] if scan_dir is None: scan_dir = root_dir if not os.path.realpath(scan_dir).startswith( os.path.realpath(root_dir)): raise DispatchException('scan_dir:%s must be a directory under ' 'root_dir:%s.' % (scan_dir, root_dir)) self._source_handler_files_in_dir( root_dir, scan_dir, allow_handlers_outside_root_dir) def add_resource_path_alias(self, alias_resource_path, existing_resource_path): """Add resource path alias. Once added, request to alias_resource_path would be handled by handler registered for existing_resource_path. Args: alias_resource_path: alias resource path existing_resource_path: existing resource path """ try: handler_suite = self._handler_suite_map[existing_resource_path] self._handler_suite_map[alias_resource_path] = handler_suite except KeyError: raise DispatchException('No handler for: %r' % existing_resource_path) def source_warnings(self): """Return warnings in sourcing handlers.""" return self._source_warnings def do_extra_handshake(self, request): """Do extra checking in WebSocket handshake. Select a handler based on request.uri and call its web_socket_do_extra_handshake function. Args: request: mod_python request. Raises: DispatchException: when handler was not found AbortedByUserException: when user handler abort connection HandshakeException: when opening handshake failed """ handler_suite = self.get_handler_suite(request.ws_resource) if handler_suite is None: raise DispatchException('No handler for: %r' % request.ws_resource) do_extra_handshake_ = handler_suite.do_extra_handshake try: do_extra_handshake_(request) except handshake.AbortedByUserException, e: # Re-raise to tell the caller of this function to finish this # connection without sending any error. self._logger.debug('%s', util.get_stack_trace()) raise except Exception, e: util.prepend_message_to_exception( '%s raised exception for %s: ' % ( _DO_EXTRA_HANDSHAKE_HANDLER_NAME, request.ws_resource), e) raise handshake.HandshakeException(e, common.HTTP_STATUS_FORBIDDEN) def transfer_data(self, request): """Let a handler transfer_data with a WebSocket client. Select a handler based on request.ws_resource and call its web_socket_transfer_data function. Args: request: mod_python request. Raises: DispatchException: when handler was not found AbortedByUserException: when user handler abort connection """ # TODO(tyoshino): Terminate underlying TCP connection if possible. try: if mux.use_mux(request): mux.start(request, self) else: handler_suite = self.get_handler_suite(request.ws_resource) if handler_suite is None: raise DispatchException('No handler for: %r' % request.ws_resource) transfer_data_ = handler_suite.transfer_data transfer_data_(request) if not request.server_terminated: request.ws_stream.close_connection() # Catch non-critical exceptions the handler didn't handle. except handshake.AbortedByUserException, e: self._logger.debug('%s', util.get_stack_trace()) raise except msgutil.BadOperationException, e: self._logger.debug('%s', e) request.ws_stream.close_connection( common.STATUS_INTERNAL_ENDPOINT_ERROR) except msgutil.InvalidFrameException, e: # InvalidFrameException must be caught before # ConnectionTerminatedException that catches InvalidFrameException. self._logger.debug('%s', e) request.ws_stream.close_connection(common.STATUS_PROTOCOL_ERROR) except msgutil.UnsupportedFrameException, e: self._logger.debug('%s', e) request.ws_stream.close_connection(common.STATUS_UNSUPPORTED_DATA) except stream.InvalidUTF8Exception, e: self._logger.debug('%s', e) request.ws_stream.close_connection( common.STATUS_INVALID_FRAME_PAYLOAD_DATA) except msgutil.ConnectionTerminatedException, e: self._logger.debug('%s', e) except Exception, e: # Any other exceptions are forwarded to the caller of this # function. util.prepend_message_to_exception( '%s raised exception for %s: ' % ( _TRANSFER_DATA_HANDLER_NAME, request.ws_resource), e) raise def passive_closing_handshake(self, request): """Prepare code and reason for responding client initiated closing handshake. """ handler_suite = self.get_handler_suite(request.ws_resource) if handler_suite is None: return _default_passive_closing_handshake_handler(request) return handler_suite.passive_closing_handshake(request) def get_handler_suite(self, resource): """Retrieves two handlers (one for extra handshake processing, and one for data transfer) for the given request as a HandlerSuite object. """ fragment = None if '#' in resource: resource, fragment = resource.split('#', 1) if '?' in resource: resource = resource.split('?', 1)[0] handler_suite = self._handler_suite_map.get(resource) if handler_suite and fragment: raise DispatchException('Fragment identifiers MUST NOT be used on ' 'WebSocket URIs', common.HTTP_STATUS_BAD_REQUEST) return handler_suite def _source_handler_files_in_dir( self, root_dir, scan_dir, allow_handlers_outside_root_dir): """Source all the handler source files in the scan_dir directory. The resource path is determined relative to root_dir. """ # We build a map from resource to handler code assuming that there's # only one path from root_dir to scan_dir and it can be obtained by # comparing realpath of them. # Here we cannot use abspath. See # https://bugs.webkit.org/show_bug.cgi?id=31603 convert = _create_path_to_resource_converter(root_dir) scan_realpath = os.path.realpath(scan_dir) root_realpath = os.path.realpath(root_dir) for path in _enumerate_handler_file_paths(scan_realpath): if (not allow_handlers_outside_root_dir and (not os.path.realpath(path).startswith(root_realpath))): self._logger.debug( 'Canonical path of %s is not under root directory' % path) continue try: handler_suite = _source_handler_file(open(path).read()) except DispatchException, e: self._source_warnings.append('%s: %s' % (path, e)) continue resource = convert(path) if resource is None: self._logger.debug( 'Path to resource conversion on %s failed' % path) else: self._handler_suite_map[convert(path)] = handler_suite # vi:sts=4 sw=4 et