WebKitTools/pywebsocket/mod_pywebsocket/__init__.py

   1 # Copyright 2009, 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 """Web Socket extension for Apache HTTP Server.
  32
  33 mod_pywebsocket is a Web Socket extension for Apache HTTP Server
  34 intended for testing or experimental purposes. mod_python is required.
  35
  36 Installation:
  37
  38 0. Prepare an Apache HTTP Server for which mod_python is enabled.
  39
  40 1. Specify the following Apache HTTP Server directives to suit your
  41    configuration.
  42
  43    If mod_pywebsocket is not in the Python path, specify the following.
  44    <websock_lib> is the directory where mod_pywebsocket is installed.
  45
  46        PythonPath "sys.path+['<websock_lib>']"
  47
  48    Always specify the following. <websock_handlers> is the directory where
  49    user-written Web Socket handlers are placed.
  50
  51        PythonOption mod_pywebsocket.handler_root <websock_handlers>
  52        PythonHeaderParserHandler mod_pywebsocket.headerparserhandler
  53
  54    To limit the search for Web Socket handlers to a directory <scan_dir>
  55    under <websock_handlers>, configure as follows:
  56
  57        PythonOption mod_pywebsocket.handler_scan <scan_dir>
  58
  59    <scan_dir> is useful in saving scan time when <websock_handlers>
  60    contains many non-Web Socket handler files.
  61
  62    Example snippet of httpd.conf:
  63    (mod_pywebsocket is in /websock_lib, Web Socket handlers are in
  64    /websock_handlers, port is 80 for ws, 443 for wss.)
  65
  66        <IfModule python_module>
  67          PythonPath "sys.path+['/websock_lib']"
  68          PythonOption mod_pywebsocket.handler_root /websock_handlers
  69          PythonHeaderParserHandler mod_pywebsocket.headerparserhandler
  70        </IfModule>
  71
  72 Writing Web Socket handlers:
  73
  74 When a Web Socket request comes in, the resource name
  75 specified in the handshake is considered as if it is a file path under
  76 <websock_handlers> and the handler defined in
  77 <websock_handlers>/<resource_name>_wsh.py is invoked.
  78
  79 For example, if the resource name is /example/chat, the handler defined in
  80 <websock_handlers>/example/chat_wsh.py is invoked.
  81
  82 A Web Socket handler is composed of the following two functions:
  83
  84     web_socket_do_extra_handshake(request)
  85     web_socket_transfer_data(request)
  86
  87 where:
  88     request: mod_python request.
  89
  90 web_socket_do_extra_handshake is called during the handshake after the
  91 headers are successfully parsed and Web Socket properties (ws_location,
  92 ws_origin, ws_protocol, and ws_resource) are added to request. A handler
  93 can reject the request by raising an exception.
  94
  95 web_socket_transfer_data is called after the handshake completed
  96 successfully. A handler can receive/send messages from/to the client
  97 using request. mod_pywebsocket.msgutil module provides utilities
  98 for data transfer.
  99 """
 100
 101
 102 # vi:sts=4 sw=4 et tw=72