Enum ControllerRequest

pub enum ControllerRequest {
    StartHermeticNetworkRealm {
        netstack: Netstack,
        responder: ControllerStartHermeticNetworkRealmResponder,
    },
    StopHermeticNetworkRealm {
        responder: ControllerStopHermeticNetworkRealmResponder,
    },
    AddInterface {
        mac_address: MacAddress,
        name: String,
        wait_any_ip_address: bool,
        responder: ControllerAddInterfaceResponder,
    },
    StartStub {
        component_url: String,
        responder: ControllerStartStubResponder,
    },
    StopStub {
        responder: ControllerStopStubResponder,
    },
    Ping {
        target: IpAddress,
        payload_length: u16,
        interface_name: Option<String>,
        timeout: i64,
        responder: ControllerPingResponder,
    },
    PollUdp {
        target: SocketAddress,
        payload: Vec<u8>,
        timeout: i64,
        num_retries: u16,
        responder: ControllerPollUdpResponder,
    },
    JoinMulticastGroup {
        address: IpAddress,
        interface_id: u64,
        responder: ControllerJoinMulticastGroupResponder,
    },
    LeaveMulticastGroup {
        address: IpAddress,
        interface_id: u64,
        responder: ControllerLeaveMulticastGroupResponder,
    },
    StartDhcpv6Client {
        params: NewClientParams,
        responder: ControllerStartDhcpv6ClientResponder,
    },
    StopDhcpv6Client {
        responder: ControllerStopDhcpv6ClientResponder,
    },
    StartOutOfStackDhcpv4Client {
        payload: ControllerStartOutOfStackDhcpv4ClientRequest,
        responder: ControllerStartOutOfStackDhcpv4ClientResponder,
    },
    StopOutOfStackDhcpv4Client {
        payload: ControllerStopOutOfStackDhcpv4ClientRequest,
        responder: ControllerStopOutOfStackDhcpv4ClientResponder,
    },
}

A controller for creating and manipulating the Network Test Realm.

The Network Test Realm corresponds to a hermetic network realm with a Netstack under test. The Controller protocol is responsible for:

• Configuring the Network Test Realm and its child components. This includes the Netstack under test and the other relevant network components (e.g. a DHCP server).
• Coordinating interactions with the system’s Netstack. This includes temporarily taking over and mutating system interfaces.

Variants

StartHermeticNetworkRealm

Starts a hermetic network realm corresponding to netstack.

Any previously running hermetic network realm will be terminated before the new realm is started. The configured realm will contain a subset of the components in the standard network realm. In particular, it will contain:

• A Netstack instance that corresponds to the provided netstack
• A DHCP server
• A DHCPv6 client
• A DNS resolver

• request netstack the type of Netstack that will be run.

• error INTERNAL for internal errors, including failure to start the specified netstack.

Fields

netstack: Netstack

responder: ControllerStartHermeticNetworkRealmResponder

StopHermeticNetworkRealm

Stops any running hermetic network realm.

All components in the hermetic network realm will be stopped. Similarly, any interfaces that were previously disabled on the system’s Netstack will be re-enabled on a best-effort basis. That is, a failure to re-enable an interface will not result in this method returning an error.

• error HERMETIC_NETWORK_REALM_NOT_RUNNING if a hermetic network realm is not running.
• error INTERNAL for internal errors, including failure to destroy the realm.

Fields

responder: ControllerStopHermeticNetworkRealmResponder

AddInterface

Attaches an interface to the hermetic Netstack.

The interface that corresponds to mac_address will disabled on the system’s Netstack, but enabled on the hermetic Netstack.

• request mac_address address of the interface to be added to the hermetic Netstack.
• request name the name to assign to the new interface.
• request wait_any_ip_address whether to wait for any IP address to be assigned to the interface before returning. This is helpful for tests that want to ensure the autoconfigured IP address is assigned and has completed duplicate address detection before proceeding.

• error ALREADY_EXISTS if an interface with name already exists on the hermetic Netstack.
• error HERMETIC_NETWORK_REALM_NOT_RUNNING if there is no running hermetic network realm.
• error INTERFACE_NOT_FOUND if an interface with mac_address could not be found on the system.
• error INTERNAL for internal errors, including failure to read the system’s interfaces or configure an interface.

