feat(dgw): align gateway scans with local planning

[irvingouj@Devolutions (irvingoujAtDevolution)]

Summary

Brings the gateway's /jet/net/scan API closer to feature parity with the local network scanner, so the same scan request shape can drive both.

New query parameters

• Targets — combinable target=<ip> (single host) and range=<lower>-<upper>. IPv4/IPv6 family validation; rejects ranges over 65 536 addresses with HTTP 400.
• Source selection — repeatable interface_id=<id> plus range_interface_policy=intersect_selected_interfaces|allow_cross_interface_range. Missing/down/loopback-only/no-scan-capable sources or out-of-interface ranges return a structured 400 ({ error, interfaceId, reason } or { error, ranges, interfaceIds }).
• Probe controls — enable_tcp_probes=false suppresses all TCP probes regardless of probe=; otherwise probe=22|rdp|https|... sets the probe list. An explicit probe list (even just probe=ping) is honored verbatim — the default COMMON_PORTS fallback only kicks in when the caller sends no probe= at all.
• Result toggles — report_ping_start, report_ping_success, report_ping_failure, report_tcp_failure, include_host_results. The previous enable_failure and enable_ping_start flags remain as deprecated aliases (see "Behavior changes" below for the enable_failure semantics split).
• Concurrency — max_concurrency, max_ping_concurrency, max_tcp_probe_concurrency.
• Strict bind — interface_bind_strict=true fails the scan if a per-interface socket bind doesn't take effect (default: warn and fall back).

New endpoint

GET /jet/net/interfaces (v2): returns each scan source with a stable id, address, startAddress/endAddress, broadcast address, prefix length, link metadata (MAC, MTU, speed, link type), and per-source capability flags (ipv4, ipv6, subnet, broadcast, zeroConf, tcpProbe, dnsResolve). The id is what interface_id= accepts.

The legacy GET /jet/net/config is retained and now carries RFC 8594 Deprecation: true plus Link: rel="successor-version" headers pointing at /jet/net/interfaces. (No Sunset date until product confirms one.)

New result format

response_format=network_scan_result_v1 opts into a new wire shape:

{ "kind": "host",    "address": "...", "source": "gateway", "discoverySource": "subnet", "isReachable": true,  "hostScanState": "reachable", "responseTimeMs": 7, "interfaceId": "...", "interfaceName": "..." }
{ "kind": "service", "address": "...", "source": "gateway", "discoverySource": "tcp_probe", "isReachable": true, "port": 3389, "serviceLabel": "RDP", "serviceType": "RDP", "responseTimeMs": 12 }

Fields are camelCase with closed lowercase enums (hostScanState ∈ { queued, probing, reachable, unreachable }, discoverySource ∈ { subnet, broadcast, tcp_probe, gateway, zero_conf }). macAddress is in the schema but only populated when neighbor-discovery information is available; it is omitted from the JSON otherwise.

Without the parameter, the legacy event format continues to be emitted unchanged.

Internals

• Per-interface socket bind for ping and TCP probes on Linux (IP_UNICAST_IF/IPV6_UNICAST_IF), macOS (IP_BOUND_IF/IPV6_BOUND_IF), and Windows (IP_UNICAST_IF). Other targets fail to compile (compile_error!).
• Event-bus capacity raised to 8192 and TypedReceiver::recv now treats RecvError::Lagged as recoverable (warn-and-continue) instead of terminating its consumer task. This fixes a class of dropouts where a wave of timeouts could starve the forwarder and cause subsequent successful events to be lost.
• ScannerConfig decomposed into { ports, timing, limits, targeting } sub-structs.
• Discovered hosts/services emit explicit ServiceReachability and LinkType ADTs instead of bare booleans/strings.
• OpenAPI schema regenerated to cover the new query parameters, the new endpoint, and the v1 result DTOs.

Behavior changes worth flagging

These are intentional and align the API with the design plan that drove this PR, but they will surprise any client relying on the pre-PR semantics. None of them affect a client that sends no query parameters at all (the default behavior is unchanged).

1. enable_failure=true now controls only ping-failure events. Pre-PR it enabled both ping-failure and TCP-probe failure entries in one knob, which generated a lot of noise that callers were filtering out client-side. The two streams are now independently gated — to restore the old "both at once" semantics, send enable_failure=true&report_tcp_failure=true together. New clients should prefer the explicit report_ping_failure=true / report_tcp_failure=true flags.
2. probe=ping no longer triggers the COMMON_PORTS fallback. An explicit probe list is taken literally. To also scan the default port list, either omit probe= entirely or list the ports explicitly.
3. probe=ping no longer auto-emits ping-failure events. Matches pre-PR baseline of start + success only. To receive failure events when probe=ping is set, add report_ping_failure=true (preferred) or enable_failure=true (legacy alias).
4. /jet/net/config now sets Deprecation: true plus a Link: ...; rel="successor-version" pointing to /jet/net/interfaces. No Sunset header yet, so clients have unbounded migration time — but they should plan to migrate.
5. response_format=network_scan_result_v1 is opt-in. Legacy is still the default. Anyone parsing the legacy shape needs no change.
6. The report_ping_status parameter was added and then removed in the course of this PR review and was never shipped to a release. Clients should use the three explicit report_ping_{start,success,failure} flags directly.

Test plan

• cargo +nightly fmt --all -- --check
• cargo clippy -p devolutions-gateway -p network-scanner --tests -- -D warnings
• cargo test -p devolutions-gateway --lib api::net
• cargo test -p testsuite --test integration_tests -- network_scanner
• Cross-platform target builds — covered by CI
• Manual smoke test via a standalone Angular/JS harness exercising the new wire shapes and toggles end-to-end

[github-actions]

Let maintainers know that an action is required on their side

