WebSocket MARS Server Support with Backward Compatibility

[gbiavati]

Support WebSocket MARS Server with Backward Compatibility

Summary

Adds support for WebSocket-based MARS client using shared filesystem access, solving pipe-related errors in high-concurrency scenarios while maintaining full backward compatibility with existing deployments.

Problem

The current pipe-based MARS client can experience issues under high concurrency:

• Pipe communication failures
• Limited error visibility
• Synchronous blocking behavior
• Process management challenges

Solution

Implements modal behavior controlled by MARS_USE_SHARES environment variable:

• MARS_USE_SHARES=false (default): Uses existing pipe-based client

  • 100% backward compatible
  • No changes required for existing deployments

• MARS_USE_SHARES=true: Uses new WebSocket client with:

  • Asynchronous job processing
  • Real-time log streaming from MARS processes
  • Connection pooling with automatic failover
  • Client-side log filtering to reduce verbose output
  • Graceful process management

Key Changes

1. New WebSocket Client Implementation

• execute_mars_shares(): New function implementing WebSocket-based MARS requests

  • Communicates with WebSocket servers on shared filesystem
  • Supports custom log handlers for filtering/parsing
  • Automatic server failover on connection failures

• get_mars_server_list_ws(): Converts HTTP pipe URLs to WebSocket URLs

  • Properly handles scheme conversion (http→ws, https→wss)
  • Port translation (9000→9001 by default)

2. Version-Aware Backward Compatibility

WebSocket mode requires both:

1. MARS_USE_SHARES=true environment variable
2. cads-mars-server >= 0.3.0 installed

New functions:

• _check_cads_mars_server_supports_websocket(): Detects cads-mars-server version
• _should_use_websocket_mode(): Determines which client to use

Handles all scenarios:

• ✅ Release versions (0.3.0, 0.3.1, etc.)
• ✅ Branch builds (0.3.0.dev1+g...) via base_version parsing
• ✅ Release candidates (0.3.0rc1)
• ✅ Older versions → automatic fallback to pipe mode with user-visible warning

3. Enhanced Logging

• WebSocket mode: Shows server version info
• Fallback scenarios: Explains why pipe mode is being used
• Better error messages and progress visibility

Backward Compatibility

No breaking changes:

• Default behavior unchanged (pipe mode)
• Existing deployments continue working without modification
• Graceful degradation if WebSocket not available
• Clear user messaging about mode selection

Configuration

Environment Variables

Some environmental variables have been added.
The existing lists of servers fetched from files are still usable and there is no need for specifying the ws protocol as it will be enforced as well as the port.

# Use WebSocket client (requires cads-mars-server >= 0.3.0)
MARS_USE_SHARES=true

# WebSocket server URLs (comma-separated or config file)
MARS_WS_SERVERS="ws://worker1:9001,ws://worker2:9001,ws://worker3:9001"

# Port configuration (defaults)
MARS_PIPE_PORT=9000
MARS_SHARES_PORT=9001

Related PRs

cads-mars-server