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.

// 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;

// Each routine can result in one of the possible verdicts.
[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 SignalStrength routine.
[Extensible]
enum SignalStrengthProblem {
  kWeakSignal,
};

// Problems related to the GatewayCanBePinged routine.
[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.
[Extensible]
enum HasSecureWiFiConnectionProblem {
  kSecurityTypeNone,
  kSecurityTypeWep8021x,
  kSecurityTypeWepPsk,
  kUnknownSecurityType,
};

// Problems related to the DnsResolverPresent routine.
[Extensible]
enum DnsResolverPresentProblem {
  kNoNameServersFound,
  kMalformedNameServers,
  kEmptyNameServers,
};

// Problems related to the DnsLatencyProblem routine.
[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.
[Extensible]
enum DnsResolutionProblem {
  // The routine was unable to successfully resolve the test host
  kFailedToResolveHost,
};

// Problems related to the CaptivePortal routine.
[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.
[Extensible]
enum HttpFirewallProblem {
  // DNS resolution failures above threshold.
  kDnsResolutionFailuresAboveThreshold,
  // Firewall detected.
  kFirewallDetected,
  // A firewall may potentially exist.
  kPotentialFirewall,
};

// Problems related to the HttpsFirewall routine.
[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.
[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.
[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,
};

// 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.
interface NetworkDiagnosticsRoutines {
  // 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.
  LanConnectivity() => (RoutineVerdict verdict);

  // Tests whether there is an acceptable signal strength on wireless networks.
  SignalStrength() => (RoutineVerdict verdict,
      array<SignalStrengthProblem> problems);

  // Tests whether the gateway of connected networks is pingable.
  GatewayCanBePinged() => (RoutineVerdict verdict,
      array<GatewayCanBePingedProblem> problems);

  // Tests whether the WiFi connection is secure. Note that if WiFi is not
  // connected, the routine will result in a |kNotRun| verdict.
  HasSecureWiFiConnection() => (RoutineVerdict verdict,
      array<HasSecureWiFiConnectionProblem> problems);

  // Tests whether a DNS resolver is available to the browser.
  DnsResolverPresent() => (RoutineVerdict verdict,
      array<DnsResolverPresentProblem> problems);

  // Tests whether the DNS latency is below an acceptable threshold.
  DnsLatency() => (RoutineVerdict verdict,
      array<DnsLatencyProblem> problem);

  // Tests whether a DNS resolution can be completed successfully.
  DnsResolution() => (RoutineVerdict verdict,
      array<DnsResolutionProblem> problems);

  // Tests whether the internet connection is behind a captive portal.
  CaptivePortal() => (RoutineVerdict verdict,
      array<CaptivePortalProblem> problems);

  // Tests whether a firewall is blocking HTTP port 80.
  HttpFirewall() => (RoutineVerdict verdict,
      array<HttpFirewallProblem> problems);

  // Tests whether a firewall is blocking HTTPS port 443.
  HttpsFirewall() => (RoutineVerdict verdict,
      array<HttpsFirewallProblem> problems);

  // Tests whether the HTTPS latency is within established tolerance levels for
  // the system.
  HttpsLatency() => (RoutineVerdict verdict,
      array<HttpsLatencyProblem> problems);

  // Tests the device's video conferencing capabalities 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.
  VideoConferencing(string? stun_server_hostname) => (RoutineVerdict verdict,
      array<VideoConferencingProblem> problems, string? support_details);
};