• Add the label release-required Please cut a new release (Devolutions Gateway, Devolutions Agent, Jetsocat, PowerShell module) when you request a maintainer to cut a new release (Devolutions Gateway, Devolutions Agent, Jetsocat, PowerShell module)

• Add the label release-blocker Follow-up is required before cutting a new release if a follow-up is required before cutting a new release

• Add the label publish-required Please publish libraries (`Devolutions.Gateway.Utils`, OpenAPI clients, etc) when you request a maintainer to publish libraries (Devolutions.Gateway.Utils, OpenAPI clients, etc.)

• Add the label publish-blocker Follow-up is required before publishing libraries if a follow-up is required before publishing libraries

[Benoît Cortier (CBenoit)]

If I understand correctly, you used Claude to backport the changes made to the net scanner in RDM? Did you notice any improvements?

[Copilot]

Pull request overview

This PR updates Devolutions Gateway’s network scan API to match the newer “local planning” model from network-scanner, including explicit target/range planning, interface-aware source selection, concurrency controls, and an opt-in v1 websocket result shape while keeping legacy behavior for existing clients.

Changes:

• Adds /jet/net/interfaces and documents /jet/net/scan (WebSocket handshake) in OpenAPI; marks /jet/net/config as deprecated via response headers.
• Introduces planning/source inventory and interface-aware execution (including optional interface binding and per-stage concurrency limits) in network-scanner.
• Refactors scan event filtering/serialization into ScanEventFilter with a configurable response format (legacy vs network_scan_result_v1), and reorganizes unit tests under src/tests/.

Reviewed changes

Copilot reviewed 33 out of 34 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
devolutions-gateway/src/openapi.rs	Registers new net scan endpoints/types in the OpenAPI document.
devolutions-gateway/src/api/net.rs	Implements new query params, planning validation, /interfaces, scan streaming changes, and deprecates /config.
devolutions-gateway/Cargo.toml	Extends openapi feature to include network-scanner/openapi.
crates/network-scanner/src/lib.rs	Exposes new modules (planner, results, sources) and mounts in-tree tests.
crates/network-scanner/src/ip_utils.rs	Adds IpFamily, single, intersection, address_count, and equality traits to support planning/validation.
crates/network-scanner/src/planner.rs	Adds target/range + interface selection planning and structured planning errors.
crates/network-scanner/src/sources.rs	Models scan-capable sources with metadata and capability flags; adds system source discovery.
crates/network-scanner/src/scanner.rs	Refactors config into timing/limits/targeting; adds interface bind support and injected source providers.
crates/network-scanner/src/task_utils.rs	Switches task context creation to use plan_scan output (planned ranges + sources).
crates/network-scanner/src/results.rs	Adds ScanEventFilter and v1 result event model + legacy serialization.
crates/network-scanner/src/ping.rs	Adds ping queue events, interface binding, and optional concurrency limiting.
crates/network-scanner/src/port_discovery.rs	Adds interface binding, optional concurrency limiting, and richer failure classification/time measurement.
crates/network-scanner/src/netbios.rs	Adds timing to NetBIOS success events.
crates/network-scanner/src/mdns.rs	Adds timing to mDNS resolved events.
crates/network-scanner/src/event_bus.rs	Adds AnyScannerEvent wrapper for generic subscriptions; adjusts broadcast match for new shape.
crates/network-scanner/src/broadcast/mod.rs	Extends broadcast events with optional timing.
crates/network-scanner/src/broadcast/asynchronous.rs	Measures and emits broadcast RTT timing.
crates/network-scanner/examples/scan.rs	Updates example for refactored scanner config and targeting controls.
crates/network-scanner/examples/port_discovery.rs	Updates example for new scan_ports signature (concurrency + interface bind).
crates/network-scanner/examples/ping_range.rs	Updates example for new ping_range signature (concurrency + interface bind).
crates/network-scanner/src/tests/mod.rs	Adds src/tests module root for in-tree unit tests.
crates/network-scanner/src/tests/ip_utils.rs	Moves/expands unit coverage for IP range utilities.
crates/network-scanner/src/tests/planner.rs	Adds unit tests for planning/source selection and policy combinations.
crates/network-scanner/src/tests/results.rs	Adds unit tests for legacy/v1 serialization and filter matrix behavior.
crates/network-scanner/src/tests/sources.rs	Adds unit tests for source selection/helpers.
crates/network-scanner/src/tests/task_utils.rs	Adds unit tests for context planning/execution config mapping.
crates/network-scanner/Cargo.toml	Adds serde + optional utoipa feature for OpenAPI schema derivations; adjusts platform deps.
crates/network-scanner-proto/src/lib.rs	Adds crate-level docs and mounts in-tree tests module.
crates/network-scanner-proto/src/netbios.rs	Moves tests out of module body.
crates/network-scanner-proto/src/tests/mod.rs	Adds src/tests module root for proto unit tests.
crates/network-scanner-proto/src/tests/netbios.rs	Adds extracted NetBIOS protocol parsing tests.
crates/network-scanner-net/src/socket.rs	Adds cross-platform socket interface binding helper.
crates/network-scanner-net/Cargo.toml	Adds libc dep for unix setsockopt implementation.
Cargo.lock	Updates dependency graph for new features/platform changes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 34 out of 35 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[irvingouj@Devolutions (irvingoujAtDevolution)]

If I understand correctly, you used Claude to backport the changes made to the net scanner in RDM? Did you notice any improvements?

Updated upon request from Paul, mainly to make the request/response shape easier to use on C# side.

[Paul Dumais (pauldumais)]

LGTM

[Benoît Cortier (CBenoit)]

I need to review this file a bit more carefully

[Benoît Cortier (CBenoit)]

LGTM