Summary

Adds bidirectional realtime WebSocket sync between the HyperPerms plugin and the web editor, enabling live permission editing with instant feedback. Changes made in the web editor are applied to the server in real-time, and changes made via commands or other sources are reflected back to the editor immediately.

Architecture

The plugin connects to a Cloudflare Durable Object (deployed separately) via WebSocket, which acts as a relay between the plugin and the web editor. This gives us:

• Sub-second change propagation in both directions
• No polling overhead
• Connection resilience with automatic reconnect
• Graceful fallback to REST when WebSocket is unavailable

What's included

Event System Additions

• TrackCreateEvent, TrackDeleteEvent, TrackModifyEvent - new track lifecycle events following the existing PRE/POST pattern used by GroupCreateEvent/GroupDeleteEvent
• EventBus integration in TrackManagerImpl to fire events on track CRUD operations
• New TRACK_CREATE, TRACK_DELETE, TRACK_MODIFY entries in EventType enum

WebSocket Echo Prevention

• ChangeApplier.applyChangesFromWebSocket() wraps change application with a ThreadLocal flag
• EventBus listeners can check ChangeApplier.isApplyingFromWebSocket() to skip re-broadcasting changes that originated from the WebSocket relay

WebSocket Client (WebSocketSessionClient)

• Built on java.net.http.HttpClient.newWebSocketBuilder(), reuses the existing HttpClient from WebEditorService
• Subscribes to all EventBus events (permission, group, user, track changes) and converts them to WebSocket ops
• Handles incoming batch.apply messages: deserializes ops into Change objects, applies via ChangeApplier, returns success/failure counts with undo ID
• Handles session.sync requests by serializing current state via SessionData.fromHyperPerms()
• Auto-reconnect with exponential backoff (1s, 2s, 4s... configurable max delay and max attempts)
• Ping/pong keepalive with configurable timeout (reconnects if no ping received within threshold)

Service Integration

• WebEditorService gains connectWebSocket(), disconnectWebSocket(), getActiveWsClient() lifecycle methods
• SessionCreateResponse now includes the wsUrl field returned by the API
• Automatic WS connection after successful session creation (when enabled in config)

Command Updates

• EditorSubCommand: displays "Live connection established" when WS connects after session creation
• ApplySubCommand: sends batch.apply over WebSocket when connected, falls back to REST otherwise

Configuration

• websocketEnabled (default: true) - master toggle for WebSocket features
• websocketReconnectMaxAttempts (default: 10) - max reconnect attempts before giving up
• websocketReconnectMaxDelaySeconds (default: 30) - cap on exponential backoff delay
• websocketPingTimeoutSeconds (default: 90) - time without ping before triggering reconnect

Shutdown

• HyperPerms.disable() calls webEditorService.disconnectWebSocket() for clean shutdown

Files Changed

Test Plan

• Create a web editor session and verify WebSocket connects (Live connection established message in console)
• Make a permission change in the web editor and verify it applies on the server
• Make a permission change via command and verify it appears in the web editor
• Test batch apply: queue multiple changes in batch mode, apply, verify all succeed
• Test undo: apply changes, use undo, verify rollback
• Test reconnection: kill the WS connection, verify auto-reconnect with backoff
• Test fallback: set websocketEnabled: false, verify REST apply still works
• Test shutdown: disable the plugin, verify WS disconnects cleanly
• Verify no echo loops: changes from WS don't fire events back to WS