diagnostics/mojo/network_diagnostics.mojom

// Copyright 2020 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
//
// Next MinVersion: 1
//
// Definitions for the NetworkDiagnosticsRoutines API exposed by the browser.
// This API is consumed by cros_healthd to retrieve network diagnostics from
// the browser.
//
// NOTE: This mojom should be kept in sync with the copy in Chromium's repo in
// src/chromeos/services/network_health/public/mojom/network_diagnostics.mojom.

module chromeos.network_diagnostics.mojom;

import "mojo/time.mojom";

// Enumeration of the possible network diagnostic routines. See
// NetworkDiagnosticsRoutines interface for more details.
[Stable, Extensible]
enum RoutineType {
  kLanConnectivity,
  kSignalStrength,
  kGatewayCanBePinged,
  kHasSecureWiFiConnection,
  kDnsResolverPresent,
  kDnsLatency,
  kDnsResolution,
  kCaptivePortal,
  kHttpFirewall,
  kHttpsFirewall,
  kHttpsLatency,
  kVideoConferencing,
  kArcHttp,
  kArcDnsResolution,
  kArcPing,
};

// Each routine can result in one of the possible verdicts.
[Stable, Extensible]
enum RoutineVerdict {
  // Routine ran successfully and no connectivity problem found.
  kNoProblem,
  // Routine ran successfully and connectivity problem found.
  kProblem,
  // Routine has not been run.
  kNotRun,
};

// Problems related to the LanConnectivity routine.
[Stable, Extensible]
enum LanConnectivityProblem {
  kNoLanConnectivity,
};

// Problems related to the SignalStrength routine.
[Stable, Extensible]
enum SignalStrengthProblem {
  kWeakSignal,
};

// Problems related to the GatewayCanBePinged routine.
[Stable, Extensible]
enum GatewayCanBePingedProblem {
  // All gateways are unreachable, hence cannot be pinged.
  kUnreachableGateway,
  // The default network cannot be pinged.
  kFailedToPingDefaultNetwork,
  // The default network has a latency above the threshold.
  kDefaultNetworkAboveLatencyThreshold,
  // One or more of the non-default networks has failed pings.
  kUnsuccessfulNonDefaultNetworksPings,
  // One or more of the non-default networks has a latency above the threshold.
  kNonDefaultNetworksAboveLatencyThreshold,
};

// Problems related to the HasSecureWiFiConnection routine.
[Stable, Extensible]
enum HasSecureWiFiConnectionProblem {
  kSecurityTypeNone,
  kSecurityTypeWep8021x,
  kSecurityTypeWepPsk,
  kUnknownSecurityType,
};

// Problems related to the DnsResolverPresent routine.
[Stable, Extensible]
enum DnsResolverPresentProblem {
  kNoNameServersFound,
  kMalformedNameServers,
  DEPRECATED_kEmptyNameServers, // DEPRECATED: Use kNoNameServersFound instead
};

// Problems related to the DnsLatencyProblem routine.
[Stable, Extensible]
enum DnsLatencyProblem {
  // The routine was unable to resolve one or more hosts.
  kHostResolutionFailure,
  // Average DNS latency across hosts is slightly above expected threshold
  kSlightlyAboveThreshold,
  // Average DNS latency across hosts is significantly above expected threshold
  kSignificantlyAboveThreshold,
};

// Problems related to the DnsResolution routine.
[Stable, Extensible]
enum DnsResolutionProblem {
  // The routine was unable to successfully resolve the test host
  kFailedToResolveHost,
};

// Problems related to the CaptivePortal routine.
[Stable, Extensible]
enum CaptivePortalProblem {
  // No active networks found.
  kNoActiveNetworks,
  // The active network is not connected or the portal state is not available.
  kUnknownPortalState,
  // A portal is suspected but no redirect was provided.
  kPortalSuspected,
  // The network is in a portal state with a redirect URL.
  kPortal,
  // A proxy requiring authentication is detected.
  kProxyAuthRequired,
  // The active network is connected but no internet is available and no proxy
  // was detected.
  kNoInternet,
};

