Add module documentation for emulated network

Bug: webrtc:12208
Change-Id: I28d5f349706751d1762b90527601eaa86906e42d
Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/200803
Reviewed-by: Andrey Logvin <landrey@webrtc.org>
Reviewed-by: Mirko Bonadei <mbonadei@webrtc.org>
Commit-Queue: Artem Titov <titovartem@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#32938}

test/network/g3doc/index.md

@@ -0,0 +1,139 @@
+# Network Emulation Framework
+
+<!--*
+# Document freshness: For more information, see go/fresh-source.
+freshness: { owner: 'titovartem' reviewed: '2021-01-07' }
+*-->
+
+[TOC]
+
+## Disclamer
+
+This documentation explain the implementation details of Network Emulation
+Framework. Framework's public APIs are located in:
+
+*   [`/api/test/network_emulation_manager.h`](https://source.chromium.org/search?q=%2Fapi%2Ftest%2Fnetwork_emulation_manager.h)
+*   [`/api/test/create_network_emulation_manager.h`](https://source.chromium.org/search?q=%2Fapi%2Ftest%2Fcreate_network_emulation_manager.h)
+*   [`/api/test/network_emulation/network_emulation_interfaces.h`](https://source.chromium.org/search?q=%2Fapi%2Ftest%2Fnetwork_emulation%2Fnetwork_emulation_interfaces.h)
+*   [`/api/test/simulated_network.h`](https://source.chromium.org/search?q=%2Fapi%2Ftest%2Fsimulated_network.h)
+
+## Overview
+
+Network Emulation Framework provides an ability to emulate network behavior
+between different clients, including a WebRTC PeerConnection client. To
+configure network behavior, the user can choose different options:
+
+*   Use predefined implementation that can be configured with parameters such as
+    packet loss, bandwidth, delay, etc.
+*   Custom implementation
+
+Conceptually the framework provides the ability to define multiple endpoints and
+routes used to connect them. All network related entities are created and
+managed by single factory class `webrtc::NetworkEmulationManager` which is
+implemented by `webrtc::test::NetworkEmulationManagerImpl` and can work in two
+modes:
+
+*   Real time
+*   Simulated time
+
+The manager has a dedicated task queue which pipes all packets through all
+network routes from senders to receivers. This task queue behaviour is
+determined by `webrtc::TimeController`, which is based on either in real time or
+simulated time mode.
+
+The network operates on IP level and supports only UDP for now.
+
+## Abstractions
+
+The framework contains the following public abstractions:
+
+*   `webrtc::NetworkBehaviorInterface` - defines how emulated network should
+    behave. It operates on packets metadata level and is responsible for telling
+    which packet at which time have to be delivered to the next receiver.
+
+*   `webrtc::EmulatedIpPacket` - represents a single packet that can be sent or
+    received via emulated network. It has source and destination address and
+    payload to transfer.
+
+*   `webrtc::EmulatedNetworkReceiverInterface` - generic packet receiver
+    interface.
+
+*   `webrtc::EmulatedEndpoint` - primary user facing abstraction of the
+    framework. It represents a network interface on client's machine. It has its
+    own unique IP address and can be used to send and receive packets.
+
+    `EmulatedEndpoint` implements `EmulatedNetworkReceiverInterface` to receive
+    packets from the network and provides an API to send packets to the network
+    and API to bind other `EmulatedNetworkReceiverInterface` which will be able
+    to receive packets from the endpoint. `EmulatedEndpoint` interface has the
+    only implementation: `webrtc::test::EmulatedEndpointImpl`.
+
+*   `webrtc::EmulatedNetworkNode` - represents single network in the real world,
+    like a 3G network between peers, or Wi-Fi for one peer and LTE for another.
+    Each `EmulatedNetworkNode` is a single direction connetion and to form
+    bidirectional connection between endpoints two nodes should be used.
+    Multiple nodes can be joined into chain emulating a network path from one
+    peer to another.
+
+    In public API this class is forward declared and fully accessible only by
+    the framework implementation.
+
+    Internally consist of two parts: `LinkEmulation`, which is responsible for
+    behavior of current `EmulatedNetworkNode` and `NetworkRouterNode` which is
+    responsible for routing packets to the next node or to the endpoint.
+
+*   `webrtc::EmulatedRoute` - represents single route from one network interface
+    on one device to another network interface on another device.
+
+    In public API this class is forward declared and fully accessible only by
+    the framework implementation.
+
+    It contains start and end endpoint and ordered list of `EmulatedNetworkNode`
+    which forms the single directional route between those endpoints.
+
+The framework has also the following private abstractions:
+
+*   `webrtc::test::NetworkRouterNode` - an `EmulatedNetworkReceiverInterface`
+    that can route incoming packets to the next receiver based on internal IP
+    routing table.
+
+*   `webrtc::test::LinkEmulation` - an `EmulatedNetworkReceiverInterface` that
+    can emulate network leg behavior via `webrtc::NetworkBehaviorInterface`
+    interface.
+
+For integrating with `webrtc::PeerConnection` there are helper abstractions:
+
+*   `webrtc::EmulatedNetworkManagerInterface` which is implemented by
+    `webrtc::test::EmulatedNetworkManager` and provides `rtc::Thread` and
+    `rtc::NetworkManager` for WebRTC to use as network thread for
+    `PeerConnection` and for `cricket::BasicPortAllocator`.
+
+    Implementation represent framework endpoints as `rtc::Network` to WebRTC.
+
+## Architecture
+
+Let's take a look on how framework's abstractions are connected to each other.
+
+When the user wants to setup emulated network, first of all, they should create
+an instance of `NetworkEmulationManager` using
+`webrtc::CreateNetworkEmulationManager(...)` API. Then user should use a manager
+to create at least one `EmulatedEndpoint` for each client. After endpoints, the
+user should create required `EmulatedNetworkNode`s and with help of manager
+chain them into `EmulatedRoute`s conecting desired endpoints.
+
+Here is a visual overview of the emulated network architecture:
+
+![Architecture](network_emulation_framework.png "Architecture")
+
+When network is hooked into `PeerConnection` it is done through network thread
+and `NetworkManager`. In the network thread the custom `rtc::SocketServer` is
+provided: `webrtc::test::FakeNetworkSocketServer`. This custom socket server
+will construct custom sockets (`webrtc::test::FakeNetworkSocket`), which
+internally bind themselves to the required endpoint. All packets processing
+inside socket have to be done on the `PeerConnection`'s network thread. When
+packet is going from `PeerConnection` to the network it's already comming from
+the network thread and when it's comming from the emulated network switch from
+the Network Emulation Framework internal task queue and `PeerConnection`'s
+network thread is done inside socket's `OnPacketReceived(...)` method.
+
+![Network Injection](network_injection_into_peer_connection.png "Network Injection")