1 # Copyright 2012, Google Inc. 2 # All rights reserved. 3 # 4 # Redistribution and use in source and binary forms, with or without 5 # modification, are permitted provided that the following conditions are 6 # met: 7 # 8 # * Redistributions of source code must retain the above copyright 9 # notice, this list of conditions and the following disclaimer. 10 # * Redistributions in binary form must reproduce the above 11 # copyright notice, this list of conditions and the following disclaimer 12 # in the documentation and/or other materials provided with the 13 # distribution. 14 # * Neither the name of Google Inc. nor the names of its 15 # contributors may be used to endorse or promote products derived from 16 # this software without specific prior written permission. 17 # 18 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 30 31 """Dispatch WebSocket request. 32 """ 33 34 35 import logging 36 import os 37 import re 38 39 from mod_pywebsocket import common 40 from mod_pywebsocket import handshake 41 from mod_pywebsocket import msgutil 42 from mod_pywebsocket import mux 43 from mod_pywebsocket import stream 44 from mod_pywebsocket import util 45 46 47 _SOURCE_PATH_PATTERN = re.compile(r'(?i)_wsh\.py$') 48 _SOURCE_SUFFIX = '_wsh.py' 49 _DO_EXTRA_HANDSHAKE_HANDLER_NAME = 'web_socket_do_extra_handshake' 50 _TRANSFER_DATA_HANDLER_NAME = 'web_socket_transfer_data' 51 _PASSIVE_CLOSING_HANDSHAKE_HANDLER_NAME = ( 52 'web_socket_passive_closing_handshake') 53 54 55 class DispatchException(Exception): 56 """Exception in dispatching WebSocket request.""" 57 58 def __init__(self, name, status=common.HTTP_STATUS_NOT_FOUND): 59 super(DispatchException, self).__init__(name) 60 self.status = status 61 62 63 def _default_passive_closing_handshake_handler(request): 64 """Default web_socket_passive_closing_handshake handler.""" 65 66 return common.STATUS_NORMAL_CLOSURE, '' 67 68 69 def _normalize_path(path): 70 """Normalize path. 71 72 Args: 73 path: the path to normalize. 74 75 Path is converted to the absolute path. 76 The input path can use either '\\' or '/' as the separator. 77 The normalized path always uses '/' regardless of the platform. 78 """ 79 80 path = path.replace('\\', os.path.sep) 81 path = os.path.realpath(path) 82 path = path.replace('\\', '/') 83 return path 84 85 86 def _create_path_to_resource_converter(base_dir): 87 """Returns a function that converts the path of a WebSocket handler source 88 file to a resource string by removing the path to the base directory from 89 its head, removing _SOURCE_SUFFIX from its tail, and replacing path 90 separators in it with '/'. 91 92 Args: 93 base_dir: the path to the base directory. 94 """ 95 96 base_dir = _normalize_path(base_dir) 97 98 base_len = len(base_dir) 99 suffix_len = len(_SOURCE_SUFFIX) 100 101 def converter(path): 102 if not path.endswith(_SOURCE_SUFFIX): 103 return None 104 # _normalize_path must not be used because resolving symlink breaks 105 # following path check. 106 path = path.replace('\\', '/') 107 if not path.startswith(base_dir): 108 return None 109 return path[base_len:-suffix_len] 110 111 return converter 112 113 114 def _enumerate_handler_file_paths(directory): 115 """Returns a generator that enumerates WebSocket Handler source file names 116 in the given directory. 117 """ 118 119 for root, unused_dirs, files in os.walk(directory): 120 for base in files: 121 path = os.path.join(root, base) 122 if _SOURCE_PATH_PATTERN.search(path): 123 yield path 124 125 126 class _HandlerSuite(object): 127 """A handler suite holder class.""" 128 129 def __init__(self, do_extra_handshake, transfer_data, 130 passive_closing_handshake): 131 self.do_extra_handshake = do_extra_handshake 132 self.transfer_data = transfer_data 133 self.passive_closing_handshake = passive_closing_handshake 134 135 136 def _source_handler_file(handler_definition): 137 """Source a handler definition string. 138 139 Args: 140 handler_definition: a string containing Python statements that define 141 handler functions. 142 """ 143 144 global_dic = {} 145 try: 146 exec handler_definition in global_dic 147 except Exception: 148 raise DispatchException('Error in sourcing handler:' + 149 util.get_stack_trace()) 150 passive_closing_handshake_handler = None 151 try: 152 passive_closing_handshake_handler = _extract_handler( 153 global_dic, _PASSIVE_CLOSING_HANDSHAKE_HANDLER_NAME) 154 except Exception: 155 passive_closing_handshake_handler = ( 156 _default_passive_closing_handshake_handler) 157 return _HandlerSuite( 158 _extract_handler(global_dic, _DO_EXTRA_HANDSHAKE_HANDLER_NAME), 159 _extract_handler(global_dic, _TRANSFER_DATA_HANDLER_NAME), 160 passive_closing_handshake_handler) 161 162 163 def _extract_handler(dic, name): 164 """Extracts a callable with the specified name from the given dictionary 165 dic. 166 """ 167 168 if name not in dic: 169 raise DispatchException('%s is not defined.' % name) 170 handler = dic[name] 171 if not callable(handler): 172 raise DispatchException('%s is not callable.' % name) 173 return handler 174 175 176 class Dispatcher(object): 177 """Dispatches WebSocket requests. 178 179 This class maintains a map from resource name to handlers. 180 """ 181 182 def __init__( 183 self, root_dir, scan_dir=None, 184 allow_handlers_outside_root_dir=True): 185 """Construct an instance. 186 187 Args: 188 root_dir: The directory where handler definition files are 189 placed. 190 scan_dir: The directory where handler definition files are 191 searched. scan_dir must be a directory under root_dir, 192 including root_dir itself. If scan_dir is None, 193 root_dir is used as scan_dir. scan_dir can be useful 194 in saving scan time when root_dir contains many 195 subdirectories. 196 allow_handlers_outside_root_dir: Scans handler files even if their 197 canonical path is not under root_dir. 198 """ 199 200 self._logger = util.get_class_logger(self) 201 202 self._handler_suite_map = {} 203 self._source_warnings = [] 204 if scan_dir is None: 205 scan_dir = root_dir 206 if not os.path.realpath(scan_dir).startswith( 207 os.path.realpath(root_dir)): 208 raise DispatchException('scan_dir:%s must be a directory under ' 209 'root_dir:%s.' % (scan_dir, root_dir)) 210 self._source_handler_files_in_dir( 211 root_dir, scan_dir, allow_handlers_outside_root_dir) 212 213 def add_resource_path_alias(self, 214 alias_resource_path, existing_resource_path): 215 """Add resource path alias. 216 217 Once added, request to alias_resource_path would be handled by 218 handler registered for existing_resource_path. 219 220 Args: 221 alias_resource_path: alias resource path 222 existing_resource_path: existing resource path 223 """ 224 try: 225 handler_suite = self._handler_suite_map[existing_resource_path] 226 self._handler_suite_map[alias_resource_path] = handler_suite 227 except KeyError: 228 raise DispatchException('No handler for: %r' % 229 existing_resource_path) 230 231 def source_warnings(self): 232 """Return warnings in sourcing handlers.""" 233 234 return self._source_warnings 235 236 def do_extra_handshake(self, request): 237 """Do extra checking in WebSocket handshake. 238 239 Select a handler based on request.uri and call its 240 web_socket_do_extra_handshake function. 241 242 Args: 243 request: mod_python request. 244 245 Raises: 246 DispatchException: when handler was not found 247 AbortedByUserException: when user handler abort connection 248 HandshakeException: when opening handshake failed 249 """ 250 251 handler_suite = self.get_handler_suite(request.ws_resource) 252 if handler_suite is None: 253 raise DispatchException('No handler for: %r' % request.ws_resource) 254 do_extra_handshake_ = handler_suite.do_extra_handshake 255 try: 256 do_extra_handshake_(request) 257 except handshake.AbortedByUserException, e: 258 raise 259 except Exception, e: 260 util.prepend_message_to_exception( 261 '%s raised exception for %s: ' % ( 262 _DO_EXTRA_HANDSHAKE_HANDLER_NAME, 263 request.ws_resource), 264 e) 265 raise handshake.HandshakeException(e, common.HTTP_STATUS_FORBIDDEN) 266 267 def transfer_data(self, request): 268 """Let a handler transfer_data with a WebSocket client. 269 270 Select a handler based on request.ws_resource and call its 271 web_socket_transfer_data function. 272 273 Args: 274 request: mod_python request. 275 276 Raises: 277 DispatchException: when handler was not found 278 AbortedByUserException: when user handler abort connection 279 """ 280 281 # TODO(tyoshino): Terminate underlying TCP connection if possible. 282 try: 283 if mux.use_mux(request): 284 mux.start(request, self) 285 else: 286 handler_suite = self.get_handler_suite(request.ws_resource) 287 if handler_suite is None: 288 raise DispatchException('No handler for: %r' % 289 request.ws_resource) 290 transfer_data_ = handler_suite.transfer_data 291 transfer_data_(request) 292 293 if not request.server_terminated: 294 request.ws_stream.close_connection() 295 # Catch non-critical exceptions the handler didn't handle. 296 except handshake.AbortedByUserException, e: 297 self._logger.debug('%s', e) 298 raise 299 except msgutil.BadOperationException, e: 300 self._logger.debug('%s', e) 301 request.ws_stream.close_connection(common.STATUS_ABNORMAL_CLOSURE) 302 except msgutil.InvalidFrameException, e: 303 # InvalidFrameException must be caught before 304 # ConnectionTerminatedException that catches InvalidFrameException. 305 self._logger.debug('%s', e) 306 request.ws_stream.close_connection(common.STATUS_PROTOCOL_ERROR) 307 except msgutil.UnsupportedFrameException, e: 308 self._logger.debug('%s', e) 309 request.ws_stream.close_connection(common.STATUS_UNSUPPORTED_DATA) 310 except stream.InvalidUTF8Exception, e: 311 self._logger.debug('%s', e) 312 request.ws_stream.close_connection( 313 common.STATUS_INVALID_FRAME_PAYLOAD_DATA) 314 except msgutil.ConnectionTerminatedException, e: 315 self._logger.debug('%s', e) 316 except Exception, e: 317 util.prepend_message_to_exception( 318 '%s raised exception for %s: ' % ( 319 _TRANSFER_DATA_HANDLER_NAME, request.ws_resource), 320 e) 321 raise 322 323 def passive_closing_handshake(self, request): 324 """Prepare code and reason for responding client initiated closing 325 handshake. 326 """ 327 328 handler_suite = self.get_handler_suite(request.ws_resource) 329 if handler_suite is None: 330 return _default_passive_closing_handshake_handler(request) 331 return handler_suite.passive_closing_handshake(request) 332 333 def get_handler_suite(self, resource): 334 """Retrieves two handlers (one for extra handshake processing, and one 335 for data transfer) for the given request as a HandlerSuite object. 336 """ 337 338 fragment = None 339 if '#' in resource: 340 resource, fragment = resource.split('#', 1) 341 if '?' in resource: 342 resource = resource.split('?', 1)[0] 343 handler_suite = self._handler_suite_map.get(resource) 344 if handler_suite and fragment: 345 raise DispatchException('Fragment identifiers MUST NOT be used on ' 346 'WebSocket URIs', 347 common.HTTP_STATUS_BAD_REQUEST) 348 return handler_suite 349 350 def _source_handler_files_in_dir( 351 self, root_dir, scan_dir, allow_handlers_outside_root_dir): 352 """Source all the handler source files in the scan_dir directory. 353 354 The resource path is determined relative to root_dir. 355 """ 356 357 # We build a map from resource to handler code assuming that there's 358 # only one path from root_dir to scan_dir and it can be obtained by 359 # comparing realpath of them. 360 361 # Here we cannot use abspath. See 362 # https://bugs.webkit.org/show_bug.cgi?id=31603 363 364 convert = _create_path_to_resource_converter(root_dir) 365 scan_realpath = os.path.realpath(scan_dir) 366 root_realpath = os.path.realpath(root_dir) 367 for path in _enumerate_handler_file_paths(scan_realpath): 368 if (not allow_handlers_outside_root_dir and 369 (not os.path.realpath(path).startswith(root_realpath))): 370 self._logger.debug( 371 'Canonical path of %s is not under root directory' % 372 path) 373 continue 374 try: 375 handler_suite = _source_handler_file(open(path).read()) 376 except DispatchException, e: 377 self._source_warnings.append('%s: %s' % (path, e)) 378 continue 379 resource = convert(path) 380 if resource is None: 381 self._logger.debug( 382 'Path to resource conversion on %s failed' % path) 383 else: 384 self._handler_suite_map[convert(path)] = handler_suite 385 386 387 # vi:sts=4 sw=4 et 388
