RabbitMQ Web STOMP 插件

概述

Web STOMP 插件使得通过 WebSocket 连接使用 STOMP 协议成为可能。

该插件的目标是在 Web 应用中启用 STOMP 消息传递。

类似的插件 Web MQTT 插件，使得通过 WebSocket 使用 MQTT 成为可能。

工作原理

RabbitMQ Web STOMP 插件是 RabbitMQ STOMP 插件提供的 STOMP 协议实现与 WebSocket 客户端之间极简的“桥梁”。

RabbitMQ Web STOMP 完全兼容 RabbitMQ STOMP 插件。

启用插件

rabbitmq_web_stomp 插件随 RabbitMQ 一起发布。

要启用该插件，请运行 rabbitmq-plugins

rabbitmq-plugins enable rabbitmq_web_stomp

用法

为了在 Web 浏览器环境中使用 STOMP，需要一个 JavaScript STOMP 库。我们测试过由 Jeff Mesnil 和 Jeff Lindsay 开发的 stomp-websocket 库。此库作为 RabbitMQ Web STOMP 示例的一部分包含在内。

WebSocket 端点可在 /ws 路径下访问

ws://127.0.0.1:15674/ws

此端点仅适用于支持 Websocket 的客户端。请注意，为了接受二进制消息，需要进行一些配置。

为了从浏览器使用 WebSocket 建立连接，您可以使用如下代码

<!-- include the client library -->
<script src="stomp.js"></script>

<script>
var ws = new WebSocket('ws://127.0.0.1:15674/ws');
var client = Stomp.over(ws);
// ...

一旦拥有 client 对象，您就可以遵循 stomp.js 库公开的 API。下一步通常是与代理建立 STOMP 连接

// ...
var on_connect = function() {
    console.log('connected');
};
var on_error =  function() {
    console.log('error');
};
client.connect('guest', 'guest', on_connect, on_error, '/');
// ...

Web STOMP 示例

一些简单的 Web STOMP 示例作为 RabbitMQ Web STOMP 示例插件提供。要运行它们，请遵循该插件的安装说明并启用该插件

rabbitmq-plugins enable rabbitmq_web_stomp_examples

这些示例可在 http://127.0.0.1:15670/ 地址访问。您将看到两个示例

• “echo” - 展示如何使用 STOMP 进行简单的消息广播
• “bunny” - 一个简单的协作画布绘画应用示例

我们鼓励您查看源代码。

配置

当未指定配置时，Web STOMP 插件将在端口 15674 的所有接口上监听，并拥有默认的登录名/密码 guest/guest。请注意，默认情况下，此用户仅允许从本地主机连接。我们强烈建议为生产系统创建一个单独的用户。

要更改监听端口，请编辑您的高级配置文件，使其包含一个带有 port 变量的 tcp_config 部分，用于 rabbitmq_web_stomp 应用程序。

例如，一个将监听端口更改为 12345 的完整配置文件如下所示

web_stomp.tcp.port = 12345

您可以使用 tcp_config 部分指定所需的任何 TCP 选项。有关接受参数的详细信息，请参阅 RabbitMQ 网络指南 和 Ranch 文档。

TLS (WSS)

该插件支持 TLS (WSS) 连接的 WebSocket。请参阅 TLS 指南以了解更多关于 RabbitMQ 中 TLS 支持的信息。

TLS 配置参数在 web_stomp.ssl 部分中提供

web_stomp.ssl.port       = 15673
web_stomp.ssl.backlog    = 1024
web_stomp.ssl.cacertfile = /path/to/ca_certificate.pem
web_stomp.ssl.certfile   = /path/to/server_certificate.pem
web_stomp.ssl.keyfile    = /path/to/server_key.pem
web_stomp.ssl.password   = changeme

TLS 监听端口、服务器证书文件、私钥和 CA 证书包是强制选项。如果私钥使用密码，则密码也是强制性的。扩展的 TLS 设置列表与核心服务器的 TLS 设置基本一致。此插件接受的完整选项列表可在 Ranch 文档中找到。

启用的 TLS 版本和密码套件

