services/network/public/mojom/host_resolver.mojom

// Copyright 2018 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.

module network.mojom;

import "mojo/public/mojom/base/time.mojom";
import "services/network/public/mojom/address_list.mojom";
import "services/network/public/mojom/ip_address.mojom";
import "services/network/public/mojom/ip_endpoint.mojom";
import "services/network/public/mojom/network_isolation_key.mojom";
import "services/network/public/mojom/network_param.mojom";
import "services/network/public/mojom/url_loader.mojom";

// A single entry from a HOSTS file.
struct DnsHost {
  string hostname;
  IPAddress address;
};

// An HTTPS server to send DNS queries to, per the DNS Queries over HTTPS spec.
// spec:  https://tools.ietf.org/html/draft-ietf-doh-dns-over-https-12
struct DnsOverHttpsServer {
  // DNS over HTTPS server URI template. Must be HTTPS.
  string server_template;

  // Whether to use POST to do DNS lookups. Otherwise, GET is used. See spec
  // for more details.
  bool use_post = false;
};

// The secure DNS mode specifies what types of lookups (secure/insecure) should
// be performed and in what order when resolving a specific query. This is
// an expanded version of DnsConfig::SecureDnsMode that includes representation
// of an optional SecureDnsMode. Needed because Mojo does not support optional
// enums.
enum OptionalSecureDnsMode {
  NO_OVERRIDE,
  OFF,
  AUTOMATIC,
  SECURE,
};

// This enum corresponds to DnsConfig::SecureDnsMode.
enum SecureDnsMode {
  OFF,
  AUTOMATIC,
  SECURE,
};

// Overridable DNS configuration values for host resolution. All fields default
// to a non-overriding state where the relevant value will be used from system
// DNS configuration.
struct DnsConfigOverrides {
  // Representation of an optional boolean. Needed because Mojo does not support
  // optional primitive types.
  enum Tristate {
    NO_OVERRIDE,
    TRISTATE_TRUE,
    TRISTATE_FALSE,
  };

  // List of nameserver addresses.
  array<IPEndPoint>? nameservers;

  // Suffix search list, used on first lookup when number of dots in given name
  // is less than |ndots|.
  array<string>? search;

  // Entries from a HOSTS file. This array is intended for serialization to/from
  // a lookup map, so unlike the source data from actual HOSTS files, each entry
  // should represent a unique host query key (|hostname| and AddressFamily).
  array<DnsHost>? hosts;

  // Whether suffix search should be performed for multi-label names.
  Tristate append_to_multi_label_name = Tristate.NO_OVERRIDE;

  // Minimum number of dots before global resolution precedes |search|.
  int8 ndots = -1;  // -1 for no override.

  // Time between retransmissions, see res_state.retrans.
  mojo_base.mojom.TimeDelta? timeout;

  // Maximum number of attempts, see res_state.retry.
  int32 attempts = -1;  // -1 for no override.

  // Whether to roundrobin entries in |nameservers| for subsequent requests.
  Tristate rotate = Tristate.NO_OVERRIDE;

  // Whether system configuration uses local IPv6 connectivity, e.g.,
  // DirectAccess. This is exposed for HostResolver to skip IPv6 probes,
  // as it may cause them to return incorrect results.
  Tristate use_local_ipv6 = Tristate.NO_OVERRIDE;

  // List of servers to query over HTTPS, queried in order
  // (https://tools.ietf.org/id/draft-ietf-doh-dns-over-https-12.txt).
  array<DnsOverHttpsServer>? dns_over_https_servers;

  // The default SecureDnsMode to use when resolving queries. It can be
  // for individual requests such as requests to resolve a DoH server hostname.
  OptionalSecureDnsMode secure_dns_mode = OptionalSecureDnsMode.NO_OVERRIDE;

  // Whether automatic upgrade to DNS over HTTPS servers is permitted.
  Tristate allow_dns_over_https_upgrade = Tristate.NO_OVERRIDE;

  // List of providers to exclude from upgrade mapping. See the
  // mapping in net/dns/dns_util.cc for provider ids.
  array<string>? disabled_upgrade_providers;
};

// Host resolution error info.
struct ResolveErrorInfo {
  // Underlying network error code. See net/base/net_error_list.h for error
  // descriptions.
  int32 error;

