譯者說
Tornado 4.3于2015年11月6日發(fā)布，該版本正式支持Python3.5的async/await關(guān)鍵字天梧，并且用舊版本CPython編譯Tornado同樣可以使用這兩個關(guān)鍵字深纲，這無疑是一種進步仲锄。其次，這是最后一個支持Python2.6和Python3.2的版本了湃鹊，在后續(xù)的版本了會移除對它們的兼容∪搴埃現(xiàn)在網(wǎng)絡(luò)上還沒有Tornado4.3的中文文檔，所以為了讓更多的朋友能接觸并學習到它币呵，我開始了這個翻譯項目怀愧，希望感興趣的小伙伴可以一起參與翻譯，項目地址是tornado-zh on Github，翻譯好的文檔在Read the Docs上直接可以看到芯义。歡迎Issues or PR哈垢。本節(jié)感謝@thisisx7翻譯
PS:本節(jié)最好直接在https://tornado-zh.readthedocs.org或者http://tornado.moelove.info/閱讀，以獲得更好的閱讀體驗(格式支持)扛拨。原諒我沒排好版QAQ
tornado.websocket — 瀏覽器與服務(wù)器雙向通信
WebSocket 協(xié)議的實現(xiàn)
WebSockets 允許瀏覽器和服務(wù)器之間進行 雙向通信
所有主流瀏覽器的現(xiàn)代版本都支持WebSockets(支持情況詳見：http://caniuse.com/websockets)
該模塊依照最新 WebSocket 協(xié)議 RFC 6455 實現(xiàn).
在 4.0 版更改: Removed support for the draft 76 protocol version.
class tornado.websocket.WebSocketHandler(application, request, **kwargs)
通過繼承該類來創(chuàng)建一個基本的 WebSocket handler.
重寫 on_message 來處理收到的消息, 使用 write_message 來發(fā)送消息到客戶端. 你也可以重寫 open 和 on_close 來處理連接打開和關(guān)閉這兩個動作.
有關(guān)JavaScript 接口的詳細信息： http://dev.w3.org/html5/websockets/ 具體的協(xié)議： http://tools.ietf.org/html/rfc6455
一個簡單的 WebSocket handler 的實例： 服務(wù)端直接返回所有收到的消息給客戶端
class EchoWebSocket(tornado.websocket.WebSocketHandler):
def open(self):
print("WebSocket opened")
def on_message(self, message):
self.write_message(u"You said: " + message)
def on_close(self):
print("WebSocket closed")
WebSockets 并不是標準的 HTTP 連接. “握手”動作符合 HTTP 標準,但是在”握手”動作之后, 協(xié)議是基于消息的. 因此,Tornado 里大多數(shù)的 HTTP 工具對于這類 handler 都是不可用的. 用來通訊的方法只有 write_message() , ping() , 和 close() . 同樣的,你的 request handler 類里應(yīng)該使用 open() 而不是 get() 或者 post()
如果你在應(yīng)用中將這個 handler 分配到 /websocket, 你可以通過如下代碼實現(xiàn):
var ws = new WebSocket("ws://localhost:8888/websocket");
ws.onopen = function() {
ws.send("Hello, world");
};
ws.onmessage = function (evt) {
alert(evt.data);
};
這個腳本將會彈出一個提示框 :”You said: Hello, world”
瀏覽器并沒有遵循同源策略(same-origin policy),相應(yīng)的允許了任意站點使用 javascript 發(fā)起任意 WebSocket 連接來支配其他網(wǎng)絡(luò).這令人驚訝,并且是一個潛在的安全漏洞,所以 從 Tornado 4.0 開始 WebSocketHandler 需要對希望接受跨域請求的應(yīng)用通過重寫.
check_origin (詳細信息請查看文檔中有關(guān)該方法的部分)來進行設(shè)置. 沒有正確配置這個屬性,在建立 WebSocket 連接時候很可能會導致 403 錯誤.
當使用安全的 websocket 連接(wss://) 時, 來自瀏覽器的連接可能會失敗,因為 websocket 沒有地方輸出 “認證成功” 的對話. 你在 websocket 連接建立成功之前,必須 使用相同的證書訪問一個常規(guī)的 HTML 頁面.
Event handlers
WebSocketHandler.open(*args, **kwargs)
當打開一個新的 WebSocket 時調(diào)用
open 的參數(shù)是從 tornado.web.URLSpec 通過正則表達式獲取的, 就像獲取 tornado.web.RequestHandler.get 的參數(shù)一樣
WebSocketHandler.on_message(message)
處理在 WebSocket 中收到的消息
這個方法必須被重寫
WebSocketHandler.on_close()
當關(guān)閉該 WebSocket 時調(diào)用
當連接被徹底關(guān)閉并且支持 status code 或 reason phtase 的時候, 可以通過 self.close_code 和 self.close_reason 這兩個屬性來獲取它們
在 4.0 版更改: Added close_code and close_reason attributes. 添加 close_code 和 close_reason 這兩個屬性
WebSocketHandler.select_subprotocol(subprotocols)
當一個新的 WebSocket 請求特定子協(xié)議(subprotocols)時調(diào)用
subprotocols 是一個由一系列能夠被客戶端正確識別出相應(yīng)的子協(xié)議 （subprotocols）的字符串構(gòu)成的 list . 這個方法可能會被重載,用來返回 list 中某 個匹配字符串, 沒有匹配到則返回 None. 如果沒有找到相應(yīng)的子協(xié)議,雖然服務(wù)端并 不會自動關(guān)閉 WebSocket 連接,但是客戶端可以選擇關(guān)閉連接.
Output
WebSocketHandler.write_message(message, binary=False)
將給出的 message 發(fā)送到客戶端
message 可以是 string 或者 dict（將會被編碼成 json ) 如果 binary 為 false, message 將會以 utf8 的編碼發(fā)送; 在 binary 模式下 message 可以是 任何 byte string.
如果連接已經(jīng)關(guān)閉, 則會觸發(fā) WebSocketClosedError
在 3.2 版更改: 添加了 WebSocketClosedError (在之前版本會觸發(fā) AttributeError)
在 4.3 版更改: 返回能夠被用于 flow control 的 Future.
WebSocketHandler.close(code=None, reason=None)
關(guān)閉當前 WebSocket
一旦揮手動作成功,socket將會被關(guān)閉.
code 可能是一個數(shù)字構(gòu)成的狀態(tài)碼, 采用 RFC 6455 section 7.4.1. 定義的值.
reason 可能是描述連接關(guān)閉的文本消息. 這個值被提給客戶端,但是不會被 WebSocket 協(xié)議單獨解釋.
在 4.0 版更改: Added the code and reason arguments.
Configuration
WebSocketHandler.check_origin(origin)
通過重寫這個方法來實現(xiàn)域的切換
參數(shù) origin 的值來自 HTTP header 中的Origin,url 負責初始化這個請求. 這個方法并不是要求客戶端不發(fā)送這樣的 heder;這樣的請求一直被允許（因為所有的瀏覽器 實現(xiàn)的 websockets 都支持這個 header ,并且非瀏覽器客戶端沒有同樣的跨域安全問題.
返回 True 代表接受,相應(yīng)的返回 False 代表拒絕.默認拒絕除 host 外其他域的請求.
這個是一個瀏覽器防止 XSS 攻擊的安全策略,因為 WebSocket 允許繞過通常的同源策略 以及不使用 CORS 頭.
要允許所有跨域通信的話（這在 Tornado 4.0 之前是默認的）,只要簡單的重寫這個方法 讓它一直返回 true 就可以了:
def check_origin(self, origin):
return True
要允許所有所有子域下的連接,可以這樣實現(xiàn):
def check_origin(self, origin):
parsed_origin = urllib.parse.urlparse(origin)
return parsed_origin.netloc.endswith(".mydomain.com")
4.0 新版功能.
WebSocketHandler.get_compression_options()
重寫該方法返回當前連接的 compression 選項
如果這個方法返回 None (默認), compression 將會被禁用. 如果它返回 dict (即使 是空的),compression 都會被開啟. dict 的內(nèi)容將會被用來控制 compression 所 使用的內(nèi)存和CPU.但是這類的設(shè)置現(xiàn)在還沒有被實現(xiàn).
4.1 新版功能.
WebSocketHandler.set_nodelay(value)
為當前 stream 設(shè)置 no-delay
在默認情況下, 小塊數(shù)據(jù)會被延遲和/或合并以減少發(fā)送包的數(shù)量. 這在有些時候會因為 Nagle’s 算法和 TCP ACKs 相互作用會造成 200-500ms 的延遲.在 WebSocket 連接 已經(jīng)建立的情況下,可以通過設(shè)置 self.set_nodelay(True) 來降低延遲（這可能 會占用更多帶寬）
更多詳細信息： BaseIOStream.set_nodelay.
在 BaseIOStream.set_nodelay 查看詳細信息.
3.1 新版功能.
Other
WebSocketHandler.ping(data)
發(fā)送 ping 包到遠端.
WebSocketHandler.on_pong(data)
當收到ping 包的響應(yīng)時執(zhí)行.
exception tornado.websocket.WebSocketClosedError
出現(xiàn)關(guān)閉連接錯誤觸發(fā).
3.2 新版功能.
Client-side support
tornado.websocket.websocket_connect(url, io_loop=None, callback=None, connect_timeout=None, on_message_callback=None, compression_options=None)
客戶端 WebSocket 支持 需要指定 url, 返回一個結(jié)果為 WebSocketClientConnection 的 Future 對象
compression_options 作為 WebSocketHandler.get_compression_options 的 返回值, 將會以同樣的方式執(zhí)行.
這個連接支持兩種類型的操作.在協(xié)程風格下,應(yīng)用程序通常在一個循環(huán)里調(diào)用～.WebSocket ClientConnection.read_message:
conn = yield websocket_connect(url)
while True:
msg = yield conn.read_message()
if msg is None: break
# Do something with msg
在回調(diào)風格下,需要傳遞 on_message_callback 到 websocket_connect 里. 在這兩種風格里,一個內(nèi)容是 None 的 message 都標志著 WebSocket 連接已經(jīng).
在 3.2 版更改: 允許使用 HTTPRequest 對象來代替 urls.
在 4.1 版更改: 添加 compression_options 和 on_message_callback .
不贊成使用 compression_options .
class tornado.websocket.WebSocketClientConnection(io_loop, request, on_message_callback=None, compression_options=None)
WebSocket 客戶端連接
這個類不應(yīng)當直接被實例化, 請使用 websocket_connect
close(code=None, reason=None)
關(guān)閉 websocket 連接
code 和 reason 的文檔在 WebSocketHandler.close 下已給出.
3.2 新版功能.
在 4.0 版更改: 添加 code 和 reason 這兩個參數(shù)
write_message(message, binary=False)
發(fā)送消息到 websocket 服務(wù)器.
read_message(callback=None)
讀取來自 WebSocket 服務(wù)器的消息.
如果在 WebSocket 初始化時指定了 on_message_callback ,那么這個方法永遠不會返回消息
如果連接已經(jīng)關(guān)閉,返回結(jié)果會是一個結(jié)果是 message 的 future 對象或者是 None. 如果 future 給出了回調(diào)參數(shù), 這個參數(shù)將會在 future 完成時調(diào)用.
可以通過下面二維碼訂閱我的文章公眾號【MoeLove】
