Skip to content

Conversation

@jaycollett
Copy link

@jaycollett jaycollett commented Jan 29, 2026

Summary

TrueNAS is deprecating the REST API (api/v2.0/) in version 26.04, requiring migration to JSON-RPC 2.0 over WebSocket. This PR adds the core WebSocket infrastructure needed to support TrueNAS CORE and SCALE apps.

Changes

  • Add phrity/websocket dependency for WebSocket communication
  • Add 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

Technical Details

The WebSocket client uses the phrity/websocket v3.x library with proper SSL context configuration:

  • Forces ALPN to HTTP/1.1 for WebSocket upgrade compatibility (TrueNAS nginx defaults to HTTP/2)
  • Supports self-signed certificates when TLS verification is disabled

Companion PR

Depends on: linuxserver/Heimdall-Apps#889

This PR provides the core infrastructure. The TrueNAS app updates are in:

Both PRs need to be merged for full functionality. Existing TrueNAS apps will continue to work with REST API until the companion PR is merged.

References

Backward Compatibility

TrueNAS Version REST API WebSocket Notes
< 25.04 REST only
25.04 ⚠️ Deprecated Both available
26.04+ ❌ Removed WebSocket required

Test Plan

  • Tested WebSocket connection with TrueNAS SCALE 25.10.1
  • Verified authentication with API key
  • Confirmed JSON-RPC 2.0 calls work (core.ping, system.info, alert.list)
  • Tested with self-signed certificates (ignore_tls option)

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: linuxserver#1530
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Development

Successfully merging this pull request may close these issues.

truenas app still use the deprecated REST API

1 participant