Skip to content

Add workspace-level bind interface selection for predictable live tests

Summary

Add a workspace-owned bind-interface selection layer for live tests so orchestration can reliably identify and select the intended network interface before launching eMuleBB, local ED2K services, mixed clients, or controller profiles.

The immediate need is deterministic test behavior on developer and release machines that may have both VPN and LAN adapters. Public-network tests need an explicit VPN path, while local live-stack tests need a predictable LAN or local-only bind path without guessing from adapter order.

Problem

Current live E2E commands accept options such as --p2p-bind-interface-name and --p2p-bind-interface-address, but the workspace does not have one shared resolver that inventories available interfaces, classifies likely VPN versus LAN candidates, validates operator intent, and records the selected bind path in the run evidence.

That leaves broad suites vulnerable to host drift:

  • adapter display names differ across machines and VPN products;
  • Windows interface ordering can change after reconnects, driver updates, or VHD/virtual adapter setup;
  • LAN-local swarms and public-network proof can accidentally inherit the wrong interface;
  • failures are harder to diagnose because the selected interface and rejected candidates are not consistently captured.

Intended Shape

  1. Add a resolver in repos\emulebb-build that can enumerate active IPv4 interfaces, addresses, route metrics, gateway presence, adapter aliases, and obvious virtual/VPN markers.
  2. Add a workspace configuration surface for named bind profiles, at minimum: vpn, lan, and local.
  3. Teach live E2E orchestration to resolve bind profiles before launching child suites and pass explicit bind names or addresses to supported harnesses.
  4. Keep command-line overrides authoritative when the operator supplies an explicit interface name or address.
  5. Write a per-run bind-selection report into the existing test artifact tree with the selected profile, selected adapter/address, rejected candidates, route/metric evidence, and any ambiguity warnings.
  6. Fail fast when a requested profile cannot be resolved or resolves ambiguously, unless the command explicitly opts into a best-effort mode.

Bind Profiles

  • vpn: intended for public-network proof. Prefer an operator-configured VPN adapter name or address. Reject plain LAN candidates unless explicitly overridden.
  • lan: intended for deterministic local live-stack tests that need other local clients to reach the eMuleBB P2P port. Prefer reachable private IPv4 addresses on physical or known local virtual adapters.
  • local: intended for controller-only and loopback-safe tests. Prefer loopback or local-only binds and prevent accidental public-network access.

Constraints

  • Public-network behavior remains opt-in and must follow the live-test network policy.
  • Local live-stack tests must remain local even when a VPN profile is available.
  • The resolver must not hardcode machine-specific adapter names in tracked code or docs. Operator-specific names belong in local config or runtime command-line arguments.
  • Existing suite-specific flags must continue to work while the workspace-level resolver is adopted.
  • The selected bind profile and effective address must be visible in live reports so failures can be reproduced.

Acceptance Criteria

  • [ ] Workspace orchestration can list candidate interfaces and classify likely VPN, LAN, and local bind candidates.
  • [ ] Live E2E commands accept a workspace bind profile and pass deterministic bind data to child suites.
  • [ ] Explicit --p2p-bind-interface-name or --p2p-bind-interface-address overrides remain supported.
  • [ ] Ambiguous or missing requested profiles fail before child suites launch.
  • [ ] Public-network suites can require a VPN profile and local live-stack suites can require a LAN/local profile.
  • [ ] Each live run records bind-selection evidence in the test-report artifact tree.
  • [ ] Focused tests cover VPN/LAN/local profile resolution, explicit override precedence, ambiguity failures, and report serialization.

Validation

  • python -m emule_workspace validate
  • Focused Python tests for bind-profile resolution and override precedence.
  • Focused live E2E smoke using a LAN/local profile.
  • Public-network dry-run or operator-gated proof using a VPN profile.