// Problems related to the HttpFirewall routine.
[Stable, Extensible]
enum HttpFirewallProblem {
  // DNS resolution failures above threshold.
  kDnsResolutionFailuresAboveThreshold,
  // Firewall detected.
  kFirewallDetected,
  // A firewall may potentially exist.
  kPotentialFirewall,
};

// Problems related to the HttpsFirewall routine.
[Stable, Extensible]
enum HttpsFirewallProblem {
  // DNS resolution failure rate is high.
  kHighDnsResolutionFailureRate,
  // Firewall detected.
  kFirewallDetected,
  // A firewall may potentially exist.
  kPotentialFirewall,
};

// Problems related to the HttpsLatency routine.
[Stable, Extensible]
enum HttpsLatencyProblem {
  // One or more DNS resolutions resulted in a failure.
  kFailedDnsResolutions,
  // One or more HTTPS requests resulted in a failure.
  kFailedHttpsRequests,
  // HTTPS request latency is high.
  kHighLatency,
  // HTTPS request latency is very high.
  kVeryHighLatency,
};

// Problems related to the VideoConferencing routine.
[Stable, Extensible]
enum VideoConferencingProblem {
  // Failed requests to a STUN server via UDP.
  kUdpFailure,
  // Failed requests to a STUN server via TCP.
  kTcpFailure,
  // Failed to establish a TLS connection to media hostnames.
  kMediaFailure,
};

// Problems related to the ArcHttp routine.
[Stable, Extensible]
enum ArcHttpProblem {
  // Failed to get the ARC Service Manager.
  kFailedToGetArcServiceManager,
  // Failed to get instance of the NetInstance service.
  kFailedToGetNetInstanceForHttpTest,
  // HTTPS request latency is high.
  kHighLatency,
  // HTTPS request latency is very high.
  kVeryHighLatency,
  // One or more HTTP requests resulted in a failure.
  kFailedHttpRequests,
};

// Problems related to the ArcDnsResolution routine.
[Stable, Extensible]
enum ArcDnsResolutionProblem {
  // Failed to get the ARC Service Manager.
  kFailedToGetArcServiceManager,
  // Failed to get instance of the NetInstance service.
  kFailedToGetNetInstanceForDnsResolutionTest,
  // DNS query latency is high.
  kHighLatency,
  // DNS query latency is very high.
  kVeryHighLatency,
  // One or more DNS queries resulted in a failure.
  kFailedDnsQueries,
};

// Problems related to the ArcPing routine.
[Stable, Extensible]
enum ArcPingProblem {
  // Failed to get the ARC Service Manager.
  kFailedToGetArcServiceManager,
  // Failed to get instance of the NetInstance service.
  kFailedToGetNetInstanceForPingTest,
  // Timeout failure when getting managed properties of networks.
  kGetManagedPropertiesTimeoutFailure,
  // All gateways are unreachable, hence cannot be pinged.
  kUnreachableGateway,
  // The default network cannot be pinged.
  kFailedToPingDefaultNetwork,
  // The default network has a latency above the threshold.
  kDefaultNetworkAboveLatencyThreshold,
  // One or more of the non-default networks has failed pings.
  kUnsuccessfulNonDefaultNetworksPings,
  // One of more of the non-default networks has a latency above the threshold.
  kNonDefaultNetworksAboveLatencyThreshold,
};

