feat: share TCP discovery scanning and target validation

[ankitgoswami]

Reviewable diff: +587/-117 across 10 files (excludes generated, test, and story files).

Summary

Fleet Server and Fleet Nodes gain a shared foundation for discovering miners without an external scanner. This PR centralizes target handling and adds the TCP reachability scanner; the following two PRs switch the runtime callers.

Stack: #1040 (this PR) → #1034 → #1035 → #1036 → #1037

This diff targets main, which already includes #1030 manual discovery fan-out. This PR carries the shared-scanner changes from #1033 onto main. This layer keeps the existing /22 and 1,024-target limits while establishing the scanner and target contract used by the rest of the stack.

Node adoption is in #1034; server adoption and dependency removal in #1035; warnings in #1036; the final API name and capacity increase in #1037.

How it works

Requests and report scopes use the same parsed address intervals, DNS rules, and normalized ports. The shared fleet-node-local-subnet target asks the node to choose its own subnet. Bounded target parsing returns the validated interval for callers to reuse; server-local discovery keeps the broader parser. The new scanner consumes addresses lazily, connects without sending application data, closes each socket, and returns sorted open ports to the existing plugin-identification layer. Each endpoint acquires process-wide capacity before its worker starts. All scanner instances share a 512-worker/socket budget with a three-second connect timeout.

Diagrams

flowchart LR
  R["Discovery targets and ports"] --> T["Shared parsing and DNS policy"]
  T --> S["Bounded TCP connect scan"]
  S --> H["Open ports per host"]
  T --> V["Report scope validation"]
  H --> P["Existing miner plugins in following PRs"]

Loading

Areas of the code involved

Area / package / file	What changed	Why it matters for review
server/internal/domain/netscan	New target parser, DNS/port policy and TCP scanner	Owns enumeration, resource limits and cancellation
server/internal/domain/fleetnode/discovery and cmd/fleetnode	Reuse shared target handling and scope matching	Keeps execution and report admission aligned
server/internal/domain/discoverylimits	Derive target count from the prefix limit	One source for the command bounds
.github/review-policy.json and docs/plans	Retarget review ownership and record the stack	Keeps the discovery trust boundary covered

Key technical decisions & trade-offs

• Use Go standard-library TCP connections; no new scanning dependency or scanning features.
• CIDRs through /30 omit only their actual network and broadcast addresses; /31, /32 and explicit ranges retain their endpoints.
• Resolve DNS once per entry with caller-selected address policy before IPv4 preference. The existing server target helper remains until feat: run Fleet Server discovery without Nmap #1035 replaces its last caller.
• Enforce ten raw port inputs before normalization and deduplication.
• Serialize host callbacks and drain workers before returning errors, retaining open ports found before failure.
• Use one strict IP-list parser at dispatch and execution so range-shaped values cannot pass as hostnames.

Testing & validation

• Scanner and target unit/race tests cover loopback IPv4/IPv6, global socket limits, connection closure, cancellation, partial results, DNS filtering and port normalization.
• Shared scanner, Fleet Node, node discovery and handler race suites pass; server lint and 73 review-policy tests pass.
• A concurrent-scan regression verifies that enumeration waits for global worker capacity; the original implementation fails this test.

Post-deploy monitoring & validation

Release the complete stack with server, nodes and client updated together. On a controlled network, compare expected miners against both server and node discovery, exercise an incomplete scan, and confirm that retained results and its warning reach the client. Pause rollout if expected devices disappear, scans cannot stop within their budgets, or completed reports are lost. No deployment was performed for these draft PRs.

---

Restack validation: affected unit/race suites, server lint, protobuf lint, client type check and 33 focused client tests pass. Database integration tests remain for CI.