Skip to content

feat(cli): add port ownership diagnosis before serve startup - #329

Open
dggyey wants to merge 4 commits into
inclusionAI:mainfrom
dggyey:feature/port-diagnosis-228
Open

feat(cli): add port ownership diagnosis before serve startup#329
dggyey wants to merge 4 commits into
inclusionAI:mainfrom
dggyey:feature/port-diagnosis-228

Conversation

@dggyey

@dggyey dggyey commented Jul 28, 2026

Copy link
Copy Markdown

What does this PR do?

Adds a port ownership diagnostic that runs before areno serve/areno proxy startup. The diagnostic checks if the target (host, port) is available for binding. If occupied, it identifies the owning process via psutil, classifies it as an AReno child process or an unrelated external service, and prints a safe, actionable suggestion — without terminating any process.

Changes

  • New areno/cli/port_diag.py: core diagnostic logic (diagnose_port(), format_diagnosis(), PortDiagnosis dataclass)
  • Modified areno/cli/serve.py: integrated diagnostic before model/worker initialization
  • Modified areno/cli/diagnostics.py: added areno port-check CLI command with --host/--port/--json options
  • Modified areno/cli/main.py: registered port-check command in the CLI group
  • New tests/test_port_diag_cpu.py: 17 CPU-only tests
  • Updated docs/cli/diagnostics.rst: CLI reference documentation
  • New docs/troubleshooting/port-conflict.rst: troubleshooting guide with minimal runnable example

Related issue

Fixes #228

Type of change

  • ✨ New feature

How was it tested?

Automated tests

pytest tests/test_port_diag_cpu.py -v

Result: 17 passed.

Manual tests on Linux (Kaggle)

Test 1: Free port

areno port-check --host 127.0.0.1 --port 18080
Port diagnostic: 127.0.0.1:18080
  Status: available
  Suggestion: Port is available for binding.

Exit code: 0

Test 2: Occupied port — PID and process detected

areno port-check --host 127.0.0.1 --port 19000
Port diagnostic: 127.0.0.1:19000
  Status: occupied
  PID: 543
  Process: python3
  AReno child: no
  Bind error: [Errno 98] Address already in use
  Suggestion: Port 19000 is held by 'python3' (PID 543). Change the port or stop that process manually.

Exit code: 1

Test 3: areno serve auto-diagnostic before model load (port occupied)

areno serve --model-path Qwen/Qwen3-0.6B --model-hub hf --port 8000
Port diagnostic: 0.0.0.0:8000
  Status: occupied
  PID: 543
  Process: python3
  AReno child: no
  Bind error: [Errno 98] Address already in use
  Suggestion: Port 8000 is held by 'python3' (PID 543). Change the port or stop that process manually.

Exit code: 1 — no model download or loading occurred; diagnostic intercepted startup before resolve_model_ref().

Checklist

  • The PR title summarizes the contribution.
  • Linked the related issue in the description (if any).
  • Existing tests pass (pytest tests/ -k cpu).
  • New behavior is covered by tests.
  • Described the test commands run and any hardware limitations.
  • Public API / CLI changes are additive and backward-compatible (see CONTRIBUTING.md).

Breaking change details

No breaking changes. The port-check command is additive. In areno serve, the diagnostic runs before model initialization but only exits early when the port is occupied by an unrelated process — when the port is available, the existing serve flow is unchanged.

zhou added 3 commits July 28, 2026 15:38
…onAI#228)

- Add areno/cli/port_diag.py with diagnose_port() function
- Integrate diagnostic into serve startup before model init
- Support IPv4/IPv6, permission-denied, stale metadata, bind races
- Add 'areno port-check' CLI command with --host/--port/--json options
- Add 17 CPU-only tests covering success, failure, and edge cases
- Add documentation for port-check command and troubleshooting guide
@dggyey dggyey changed the title Feature/port diagnosis 228 feat(cli): add port ownership diagnosis before serve startup Jul 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Diagnose serving port ownership before startup

1 participant