// Copyright 2020 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.dhcpv6;

using fuchsia.net.interfaces.admin;
using fuchsia.net.name;
using fuchsia.net;
using zx;

/// Default port a DHCPv6 client should listen to according to [RFC 8415,
/// Section 7.2](https://tools.ietf.org/html/rfc8415#section-7.2).
const uint16 DEFAULT_CLIENT_PORT = 546;

/// Configuration for an address type.
table AddressConfig {
    /// Number of addresses.
    ///
    /// If not set, interpreted as 0 (no addresses will be requested).
    1: uint8 address_count;

    /// Preferred addresses.
    ///
    /// Used for requesting specific addresses from DHCPv6 servers. The
    /// addresses are used as hints by DHCPv6 servers, but may be ignored. If
    /// the DHCPv6 server does not assign the preferred addresses and responds
    /// with different addresses instead, the DHCPv6 client's behaviour is to
    /// accept the assigned addresses.
    ///
    /// If the size of `preferred_addresses` is greater than `address_count`,
    /// the client will pick from `preferred_addresses` until `address_count`
    /// addresses are assigned to it.
    ///
    /// Optional field. If not set, or if `preferred_addresses` is empty, no
    /// address hints are provided.
    2: vector<fuchsia.net.Ipv6Address>:MAX preferred_addresses;
};

/// Configuration for negotiating addresses.
table AddressAssignmentConfig {
    /// Non-temporary address configuration.
    ///
    /// Configures the client to negotiate non-temporary addresses (IA_NA), as
    /// defined in
    /// [RFC 8415, section 6.2](https://tools.ietf.org/html/rfc8415#section-6.2).
    ///
    /// It not set, interpreted as an empty `AddressConfig` (no non-temporary
    /// addresses will be negotiated).
    1: AddressConfig non_temporary_address_config;
};

/// Configuration for requesting configuration information.
table InformationConfig {
    /// Request a list of available DNS servers
    /// [RFC 3646](https://tools.ietf.org/html/rfc3646).
    ///
    /// If not set, interpreted as false;
    1: bool dns_servers;
};

/// Configuration for starting the DHCPv6 client.
///
/// If the configuration requests both addresses and other configuration
/// parameters, all information is requested in the same message exchange,
/// running in stateful mode. If only configuration parameters are requested
/// (no addresses), the client runs in stateless mode, as described in
/// [RFC 8415, Section 6.1](https://tools.ietf.org/html/rfc8415#section-6.1).
///
/// If the configuration does not request any information (neither addresses
/// nor other configuration information), the [`fuchsia.net.dhcpv6/Client`]
/// creation will fail.
table ClientConfig {
    /// Configuration for negotiating addresses.
    ///
    /// If set, the client runs in stateful mode, as described in
    /// [RFC 8415, Section 6.2](https://tools.ietf.org/html/rfc8415#section-6.2).
    ///
    /// If not set, interpreted as an empty `AddressAssignmentConfig` (no
    /// addresses will be negotiated).
    1: AddressAssignmentConfig address_assignment_config;

    /// Configuration for requesting configuration information.
    ///
    /// If not set, interpreted as an empty `InformationConfig` (no
    /// configuration information will be requested).
    2: InformationConfig information_config;
};

/// Parameters for calling [`fuchsia.net.dhcpv6/ClientProvider.NewClient`].
table NewClientParams {
    /// The ID of the interface the client will run on.
    ///
    /// Required.
    1: uint64 interface_id;

    /// The socket address to use when communicating with servers.
    ///
    /// DHCPv6 servers listen for link-local multicasts, so not using a
    /// link-local address here may cause interoperability issues.
    ///
    /// Client creation will fail with `INVALID_ARGS` if:
    ///
    /// * a multicast address is provided;
    /// * or a link-local address is provided, and its zone index doesn't match
    ///   `interface_id` (Fuchsia has a 1:1 mapping from zone index to interface
    ///   ID).
    ///
    /// Client creation will fail if it fails to bind a socket to this address.
    ///
    /// Required.
    2: fuchsia.net.Ipv6SocketAddress address;

    /// The [`fuchsia.net.dhcpv6/ClientConfig`] the client starts with.
    ///
    /// Client creation will fail if `config` is not requesting any
    /// information.
    ///
    /// Required.
    3: ClientConfig config;
};

/// Provides a method to create new clients.
[Discoverable]
protocol ClientProvider {
    /// Provides a DHCPv6 client.
    ///
    /// + request `params` the parameters to create the client with.
    /// + request `request` the channel handle that can be used to control the
    ///     newly created client. Will be closed if a client cannot be created,
    ///     with an epitaph explaining the reason.
    NewClient(NewClientParams params, request<Client> request);
};

/// Provides methods to watch for discovered network configurations.
///
/// The lifetime of the the client is tied to the channel; closing the channel
/// will result in shutting down the client.
protocol Client {
    compose fuchsia.net.name.DnsServerWatcher;

    /// Returns an address and its parameters.
    ///
    /// Yields a value for every address acquired by the client.
    ///
    /// [`fuchsia.net.interfaces.admin/AddressParameters.address_state_provider`]
    /// is closed if the address becomes invalid (its valid lifetime expires
    /// and Renew and Rebind fail).
    ///
    /// It is invalid to call `WatchAssignmentState` while a previous call is
    /// still pending. Doing so will cause the channel to be closed.
    ///
    /// - response `address` the assigned address.
    /// - response `address_parameters` the parameters of the address.
    WatchAddress()
        -> (fuchsia.net.Subnet address,
            fuchsia.net.interfaces.admin.AddressParameters address_parameters);

    /// Shuts down the `Client`.
    ///
    /// Blocks until any held addresses are gracefully released, as described
    /// in
    /// [RFC 8415, Section 18.2.7](https://tools.ietf.org/html/rfc8415#section-18.2.7).
    ///
    /// The channel is closed after shutdown, regardless of whether an error is
    /// returned.
    ///
    /// * error a `zx.status` if any of the addresses were not gracefully
    ///     released, e.g. the client times out waiting for Reply to Release,
    ///     or the interface is down and sending Release fails.
    Shutdown() -> () error zx.status;
};