blob: 19da4d52eca0605fcb66cafe1ba796da1b6ea98e [file] [log] [blame]
// 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_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_request.mojom";
// An HTTPS server to send DNS queries to, per the DNS Queries over HTTPS spec.
// spec:
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 net::SecureDnsMode that includes representation of an
// optional SecureDnsMode. Needed because Mojo does not support optional enums.
enum OptionalSecureDnsMode {
// This enum corresponds to net::SecureDnsMode.
enum SecureDnsMode {
// 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 {
// 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;
// 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? fallback_period;
// 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
// (
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/ for provider ids.
array<string>? disabled_upgrade_providers;
// Whether to clear data read from the system HOSTS file.
bool clear_hosts = false;
// 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( 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:
enum DnsQueryType {
// 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.
// Results will only be retrieved from the system or OS, e.g. via the
// getaddrinfo() system call.
// Results will only come from DNS queries.
// Results will only come from Multicast DNS queries.
// 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.
// 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.
// Results may come from the host cache even if stale (by expiration or
// network changes).
// Results will not come from the host cache.
// 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 =
// 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 {
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.
// 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);