__init__.py (6145B)
1 # Copyright 2011, 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 """ A Standalone WebSocket Server for testing purposes 30 31 mod_pywebsocket is an API that provides WebSocket functionalities with 32 a standalone WebSocket server. It is intended for testing or 33 experimental purposes. 34 35 Installation 36 ============ 37 1. Follow standalone server documentation to start running the 38 standalone server. It can be read by running the following command: 39 40 $ pydoc mod_pywebsocket.standalone 41 42 2. Once the standalone server is launched verify it by accessing 43 http://localhost[:port]/console.html. Include the port number when 44 specified on launch. If everything is working correctly, you 45 will see a simple echo console. 46 47 48 Writing WebSocket handlers 49 ========================== 50 51 When a WebSocket request comes in, the resource name 52 specified in the handshake is considered as if it is a file path under 53 <websock_handlers> and the handler defined in 54 <websock_handlers>/<resource_name>_wsh.py is invoked. 55 56 For example, if the resource name is /example/chat, the handler defined in 57 <websock_handlers>/example/chat_wsh.py is invoked. 58 59 A WebSocket handler is composed of the following three functions: 60 61 web_socket_do_extra_handshake(request) 62 web_socket_transfer_data(request) 63 web_socket_passive_closing_handshake(request) 64 65 where: 66 request: mod_python request. 67 68 web_socket_do_extra_handshake is called during the handshake after the 69 headers are successfully parsed and WebSocket properties (ws_origin, 70 and ws_resource) are added to request. A handler 71 can reject the request by raising an exception. 72 73 A request object has the following properties that you can use during the 74 extra handshake (web_socket_do_extra_handshake): 75 - ws_resource 76 - ws_origin 77 - ws_version 78 - ws_extensions 79 - ws_deflate 80 - ws_protocol 81 - ws_requested_protocols 82 83 The last two are a bit tricky. See the next subsection. 84 85 86 Subprotocol Negotiation 87 ----------------------- 88 89 ws_protocol is always set to None when 90 web_socket_do_extra_handshake is called. If ws_requested_protocols is not 91 None, you must choose one subprotocol from this list and set it to 92 ws_protocol. 93 94 Data Transfer 95 ------------- 96 97 web_socket_transfer_data is called after the handshake completed 98 successfully. A handler can receive/send messages from/to the client 99 using request. mod_pywebsocket.msgutil module provides utilities 100 for data transfer. 101 102 You can receive a message by the following statement. 103 104 message = request.ws_stream.receive_message() 105 106 This call blocks until any complete text frame arrives, and the payload data 107 of the incoming frame will be stored into message. When you're using IETF 108 HyBi 00 or later protocol, receive_message() will return None on receiving 109 client-initiated closing handshake. When any error occurs, receive_message() 110 will raise some exception. 111 112 You can send a message by the following statement. 113 114 request.ws_stream.send_message(message) 115 116 117 Closing Connection 118 ------------------ 119 120 Executing the following statement or just return-ing from 121 web_socket_transfer_data cause connection close. 122 123 request.ws_stream.close_connection() 124 125 close_connection will wait 126 for closing handshake acknowledgement coming from the client. When it 127 couldn't receive a valid acknowledgement, raises an exception. 128 129 web_socket_passive_closing_handshake is called after the server receives 130 incoming closing frame from the client peer immediately. You can specify 131 code and reason by return values. They are sent as a outgoing closing frame 132 from the server. A request object has the following properties that you can 133 use in web_socket_passive_closing_handshake. 134 - ws_close_code 135 - ws_close_reason 136 137 138 Threading 139 --------- 140 141 A WebSocket handler must be thread-safe. The standalone 142 server uses threads by default. 143 144 145 Configuring WebSocket Extension Processors 146 ------------------------------------------ 147 148 See extensions.py for supported WebSocket extensions. Note that they are 149 unstable and their APIs are subject to change substantially. 150 151 A request object has these extension processing related attributes. 152 153 - ws_requested_extensions: 154 155 A list of common.ExtensionParameter instances representing extension 156 parameters received from the client in the client's opening handshake. 157 You shouldn't modify it manually. 158 159 - ws_extensions: 160 161 A list of common.ExtensionParameter instances representing extension 162 parameters to send back to the client in the server's opening handshake. 163 You shouldn't touch it directly. Instead, call methods on extension 164 processors. 165 166 - ws_extension_processors: 167 168 A list of loaded extension processors. Find the processor for the 169 extension you want to configure from it, and call its methods. 170 """ 171 172 # vi:sts=4 sw=4 et tw=72