Repository navigation
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Critical flaws in credential refresh, ACK timing, fallback session preservation, and ping/pong handling can break resumption, duplicate message delivery, or terminate healthy sessions.
5 open issues
ACK interval can exceed the configured acknowledgement window · New Refresh connection credentials when resuming transports · New Startup fallback discards a negotiated resumable session · New Numbered control frames desynchronize client acknowledgements · New Resumable upgrades drop custom socket ping/pong callbacks · New
What changed in this PR
Adds resumable channel sessions by sharing session management between WebSockets and long polling, allowing connections to recover without rejoining channels.
Changes:
- Introduces shared server sessions with message replay, acknowledgements, deduplication, and resume callbacks.
- Adds opt-in resumable WebSockets, automatic long-poll recovery, and client suspension/resumption notifications.
- Documents configuration and adds client and integration coverage for recovery and transport switching.
| File | Description |
|---|---|
| test/support/websocket_client.exs | Buffers frames received during WebSocket upgrades. |
| test/phoenix/integration/websocket_resume_test.exs | Tests resumable WebSockets and transport switching. |
| test/phoenix/integration/long_poll_socket_test.exs | Updates session supervisor cleanup. |
| test/phoenix/integration/long_poll_channels_test.exs | Tests replay, deduplication, resume checks, and compatibility. |
| lib/phoenix/transports/websocket.ex | Negotiates and starts resumable sessions. |
| lib/phoenix/transports/websocket_pipe.ex | Connects WebSockets to persistent sessions. |
| lib/phoenix/transports/session.ex | Implements shared session lifecycle and message buffering. |
| lib/phoenix/transports/long_poll.ex | Adds acknowledgements, sequencing, and resume requests. |
| lib/phoenix/transports/long_poll_server.ex | Removes the superseded long-poll session implementation. |
| lib/phoenix/socket/transport.ex | Defines the optional transport resume callback. |
| lib/phoenix/socket.ex | Adds socket resume validation and dispatch. |
| lib/phoenix/endpoint.ex | Accepts and documents resumable WebSocket options. |
| lib/phoenix.ex | Starts the shared session supervisor. |
| CHANGELOG.md | Describes recovery features and new callbacks. |
| assets/test/suspend_test.js | Tests suspension and resumption notifications. |
| assets/test/socket_test.js | Updates callback and retry-option coverage. |
| assets/test/resumable_websocket_test.js | Tests WebSocket recovery, replay, and fallback. |
| assets/test/longpoll_test.js | Tests retry, sequencing, compatibility, and session handoff. |
| assets/js/phoenix/socket.js | Integrates resumable transport and recovery callbacks. |
| assets/js/phoenix/resumable_websocket.js | Implements resumable WebSockets and long-poll handoff. |
| assets/js/phoenix/longpoll.js | Adds retry, replay handling, and session continuation. |
| assets/js/phoenix/index.js | Exports and documents the resumable transport. |
| assets/js/phoenix/constants.js | Defines recovery backoff and session-loss close code. |
| assets/js/phoenix/connection.js | Routes transport suspension and recovery events. |
Review effort: Balanced
SteffenDE
commented
Nov 11, 2026
SteffenDE
left a comment
Member
Author
There was a problem hiding this comment.
We might also want to exclude the heartbeat from seq/ack counting
SteffenDE
added a commit
that referenced
this pull request
Nov 11, 2026
Should probably be part of #6887
Long-poll request failures currently close the socket and force channels to rejoin, even when the server session is still alive. This change retries interrupted requests so channels can stay joined and outgoing pushes can be buffered during recovery. The server retains message batches until acknowledged and deduplicates retried pushes using sequence numbers. The client exposes `socket.onSuspend` and `socket.onResume` callbacks for recovery status; push timeouts still apply. If the session expires, or an older server is encountered during a rolling deploy, the client falls back to the existing reconnect behavior.
Long polling acknowledged batches of messages, which ties the bookkeeping to how long polling groups messages. Both directions now number individual messages, so another transport can resume a session in the future. The long-poll server becomes Phoenix.Transports.Session. It keeps the messages the client did not acknowledge, sends all of them with the number of the last one, and the client drops the ones it already received. Incoming messages must arrive in order, as a gap means that messages were lost. A poll after a failed one resumes the session, which invokes the new optional Phoenix.Socket.resume/3 callback with the params and connect_info of the new request. Returning :error stops the socket, so the client connects again.
With the new `:resumable` WebSocket option, clients that opt in with the `resumable: true` option of the phoenix.js Socket resume their socket over a new WebSocket after the connection failed, without rejoining channels. The socket runs in a Phoenix.Transports.Session, which long polling uses as well. The WebSocket process attaches to it as a pipe. Both sides number their messages like long polling, keep them until the other side confirmed them, and send the missed ones again after resuming. The client resumes with the token of the session and the number of the last message it received, which invokes Phoenix.Socket.resume/3. The new ResumableWebSocket transport resumes the session with backoff, reports interruptions with onSuspend and onResume, and resumes instead of reconnecting when the heartbeat times out. When the session is gone, or the server does not support resuming, it closes so the socket connects again.
A socket that started over a WebSocket can now continue with long polling, and the other way around, as both transports resume the same session with the same message numbers. On the server, a resume detaches the WebSocket of the session, so a client can switch to long polling. Polls the client gave up on when it resumed over a WebSocket expire instead of taking its messages. Long polling sends binary messages in base64 with a "base64:" prefix, which a session can have when it started over a WebSocket. On the client, ResumableWebSocket falls back to long polling when it cannot resume the session over a WebSocket within the longPollFallbackMs option of the socket, for example when a proxy stops allowing WebSockets. It hands the session to a LongPoll, which resumes it with the token and the number of the last message received, and sends the messages the server did not confirm. The socket keeps its connection and channels stay joined.
The comment described a Phoenix 1.8 session receiving a resume, which cannot happen, as clients only resume sessions that numbered their messages. The timeout fires when the session is slow to check the resume. Polling anyway is safe, as the session handles the resume before the flush that follows, so a rejected resume never delivers messages.
The pipe and the session closed WebSockets with bare RFC 6455 codes, which hid why they close. Both now use a map of named codes, and the client uses a shared CLOSE_SESSION_GONE constant for the code that makes the socket connect again when a session is gone.
WebSock.terminate/2 is optional, and the pipe has nothing to clean up, as the session monitors it.
The code they cover already has TODOs for Phoenix 1.10, so the tests point to them as well.
Transports found the session by the pid in the token alone. After a session stopped, another session can get its pid, so an old token could resume it. A token is valid for 2 weeks, and on nodes without distribution, pids look the same after a restart. Clients that resume now send the random topic of the token with :resume and :pipe_attach. A session rejects a topic that is not its own but keeps running for its own client. The WebSocket pipe also requires the endpoint id of the token for pids of its own node, like long polling does. Long polling keeps the subscribe of Phoenix 1.8 for its other requests, so newer nodes and Phoenix 1.8 sessions keep working together during a deploy.
Long-poll requests only carry the session token. A request without phx:resume reached a session that a WebSocket started, so the socket never checked it with resume/3. A POST was dispatched even while the WebSocket was attached, and a poll without an ack acknowledged the messages of the WebSocket. The session now stores the transport the client connected or resumed with last, and rejects long-poll requests while it is another one. The client gets 410 and the session keeps running for its WebSocket. phoenix.js already resumes with its first poll and sends afterwards.
A "disconnect" broadcast stops the socket with {:shutdown, :disconnected}.
Bandit and Cowboy close a WebSocket with 1000 in this case, but the
session told its client 1011. LiveView reloads the page on 1000, so a
resumable socket rejoined its LiveViews instead of reloading.
A session kept the :window_ms of the transport that started it. When a WebSocket session continued with long polling, a poll could wait longer for messages than the session waited for its client, so the session stopped as inactive while the poll was pending. The session now takes the window from the options of the transport the client resumed with.
The server held a poll with phx:resume for :window_ms when the session had no messages for the client. A client that continues a WebSocket session with long polling buffers its messages until this poll returns, and onResume only runs then, so both took up to 10 seconds by default. The poll now returns once the session handled it. The session answers requests in order and only answers a flush when it has messages, so the answer to a request sent after the flush tells that it has none.
The socket sets the timeout of its transport to longpollerTimeout, which ResumableWebSocket also used for an attempt to resume. With the default of 20 seconds, one attempt the server did not answer took longer than the server keeps the session, which is 15 seconds by default. An attempt now times out after 10 seconds. The timeout the socket sets only applies to the LongPoll we fall back to.
A listen that waited for :window_ms sent :expired and returned 204 right away. The session could still answer a flush the listen had sent before. For clients that acknowledge, the session keeps these messages and sends them with the next poll. For clients that don't, it drops the messages it sends, so they were lost. This ports #6901 from v1.8 for the flush without ack. After the window, the listen asks the session for an echo. If the session answered the flush, the messages arrive before the echo. Without an answer within :pubsub_timeout_ms, the listen responds with 410 and the client starts a new session. The poll that resumes uses the same echo with its own ref.
SteffenDE
force-pushed
the
sd-resumable-transport
branch
from
November 11, 2026 18:15
b57fc06 to
91b2e0c
Compare
SteffenDE
added a commit
that referenced
this pull request
Nov 11, 2026
Should probably be part of #6887
This was referenced Nov 15, 2026
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Works upon #6885 and generalizes it into a
Phoenix.Transports.Session, such that websockets are resumable if configured with(and enabled on the client)
Longpoll is resumable by default.