  // Whether |error| came from a DNS-over-HTTPS lookup. This will be false if
  // the answer was obtained from the cache or if |error| is net::OK since this
  // field is intended to identify secure DNS *network* failures.
  bool is_secure_network_error = false;
};

// Control handle used to control outstanding NetworkContext::ResolveHost
// requests. Handle is optional for all requests, and may be closed at any time
// without affecting the request.
//
// TODO(crbug.com/821021): Add support to change priority.
interface ResolveHostHandle {
  // Requests cancellation of the resolution request. Doing so may have no
  // effect if a result was already sent. If successful, cancellation results in
  // ResolveHostClient::OnComplete being invoked with |result|, which should be
  // a non-OK network error code.
  Cancel(int32 result);
};

// Response interface used to receive results of NetworkContext::ResolveHost
// requests.
//
// If only some result types are expected for an implementation, e.g. only
// address types will be queried, see
// services/network/public/cpp/resolve_host_client_base.h for a partial C++
// implementation that allows overriding just expected result types.
interface ResolveHostClient {
  // Called on completion of a resolve host request. Results are a network error
  // code, additional error info, and on success (result == OK,
  // resolve_error_info.error == OK) and when results are in address form, an
  // AddressList. The error code in |resolve_error_info.error| should be used
  // when detailed error information is needed, whereas the error code in
  // |result| should be used when less specific error information (i.e. OK vs
  // ERR_NAME_NOT_RESOLVED) is sufficient.
  //
  // Always called last to signal completion of the ResolveHost() request.
  // Unless the ResolveHostClient is closed, this method will always be called
  // exactly once, and afterwards, no more methods in the interface will be
  // called.
  OnComplete(int32 result,
             ResolveErrorInfo resolve_error_info,
             AddressList? resolved_addresses);

  // One or more On...Results() methods may be called when non-address results
  // are available. Always called before OnComplete().
  OnTextResults(array<string> text_results);
  OnHostnameResults(array<HostPortPair> hosts);
};

// DNS query type for a ResolveHostRequest.
// See:
// https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-4
enum DnsQueryType {
  UNSPECIFIED,
  A,
  AAAA,
  TXT,
  PTR,
  SRV,
};

// Parameter-grouping struct for additional optional parameters for
// HostResolver::ResolveHost() calls. All fields are optional and have a
// reasonable default.
struct ResolveHostParameters {
  // Requested DNS query type. If UNSPECIFIED, resolver will pick A or AAAA (or
  // both) based on IPv4/IPv6 settings.
  DnsQueryType dns_query_type = DnsQueryType.UNSPECIFIED;

  // The initial net priority for the host resolution request.
  RequestPriority initial_priority = RequestPriority.kLowest;

  // Enumeration to specify the allowed results source for requests.
  enum Source {
    // Resolver will pick an appropriate source. Results could come from DNS,
    // MulticastDNS, HOSTS file, etc.
    ANY,

    // Results will only be retrieved from the system or OS, e.g. via the
    // getaddrinfo() system call.
    SYSTEM,

    // Results will only come from DNS queries.
    DNS,

    // Results will only come from Multicast DNS queries.
    MULTICAST_DNS,

    // No external sources will be used. Results will only come from fast local
    // sources that are available no matter the source setting, e.g. cache,
    // hosts file, IP literal resolution, etc.
    LOCAL_ONLY,
  };

  // The source to use for resolved addresses. Default allows the resolver to
  // pick an appropriate source. Only affects use of big external sources (eg
  // calling the system for resolution or using DNS). Even if a source is
  // specified, results can still come from cache, resolving "localhost" or IP
  // literals, etc.
  Source source = Source.ANY;

  // Cache usage mode for ResolveHostRequest. Values corresponding to
  // HostResolver::ResolveHostParameters::CacheUsage
  enum CacheUsage {
    // Results may come from the host cache if non-stale.
    ALLOWED,

    // Results may come from the host cache even if stale (by expiration or
    // network changes).
    STALE_ALLOWED,

    // Results will not come from the host cache.
    DISALLOWED,
  };

  // Indicates what DNS cache entries, if any, can be used to provide a
  // response.
  CacheUsage cache_usage = CacheUsage.ALLOWED;

