blob: fce8cc7c228844735006c907462a5f217bc080c2 [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_address.mojom";
import "services/network/public/mojom/ip_endpoint.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:
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 {
// This enum corresponds to DnsConfig::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;
// 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;
// Whether source port randomization is required. This uses additional
// resources on some platforms.
Tristate randomize_ports = 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
// (
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;
// 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, and on success (network error code OK) and when results are in
// address form, an AddressList.
// 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, 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;
// If |false|, results will not come from the host cache.
bool allow_cached_response = true;
// If set, the outstanding request can be controlled, eg cancelled, via the
// handle.
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|.
// 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,
ResolveHostParameters? optional_parameters,
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,
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 settings of
// the system that may affect results of host resolution.
// An interface that broadcasts DNS config change events.
interface DnsConfigChangeManager {
// Requests to receive notification when there is a DNS config change.
RequestNotifications(DnsConfigChangeManagerClient client_ptr);