// 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 "net/interfaces/address_list.mojom";
import "services/network/public/mojom/network_param.mojom";
import "services/network/public/mojom/url_loader.mojom";

// 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.
//
// TODO(crbug.com/821021): Add additional methods to receive non-address
// results (eg TXT DNS responses).
interface ResolveHostClient {
  // Called on completion of a resolve host request. Results are a network error
  // code, and on success (network error code OK), an AddressList.
  OnComplete(int32 result, net.interfaces.AddressList? resolved_addresses);
};

// Parameter-grouping struct for additional optional parameters for
// HostResolver::CreateRequest() calls. All fields are optional and have a
// reasonable default.
struct ResolveHostParameters {
  // 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,
  };

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

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

// Interface that can be passed to code/processes without direct access to
// NetworkContext to make ResolveHost requests. If destroyed, all outstanding
// ResolveHost 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|.
  //
  // TODO(crbug.com/821021): Implement more complex functionality to meet full
  // capabilities of Resolve() and DnsClient/MDnsClient functionality.
  ResolveHost(HostPortPair host,
              ResolveHostParameters? optional_parameters,
              ResolveHostClient response_client);
};