Tornado 4.3文件翻譯: web框架-websocket瀏覽器與伺服器雙向通訊

TaoBeier發表於2016-03-28
Web框架瀏覽器伺服器

譯者說

Tornado 4.3於2015年11月6日釋出，該版本正式支援Python3.5的async/await關鍵字，並且用舊版本CPython編譯Tornado同樣可以使用這兩個關鍵字，這無疑是一種進步。其次，這是最後一個支援Python2.6和Python3.2的版本了，在後續的版本了會移除對它們的相容。現在網路上還沒有Tornado4.3的中文文件，所以為了讓更多的朋友能接觸並學習到它，我開始了這個翻譯專案，希望感興趣的小夥伴可以一起參與翻譯，專案地址是tornado-zh on Github，翻譯好的文件在Read the Docs上直接可以看到。歡迎Issues or PR。本節感謝@thisisx7翻譯

PS:本節最好直接在https://tornado-zh.readthedocs.org或者http://tornado.moelove.info/閱讀，以獲得更好的閱讀體驗(格式支援)。原諒我沒排好版QAQ

tornado.websocket — 瀏覽器與伺服器雙向通訊

WebSocket 協議的實現

WebSockets 允許瀏覽器和伺服器之間進行 雙向通訊

所有主流瀏覽器的現代版本都支援WebSockets(支援情況詳見：http://caniuse.com/websockets)

該模組依照最新 WebSocket 協議 RFC 6455 實現.

在 4.0 版更改: Removed support for the draft 76 protocol version.

class tornado.websocket.WebSocketHandler(application, request, **kwargs)

通過繼承該類來建立一個基本的 WebSocket handler.

重寫 on_message 來處理收到的訊息, 使用 write_message 來傳送訊息到客戶端. 你也可以重寫 open 和 on_close 來處理連線開啟和關閉這兩個動作.

有關JavaScript 介面的詳細資訊： http://dev.w3.org/html5/websockets/ 具體的協議： http://tools.ietf.org/html/rfc6455

一個簡單的 WebSocket handler 的例項： 服務端直接返回所有收到的訊息給客戶端

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 標準,但是在”握手”動作之後, 協議是基於訊息的. 因此,Tornado 裡大多數的 HTTP 工具對於這類 handler 都是不可用的. 用來通訊的方法只有 write_message() , ping() , 和 close() . 同樣的,你的 request handler 類裡應該使用 open() 而不是 get() 或者 post()

如果你在應用中將這個 handler 分配到 /websocket, 你可以通過如下程式碼實現:

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),相應的允許了任意站點使用 javascript 發起任意 WebSocket 連線來支配其他網路.這令人驚訝,並且是一個潛在的安全漏洞,所以 從 Tornado 4.0 開始 WebSocketHandler 需要對希望接受跨域請求的應用通過重寫.

check_origin (詳細資訊請檢視文件中有關該方法的部分)來進行設定. 沒有正確配置這個屬性,在建立 WebSocket 連線時候很可能會導致 403 錯誤.

當使用安全的 websocket 連線(wss://) 時, 來自瀏覽器的連線可能會失敗,因為 websocket 沒有地方輸出 “認證成功” 的對話. 你在 websocket 連線建立成功之前,必須 使用相同的證照訪問一個常規的 HTML 頁面.

Event handlers

WebSocketHandler.open(args, *kwargs)

當開啟一個新的 WebSocket 時呼叫

open 的引數是從 tornado.web.URLSpec 通過正規表示式獲取的, 就像獲取 tornado.web.RequestHandler.get 的引數一樣

WebSocketHandler.on_message(message)

處理在 WebSocket 中收到的訊息

這個方法必須被重寫

WebSocketHandler.on_close()

當關閉該 WebSocket 時呼叫

當連線被徹底關閉並且支援 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 請求特定子協議(subprotocols)時呼叫

subprotocols 是一個由一系列能夠被客戶端正確識別出相應的子協議 （subprotocols）的字串構成的 list . 這個方法可能會被過載,用來返回 list 中某 個匹配字串, 沒有匹配到則返回 None. 如果沒有找到相應的子協議,雖然服務端並 不會自動關閉 WebSocket 連線,但是客戶端可以選擇關閉連線.

Output

WebSocketHandler.write_message(message, binary=False)

將給出的 message 傳送到客戶端

message 可以是 string 或者 dict（將會被編碼成 json ) 如果 binary 為 false, message 將會以 utf8 的編碼傳送; 在 binary 模式下 message 可以是 任何 byte string.

