WebSocket 使用指南

目录

概述

Tomcat 提供对 RFC 6455 定义的 WebSocket 的支持。

应用程序开发

Tomcat 实现由 Jakarta WebSocket 项目定义的 Jakarta WebSocket 2.1 API。

有几个示例应用程序演示了如何使用 WebSocket API。您需要查看客户端 HTML 和服务器端 代码。

Tomcat WebSocket 特定配置

Tomcat 为 WebSocket 提供了许多 Tomcat 特定配置选项。预计这些选项将随着时间的推移被吸收到 WebSocket 规范中。

在阻塞模式下发送 WebSocket 消息时使用的写入超时默认值为 20000 毫秒（20 秒）。可以通过在附加到 WebSocket 会话的用户属性集合中设置属性 org.apache.tomcat.websocket.BLOCKING_SEND_TIMEOUT 来更改此值。分配给此属性的值应为 Long，并表示要使用的超时时间（以毫秒为单位）。对于无限超时，请使用 -1。

会话关闭超时默认设置为 30000 毫秒（30 秒）。可以通过在附加到 WebSocket 会话的用户属性集合中设置属性 `org.apache.tomcat.websocket.SESSION_CLOSE_TIMEOUT` 来更改此设置。分配给此属性的值应为 `Long` 类型，表示要使用的超时时间（以毫秒为单位）。小于或等于零的值将被忽略。

除了 Jakarta WebSocket API 中的 `Session.setMaxIdleTimeout(long)` 方法之外，Tomcat 还提供了对由于缺乏活动而导致的会话超时进行更精细控制的功能。在附加到 WebSocket 会话的用户属性集合中设置属性 `org.apache.tomcat.websocket.READ_IDLE_TIMEOUT_MS` 将在指定毫秒数内未收到任何 WebSocket 消息时触发会话超时。设置属性 `org.apache.tomcat.websocket.WRITE_IDLE_TIMEOUT_MS` 将在指定毫秒数内未发送任何 WebSocket 消息时触发会话超时。这些属性可以单独使用或一起使用，也可以与 `Session.setMaxIdleTimeout(long)` 一起使用。如果未指定相关属性，则将应用读写空闲超时。

如果应用程序未为传入的二进制消息定义 `MessageHandler.Partial`，则必须缓冲所有传入的二进制消息，以便可以在一次调用注册的二进制消息 `MessageHandler.Whole` 时传递整个消息。二进制消息的默认缓冲区大小为 8192 字节。可以通过将 servlet 上下文初始化参数 `org.apache.tomcat.websocket.binaryBufferSize` 设置为所需的字节数来更改 Web 应用程序的缓冲区大小。

如果应用程序未为传入的文本消息定义 `MessageHandler.Partial`，则必须缓冲所有传入的文本消息，以便可以在一次调用注册的文本消息 `MessageHandler.Whole` 时传递整个消息。文本消息的默认缓冲区大小为 8192 字节。可以通过将 servlet 上下文初始化参数 `org.apache.tomcat.websocket.textBufferSize` 设置为所需的字节数来更改 Web 应用程序的缓冲区大小。

当使用 WebSocket 客户端连接到服务器端点时，建立连接期间 IO 操作的超时时间由提供的 `jakarta.websocket.ClientEndpointConfig` 的 `userProperties` 控制。该属性为 `org.apache.tomcat.websocket.IO_TIMEOUT_MS`，表示以毫秒为单位的超时时间（以 `String` 类型表示）。默认值为 5000（5 秒）。

当使用 WebSocket 客户端连接到安全的服务器端点时，应通过 `jakarta.websocket.ClientEndpointConfig.getSSLContext()` 配置客户端 SSL 配置。Tomcat 10.1.x 仍然支持 WebSocket 2.1 之前的配置方法，其中 TLS 配置是通过提供的 `jakarta.websocket.ClientEndpointConfig` 的 `userProperties` 进行的。但是，这种方法已过时，将在 Tomcat 11 中删除。支持以下用户属性：

  • org.apache.tomcat.websocket.SSL_CONTEXT
  • org.apache.tomcat.websocket.SSL_PROTOCOLS
  • org.apache.tomcat.websocket.SSL_TRUSTSTORE
  • org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWD

默认的信任库密码是changeit。

如果设置了org.apache.tomcat.websocket.SSL_CONTEXT 属性，则会忽略org.apache.tomcat.websocket.SSL_TRUSTSTORE 和 org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWD 属性。

对于安全的服务器端点，默认情况下启用主机名验证。要绕过此验证（不推荐），需要通过org.apache.tomcat.websocket.SSL_CONTEXT 用户属性提供自定义的SSLContext。自定义的SSLContext 必须配置为使用扩展javax.net.ssl.X509ExtendedTrustManager 的自定义TrustManager。然后，可以通过适当的抽象方法实现来控制所需的验证（或不验证）。

当使用 WebSocket 客户端连接到服务器端点时，客户端将遵循的 HTTP 重定向次数由提供的jakarta.websocket.ClientEndpointConfig 的userProperties 控制。该属性是org.apache.tomcat.websocket.MAX_REDIRECTIONS。默认值为 20。可以通过配置值为零来禁用重定向支持。

当使用 WebSocket 客户端连接到需要 BASIC 或 DIGEST 身份验证的服务器端点时，必须设置以下用户属性

  • org.apache.tomcat.websocket.WS_AUTHENTICATION_USER_NAME
  • org.apache.tomcat.websocket.WS_AUTHENTICATION_PASSWORD

可选地，可以将 WebSocket 客户端配置为仅在服务器身份验证挑战包含特定领域时才发送凭据，方法是在可选用户属性中定义该领域

  • org.apache.tomcat.websocket.WS_AUTHENTICATION_REALM

当使用 WebSocket 客户端通过需要 BASIC 或 DIGEST 身份验证的转发代理（也称为网关）连接到服务器端点时，必须设置以下用户属性

  • org.apache.tomcat.websocket.WS_PROXY_AUTHENTICATION_USER_NAME
  • org.apache.tomcat.websocket.WS_PROXY_AUTHENTICATION_PASSWORD

可选地，可以将 WebSocket 客户端配置为仅在服务器身份验证挑战包含特定领域时才发送凭据，方法是在可选用户属性中定义该领域

  • org.apache.tomcat.websocket.WS_PROXY_AUTHENTICATION_REALM