// Copyright 2021 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.name;

using fuchsia.net;

/// Lookup operation errors.
type LookupError = strict enum {
    /// 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;
};

/// Maximum number of addresses that can be returned by a lookup.
// Chosen to match libc's MAXADDRS.
//
// TODO(https://fxbug.dev/42171305): Remove this when the client can specify the
// maximum number of addresses it can receive.
const MAX_ADDRESSES uint16 = 1024;

/// Provides name and address resolution.
@discoverable
closed protocol Lookup {
    /// Lookup a list of IP addresses by hostname.
    strict LookupIp(struct {
        /// The hostname to look up.
        ///
        /// Must be a valid host domain name; i.e. may not be an IP address in
        /// dotted-decimal notation.
        ///
        /// If it is an Internationalized Domain Name, it must be encoded as per
        /// RFC 3490.
        hostname fuchsia.net.Hostname;
        options @generated_name("LookupIpOptions") table {
            /// Include IPv4 results.
            ///
            /// If not set, interpreted as false.
            1: ipv4_lookup bool;
            /// Include IPv6 results.
            ///
            /// If not set, interpreted as false.
            2: ipv6_lookup bool;
            /// 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).
            ///
            /// If not set, interpreted as false.
            3: sort_addresses bool;
            /// Include the canonical name.
            ///
            /// If not set, interpreted as false.
            @available(added=12)
            4: canonical_name_lookup bool;
        };
    }) -> (struct {
        result @generated_name("LookupResult") table {
            /// The IP addresses resulting from a lookup.
            ///
            /// If sorting was requested, `addresses` is sorted in order of
            /// preference, most preferred destination address first.
            1: addresses vector<fuchsia.net.IpAddress>:MAX_ADDRESSES;
            /// The canonical name of the requested hostname.
            ///
            /// Provided only if requested.
            @available(added=12)
            2: canonical_name fuchsia.net.Hostname;
        };
    }) error LookupError;
    /// Look up a hostname by IP address.
    strict LookupHostname(struct {
        addr fuchsia.net.IpAddress;
    }) -> (struct {
        hostname fuchsia.net.Hostname;
    }) error LookupError;
};