如果連線已經關閉, 則會觸發 WebSocketClosedError

在 3.2 版更改: 新增了 WebSocketClosedError (在之前版本會觸發 AttributeError)

在 4.3 版更改: 返回能夠被用於 flow control 的 Future.

WebSocketHandler.close(code=None, reason=None)

關閉當前 WebSocket

一旦揮手動作成功,socket將會被關閉.

code 可能是一個數字構成的狀態碼, 採用 RFC 6455 section 7.4.1. 定義的值.

reason 可能是描述連線關閉的文字訊息. 這個值被提給客戶端,但是不會被 WebSocket 協議單獨解釋.

在 4.0 版更改: Added the code and reason arguments.

Configuration

WebSocketHandler.check_origin(origin)

通過重寫這個方法來實現域的切換

引數 origin 的值來自 HTTP header 中的Origin,url 負責初始化這個請求. 這個方法並不是要求客戶端不傳送這樣的 heder;這樣的請求一直被允許（因為所有的瀏覽器 實現的 websockets 都支援這個 header ,並且非瀏覽器客戶端沒有同樣的跨域安全問題.

返回 True 代表接受,相應的返回 False 代表拒絕.預設拒絕除 host 外其他域的請求.

這個是一個瀏覽器防止 XSS 攻擊的安全策略,因為 WebSocket 允許繞過通常的同源策略 以及不使用 CORS 頭.

要允許所有跨域通訊的話（這在 Tornado 4.0 之前是預設的）,只要簡單的重寫這個方法 讓它一直返回 true 就可以了:

def check_origin(self, origin):
    return True

要允許所有所有子域下的連線,可以這樣實現:

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 的內容將會被用來控制 compression 所 使用的記憶體和CPU.但是這類的設定現在還沒有被實現.

4.1 新版功能.

WebSocketHandler.set_nodelay(value)

為當前 stream 設定 no-delay

在預設情況下, 小塊資料會被延遲和/或合併以減少傳送包的數量. 這在有些時候會因為 Nagle’s 演算法和 TCP ACKs 相互作用會造成 200-500ms 的延遲.在 WebSocket 連線 已經建立的情況下,可以通過設定 self.set_nodelay(True) 來降低延遲（這可能 會佔用更多頻寬）

更多詳細資訊： BaseIOStream.set_nodelay.

在 BaseIOStream.set_nodelay 檢視詳細資訊.

3.1 新版功能.

Other

WebSocketHandler.ping(data)

傳送 ping 包到遠端.

WebSocketHandler.on_pong(data)

當收到ping 包的響應時執行.

exception tornado.websocket.WebSocketClosedError

出現關閉連線錯誤觸發.

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, 返回一個結果為 WebSocketClientConnection 的 Future 物件

compression_options 作為 WebSocketHandler.get_compression_options 的 返回值, 將會以同樣的方式執行.

這個連線支援兩種型別的操作.在協程風格下,應用程式通常在一個迴圈裡呼叫～.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

在回撥風格下,需要傳遞 on_message_callback 到 websocket_connect 裡. 在這兩種風格里,一個內容是 None 的 message 都標誌著 WebSocket 連線已經.

在 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 客戶端連線

這個類不應當直接被例項化, 請使用 websocket_connect

close(code=None, reason=None)

關閉 websocket 連線

code 和 reason 的文件在 WebSocketHandler.close 下已給出.

3.2 新版功能.

在 4.0 版更改: 新增 code 和 reason 這兩個引數

write_message(message, binary=False)

傳送訊息到 websocket 伺服器.

read_message(callback=None)

讀取來自 WebSocket 伺服器的訊息.

如果在 WebSocket 初始化時指定了 on_message_callback ,那麼這個方法永遠不會返回訊息

如果連線已經關閉,返回結果會是一個結果是 message 的 future 物件或者是 None. 如果 future 給出了回撥引數, 這個引數將會在 future 完成時呼叫.

相關文章