sdk/fidl/fuchsia.net/namelookup.fidl

// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.net;

/// The maximum number of IPs returned by a lookup.
const uint64 MAX_LOOKUP_IPS = 256;

struct IpAddressInfo {
    /// All of the IPv4 addresses for the requested hostname.
    vector<Ipv4Address>:MAX_LOOKUP_IPS ipv4_addrs;
    /// All of the IPv6 addresses for the requested hostname.
    vector<Ipv6Address>:MAX_LOOKUP_IPS ipv6_addrs;
    /// The canonical name of the requested hostname (usually the DNS CNAME record, if one exists).
    string:256? canonical_name;
};

enum LookupError {
    /// No result was found for this query.
    NOT_FOUND = 1;
    /// The lookup failed, but may succeed at a later time. For instance, the
    /// network or DNS server may be unreachable.
    TRANSIENT = 2;
    /// The lookup failed due to an invalid argument (for instance, the hostname was not encoded
    /// correctly, or was too long).
    INVALID_ARGS = 3;
    /// The lookup failed due to an internal error.
    INTERNAL_ERROR = 4;
};

bits LookupIpOptions : uint8 {
    /// If the lookup should return IPv4 addresses.
    V4_ADDRS = 0b001;
    /// If the lookup should return IPv6 addresses.
    V6_ADDRS = 0b010;
    /// If the lookup should return a canonical_name, if one exists.
    CNAME_LOOKUP = 0b100;
};

/// Lookup operation options.
table LookupIpOptions2 {
    /// Include IPv4 results. Defaults to false.
    1: bool ipv4_lookup;
    /// Include IPv6 results. Defaults to false.
    2: bool ipv6_lookup;
    /// Sort addresses in order of preference.
    ///
    /// It true, Addresses are sorted according to destination address selection described in [RFC
    /// 6724 Section 6](https://tools.ietf.org/html/rfc6724#section-6).
    ///
    /// Defaults to false.
    3: bool sort_addresses;
};

/// The result of a lookup operation.
table LookupResult {
    /// The IP addresses resulting from a lookup.
    ///
    /// If sorting was requested, `addresses` is sorted in order of preference, most preferred
    /// destination address first.
    1: vector<IpAddress>:MAX_LOOKUP_IPS addresses;
};

/// The maximum length of a hostname, as per [RFC 1035 section 2.3.4](https://tools.ietf.org/html/rfc1035#section-2.3.4).
const uint64 MAX_HOSTNAME_SIZE = 255;

/// A hostname.
///
/// Although the maximum length of a domain or hostname is 255 characters,
/// each label within a name must not be longer than 63 characters as per
/// [RFC 1035 section 2.3.4](https://tools.ietf.org/html/rfc1035#section-2.3.4).
/// A label in a host name is the alphanumeric characters or hyphens, seperated
/// by a period (e.g. abc.com has two labels, 'abc' and 'com').
alias Hostname = string:MAX_HOSTNAME_SIZE;

// TODO(https://fxbug.dev/21414): support CNAME.
// TODO(https://fxbug.dev/21415): Figure out a way to expose scope ID for IPv6 addresses.
// TODO(https://fxbug.dev/49741): Move to fuchsia.net.name once build unification is done.
[Discoverable]
protocol NameLookup {
    /// Look up a list of IP addresses by hostname.
    ///
    /// If `hostname` is an Internationalized Domain Name, it must be encoded as per RFC 3490.
    [Deprecated = "Use LookupIp2"]
    LookupIp(Hostname hostname, LookupIpOptions options) -> (IpAddressInfo addr) error LookupError;
    /// Lookup a list of IP addresses by hostname.
    ///
    /// If `hostname` is an Internationalized Domain Name, it must be encoded as per RFC 3490.
    LookupIp2(Hostname hostname, LookupIpOptions2 options) -> (LookupResult result) error LookupError;
    /// Look up a hostname by IP address.
    LookupHostname(IpAddress addr) -> (Hostname hostname) error LookupError;
};