[SYSTEMDS-3959] Report an error when a federated worker cannot bind its port

[gaturchenko]

The command systemds WORKER 80505 terminated silently with exit code 0. There are 2 causes:

1. No range check for -w <port>, neither in bin/systemds nor when parsing the option
2. FederatedWorker.run() captured every exception in a catch-all and logged only e.getMessage(), which is empty or ambigous for a bind failure. The same held for occupied and reserved ports, and for the -fedMonitoring backend

The following changes were implemented:

• PortUtils (new): the shared range constants and validation, as well as explicit port and cause naming in case of errors;
• DMLOptions: -w and -fedMonitoring reject non-integers and ports outside [1, 65535] at parse time, naming the incorrect option. A missing (optional) -w argument now falls back to the default port instead of throwing NumberFormatException.
• FederatedWorker / FederatedMonitoringServer: a failed bind is logged through explainBindFailure and re-thrown as DMLRuntimeException. The monitoring backend now separates InterruptedException (a normal shutdown) from a real failure.
• bin/systemds: adds a range check, a warning for reserved ports, and exit 1. Previously, an error was printed and the JVM was launched regardless.
• FederatedWorkerPortTest (new): 14 tests covering the range predicates, option parsing, and the two worker paths (out-of-range and occupied port).

Resulting messages:

$ systemds WORKER 80505
error: Port 80505 for the federated worker is out of range, expected a port in [1, 65535]

$ systemds WORKER 80
warning: Port 80 for the federated worker is a reserved system port, binding it requires elevated privileges
ERROR federated.FederatedWorker: Federated worker stopped: no permission to bind port 80, ports below 1024 are reserved and require elevated privileges (Permission denied)

$ systemds WORKER 8001   # port taken
ERROR federated.FederatedWorker: Federated worker stopped: port 8001 is already in use (Address already in use)

[codecov]

Codecov Report

❌ Patch coverage is 64.10256% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.38%. Comparing base (9dccbc3) to head (1e8037d).
⚠️ Report is 17 commits behind head on main.

Files with missing lines	Patch %	Lines
...ederated/monitoring/FederatedMonitoringServer.java	12.50%	6 Missing and 1 partial ⚠️
...rc/main/java/org/apache/sysds/utils/PortUtils.java	66.66%	3 Missing and 4 partials ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #2586      +/-   ##
============================================
- Coverage     71.44%   71.38%   -0.07%     
- Complexity    50437    50550     +113     
============================================
  Files          1629     1633       +4     
  Lines        195513   196270     +757     
  Branches      38118    38208      +90     
============================================
+ Hits         139686   140101     +415     
- Misses        44867    45144     +277     
- Partials      10960    11025      +65     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gaturchenko]

Waiting for the review by @ywcb00

[Baunsgaard]

Only criticism. I am strongly against adding more logic to the systemds file. Can we not just have the error message and verification inside Java. This gives a single point of failure, rather than splitting the logic in two.

While there was some logic already verifying basic number compatibility, i think that should also just be cleaned up and moved into the java PortUtils you have defined.