fix(bin): replace lsof with /dev/tcp in server check_port; remove dea…

[bitflicker64]

Purpose of the PR

Fix a startup hang in kind/Kubernetes environments caused by lsof scanning an enormous file descriptor table, and remove dead check_port code from pd/store.

Main Changes

hugegraph-server/.../util.sh

• Replace lsof -i :PORT with a layered probe: ss -ltn → netstat -ltn/netstat -an → bash /dev/tcp with timeout 1
• Resolve hostnames to numeric IPs via getent/dscacheutil before matching against ss -n/netstat -n output
• Address-family-aware wildcard matching so IPv4 targets don't conflict with IPv6 wildcard listeners
• Fall through to next tool when ss exits non-zero
• 2-second watchdog deadline for /dev/tcp when timeout is unavailable
• Strip leading/trailing whitespace from URL and host
• Parse IPv6 bracket notation (http://[::1]:8080 and [::1]:8080)
• Validate port as decimal in range 1–65535 (force base-10 to prevent octal misinterpretation)
• Add curl -fL in download() so HTTP errors exit non-zero

hugegraph-pd/.../util.sh and hugegraph-store/.../util.sh

• Remove check_port — never called by PD or Store startup scripts
• Fix command_available: was using command substitution that always produced empty result
• Fix download() curl branch: was writing to broken path; now uses mkdir -p + basename
• Add curl -fL

.github/workflows/server-ci.yml

• Remove lsof from preflight prerequisites
• Add fuser preflight check on Linux for port cleanup

test-start-hugegraph*.sh

• Replace lsof -ti :PORT | xargs kill -9 with OS-aware cleanup (fuser -k PORT/tcp on Linux, lsof on macOS)
• Warn when neither tool is available

Tests

New test-check-port.sh — 34 mock-driven unit tests covering ss, GNU netstat, BSD netstat, /dev/tcp + timeout, real ephemeral-port listener, IPv4/IPv6, wildcard vs specific-address matching, tool-failure fallthrough, hostname resolution, URL whitespace normalization, IPv6 hextet guard, edge cases, and download() curl fallback for PD and Store.

Verifying these changes

• 34 mock-driven unit tests (all pass)
• lsof removed from CI preflight; fuser enforced on Linux
• For the original kind/k8s hang: start server in pod with large ulimit -n — starts without hanging

Does this PR potentially affect the following parts?

• Nope

Documentation Status

• Doc - No Need

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 36.55%. Comparing base (89b648a) to head (745a8bb).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #3105      +/-   ##
============================================
- Coverage     37.43%   36.55%   -0.89%     
+ Complexity      520      498      -22     
============================================
  Files           808      808              
  Lines         69581    69594      +13     
  Branches       9165     9169       +4     
============================================
- Hits          26048    25440     -608     
- Misses        40750    41402     +652     
+ Partials       2783     2752      -31     

☔ 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.

[bitflicker64]

@copilot review

[imbajin]

Blocking: yes. Summary: The new probe can miss or stall on real port conflicts, and the corrected command detection exposes a broken curl-only path. Evidence: static review of 6395c0c; bash -n passed; codecov/project is failing on this head.

[imbajin]

Blocking: yes. Summary: The fallback probe can execute configuration text as shell code and misparses a supported IPv6 URL form; the no-lsof branch matrix also remains untested. Evidence: exact-head static review, bash -n on all three changed scripts, and controlled reproductions for command execution and [::1]:8080 parsing.

[imbajin]

Blocking: yes. Summary: The listener-table probes can reject valid binds or silently skip collision detection, and the PD startup test still does not enforce its new lsof-free cleanup path. Evidence: exact-head static inspection, targeted shell reproductions, the 19-test check_port suite, and successful visible checks.

[imbajin]

⚠️ The primary probes do not identify the configured local endpoint: they match every listener by port, and the ss expression can even match the target digits inside an IPv6 address (for example, [2001:db8:8080::1]:9090 matches a check for port 8080). A listener on another specific interface can therefore reject a valid bind, while an IPv6 hextet can produce the same false positive. Please parse the local-address field and compare the configured host/port with wildcard and dual-stack conflict semantics, then add distinct-address and IPv6-hextet regressions.

[imbajin]

⚠️ Tool presence is treated as a successful probe. If an installed ss exits nonzero, this branch neither distinguishes that failure from an empty listener table nor tries netstat or /dev/tcp; the same silent-free result occurs when both netstat invocations fail. Please capture each probe's execution status, advance to the next layer on failure, and add cases where a present tool returns nonzero.

[imbajin]

⚠️ This cleanup now depends on fuser, but the PD workflow preflight still requires lsof curl java and never checks fuser. An lsof-free environment therefore skips the revised suite, while a runner without fuser executes it with silently ineffective port cleanup. Please remove the obsolete lsof gate, require fuser (or make cleanup dependency-free), and fail explicitly when cleanup cannot release the test ports.

[imbajin]

Blocking: yes — 6.0/10 on current head d315ae8. The main direction and CI are good, but the following issues still need to be addressed before merge.

New current-head findings:

• Hostname inputs bypass collision detection: ss -n/netstat -n report numeric addresses, so a supported value such as localhost is missed.
• The real-listener test can pass without creating its listener: fixed port 54321 may already be occupied and Python bind success is not verified.

Existing comments that remain applicable on d315ae8 (not reposted; +1 used for deduplication):

• No hard deadline without the external timeout command: the raw /dev/tcp fallback can still stall on dropped SYN packets.
• URL normalization is still incomplete: bracketed IPv6 was fixed, but leading/trailing whitespace accepted by ServerOptions still bypasses this check.
• Endpoint/dual-stack conflict semantics remain incomplete: the old IPv6-hextet false positive was fixed, but IPv4 and IPV6_V6ONLY IPv6 wildcard listeners are still treated as unconditional cross-family conflicts.
• fuser cleanup remains unenforced: Linux startup tests use fuser without checking that it exists and suppress cleanup failures.

Please do not treat these linked threads as fully resolved merely because some are outdated or marked resolved against older revisions; the specific residual behaviors above were revalidated on the current head.

[imbajin]

‼️ ss -n and netstat -n report numeric addresses, but this pattern compares them with the configured hostname text. ServerOptionsTest.testUrlNormalizationPreservesHostnameCase explicitly supports hostnames; with restserver.url=http://localhost:8080 and ss reporting 127.0.0.1:8080, this branch sets port_checked=1, misses the listener, and never reaches the resolving /dev/tcp fallback. A controlled run on this head returns success (port free) for that occupied endpoint. Please resolve hostnames to their IPv4/IPv6 addresses before matching, or use a deadline-bounded probe for hostname inputs, and add a hostname-to-numeric-listener regression.

[imbajin]

⚠️ This is a fixed port, not an ephemeral one, and the test never verifies that the Python child actually bound it. If 54321 is already occupied, Python exits immediately, check_port connects to the unrelated listener, and the test still passes. Please bind port 0 and return the selected port to the test (or at least assert child liveness/readiness before calling check_port) so this cannot produce a false-positive green result.

[bitflicker64]

fixing remaining issues