// Union of all possible routine problems. See each problem enum definition for
// more details.
[Stable]
union RoutineProblems {
  array<LanConnectivityProblem> lan_connectivity_problems;
  array<SignalStrengthProblem> signal_strength_problems;
  array<GatewayCanBePingedProblem> gateway_can_be_pinged_problems;
  array<HasSecureWiFiConnectionProblem> has_secure_wifi_connection_problems;
  array<DnsResolverPresentProblem> dns_resolver_present_problems;
  array<DnsLatencyProblem> dns_latency_problems;
  array<DnsResolutionProblem> dns_resolution_problems;
  array<CaptivePortalProblem> captive_portal_problems;
  array<HttpFirewallProblem> http_firewall_problems;
  array<HttpsFirewallProblem> https_firewall_problems;
  array<HttpsLatencyProblem> https_latency_problems;
  array<VideoConferencingProblem> video_conferencing_problems;
  array<ArcHttpProblem> arc_http_problems;
  array<ArcDnsResolutionProblem> arc_dns_resolution_problems;
  array<ArcPingProblem> arc_ping_problems;
};

// A single routine's result.
[Stable]
struct RoutineResult {
  // The result of the routine.
  RoutineVerdict verdict;
  // The list of detected problems, if any.
  RoutineProblems problems;
  // The timestamp when the routine was completed.
  mojo_base.mojom.Time timestamp;
};

// This interface is to be used by any clients that need to run specific
// network-related diagnostics. Expected clients of this interface are
// NetworkHealth, cros_healthd, and a connectivity diagnostics Web UI (to name
// a few). The bound implementation is intended to live in the browser process.
// Deprecated Methods: 1 - 11
// Next Method ID: 29
[Stable]
interface NetworkDiagnosticsRoutines {
  // Returns the most recent result for the specified routine type, if it has
  // been run.
  GetResult@27(RoutineType routine) => (RoutineResult? result);

  // Returns a map of all previously run routine types and their most recent
  // result.
  GetAllResults@28() => (map<RoutineType, RoutineResult> results);

  // Tests whether the device is connected to a LAN. It is possible that the
  // device may be trapped in a captive portal yet pass this test successfully.
  // Captive portal checks are done separately and are outside of the scope of
  // this routine. See CaptivePortal() below.
  RunLanConnectivity@12() => (RoutineResult result);

  // Tests whether there is an acceptable signal strength on wireless networks.
  RunSignalStrength@13() => (RoutineResult result);

  // Tests whether the gateway of connected networks is pingable.
  RunGatewayCanBePinged@14() => (RoutineResult result);

  // Tests whether the WiFi connection is secure. Note that if WiFi is not
  // connected, the routine will result in a |kNotRun| verdict.
  RunHasSecureWiFiConnection@15() => (RoutineResult result);

  // Tests whether a DNS resolver is available to the browser.
  RunDnsResolverPresent@16() => (RoutineResult result);

  // Tests whether the DNS latency is below an acceptable threshold.
  RunDnsLatency@17() => (RoutineResult result);

  // Tests whether a DNS resolution can be completed successfully.
  RunDnsResolution@18() => (RoutineResult result);

  // Tests whether the internet connection is behind a captive portal.
  RunCaptivePortal@19() => (RoutineResult result);

  // Tests whether a firewall is blocking HTTP port 80.
  RunHttpFirewall@20() => (RoutineResult result);

  // Tests whether a firewall is blocking HTTPS port 443.
  RunHttpsFirewall@21() => (RoutineResult result);

  // Tests whether the HTTPS latency is within established tolerance levels for
  // the system.
  RunHttpsLatency@22() => (RoutineResult result);

  // Tests the device's video conferencing capabilities by testing whether the
  // device can:
  // (1) Contact either a default or specified STUN server via UDP.
  // (2) Contact either a default or specified STUN server via TCP.
  // (3) Reach common media endpoints.
  RunVideoConferencing@23(string? stun_server_hostname)
      => (RoutineResult result);

  // Tests whether ARC can make successful HTTP GET requests to the resources
  // needed during the ARC Provisioning step.
  RunArcHttp@24() => (RoutineResult result);

  // Tests whether ARC can reach the connected networks' gateways.
  RunArcPing@25() => (RoutineResult result);

  // Tests whether ARC can make successful DNS queries to the hostnames
  // needed during the ARC Provisioning step.
  RunArcDnsResolution@26() => (RoutineResult result);
};