Fields

mac_address: MacAddress

name: String

wait_any_ip_address: bool

responder: ControllerAddInterfaceResponder

StartStub

Starts a test stub.

Any previously running stub will be terminated before the provided stub corresponding to component_url is started.

• request component_url the URL of the component to run.

• error COMPONENT_NOT_FOUND if a component correspodning to component_url could not be resolved.
• error HERMETIC_NETWORK_REALM_NOT_RUNNING if there is no running hermetic network realm.
• error INTERNAL for internal errors, including failure to add the desired stub within the hermetic network realm.
• error INVALID_ARGUMENTS if the component_url is malformed.

Fields

component_url: String

responder: ControllerStartStubResponder

StopStub

Stops the currently running stub.

Other existing hermetic network realm components will continue to be run after this is invoked.

• error HERMETIC_NETWORK_REALM_NOT_RUNNING if there is no running hermetic network realm.
• error STUB_NOT_RUNNING if there is no running stub.
• error INTERNAL for internal errors, including failure to destroy the stub component.

Fields

responder: ControllerStopStubResponder

Ping

Sends an ICMP echo request to the target using a socket provided by the hermetic Netstack.

• request target the address to ping.
• request payload_length the body size of the ICMP packet. Specifically, the packet body will be filled with zeros of payload_length.
• request interface_name an optional interface to bind the socket to.
• request timeout a timeout in nanoseconds to wait for a reply. If less than or equal to 0, then returns success immediately after the ping is sent.

• error HERMETIC_NETWORK_REALM_NOT_RUNNING if there is no running hermetic network realm.
• error INTERFACE_NOT_FOUND if interface_name does not exist in the hermetic Netstack.
• error INTERNAL for internal errors, including failure to create a socket or generate the ping request and response.
• error INVALID_ARGUMENTS if target corresponds to a link-local address and an interface_name is not specified or the payload_length exceeds the maximum allowable size.
• error PING_FAILED if there was an error sending or receiving the ping.
• error TIMEOUT_EXCEEDED if the ping reply is not received before the specifed timeout.

Fields

target: IpAddress

payload_length: u16

interface_name: Option<String>

timeout: i64

responder: ControllerPingResponder

PollUdp

Polls the specified socket address with UDP datagrams containing the specified payload using a socket provided by the hermetic Netstack.

Waits for a single reply from the target address and returns it.

• request target the socket address to poll.
• request payload the content to place in the UDP datagram.
• request timeout a timeout in nanoseconds to wait for a reply, per retry.
• request num_retries the number of poll attempts to make before giving up and returning an error.

• error HERMETIC_NETWORK_REALM_NOT_RUNNING if there is no running hermetic network realm.
• error ADDRESS_UNREACHABLE if all poll attempts expire without successfully receiving a reply from the target address, and no route was found to the target address.
• error TIMEOUT_EXCEEDED if the target address was routable, but all of the retry attempts expire without successfully receiving a reply from the target address.
• error INTERNAL for internal errors, including failure to create a socket or other failures to send/receive datagrams from the target address.

Fields

target: SocketAddress

payload: Vec<u8>

timeout: i64

num_retries: u16

responder: ControllerPollUdpResponder

JoinMulticastGroup

Joins a multicast group.

Membership will be maintained until LeaveMulticastGroup or StopHermeticNetworkRealm is invoked.

• request address the group address to join.
• request interface_id the interface that should be used to join the group. A value of 0 indicates that any interface may be used.

• error ADDRESS_IN_USE if the provided address was previously joined.
• error HERMETIC_NETWORK_REALM_NOT_RUNNING if there is no running hermetic network realm.
• error INTERNAL for internal errors.
• error INVALID_ARGUMENTS if the specified interface_id does not exist or the address does not correspond to a valid multicast address.

Fields

address: IpAddress

interface_id: u64

responder: ControllerJoinMulticastGroupResponder

LeaveMulticastGroup

Leaves a multicast group that was previously joined using the JoinMulticastGroup method.

