codecamp

Tornado 与浏览器的双向通信

WebSocket 协议的实现,WebSockets 允许浏览器和服务器之间的双向通信。

所有主流浏览器的当前版本都支持 WebSockets,尽管不支持 WebSockets 的旧版本仍在使用

该模块实现了 RFC 6455 中定义的 WebSocket 协议的最终版本。某些浏览器版本(尤其是 Safari 5.x)实现了该协议的早期草案(称为“draft 76”)并且与该模块不兼容。

在 4.0 版更改: 删除了对草案 76 协议版本的支持。

class tornado.websocket.WebSocketHandler(application: tornado.web.Application, request: tornado.httputil.HTTPServerRequest, **kwargs)

子类化此类以创建基本的 WebSocket 处理程序。

重写 ​on_message来处理传入的消息,并使用 ​write_message将消息发送到客户端。 您还可以覆盖 ​open和 ​on_close来处理打开和关闭的连接。

可以通过覆盖 ​set_default_headers或 ​prepare来发送自定义升级响应表头。

这是一个示例 WebSocket 处理程序,它将所有接收到的消息返回给客户端:

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 连接。WebSocket只是使用HTTP协议来完成一部分握手,但在握手之后,协议是基于消息的。 因此,大多数 Tornado HTTP 工具在这种类型的处理程序中不可用。 您可用的唯一通信方法是 ​write_message()​、​ping()​ 和 ​close()​。 同样,您的请求处理程序类应该实现 ​open()​ 方法而不是 ​get()​ 或 ​post()​。

如果您将上面的处理程序映射到应用程序中的 ​/websocket​,您可以在 JavaScript 中调用它:

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”。

Web 浏览器允许任何站点打开与任何其他站点的 websocket 连接,而不是使用同源策略来管理来自 JavaScript 的其他网络访问。 这可能令人惊讶并且是一个潜在的安全漏洞,因此由于 Tornado 4.0 ​WebSocketHandler要求希望接收跨域 websocket 的应用程序通过覆盖 ​check_origin方法来选择加入。 不这样做是建立 websocket 连接时最可能导致 403 错误的原因。

