blob: a04669420a0fff1a082ee5e5cdbb6295ea26b0bc [file] [log] [blame]
// Copyright 2018 The Chromium Authors
// 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/host_resolver_endpoint_result.mojom";
import "services/network/public/mojom/ip_address.mojom";
import "services/network/public/mojom/ip_endpoint.mojom";
import "services/network/public/mojom/network_anonymization_key.mojom";
import "services/network/public/mojom/network_param.mojom";
import "services/network/public/mojom/request_priority.mojom";
import "url/mojom/scheme_host_port.mojom";
struct DnsOverHttpsServerConfig {
string server_template;
array<array<network.mojom.IPAddress>> endpoints;
// The DNS over HTTPS configuration, containing zero or more servers.
struct DnsOverHttpsConfig {
array<DnsOverHttpsServerConfig> servers;
// 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 {
// This enum corresponds to net::SecureDnsPolicy
enum SecureDnsPolicy {
// The "bootstrap" policy is only used within the network process, so it is
// not exposed via Mojo.
// The target host of ResolveHost method.
union HostResolverHost {
url.mojom.SchemeHostPort scheme_host_port;
HostPortPair host_port_pair;
// 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;
// DNS over HTTPS configuration, containing servers to query.
DnsOverHttpsConfig? dns_over_https_config;
// The SecureDnsMode to use when resolving queries. If set, it overrides
// the resolver's current configured mode, and can in turn be overridden by
// ResolveHostParameters.secure_dns_policy.
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;
// Whether to clear data read from the system HOSTS file.
bool clear_hosts = 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.
// If results are not in address form, e.g. for a TXT request,
// `resolved_addresses` and `endpoint_results_with_metadata` may be either
// empty or null.
// 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.
// TODO( HostResolverEndpointResult is intended to be
// a full replacement for AddressList, so it should be modified to include all
// results, not just those with metadata, and be renamed accordingly. Maybe
// just delete the AddressList result entirely while at it to avoid any
// concerns of passing redundant data.
OnComplete(int32 result,
ResolveErrorInfo resolve_error_info,
AddressList? resolved_addresses,
array<HostResolverEndpointResult>? endpoint_results_with_metadata);
// One or more On...Results() methods may be called when non-address results
// are available and non-empty. 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;
// Controls the resolver's Secure DNS behavior for this request.
SecureDnsPolicy secure_dns_policy = SecureDnsPolicy.ALLOW;
// Enumeration for specifying the purpose of a host resolve request.
// These values are used for UMA. Entries should not be reordered. Keep this
// in sync with tools/metrics/histograms/enums.xml.
// TODO( Consider adding more values if kPreconnect isn't
// a majority of the purpose of host resolve requests.
enum Purpose {
// Specifies the purpose of the request.
Purpose purpose = Purpose.kUnspecified;
// 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_anonymization_key` specifies what NetworkAnonymizationKey to use
// as index into the host cache. This both allows a URLLoader created with the
// same NetworkAnonymizationKey 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 NetworkAnonymizationKey.
// 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`.
// When `host` is a SchemeHostPort, behaves under the assumption that the
// resolution is being done for the purpose of making a connection with the
// specified scheme to the specified host and port. This could result in
// scheme-specific DNS queries, e.g. for HTTPS resource records, and special
// errors if DNS indicates a connection should not be made using the
// specified scheme, e.g. ERR_DNS_NAME_HTTPS_ONLY indicates that a connection
// should not be made without first redirecting an http or ws request to an
// https or wss request.
ResolveHost(HostResolverHost host,
NetworkAnonymizationKey network_anonymization_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);