1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/testing/mochitest/pywebsocket/mod_pywebsocket/__init__.py Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,184 @@
1.4 +# Copyright 2011, Google Inc.
1.5 +# All rights reserved.
1.6 +#
1.7 +# Redistribution and use in source and binary forms, with or without
1.8 +# modification, are permitted provided that the following conditions are
1.9 +# met:
1.10 +#
1.11 +# * Redistributions of source code must retain the above copyright
1.12 +# notice, this list of conditions and the following disclaimer.
1.13 +# * Redistributions in binary form must reproduce the above
1.14 +# copyright notice, this list of conditions and the following disclaimer
1.15 +# in the documentation and/or other materials provided with the
1.16 +# distribution.
1.17 +# * Neither the name of Google Inc. nor the names of its
1.18 +# contributors may be used to endorse or promote products derived from
1.19 +# this software without specific prior written permission.
1.20 +#
1.21 +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1.22 +# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
1.23 +# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
1.24 +# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
1.25 +# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1.26 +# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
1.27 +# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
1.28 +# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
1.29 +# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
1.30 +# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
1.31 +# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.32 +
1.33 +
1.34 +"""WebSocket extension for Apache HTTP Server.
1.35 +
1.36 +mod_pywebsocket is a WebSocket extension for Apache HTTP Server
1.37 +intended for testing or experimental purposes. mod_python is required.
1.38 +
1.39 +
1.40 +Installation:
1.41 +
1.42 +0. Prepare an Apache HTTP Server for which mod_python is enabled.
1.43 +
1.44 +1. Specify the following Apache HTTP Server directives to suit your
1.45 + configuration.
1.46 +
1.47 + If mod_pywebsocket is not in the Python path, specify the following.
1.48 + <websock_lib> is the directory where mod_pywebsocket is installed.
1.49 +
1.50 + PythonPath "sys.path+['<websock_lib>']"
1.51 +
1.52 + Always specify the following. <websock_handlers> is the directory where
1.53 + user-written WebSocket handlers are placed.
1.54 +
1.55 + PythonOption mod_pywebsocket.handler_root <websock_handlers>
1.56 + PythonHeaderParserHandler mod_pywebsocket.headerparserhandler
1.57 +
1.58 + To limit the search for WebSocket handlers to a directory <scan_dir>
1.59 + under <websock_handlers>, configure as follows:
1.60 +
1.61 + PythonOption mod_pywebsocket.handler_scan <scan_dir>
1.62 +
1.63 + <scan_dir> is useful in saving scan time when <websock_handlers>
1.64 + contains many non-WebSocket handler files.
1.65 +
1.66 + If you want to support old handshake based on
1.67 + draft-hixie-thewebsocketprotocol-75:
1.68 +
1.69 + PythonOption mod_pywebsocket.allow_draft75 On
1.70 +
1.71 + If you want to allow handlers whose canonical path is not under the root
1.72 + directory (i.e. symbolic link is in root directory but its target is not),
1.73 + configure as follows:
1.74 +
1.75 + PythonOption mod_pywebsocket.allow_handlers_outside_root_dir On
1.76 +
1.77 + Example snippet of httpd.conf:
1.78 + (mod_pywebsocket is in /websock_lib, WebSocket handlers are in
1.79 + /websock_handlers, port is 80 for ws, 443 for wss.)
1.80 +
1.81 + <IfModule python_module>
1.82 + PythonPath "sys.path+['/websock_lib']"
1.83 + PythonOption mod_pywebsocket.handler_root /websock_handlers
1.84 + PythonHeaderParserHandler mod_pywebsocket.headerparserhandler
1.85 + </IfModule>
1.86 +
1.87 +2. Tune Apache parameters for serving WebSocket. We'd like to note that at
1.88 + least TimeOut directive from core features and RequestReadTimeout
1.89 + directive from mod_reqtimeout should be modified not to kill connections
1.90 + in only a few seconds of idle time.
1.91 +
1.92 +3. Verify installation. You can use example/console.html to poke the server.
1.93 +
1.94 +
1.95 +Writing WebSocket handlers:
1.96 +
1.97 +When a WebSocket request comes in, the resource name
1.98 +specified in the handshake is considered as if it is a file path under
1.99 +<websock_handlers> and the handler defined in
1.100 +<websock_handlers>/<resource_name>_wsh.py is invoked.
1.101 +
1.102 +For example, if the resource name is /example/chat, the handler defined in
1.103 +<websock_handlers>/example/chat_wsh.py is invoked.
1.104 +
1.105 +A WebSocket handler is composed of the following three functions:
1.106 +
1.107 + web_socket_do_extra_handshake(request)
1.108 + web_socket_transfer_data(request)
1.109 + web_socket_passive_closing_handshake(request)
1.110 +
1.111 +where:
1.112 + request: mod_python request.
1.113 +
1.114 +web_socket_do_extra_handshake is called during the handshake after the
1.115 +headers are successfully parsed and WebSocket properties (ws_location,
1.116 +ws_origin, and ws_resource) are added to request. A handler
1.117 +can reject the request by raising an exception.
1.118 +
1.119 +A request object has the following properties that you can use during the
1.120 +extra handshake (web_socket_do_extra_handshake):
1.121 +- ws_resource
1.122 +- ws_origin
1.123 +- ws_version
1.124 +- ws_location (Hixie 75 and HyBi 00 only)
1.125 +- ws_extensions (Hybi 06 and later)
1.126 +- ws_deflate (HyBi 06 and later)
1.127 +- ws_protocol
1.128 +- ws_requested_protocols (HyBi 06 and later)
1.129 +
1.130 +The last two are a bit tricky.
1.131 +
1.132 +For HyBi 06 and later, ws_protocol is always set to None when
1.133 +web_socket_do_extra_handshake is called. If ws_requested_protocols is not
1.134 +None, you must choose one subprotocol from this list and set it to
1.135 +ws_protocol.
1.136 +
1.137 +For Hixie 75 and HyBi 00, when web_socket_do_extra_handshake is called,
1.138 +ws_protocol is set to the value given by the client in
1.139 +Sec-WebSocket-Protocol (WebSocket-Protocol for Hixie 75) header or None if
1.140 +such header was not found in the opening handshake request. Finish extra
1.141 +handshake with ws_protocol untouched to accept the request subprotocol.
1.142 +Then, Sec-WebSocket-Protocol (or WebSocket-Protocol) header will be sent to
1.143 +the client in response with the same value as requested. Raise an exception
1.144 +in web_socket_do_extra_handshake to reject the requested subprotocol.
1.145 +
1.146 +web_socket_transfer_data is called after the handshake completed
1.147 +successfully. A handler can receive/send messages from/to the client
1.148 +using request. mod_pywebsocket.msgutil module provides utilities
1.149 +for data transfer.
1.150 +
1.151 +You can receive a message by the following statement.
1.152 +
1.153 + message = request.ws_stream.receive_message()
1.154 +
1.155 +This call blocks until any complete text frame arrives, and the payload data
1.156 +of the incoming frame will be stored into message. When you're using IETF
1.157 +HyBi 00 or later protocol, receive_message() will return None on receiving
1.158 +client-initiated closing handshake. When any error occurs, receive_message()
1.159 +will raise some exception.
1.160 +
1.161 +You can send a message by the following statement.
1.162 +
1.163 + request.ws_stream.send_message(message)
1.164 +
1.165 +Executing the following statement or just return-ing from
1.166 +web_socket_transfer_data cause connection close.
1.167 +
1.168 + request.ws_stream.close_connection()
1.169 +
1.170 +When you're using IETF HyBi 00 or later protocol, close_connection will wait
1.171 +for closing handshake acknowledgement coming from the client. When it
1.172 +couldn't receive a valid acknowledgement, raises an exception.
1.173 +
1.174 +web_socket_passive_closing_handshake is called after the server receives
1.175 +incoming closing frame from the client peer immediately. You can specify
1.176 +code and reason by return values. They are sent as a outgoing closing frame
1.177 +from the server. A request object has the following properties that you can
1.178 +use in web_socket_passive_closing_handshake.
1.179 +- ws_close_code
1.180 +- ws_close_reason
1.181 +
1.182 +A WebSocket handler must be thread-safe if the server (Apache or
1.183 +standalone.py) is configured to use threads.
1.184 +"""
1.185 +
1.186 +
1.187 +# vi:sts=4 sw=4 et tw=72