• request address the group address to leave.
• request interface_id the interface that was previously used to join the multicast group.

• error ADDRESS_NOT_AVAILABLE if the provided address was not previously joined.
• error HERMETIC_NETWORK_REALM_NOT_RUNNING if there is no running hermetic network realm.
• error INTERNAL for internal errors, including failure to connect to hermetic network realm services.
• error INVALID_ARGUMENTS if the specified interface_id does not exist or the address does not correspond to a valid multicast address.

Fields

address: IpAddress

interface_id: u64

responder: ControllerLeaveMulticastGroupResponder

StartDhcpv6Client

Starts a DHCPv6 client with the provided parameters.

• request params parameters to start this DHCPv6 client with. Required.

• error HERMETIC_NETWORK_REALM_NOT_RUNNING if there is no running hermetic network realm.
• error INTERNAL for internal errors, including failure to connect to hermetic network realm services.
• error INVALID_ARGUMENTS if any required parameters are omitted.
• error ALREADY_EXISTS if there is a client running on the interface identified by params.interface_id already.

Fields

params: NewClientParams

responder: ControllerStartDhcpv6ClientResponder

StopDhcpv6Client

Stops all DHCPv6 clients.

• error DHCPV6_CLIENT_NOT_RUNNING if no DHCPv6 client is running.

Fields

responder: ControllerStopDhcpv6ClientResponder

StartOutOfStackDhcpv4Client

Starts a DHCPv4 client on the provided interface.

• request interface_id the interface to start a DHCPv4 client on. Required.

Fields

payload: ControllerStartOutOfStackDhcpv4ClientRequest

responder: ControllerStartOutOfStackDhcpv4ClientResponder

StopOutOfStackDhcpv4Client

Stops the DHCPv4 client on the provided interface.

• request interface_id the interface to stop a DHCPv4 client client on. Required.

• error DHCPV4_CLIENT_NOT_RUNNING if no DHCPv4 client is running.
• error DHCPV4_CLIENT_SHUTDOWN_FAILED if shutting down the DHCPv4 client failed.

Fields

payload: ControllerStopOutOfStackDhcpv4ClientRequest

responder: ControllerStopOutOfStackDhcpv4ClientResponder

Implementations

impl ControllerRequest

pub fn into_start_hermetic_network_realm( self, ) -> Option<(Netstack, ControllerStartHermeticNetworkRealmResponder)>

pub fn into_stop_hermetic_network_realm( self, ) -> Option<ControllerStopHermeticNetworkRealmResponder>

pub fn into_add_interface( self, ) -> Option<(MacAddress, String, bool, ControllerAddInterfaceResponder)>

pub fn into_start_stub(self) -> Option<(String, ControllerStartStubResponder)>

pub fn into_stop_stub(self) -> Option<ControllerStopStubResponder>

pub fn into_ping( self, ) -> Option<(IpAddress, u16, Option<String>, i64, ControllerPingResponder)>

pub fn into_poll_udp( self, ) -> Option<(SocketAddress, Vec<u8>, i64, u16, ControllerPollUdpResponder)>

pub fn into_join_multicast_group( self, ) -> Option<(IpAddress, u64, ControllerJoinMulticastGroupResponder)>

pub fn into_leave_multicast_group( self, ) -> Option<(IpAddress, u64, ControllerLeaveMulticastGroupResponder)>

pub fn into_start_dhcpv6_client( self, ) -> Option<(NewClientParams, ControllerStartDhcpv6ClientResponder)>

pub fn into_stop_dhcpv6_client( self, ) -> Option<ControllerStopDhcpv6ClientResponder>

pub fn into_start_out_of_stack_dhcpv4_client( self, ) -> Option<(ControllerStartOutOfStackDhcpv4ClientRequest, ControllerStartOutOfStackDhcpv4ClientResponder)>

pub fn into_stop_out_of_stack_dhcpv4_client( self, ) -> Option<(ControllerStopOutOfStackDhcpv4ClientRequest, ControllerStopOutOfStackDhcpv4ClientResponder)>

pub fn method_name(&self) -> &'static str

Name of the method defined in FIDL

Trait Implementations

impl Debug for ControllerRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.