vnet: Usage Policy

Purpose of vnet

The vnet (Virtual NETwork) was introduced primarily to ensure that pion would work correctly over the various configurations of the network.

Building such a test environment involving different types of NATs in the path and setting up STUN and TURN servers, with all permutations of these components in the real network is very hard and time-consuming.

The vnet wraps the network interface (the net package), which allows us to test pion modules on various network configurations, virtually built on memory, without having to physically prepare ICE servers and different types of NATs, so that all connectivity testing can be performed on our CI testing to efficiently detect regressions as we update our code.

Requirements to vnet

Do not add extra calls to the call stack

We'd like to keep prod debugging/stack-traces as simple as possible. When vnet is disabled, calling threads should not add extra calls to the call stack with the only exception of a wrapper method in vnet.Net class, with a single if branch.

We don't want users to debug and read pion/transport when fixing an issue for 'real world' Pion WebRTC usage.

Allow enabling vnet from pion/webrtc's SettingEngine

The vnet MUST be disabled by default. We should be able to enable it from SettingEngine, as a root "switch", so that all pion modules that depend on net package will use vnet instead when it is enabled.

Usage Policy

Never use vnet in your production code

The vnet is designed to test pion modules, not meant to be used in the users code.

Log Warning from each pion module if vnet is enabled

To avoid a situation where vnet is accidentally enabled, we should log warning to alert it.

Here's an example:

func NetAgent(config *AgentConfig) *Agent {
    log := config.LoggerFactory.NewLogger("mod")
    if config.Net == nil {
        config.Net = vnet.NewNet(nil) // defaults to native operation
    } else if config.Net.IsVirtual() {
        log.Warn("vnet is enabled")
    }

    return &Agent {
         :
        net: config.Net,
        log: log,
    }
}