  // If set, the outstanding request can be controlled, eg cancelled, via the
  // handle.
  pending_receiver<ResolveHostHandle>? control_handle;

  // If |true|, requests that the resolver include AddressList::canonical_name
  // in the results. If the resolver can do so without significant performance
  // impact, canonical_name may still be included even if parameter is set to
  // |false|.
  bool include_canonical_name = false;

  // Hint to the resolver that resolution is only being requested for loopback
  // hosts.
  bool loopback_only = false;

  // Set |true| iff the host resolve request is only being made speculatively
  // to fill the cache and the result addresses will not be used. The request
  // will receive special logging/observer treatment, and
  // ResolveHostClient::OnComplete will not receive any addresses.
  bool is_speculative = false;

  // Set to override the resolver's default secure dns mode for this request.
  OptionalSecureDnsMode secure_dns_mode_override =
      OptionalSecureDnsMode.NO_OVERRIDE;
};

// Response interface used to receive notifications from
// HostResolver::MdnsListen requests. All methods have a |query_type| field to
// allow a single BindingSet and implementation to be used to listen for updates
// for multiple types for the same host.
interface MdnsListenClient {
  enum UpdateType {
    ADDED,
    CHANGED,
    REMOVED
  };

  OnAddressResult(UpdateType update_type,
                  DnsQueryType query_type,
                  IPEndPoint endpoint);
  OnTextResult(UpdateType update_type,
               DnsQueryType query_type,
               array<string> text_records);
  OnHostnameResult(UpdateType update_type,
                   DnsQueryType query_type,
                   HostPortPair host);

  // For results which may be valid MDNS but are not handled/parsed by network
  // service, e.g. pointers to the root domain.
  OnUnhandledResult(UpdateType update_type, DnsQueryType query_type);
};

// Interface that can be passed to code/processes without direct access to
// NetworkContext to make ResolveHost requests. If destroyed, all outstanding
// ResolveHost and MdnsListen requests from the destroyed interface will be
// cancelled.
interface HostResolver {
  // Resolves the given hostname (or IP address literal). Results are a network
  // error code, and on success (network error code OK), an AddressList. All
  // results are sent via the passed |response_client|.
  //
  // |network_isolation_key| specifies what NetworkIsolationKey to use as an
  // index into the host cache. This both allows a URLLoader created with the
  // same NetworkIsolationKey to access the host cache entry populated by a
  // call to the HostResolver, and prevents the result from being leaked to
  // URLLoaders made using a different NetworkIsolationKey.
  //
  // Additional optional parameters may be set using |optional_parameters|. If
  // unset, reasonable defaults will be used, equivalent to using a
  // ResolveHostParameters struct without changing any fields from their default
  // values.
  //
  // Results in ERR_NAME_NOT_RESOLVED if hostname is invalid, or if it is an
  // incompatible IP literal (e.g. IPv6 is disabled and it is an IPv6 literal).
  //
  // All outstanding requests are cancelled if the HostResolver or parent
  // NetworkContext are destroyed. Such requests will receive ERR_FAILED via
  // |response_client|.
  ResolveHost(HostPortPair host,
              NetworkIsolationKey network_isolation_key,
              ResolveHostParameters? optional_parameters,
              pending_remote<ResolveHostClient> response_client);

  // Starts a listener to watch for updates to a multicast DNS result. Result is
  // a network error code indicating the success of starting the listener. On
  // success (result OK), |response_client| will begin receiving update
  // notifications.
  //
  // All outstanding listeners are cancelled and will receive no further
  // notifications if the HostResolver or parent NetworkContext are destroyed.
  MdnsListen(HostPortPair host,
             DnsQueryType query_type,
             pending_remote<MdnsListenClient> response_client)
      => (int32 result);
};

// A client interface that subscribes to DNS config change events from
// DnsConfigChangeManager.
interface DnsConfigChangeManagerClient {
  // Notifies that a potential change has been detected in the DNS configuration
  // that may affect results of host resolution. May be a change in system DNS
  // settings or effective changes added on top by Chrome net code.
  OnDnsConfigChanged();
};

// An interface that broadcasts DNS config change events.
interface DnsConfigChangeManager {
  // Requests to receive notification when there is a DNS config change.
  RequestNotifications(pending_remote<DnsConfigChangeManagerClient> client);
};