可以配置 RabbitMQ 使用哪些 TLS 版本和密码套件。请注意，并非所有系统都提供所有套件。

RabbitMQ TLS 指南包含关于 TLS 版本的章节以及关于密码套件的章节。以下是高级配置格式中的一个示例，该示例为插件配置了密码套件以及许多其他 TLS 选项

web_stomp.ssl.port       = 15673
web_stomp.ssl.backlog    = 1024
web_stomp.ssl.certfile   = /path/to/server_certificate.pem
web_stomp.ssl.keyfile    = /path/to/server_key.pem
web_stomp.ssl.cacertfile = /path/to/ca_certificate_bundle.pem
web_stomp.ssl.password   = changeme

web_stomp.ssl.honor_cipher_order   = true
web_stomp.ssl.honor_ecc_order      = true
web_stomp.ssl.client_renegotiation = false
web_stomp.ssl.secure_renegotiate   = true

web_stomp.ssl.versions.1 = tlsv1.2
web_stomp.ssl.versions.2 = tlsv1.1
web_stomp.ssl.ciphers.1 = ECDHE-ECDSA-AES256-GCM-SHA384
web_stomp.ssl.ciphers.2 = ECDHE-RSA-AES256-GCM-SHA384
web_stomp.ssl.ciphers.3 = ECDHE-ECDSA-AES256-SHA384
web_stomp.ssl.ciphers.4 = ECDHE-RSA-AES256-SHA384
web_stomp.ssl.ciphers.5 = ECDH-ECDSA-AES256-GCM-SHA384
web_stomp.ssl.ciphers.6 = ECDH-RSA-AES256-GCM-SHA384
web_stomp.ssl.ciphers.7 = ECDH-ECDSA-AES256-SHA384
web_stomp.ssl.ciphers.8 = ECDH-RSA-AES256-SHA384
web_stomp.ssl.ciphers.9 = DHE-RSA-AES256-GCM-SHA384

故障排除 TLS (WSS)

有关更多信息，请参阅 RabbitMQ TLS 和 TLS 故障排除。

基本 HTTP 身份验证

use_http_auth 选项通过允许客户端在 HTTP 授权头（使用 HTTP Basic Auth）中发送登录名和密码来扩展身份验证。如果存在，将使用这些凭据。否则，将使用默认的 STOMP 凭据。如果 CONNECT 帧中包含凭据，它们将被忽略。

这是一个高级功能，仅通过高级配置文件或经典配置格式公开

[
  {rabbitmq_web_stomp,
      [{use_http_auth, true}]}
].

代理协议

Web STOMP 插件支持 代理协议 (proxy protocol)。此功能默认处于禁用状态，若要为客户端激活它

web_stomp.proxy_protocol = true

有关代理协议的更多信息，请参阅 网络指南。

高级选项

Web STOMP 插件在底层使用 Cowboy HTTP 和 WebSocket 服务器。Cowboy 提供了许多选项，可用于自定义服务器在处理 WebSocket 连接方面的行为。

有些设置是通用的 HTTP 设置，有些则是特定于 WebSocket 的。

内容编码

默认情况下，Web STOMP 插件将期望处理编码为 UTF-8 的消息。如果需要，可以使用 ws_frame 选项将此插件公开的 WebSocket 端点切换为二进制模式

web_stomp.ws_frame = binary

HTTP 选项

通用 HTTP 服务器设置可以使用 web_stomp.cowboy_opts.* 键指定，例如

# connection inactivity timeout
web_stomp.cowboy_opts.idle_timeout = 60000
# max number of pending requests allowed on a connection
web_stomp.cowboy_opts.max_keepalive = 200
# max number of headers in a request
web_stomp.cowboy_opts.max_headers   = 100
# max number of empty lines before request body
web_stomp.cowboy_opts.max_empty_lines = 5
# max request line length allowed in requests
web_stomp.cowboy_opts.max_request_line_length

WebSocket 选项

# WebSocket traffic compression is enabled by default
web_stomp.ws_opts.compress = true

# WebSocket connection inactivity timeout
web_stomp.ws_opts.idle_timeout = 60000

web_stomp.ws_opts.max_frame_size = 50000