WebSocket Architecture
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/org/example/coding_convention/config/WebSocketConfig.java
- src/main/java/org/example/coding_convention/websocket/WebSocketController.java
- src/main/java/org/example/coding_convention/websocket/editor/MouseController.java
- src/main/java/org/example/coding_convention/websocket/editor/EditorDto.java
- src/main/java/org/example/coding_convention/websocket/chat/ChatMessageDto.java
- README.md
The WebSocket architecture in the PhanesEditor project provides the backbone for real-time collaboration, enabling synchronized code editing, live chat, and user presence tracking (mouse/cursor positions). It is designed to facilitate multi-user interaction within specific project environments, ensuring that updates are broadcasted only to relevant participants in a project-based channel structure.
The system utilizes the STOMP (Simple Text Oriented Messaging Protocol) over WebSockets to manage structured messaging between clients and the server. This architecture separates real-time events—such as code changes and cursor movements—from standard RESTful CRUD operations, allowing for a responsive and scalable collaborative environment.
Sources: README.md:16-56, src/main/java/org/example/coding_convention/config/WebSocketConfig.java:12-16
Core Configuration and Messaging Protocol
The project implements WebSocketMessageBrokerConfigurer to enable a STOMP-based message broker. This configuration defines the handshake endpoints, security interceptors, and the routing prefixes used for publishing and subscribing to messages.
Endpoint and Security
The primary WebSocket connection point is established at /websocket. To ensure secure communication, the connection undergoes two layers of verification:
- JwtHandshakeInterceptor: Handles initial token validation during the HTTP upgrade.
- AuthChannelInterceptor: Validates inbound messages at the application level to ensure the user is an authorized project member.
Sources: src/main/java/org/example/coding_convention/config/WebSocketConfig.java:18-30, README.md:58-65
Broker Routing
The messaging system uses distinct prefixes to differentiate between client requests and server broadcasts:
| Prefix | Type | Description |
|---|---|---|
/topic | Destination | Used for broadcasting messages to subscribers (Outbound). |
/app | Application | Used for messages directed to @MessageMapping handlers (Inbound). |
Sources: src/main/java/org/example/coding_convention/config/WebSocketConfig.java:32-36
Data Flow and Component Interaction
The WebSocket architecture facilitates three primary real-time features: collaborative editing, chat, and presence tracking.
The diagram shows the journey of a WebSocket message from the client through the security layers to the specialized controllers, and finally to the broker for broadcasting to project members.
Sources: src/main/java/org/example/coding_convention/config/WebSocketConfig.java:27-36, src/main/java/org/example/coding_convention/websocket/WebSocketController.java:21-31, src/main/java/org/example/coding_convention/websocket/editor/MouseController.java:10-21
Feature Implementation Details
Real-Time Chat System
The chat system maps messages to specific room IDs, which typically correspond to project IDs. The WebSocketController processes incoming ChatMessageDto objects, enriches them with the sender's identity and a timestamp, and then broadcasts them to the project's topic.
Sources: src/main/java/org/example/coding_convention/websocket/WebSocketController.java:21-25, src/main/java/org/example/coding_convention/websocket/chat/ChatMessageDto.java:10-20
Collaborative Editor Sync
The editor handles code changes through a specialized EditorDto.Code structure that includes line/column ranges and the specific text modification. This allows the backend to broadcast granular updates rather than the entire file content.
This sequence illustrates how a code change from one user is propagated to all other members subscribed to the specific editor room.
Sources: src/main/java/org/example/coding_convention/websocket/WebSocketController.java:27-30, src/main/java/org/example/coding_convention/websocket/editor/EditorDto.java:6-21
User Presence (Mouse and Cursor)
The MouseController manages high-frequency updates for mouse coordinates and text cursor positions. Unlike chat or code changes, these are often broadcasted to broader topics like /topic/mouse or /topic/cursor.
| Object | Fields | Purpose |
|---|---|---|
MousePosition | id, x, y | Syncs the physical mouse pointer location of participants. |
CursorPosition | senderId, line, column | Syncs the active text insertion point in the editor. |
Sources: src/main/java/org/example/coding_convention/websocket/editor/MouseController.java:10-21, src/main/java/org/example/coding_convention/websocket/editor/MousePosition.java:3-10, src/main/java/org/example/coding_convention/websocket/editor/CursorPosition.java:3-10
Project-Based Access Control
A critical design point of the PhanesEditor WebSocket architecture is that all real-time interactions are restricted by project membership. Access control is enforced by:
- Channel Structuring: Using
{roomId}variables in destinations to isolate traffic between different projects. - Membership Validation: The
AuthChannelInterceptorchecks if the authenticated user is a registered member of the project associated with the targetroomIdbefore allowing message processing.
Sources: README.md:46-56, src/main/java/org/example/coding_convention/config/WebSocketConfig.java:28-30
The PhanesEditor WebSocket architecture effectively bridges the gap between a standard web application and a collaborative development environment by utilizing a STOMP-based broker, ensuring that every code change, message, and movement is synchronized across authorized project members with low latency and high security.