WebSocket 使用說明

目錄

概觀

Tomcat 提供對 WebSocket 的支援，定義於 RFC 6455。

應用程式開發

Tomcat 實作 Jakarta WebSocket 專案定義的 Jakarta WebSocket 2.1 API。

有幾個範例應用程式示範如何使用 WebSocket API。您需要查看客戶端 HTML 和伺服器端 程式碼。

Tomcat WebSocket 特定組態

Tomcat 提供許多 Tomcat 特定的 WebSocket 組態選項。預期這些選項會隨著時間被吸收進 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 context 初始化參數 org.apache.tomcat.websocket.binaryBufferSize 設定為以位元組為單位的所需值，來變更 Web 應用程式的設定。

如果應用程式未定義用於傳入文字訊息的 MessageHandler.Partial，則任何傳入的文字訊息都必須進行緩衝，才能在單一呼叫中將整個訊息傳遞給已註冊的文字訊息 MessageHandler.Whole。文字訊息的預設緩衝區大小為 8192 位元組。可以透過將 servlet context 初始化參數 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 必須使用自訂的 TrustManager 來設定，此 TrustManager 會延伸 javax.net.ssl.X509ExtendedTrustManager。然後，可以透過適當的個別抽象方法實作來控制所需的驗證（或不驗證）。

使用 WebSocket 伺服器端點時，伺服器端點會追蹤的 HTTP 重新導向次數會由提供的 jakarta.websocket.ClientEndpointConfig 的 userProperties 控制。此屬性為 org.apache.tomcat.websocket.MAX_REDIRECTIONS。預設值為 20。可以透過設定值為 0 來停用重新導向支援。

使用 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