WebSockets
Winter Boot 2.3 serves WebSockets on the same port as your REST API. A handler is a bean annotated with #[WebSocketController]. The upgrade request runs through your HandlerInterceptors like any other request, so cookie sessions, authentication and tenant context work unchanged.
When the application has no #[WebSocketController] (and server.websocket.enabled is not true), nothing changes: the server stays a plain HTTP server.
One port for HTTP and WebSocket
Section titled “One port for HTTP and WebSocket”There is no separate WebSocket port. HTTP and WebSocket share server.port: Swoole’s WebSocket server is an HTTP server as well, so ordinary requests go to your REST routes, and a request carrying Upgrade: websocket becomes a socket.
server: port: 8080 context-path: /| Client | URL |
|---|---|
| REST call | http://host:8080/api/orders |
| WebSocket | ws://host:8080/ws/assistant |
| Behind TLS (ingress, load balancer) | https://app.example.com/api/... and wss://app.example.com/ws/... |
- Sockets live under
server.context-path, like routes. - One proxy or ingress route serves both. Only the WebSocket location needs the upgrade headers forwarded (see Behind a proxy).
- The admin listener (
server.admin.port) stays a separate, plain HTTP port; WebSocket upgrades are refused there.
A handler
Section titled “A handler”<?php
namespace app\web;
use dev\winterframework\stereotype\Autowired;use dev\winterframework\stereotype\web\WebSocketController;use dev\winterframework\web\client\HttpEntity;use dev\winterframework\web\client\RestTemplate;use dev\winterframework\web\client\StreamDecoder;use dev\winterframework\web\http\HttpRequest;use dev\winterframework\web\sse\SseEvent;use dev\winterframework\web\websocket\WebSocketHandler;use dev\winterframework\web\websocket\WebSocketMessage;use dev\winterframework\web\websocket\WebSocketSession;
#[WebSocketController(path: '/ws/assistant')]class AssistantSocket implements WebSocketHandler{ #[Autowired] private RestTemplate $rest;
public function onOpen(WebSocketSession $session, HttpRequest $handshake): void { // The interceptors already authenticated the handshake (401 otherwise), // and their context is still set here: remember who this is. $session->setAttribute('userId', TenantContext::current()->userId); $session->send(['type' => 'ready']); }
public function onMessage(WebSocketSession $session, WebSocketMessage $message): void { $msg = $message->json(); match ($msg['type'] ?? '') { 'echo' => $session->send(['type' => 'echo', 'text' => $msg['text'] ?? '']), 'ask' => $this->answer($session, (string)($msg['question'] ?? '')), 'stop' => $session->cancelWork('answer', 'stopped by user'), default => $session->send(['type' => 'error', 'error' => 'unknown message']), }; }
/** Streams the model's answer in parts; a "stop" message cancels it. */ private function answer(WebSocketSession $session, string $question): void { $token = $session->beginWork('answer'); // cancels an answer still running try { $this->rest->exchangeStream( 'POST', 'https://llm.example.com/v1/chat', new HttpEntity(['stream' => true, 'question' => $question]), fn (SseEvent $event) => $session->send(['type' => 'part', 'text' => $event->json()['text'] ?? '']), decoder: StreamDecoder::sse(), cancel: $token, // "stop" or the socket closing ends the call at once ); $session->send(['type' => $token->isCancelled() ? 'stopped' : 'done']); } finally { $session->endWork('answer', $token); } }
public function onClose(WebSocketSession $session, int $code, string $reason): void { }}In the browser:
const ws = new WebSocket(`wss://${location.host}/ws/assistant`); // the session cookie goes alongws.onmessage = (e) => render(JSON.parse(e.data));ws.send(JSON.stringify({ type: 'ask', question: 'Who has paid this month?' }));stopButton.onclick = () => ws.send(JSON.stringify({ type: 'stop' }));The class becomes a bean (autowiring works as in a #[Service]). Paths are relative to server.context-path and match exactly; several handlers can serve different paths. An upgrade to any other path is answered 404.
The interface methods:
| Method | When |
|---|---|
onOpen($session, $handshake) |
After the 101 response. Reject with $session->close(WebSocketCloseCode::POLICY_VIOLATION, 'reason'). Messages that arrive meanwhile wait until it returns. |
onMessage($session, $message) |
Every text or binary message (fragments already joined). $message->isBinary(), getPayload(), json() (decodes to arrays; throws JsonException on invalid JSON, which reaches onError() if you don’t catch it). |
onClose($session, $code, $reason) |
Exactly once per opened connection, after onOpen() returned: the peer’s close code, the code you passed to close(), or 1006 when the connection dropped. |
Implement WebSocketErrorHandler (onError($session, Throwable $e)) as well to see exceptions your handler throws; otherwise they are logged. The connection stays open after an exception in onMessage(); an exception in onOpen() closes it with 1011.
The handshake
Section titled “The handshake”The upgrade request goes through the HTTP pipeline before anything is upgraded:
- Unknown path →
404. BadSec-WebSocket-Key/method →400; a version other than 13 →426. Origincheck (see below) →403.- Your app-level
HandlerInterceptor::preHandle(). A veto sends the interceptor’s response (401, …) and nothing is upgraded. postHandle(), so headers and cookies your interceptors add (a refreshed session cookie) go out with the101response.- The
101response, then the context hooks’capture()and youronOpen(), in the same coroutine, with the interceptors’ context still set. afterCompletion()once.
Origin check
Section titled “Origin check”Browsers send cookies with a WebSocket handshake from any site, so a cookie-authenticated socket needs an Origin check (cross-site WebSocket hijacking). By default only pages from the same host may connect: the Origin must match the Host header (scheme default ports included). Clients that send no Origin (servers, mobile apps) are allowed; Origin: null never is.
Behind a proxy that rewrites Host, or for a front end on another host, list the allowed origins exactly:
server: websocket: allowedOrigins: [ 'https://app.example.com', 'http://localhost:5173' ]'*' allows any origin; only use it for sockets that do not rely on cookies.
This list is separate from the two other origin lists, and an empty list means something different for each:
| Setting | [] (the default) means |
|---|---|
server.websocket.allowedOrigins |
same host only |
winter.web.cors.allowedOrigins |
CORS off: no cross-origin access |
winter.mcp.allowedOrigins |
any request with an Origin header is refused |
A front end on another origin that calls your API (CORS) and opens a socket needs its origin in both winter.web.cors.allowedOrigins and server.websocket.allowedOrigins.
Per-connection context
Section titled “Per-connection context”Each message runs in a new coroutine, where the context your interceptors set for the handshake (tenant, user, principal) is gone. Winter Boot binds the handshake request as the current request for every call (ApplicationContext::getCurrentHttpRequest(), cookies included). For your own request-scoped state, register a RequestContextPropagator:
use dev\winterframework\core\web\RequestContextPropagator;use dev\winterframework\web\http\HttpRequest;
class TenantContextPropagator implements RequestContextPropagator{ // Once, in the handshake coroutine, after the interceptors accepted it. // Return whatever restore() needs; the framework keeps it with the connection. public function capture(HttpRequest $request): mixed { return TenantContext::current(); }
// Before every onMessage() / onClose(), in that call's coroutine. public function restore(mixed $snapshot): void { TenantContext::set($snapshot); }
// After every call, also when it failed. public function clear(): void { TenantContext::clear(); }}public function addInterceptors(InterceptorRegistry $registry): void{ $registry->addInterceptor(new WebSessionAuthenticator(), '^\/api', '^\/ws'); $registry->addContextPropagator(new TenantContextPropagator());}The snapshot is not a session attribute: attributes stay your own data (what you find sessions by). A restore() that throws fails closed: the handler is not called and the connection closes with 1011. Coroutines your handler starts itself (go()) do not inherit the context; restore it there too if they need it.
Sessions
Section titled “Sessions”WebSocketSession is the connection:
| Method | |
|---|---|
getId() |
An opaque session id (a random string), unique across workers and pods and never reused: safe to store, e.g. to route a notification back to this connection. |
getPath(), getHandshake(), getHeader(), getCookie() |
The upgrade request. |
getAttribute(), setAttribute(), hasAttribute(), removeAttribute() |
Your per-connection data. |
send(string|array|JsonSerializable) |
Text frame; arrays and objects are sent as JSON. |
sendBinary(string) |
Binary frame. |
close(int $code = 1000, string $reason = '') |
Close with a code (1000-1003, 1007-1014, 3000-4999; the reason is cut to 123 bytes). |
isOpen() |
Open and not closing. |
send() returns false when the connection is closed; it never throws for that. Data that cannot be JSON-encoded is a programming error and throws JsonException. It is safe from any coroutine of the same worker, so a long task can stream into the socket while other messages are handled.
Slow clients
Section titled “Slow clients”When a client reads slower than you send (a phone on a weak network), Swoole buffers the frames, roughly 10 MB per connection with the default socket buffers. Once that is full, send() waits: the calling coroutine is suspended until the client reads or disconnects, with no time limit. Only that coroutine waits, not the worker or other connections. When the client disconnects, the waiting send() returns false. A client that stopped reading can still answer pings at the network level, so the idle timeout does not end this wait.
For token streaming this is usually what you want (no tokens are dropped). If a task must not wait forever on one client, measure it yourself:
$started = microtime(true);foreach ($tokens as $token) { if (!$session->send(['type' => 'part', 'text' => $token]) || microtime(true) - $started > 120) { $session->close(WebSocketCloseCode::POLICY_VIOLATION, 'Too slow'); return; }}server.swoole.buffer_output_size and socket_buffer_size change how much is buffered before send() waits.
Connection limits
Section titled “Connection limits”Nothing limits sockets per user or per IP address: that is the application’s job (count a user’s sessions with WebSocketSessions::findByAttribute() in onOpen() and close the extra one). The server-wide cap is Swoole’s server.swoole.max_connection, shared by HTTP and WebSocket connections.
Long-running work and “stop”
Section titled “Long-running work and “stop””Messages of one connection are handled concurrently: a minute-long onMessage() does not hold back the next message. Their order is therefore not guaranteed once a handler waits on I/O. beginWork() gives a task a CancellationToken:
$session->beginWork('answer')returns a token. A task already running under the same name is cancelled first, so a new question replaces the old answer.$session->cancelWork('answer')cancels it (from the “stop” message).- Closing the connection cancels every task.
- The task checks
$token->isCancelled()(orthrowIfCancelled()) between steps, and callsendWork('answer', $token)when done.
CancellationToken (dev\winterframework\util\concurrent) is the framework’s single cancellation type. Pass it straight to RestTemplate::exchangeStream(..., cancel: $token), as in the example above: the upstream request ends within about 100 ms of the “stop”, even while the model is still thinking.
onClose() can run while an onMessage() of the same connection is still working; by then every token of the connection is cancelled, so work that checks its token winds down.
A connection may have at most server.websocket.maxConcurrentMessages (default 32) messages in progress; one more closes it with 1008.
Push from elsewhere
Section titled “Push from elsewhere”Autowire WebSocketSessions to reach open connections from services, scheduled tasks or REST endpoints:
#[Autowired]private WebSocketSessions $sockets;
public function notify(int $userId, array $event): void{ $this->sockets->sendToAttribute('userId', $userId, ['type' => 'notification', ...$event]); // or: foreach ($this->sockets->findByAttribute('userId', $userId) as $session) { ... }}Closing, timeouts and restarts
Section titled “Closing, timeouts and restarts”- Heartbeat and idle timeout: the server pings every connection every
heartbeatIntervalseconds (default 30). Browsers answer automatically. A connection with no frame at all (messages, pings or pongs) foridleTimeoutseconds (default 90) is closed with1000“Idle timeout”. - Message size: a message larger than
maxMessageSizebytes (default 1 MiB, counted after fragments are joined) closes the connection with1009. Swoole drops frames aboveserver.swoole.package_max_length(default 2 MiB, it also caps HTTP bodies) before Winter Boot sees them; amaxMessageSizeabove it stops the application at startup. - Reload and shutdown (
SIGUSR1,SIGTERM): as soon as a worker starts exiting, it closes its connections with1001(going away), so clients reconnect to the next worker or pod.onClose()still runs once for each. - A connection can also drop without a close frame (network loss, a killed process): browsers report
1006. Treat both1001and1006as “reconnect”.
ws.onclose = (e) => { if (e.code === 1001 || e.code === 1006) setTimeout(connect, 1000 + Math.random() * 2000); };Behind a proxy or load balancer
Section titled “Behind a proxy or load balancer”- Forward the upgrade. nginx needs
proxy_http_version 1.1;,proxy_set_header Upgrade $http_upgrade;andproxy_set_header Connection "upgrade";on the WebSocket location. Ingress controllers and AWS ALB forward WebSockets without extra settings. - Idle timeouts. Proxies close connections that stay quiet too long: ingress-nginx after 60 s (
proxy-read-timeout), AWS ALB after 60 s (idle timeout). The server pings everyheartbeatInterval(default 30 s), which keeps the connection busy; keep it below the proxy’s timeout. - Origin. If the proxy rewrites
Host, the same-host Origin check fails: list your origins inallowedOrigins. - No sticky sessions needed. A WebSocket stays on the pod and worker that accepted it for its whole life. A reconnect may land anywhere, so keep conversation state in your database or cache, not only in the session.
dispatch_modedoes not matter. Winter Boot runs Swoole in its defaultSWOOLE_BASEmode, where a connection is handled by the worker that accepted it, so every message of a socket reaches the same worker whateverserver.swoole.dispatch_modesays. It is neither refused nor overridden.
Relaying an HTTP stream over the socket
Section titled “Relaying an HTTP stream over the socket”Keep the socket thin and the logic in your REST API: the handler calls your own streamed endpoint as the user, by forwarding the handshake’s cookie, and passes each server-sent event on. The API does the authorisation, database work and AI call. The socket only holds a coroutine while the answer streams, never a database connection, and “stop” cancels the upstream call.
#[WebSocketController(path: '/ws/assistant')]class AssistantRelaySocket implements WebSocketHandler{ #[Autowired] private RestTemplate $rest;
public function onOpen(WebSocketSession $session, HttpRequest $handshake): void { }
public function onMessage(WebSocketSession $session, WebSocketMessage $message): void { $msg = $message->json(); if (($msg['type'] ?? '') === 'stop') { $session->cancelWork('answer'); return; } $token = $session->beginWork('answer'); try { $this->rest->exchangeStream( 'POST', 'http://127.0.0.1:8080/api/assistant/chat', // this same service, or the API's internal address new HttpEntity(['question' => $msg['question'] ?? ''], [ 'Cookie' => $session->getHandshake()->getCookieHeader(), // act as the logged-in user 'Accept' => 'text/event-stream', // The API sees the relay as its client: pass the user's address and language on. 'X-Forwarded-For' => self::forwardedFor($session), 'Accept-Language' => (string)$session->getHeader('Accept-Language'), ]), function (SseEvent $e) use ($session): bool { // JSON data stays structured; anything else is passed on as text (json() would throw). $data = json_decode($e->data, true); return $session->send(['type' => $e->event, 'data' => $data ?? $e->data]); }, decoder: StreamDecoder::sse(), cancel: $token, // "stop", a newer question or the socket closing ends the call at once ); } catch (HttpStatusCodeException $e) { // The API's body says why (403, 429 with when the limit resets): pass that on, not just the status. $body = json_decode($e->getResponseBody(), true); $session->send([ 'type' => 'error', 'status' => $e->getStatusCode(), 'message' => is_array($body) ? ($body['error'] ?? $body['message'] ?? null) : null, ]); } finally { $session->endWork('answer', $token); } }
public function onClose(WebSocketSession $session, int $code, string $reason): void { }
/** The handshake's X-Forwarded-For (set by your ingress) plus the address that connected. */ private static function forwardedFor(WebSocketSession $session): string { $chain = array_filter([ trim((string)$session->getHeader('X-Forwarded-For')), (string)$session->getHandshake()->getRemoteAddr(), ]); return implode(', ', $chain); }}A cancelled token (a “stop” message, a newer question, the socket closing) ends the upstream request within about 100 ms, even while the API is silent, and send() returning false (the client left) ends it at the next event. Either way the API sees its own client disconnect and can stop the model (with getCancellationToken() on its side). Errors from the API (401, 429, …) arrive as HttpStatusCodeException before any event; getResponseBody() holds the API’s explanation (with Winter Boot’s default error controller, the detail is in error).
- Client address. Without
X-Forwarded-Forthe API sees the relay (127.0.0.1) as every user’s address: audit logs record the wrong IP, and IP-keyed rate limits put all socket users in one bucket. The API must trustX-Forwarded-Foronly from known hops (the relay, your ingress) and read it from the right, skipping those hops: a client can send any value in the left part. - Event data. Decode tolerantly as above, or make the API send JSON in every event:
SseEvent::json()throws on anything else, which would end the whole answer. - Forwarding cookies. Use
getHandshake()->getCookieHeader(): under Swoole the handshake’sCookieheader is not among its headers (getHeader('Cookie')isnull), because Swoole parses cookies out of them. - Cookies back. A refreshed session cookie in the API’s response (
Set-Cookie) never reaches the browser through the relay; the browser’s cookie is refreshed by its next direct API request.
Testing
Section titled “Testing”Handlers are plain classes: call them with a TestWebSocketSession, which behaves like a real connection (close rules, attributes, work tokens) and records what is sent.
use dev\winterframework\test\web\TestWebSocketSession;use dev\winterframework\web\websocket\WebSocketMessage;
$session = new TestWebSocketSession('/ws/assistant');$session->setAttribute('userId', 42);
$handler = new MySocket(/* fakes */);$handler->onMessage($session, WebSocketMessage::text('{"type":"echo","text":"hi"}'));
assert($session->getSentJson() === [['type' => 'echo', 'text' => 'hi']]);TestWebSocketSession |
|
|---|---|
new TestWebSocketSession($path, ?HttpRequest $handshake) |
An open session; pass a handshake request to give it headers and cookies. |
getSentMessages(), getSentJson(), getSentFrames() |
Text frames as sent, decoded as JSON, or every frame with its binary flag. |
getCloseCode(), getCloseReason() |
What close() sent; null while open. |
disconnect() |
The client leaves: send() returns false, isOpen() turns false. |
To test a RequestContextPropagator, call capture() with a request and restore() with what it returned.
For the full path (handshake through your interceptors, Origin, close codes), Winter Boot’s own tests boot a small application in a subprocess and connect with Swoole’s coroutine client (Swoole\Coroutine\Http\Client::upgrade()); see srcTests/swoole/WebSocketSwooleTest.php and srcTests/swoole/support/FixtureServer.php in the repository. Set open_websocket_close_frame on that client to receive close codes, and check statusCode === 101 after upgrade(), which also returns true for a refused handshake.
Configuration
Section titled “Configuration”All keys are optional (see the application.yml reference):
server: websocket: enabled: true # default: on when a #[WebSocketController] exists; false turns it off allowedOrigins: [] # [] = same host only maxMessageSize: 1048576 # bytes idleTimeout: 90 # seconds, 0 = never heartbeatInterval: 30 # seconds, 0 = no pings maxConcurrentMessages: 32 compression: false # permessage-deflatewebsocket_compression can also be set under server.swoole, like any Swoole setting. Winter Boot always sets open_websocket_close_frame, open_websocket_ping_frame and open_websocket_pong_frame to true, since it needs those frames for close codes and the idle timeout.
Logging and metrics
Section titled “Logging and metrics”Each connection logs one INFO line when it opens and one when it closes (path, connection id, close code, message count, duration). Message bodies, headers and query values are never logged. These Prometheus counters are registered on the first connection, labelled with the handler path, and stored when a metrics store is configured (winter.kv.port or winter.prometheus.beanClass; without one, metrics are discarded):
websocket_connections_openedwebsocket_connections_closed(also labelledcode)websocket_messages_receivedwebsocket_errors
Not supported
Section titled “Not supported”Sub-protocols such as STOMP, rooms or broadcast across workers and pods, and WebSockets over HTTP/2.