Add WebSocket support for TrueNAS JSON-RPC 2.0 API#1578
Merged
Conversation
TrueNAS is deprecating the REST API (api/v2.0/) in version 26.04, requiring migration to JSON-RPC 2.0 over WebSocket. This commit adds: - phrity/websocket dependency for WebSocket communication - TrueNASWebSocketClient helper class that handles: - Connection to ws(s)://host/api/current - Authentication via auth.login_with_api_key - JSON-RPC 2.0 request/response formatting - TLS verification toggle - Proper connection cleanup Refs: #1530
The WebSocket support added for TrueNAS JSON-RPC 2.0 requires the phrity/websocket library to actually be available at runtime. This repo commits the vendor/ tree (CI does not run composer install), so the dependency and composer.lock must be committed for class_exists() checks in the TrueNAS app to succeed. - composer require phrity/websocket:^3.6 (resolves to 3.7.3) with lock and vendor/ committed - Fix TrueNASWebSocketClient to catch WebSocket\Exception\Exception (phrity/websocket v3 namespace) instead of the non-existent WebSocket\ConnectionException from the old textalk/websocket v1/v2 API, so connection/call failures are logged and wrapped as intended
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
3 participants
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.
Revives #1538 (closed as stale, original work by @jaycollett — his commit authorship is preserved on the first commit).
The TrueNAS app merged in linuxserver/Heimdall-Apps#889 ships
TrueNASApiTraitthat gates its WebSocket JSON-RPC path onApp\Helpers\TrueNASWebSocketClientandWebSocket\Clientexisting in core. Without this PR the app silently degrades to REST-only, and TrueNAS removes the REST API in 26.04 — so the migration's whole point is dead code until core ships this.Two additions over the original PR:
vendor/and CI doesn't run composer install, so a composer.json-only change would never makeWebSocket\Clientexist at runtime.phrity/websocket ^3.6(resolves 3.7.3) plus its transitive deps are committed with the updated lock;composer validatepasses and the regenerated autoloader resolves all three classes.WebSocket\ConnectionException, which only existed in the old textalk/websocket v1/v2 — in phrity v3 exceptions live underWebSocket\Exception\*, so those catch blocks could never match. It now catchesWebSocket\Exception\Exception.Helper reviewed against the installed v3 API (
text(),receive()->getContent(),setTimeout(),setContext(),close()): TLS verification only disabled behind explicitignore_tls, ALPN forced to http/1.1 for TrueNAS's nginx, 15s timeout, no API-key logging. Not exercised against a live TrueNAS box — the app'sautomode falls back to REST if the socket fails, so worst case is unchanged behavior.