blob: 12abd012d6191169d426c91d2e4f7c25330412e0 [file] [log] [blame]
// 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.
@available(added=7)
library fuchsia.net.interfaces;
using fuchsia.hardware.network;
using fuchsia.net;
using zx;
/// The maximum length of an interface name.
// `sizeof((struct ifreq).ifr_name) == 16`; the last byte is reserved for the
// null terminator.
const INTERFACE_NAME_LENGTH uint8 = 15;
/// An interface name as a sequence of bytes.
alias Name = string:INTERFACE_NAME_LENGTH;
// TODO(https://fxbug.dev/42159332): Use built-in empty struct when available.
type Empty = struct {};
/// Information about the preferred lifetime of an IP address or delegated
/// prefix.
@available(added=9)
type PreferredLifetimeInfo = strict union {
/// The end of the preferred lifetime.
///
/// The address/prefix should *not* be considered deprecated if `zx.Time`
/// is in the past. `preferred_until` is exchanged as a means to inform
/// the deadline where deprecation is expected to happen.
///
/// The preferred lifetime of addresses is defined in
/// [RFC 4862, section 2](https://tools.ietf.org/html/rfc4862#section-2).
///
/// Addresses configured using a delegated prefix must have a preferred
/// lifetime no longer than that of the prefix according to
/// [RFC 8415, section 6.3](https://datatracker.ietf.org/doc/html/rfc8415#section-6.3).
///
/// Must be greater than 0. If `zx.Time.INFINITE`, the preferred lifetime
/// does not expire.
1: preferred_until zx.Time;
/// The address/prefix is deprecated.
///
/// Deprecated addresses should no longer be used for initiating
/// new connections unless explicitly requested, or if no other
/// non-deprecated addresses are assigned (as described in
/// [RFC 4862, section 1](https://tools.ietf.org/html/rfc4862#section-1)).
///
/// Addresses configured using a deprecated delegated prefix must also be
/// deprecated according to
/// [RFC 8415, section 6.3](https://datatracker.ietf.org/doc/html/rfc8415#section-6.3).
///
/// An address/prefix can become undeprecated if its preferred lifetime is
/// extended.
2: deprecated Empty;
};
/// Assignment state of an IP address.
@available(added=HEAD)
type AddressAssignmentState = strict enum {
// TODO(https://fxbug.dev/42163322): Replace this comment with FIDL that
// actually reserves 0.
//
// The value of 0 is reserved and should never be added to avoid the
// ambiguity of 0 being the default integer value in some languages. See:
// https://fuchsia.dev/fuchsia-src/concepts/api/fidl#enum.
/// Address assignment is in progress, e.g. Duplicate Address Detection
/// is being performed. The address cannot be used when in this state
/// (cannot bind to it yet or receive packets destined to it).
///
/// The Duplicate Address Detection mechanism is described in
/// [RFC 4862, section 5.4](https://tools.ietf.org/html/rfc4862#section-5.4)
TENTATIVE = 1;
/// The address is assigned to an interface.
ASSIGNED = 2;
/// The address is unavailable, e.g. if the interface holding the address
/// is offline.
UNAVAILABLE = 3;
};
/// Properties of a network interface.
type Properties = table {
/// An opaque identifier for the interface. Its value will not be reused
/// even if the device is removed and subsequently re-added. Immutable.
1: id fuchsia.net.InterfaceId;
/// The addresses currently installed on the interface.
///
/// Addresses are sorted on [`Address.addr`], and no two addresses can have
/// the same `Address.addr` value.
///
/// Only assigned addresses are included unless the watcher was created with
/// [`WatcherOptions.include_non_assigned_addresses`] set to `true`.
2: addresses vector<@generated_name("Address") table {
/// The address and prefix length.
///
/// Required.
1: addr fuchsia.net.Subnet;
/// The time after which the address will no longer be valid.
///
/// Its value must be greater than 0. A value of `ZX_TIME_INFINITE`
/// indicates that the address will always be valid. The value is
/// derived from the monotonic clock.
///
/// As a `zx.Time`, the value has
/// [monotonic clock semantics](https://fuchsia.dev/fuchsia-src/concepts/time/monotonic),
/// which implies that it has no meaning outside of the host on which it
/// was generated and no meaning across host restarts.
///
/// Optional; may be omitted due to disinterest.
2: valid_until zx.Time;
// TODO(https://fxbug.dev/42058987): Send this field to clients.
/// Preferred lifetime information.
///
/// Optional; may be omitted due to disinterest.
@available(added=9)
3: preferred_lifetime_info PreferredLifetimeInfo;
/// The address's assignment state.
///
/// Required.
@available(added=HEAD)
4: assignment_state AddressAssignmentState;
}>:MAX;
/// The device is enabled and its physical state is online.
3: online bool;
/// The device class of the interface. Immutable.
4: device_class strict union {
/// The interface is loopback.
1: loopback Empty;
/// The interface's network device class.
2: device fuchsia.hardware.network.DeviceClass;
};
/// Whether there is a default IPv4 route through this interface.
5: has_default_ipv4_route bool;
/// Whether there is a default IPv6 route through this interface.
6: has_default_ipv6_route bool;
/// The name of the interface. Immutable.
7: name Name;
};
/// Network interface state inspection and observation.
@discoverable
closed protocol State {
/// Initialize a watcher for interface state.
///
/// The server enqueues interface addition, deletion and property changes as
/// they occur, which can then be retrieved via the pipelined protocol.
///
/// + request `options` specifies the behavior of the [`Watcher`].
/// + request `watcher` grants access to a [`Watcher`]. Closed if the queue
/// cannot be allocated or if the queue is full when the server attempts
/// to enqueue an event.
strict GetWatcher(resource struct {
/// Options for configuring the interface state watcher.
options @generated_name("WatcherOptions") table {
// TODO(https://fxbug.dev/42061967): Implement disinterest in address
// properties in NS3.
// TODO(https://fxbug.dev/42061967): Add netemul integration tests
// once fuchsia.net.interfaces.admin/Control.AddAddress supports
// address lifetimes.
/// Bitfield for registering interest in address properties.
///
/// Optional; interpreted as all bits set to 0 if not present.
@available(added=HEAD)
1: address_properties_interest flexible bits : uint64 {
VALID_UNTIL = 0x01;
PREFERRED_LIFETIME_INFO = 0x02;
};
/// Flag to determine if only assigned addresses are returned (where
/// the assignment state is [`AddressAssignmentState::Assigned`]) or
/// all addresses are returned.
///
/// Optional; interpreted as false if not present.
@available(added=HEAD)
2: include_non_assigned_addresses bool;
// TODO(https://fxbug.dev/42061481): Add bitfield for registering
// interest in the other interface property fields.
};
watcher server_end:Watcher;
});
};
/// Observer protocol for changes to network interfaces (addition, deletion, and
/// interface property changes).
closed protocol Watcher {
/// Hanging get for an interface addition/deletion change.
///
/// Clients should only have one call of this method at a time; a second
/// call to this method while a call is already pending will cause the
/// server end of the protocol to be closed.
///
/// If there are N interfaces present at the time the server end of the
/// protocol is initialized, then the first N invocations of this method
/// will return [`Event.existing`] followed by a single [`Event.idle`]
/// indicating that all existing interfaces have been sent. Subsequent calls
/// will immediately return if there is a change to be reported, or block
/// until a change occurs.
///
/// The server may choose to coalesce property change events, e.g. when
/// multiple independent property changes occur. As a result, clients cannot
/// assume that the order in which they observe the interface changes is the
/// order in which the changes occurred.
///
/// - response `event` the interface change event.
strict Watch() -> (struct {
event strict union {
/// Properties of an interface that existed when watching started.
///
/// All interested fields and [`Properties.id`] are set.
1: existing Properties;
/// Properties of an interface that was added while watching.
///
/// All interested fields and [`Properties.id`] are set.
2: added Properties;
/// ID of an interface that was removed while watching.
3: removed fuchsia.net.InterfaceId;
/// Properties of an interface that changed while watching.
///
/// Only [`Properties.id`] and interested fields which have changed
/// are set with the new values.
4: changed Properties;
/// Sentinel value indicating no more [`existing`] events will be
/// sent.
5: idle Empty;
};
});
};