Skip to main content

Module router

Module router 

Source
Expand description

A Router routes PacketRcs between PacketDevices and the simulated network, enforcing configured send/receive rate limits on the interfaces and the upstream/downstream links to a modeled network provider.

The Router is responsible for actually moving packets around between sockets and the simulated network. It initiates packet forwarding and internally schedules tasks to ensure that packets are continually forwarded over time without exceeding the configured RateLimits.

The Router implemented here is doing the job of multiple real world physical components, rather than being a one-to-one mapping to a known network component. It is managing sending from a physical network interface card at a certain speed, and also it is managing the first-hop router device that the network interface card is attached to, shaping traffic, and using a codel queue to aggregate all its ports up through a single upstream link.

PacketDevices are registered using Router::attach_packet_device, assigning an Ipv4Addr to it. The address provided by the caller will later be passed to RouterContext::get_packet_device_fn to obtain the underlying object that implements the PacketDevice trait. This packet device supplies the router with a stream of packets (through its implementation of PacketDevice::pop) that will be forwarded to the network, and it acts as a sink for incoming packets with a destination address matching the packet device’s address.

Ipv4Addr::LOCALHOST has special meaning, and it is expected that a packet device will be registered at this address. The router uses the device as the loopback device, applying its rate limits for local packets being sent from any device.

The Router operates its own event management queues and its scheduler must be run at appropriate times to faciliate the routing process. Router::run must be called with event RouterEvent::DeviceInterrupt when a packet device changes state from empty to non-empty, to alert an idle router to start forwarding packets from that device. Router::run must be called with event RouterEvent::PacketArrival when a packet arrives from the simulated network. Finally, if Router::run returns an EmulatedTime, then Router::run must be called with event RouterEvent::Wakeup at the specified time. All other routing tasks are handled internally.

The Router is designed to avoid directly relying on Shadow runtime components and to be easy to test with unit tests. This is enabled through the RouterContext object, which defines the minimal external API the router needs to function. This context must be provided when calling Router::run.

A variety of queues are used to model rate limits, as shown below. Each tx queue and rx queue is a lossy rate-limited queue that can drop packets if it becomes bloated (e.g., if we are allowed to push() to a queue at a faster rate than we are allowed to pop() from it based on the configured rate limits). Note, all pop() and push() actions are carried out by the router, not the individual components listed here.

+–––––––+ +–––––––+ | PacketDevice | | PacketDevice | +–––––––+ +–––––––+ | | Event::DeviceInterrupt Event::DeviceInterrupt | | V push() V push() +———–+ +———–+ | Interface | | Interface | | tx queue | | tx queue | +———–+ +———–+ | | pop() @ dev tx rate limit pop() @ dev tx rate limit | | +–––––––+—————+ | V push() +—————––+ | Global router | | tx queue | +—————––+ | pop() @ upstream tx rate limit | V Context::send_packet_fn() +––––––––––+ | packets to network | +––––––––––+ ||| core link ||| models latency, packet loss ||| unlimited bandwidth VVV +–––––––––––+ | packets from network | +–––––––––––+ | RouterEvent::PacketArrival | V push() +—————––+ | Global router | | rx queue | +—————––+ | pop() @ downstream rx rate limit | +–––––––+—————+ | | V push() V push() +———–+ +———–+ | Interface | | Interface | | rx queue | | rx queue | +———–+ +———–+ | | pop() @ dev rx rate limit pop() @ dev rx rate limit | | V push() V push() +–––––––+ +–––––––+ | PacketDevice | | PacketDevice | +–––––––+ +–––––––+

Note: the cross-device loopback process is not shown above.

Structs§

Context
Generalizes the runtime state needed to run the router.
Router
A Router routes PacketRcs between PacketDevices and the simulated network, enforcing configured send/receive rate limits on the interfaces and the upstream/downstream links to a modeled network provider.

Enums§

Event
The events handled by the Router.

Type Aliases§

RouterContext
An alias for the router context, to clearly separate it from other contexts in the simulator. Code external to the router should probably prefer this RouterContext to the Context syntax for clarity.
RouterEvent
An alias for a router event, to clearly separate it from other events in the simulator. Code external to the router should probably prefer this RouterEvent to the Event syntax for clarity.