当使用带有自签名证书的安全 websocket 连接 (​wss://​) 时,来自浏览器的连接可能会失败,因为它想要显示“接受此证书”对话框但无处显示。 在 websocket 连接成功之前,您必须首先使用相同的证书访问常规 HTML 页面以接受它。

如果应用程序设置 ​websocket_ping_interval的值为非零值,则会定期发送 ping,如果在 ​websocket_ping_timeout之前没有收到响应,则连接将关闭。

大于 ​websocket_max_message_size应用程序设置(默认 10MiB)的消息将不被接受。

在 4.5 版更改:添加了 ​websocket_ping_interval、​websocket_ping_timeout和 ​websocket_max_message_size

事件处理程序

WebSocketHandler.open(*args, **kwargs) → Optional[Awaitable[None]]

打开新的 WebSocket 时调用。

open的参数是从​tornado.web.URLSpec正则表达式中提取的,就像tornado.web.RequestHandler.get的参数一样。

open可能是一个协程。 在 ​open返回之前不会调用 ​on_message​。

在 5.1 版更改: ​open可能是一个协程。

WebSocketHandler.on_message(message: Union[str, bytes]) → Optional[Awaitable[None]]

处理 WebSocket 上的传入消息

必须重写此方法。

在 4.5 版更改: ​on_message​可以是协程。

WebSocketHandler.on_close() → None

当 WebSocket 关闭时调用。

如果连接完全关闭并且提供了状态代码或原因短语,则这些值将作为属性用于 ​self.close_code​ 和 ​self.close_reason

在 4.0 版更改: 添加了 ​close_code和 ​close_reason属性。

WebSocketHandler.select_subprotocol(subprotocols: List[str]) → Optional[str]

重写以实现子协议协商。

subprotocols是标识客户端提出的子协议的字符串列表。 可以重写此方法以返回其中一个字符串以选择它,或者返回 ​None以不选择子协议。

未能选择子协议不会自动中止连接,尽管如果没有选择任何建议的子协议,客户端可能会关闭连接。

列表可能为空,在这种情况下,此方法必须返回 ​None​。 即使没有提出子协议,该方法也总是只调用一次,以便可以将这一事实告知处理程序。

在 5.1 版更改: 以前,如果客户端没有提出子协议,则使用包含空字符串而不是空列表的列表调用此方法。

WebSocketHandler.selected_subprotocol

select_subprotocol返回的子协议。

5.1 版中的新功能。

WebSocketHandler.on_ping(data: bytes) → None

在收到 ping 帧时调用。

输出

WebSocketHandler.write_message(message: Union[bytes, str, Dict[str, Any]], binary: bool = False) → Future[None]

将给定消息发送到此 Web Socket 的客户端。

消息可以是字符串或字典(将被编码为 json)。 如果 ​binary参数为 false,则消息将作为 utf8 发送; 在二进制模式下,任何字节串都是允许的。

如果连接已经关闭,则引发 ​WebSocketClosedError​。 返回可用于流量控制的 ​Future​。

在 3.2 版更改:添加了 ​WebSocketClosedError​(以前关闭的连接会引发 ​AttributeError​)

在 4.3 版更改: 返回可用于流量控制的 ​Future​。

在 5.0 版更改: 持续引发 ​WebSocketClosedError​。 以前有时会引发 ​StreamClosedError​。

WebSocketHandler.close(code: Optional[int] = None, reason: Optional[str] = None) → None

关闭此 Web Socket。

一旦关闭握手成功,套接字将被关闭。

code可以是数字状态代码,取自 RFC 6455 第 7.4.1 节中定义的值。​reason​可能是关于连接关闭原因的文本消息。 这些值可供客户端使用,但不会被 websocket 协议解释。

在 4.0 版更改: 添加了​code​和​reason​参数。

配置

WebSocketHandler.check_origin(origin: str) → bool

覆盖以启用对允许备用来源的支持。

origin参数是 ​OriginHTTP 表头的值,即负责发起此请求的 url。 不发送此表头的客户端不会调用此方法; 这样的请求总是被允许的(因为所有实现 WebSockets 的浏览器都支持这个表头,并且非浏览器客户端没有相同的跨站点安全问题)。

应该返回 ​True来接受请求或 ​False来拒绝它。 默认情况下,拒绝所有来自主机以外的主机的请求。

这是针对浏览器上的跨站点脚本攻击的安全保护,因为允许 WebSocket 绕过通常的同源策略并且不使用 CORS 表头。

注意:这是一项重要的安全措施;不要在不了解安全隐患的情况下禁用它。 特别是,如果您的身份验证是基于 cookie 的,您要么限制 ​check_origin() 允许的来源,要么为 websocket 连接实现类似 XSRF 的保护。

要接受所有跨域流量(这是 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")

WebSocketHandler.get_compression_options() → Optional[Dict[str, Any]]

覆盖以返回连接的压缩选项。

如果此方法返回 None(默认值),压缩将被禁用。 如果它返回一个 dict(甚至是一个空的),它将被启用。 dict 的内容可用于控制以下压缩选项:

compression_level指定压缩级别。

mem_level指定用于内部压缩状态的内存量。

WebSocketHandler.set_nodelay(value: bool) → None

为此流设置无延迟标志。

默认情况下,小消息可能会被延迟组合以最小化发送的数据包数量。 由于 Nagle 的算法和 TCP 延迟 ACK 之间的交互,这有时会导致 200-500 毫秒的延迟。 要减少此延迟(以可能增加带宽使用为代价),请在建立 websocket 连接后调用 ​self.set_nodelay(True)​。

其他

WebSocketHandler.ping(data: Union[str, bytes] = b'') → None

向远端发送 ping 帧。

data 参数允许作为 ping 消息的一部分发送少量数据(最多 125 个字节)。 请注意,并非所有 websocket 实现都会将此数据公开给应用程序。

考虑使用 ​websocket_ping_interval应用程序设置,而不是手动发送 ping。

在 5.1 版更改: data 参数现在是可选的。

WebSocketHandler.on_pong(data: bytes) → None

在收到对 ping 帧的响应时调用。

exception tornado.websocket.WebSocketClosedError

由关闭连接上的操作引发。

客户端支持

tornado.websocket.websocket_connect(url: Union[str, tornado.httpclient.HTTPRequest], callback: Optional[Callable[[Future[WebSocketClientConnection]], None]] = None, connect_timeout: Optional[float] = None, on_message_callback: Optional[Callable[[Union[None, str, bytes]], None]] = None, compression_options: Optional[Dict[str, Any]] = None, ping_interval: Optional[float] = None, ping_timeout: Optional[float] = None, max_message_size: int = 10485760, subprotocols: Optional[List[str]] = None) → Awaitable[WebSocketClientConnection]

接受一个 url 并返回一个 Future,其结果是一个 ​WebSocketClientConnection​。
compression_options ​的执行方式与 ​WebSocketHandler.get_compression_options​ 的返回值相同。
该连接支持两种操作方式。 在协程风格中,应用程序通常会在循环中调用 ​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 ​消息表示连接已关闭。

subprotocols可以是指定提议的子协议的字符串列表。 当连接完成时,可以在连接对象的 ​selected_subprotocol属性上找到所选协议。

在 3.2 版更改: 也接受 ​HTTPRequest对象代替 url。

在 4.1 版更改:添加了 ​compression_options和 ​on_message_callback

在 4.5 版更改:添加了 ​ping_interval、​ping_timeout和 ​max_message_size参数,它们与 ​WebSocketHandler中的含义相同。

在 5.0 版中更改: ​io_loop参数(自 4.1 版以来已弃用)已被删除。

在 5.1 版更改: 添加了 ​subprotocols参数。

class tornado.websocket.WebSocketClientConnection(request: tornado.httpclient.HTTPRequest, on_message_callback: Optional[Callable[[Union[None, str, bytes]], None]] = None, compression_options: Optional[Dict[str, Any]] = None, ping_interval: Optional[float] = None, ping_timeout: Optional[float] = None, max_message_size: int = 10485760, subprotocols: Optional[List[str]] = [])

WebSocket 客户端连接。

这个类不应该直接实例化; 请改用 ​websocket_connect ​函数。

close(code: Optional[int] = None, reason: Optional[str] = None) → None

关闭 websocket 连接。

code​和​reason​记录在 ​WebSocketHandler.close​ 下。

write_message(message: Union[str, bytes], binary: bool = False) → Future[None]

向 WebSocket 服务器发送消息。

如果流已关闭,则引发 ​WebSocketClosedError​。 返回可用于流量控制的 ​Future

在 5.0 版更改:在关闭的流上引发的异常从 ​StreamClosedError​更改为 ​WebSocketClosedError​。

read_message(callback: Optional[Callable[[Future[Union[None, str, bytes]]], None]] = None) → Awaitable[Union[None, str, bytes]]

从 WebSocket 服务器读取消息。
如果在 WebSocket 初始化时指定了 ​on_message_callback​,则此函数将永远不会返回消息
返回结果为​future​的消息,如果连接已关闭,则返回 ​None​。 如果给定了回调参数,它将在准备好时与​future​一起调用。

ping(data: bytes = b'') → None

向远端发送 ping 帧。

data参数允许作为 ping 消息的一部分发送少量数据(最多 125 个字节)。 请注意,并非所有 websocket 实现都会将此数据公开给应用程序。

考虑对 ​websocket_connect使用 ​ping_interval参数,而不是手动发送 ping。

selected_subprotocol

服务器选择的子协议

Tornado 国际化支持
Tornado 非阻塞HTTP服务器
温馨提示
下载编程狮App,免费阅读超1000+编程语言教程
取消
确定
目录

关闭

MIP.setData({ 'pageTheme' : getCookie('pageTheme') || {'day':true, 'night':false}, 'pageFontSize' : getCookie('pageFontSize') || 20 }); MIP.watch('pageTheme', function(newValue){ setCookie('pageTheme', JSON.stringify(newValue)) }); MIP.watch('pageFontSize', function(newValue){ setCookie('pageFontSize', newValue) }); function setCookie(name, value){ var days = 1; var exp = new Date(); exp.setTime(exp.getTime() + days*24*60*60*1000); document.cookie = name + '=' + value + ';expires=' + exp.toUTCString(); } function getCookie(name){ var reg = new RegExp('(^| )' + name + '=([^;]*)(;|$)'); return document.cookie.match(reg) ? JSON.parse(document.cookie.match(reg)[2]) : null; }