notwork

README

notwork

A tiny package to help with creating transient Linux virtual network elements for testing purposes. It leverages both the Ginkgo testing framework and matching (erm, sic!) Gomega matchers.

Usage Example

To create a transient MACVLAN network interface with a dummy-type parent network interface for the duration of a test (node):

import (
    "github.com/thediveo/notwork/dummy"
    "github.com/thediveo/notwork/macvlan"

    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
)

var _ = Describe("some testing", func() {

    It("creates a transient MACVLAN with a dummy parent", func() {
        mcvlan := macvlan.NewTransient(dummy.NewTransient())
        // ...virtual network interface will be automatically removed
        // at the end of this test.
    })

})

Using Throw-Away Network Namespaces

Even better, don't trash around the host network namespace, but instead use a throw-away network namespace that is separate from the host network namespace.

import (
    "github.com/thediveo/notwork/dummy"
    "github.com/thediveo/notwork/macvlan"
    "github.com/thediveo/notwork/netns"

    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
)

var _ = Describe("some isolated testing", func() {

    It("creates a transient MACVLAN with a dummy parent inside a throw-away netns", func() {
        defer netns.EnterTransient()() // !!! double ()()
        // we're not in a new transient network namespace and there's just
        // a lonely lo at this time.
        mcvlan := macvlan.NewTransient(dummy.NewTransient())
    })

})

VETH Pair Ends in Different Network Namespaces

With the previous examples under our black notwork belts, let's create a VETH pair of network interfaces that connect two transient network namespaces.

import (
  "github.com/notwork/netns"
  "github.com/notwork/veth"
)

var _ = Describe("some isolated testing", func() {

	It("connects two temporary network namespaces", func() {
		dupondNetns := netns.NewTransient() // create, but don't enter
		dupontNetns := netns.NewTransient() // create, but don't enter
		dupond, dupont := veth.NewTransient(InNamespace(dupondNetns), WithPeerNamespace(dupontNetns))
	})

})

As for the names of the VETH pair end variables, please refer to Dupond et Dupont.

Make Targets

• make: lists all targets.
• make coverage: runs all tests with coverage and then updates the coverage badge in README.md.
• make pkgsite: installs x/pkgsite, as well as the browser-sync and nodemon npm packages first, if not already done so. Then runs the pkgsite and hot reloads it whenever the documentation changes.
• make report: installs @gojp/goreportcard if not yet done so and then runs it on the code base.
• make test: runs all tests (as root), always.
• make vuln: installs x/vuln/cmd/govulncheck and then runs it.

Copyright and License

Copyright 2023 Harald Albrecht, licensed under the Apache License, Version 2.0.

Documentation

Overview

Package notwork helps unit tests to create transient virtual network interfaces. It leverages both the Ginkgo testing framework and matchting (erm, sic!) Gomega matchers.

Usage Example

To create a transient MACVLAN network interface with a dummy-type parent network interface for the duration of a test (node):

import (
    "github.com/thediveo/notwork/dummy"
    "github.com/thediveo/notwork/macvlan"

    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
)

var _ = Describe("some testing", func() {

    It("creates a transient MACVLAN with a dummy parent", func() {
        mcvlan := macvlan.NewTransient(dummy.NewTransient())
    })

})

The MACVLAN and dummy network interfaces will automatically removed at the end of the test (node) they are created in, regardless of success or failure.

If creating any of the virtual network interfaces fails, the test will immediately fail.

Using Throw-Away Network Namespaces

Even better, don't trash around the host network namespace, but instead use a throw-away network namespace that is separate from the host network namespace.

import (
	"github.com/thediveo/notwork/dummy"
	"github.com/thediveo/notwork/macvlan"
	"github.com/thediveo/notwork/netns"

	. "github.com/onsi/ginkgo/v2"
	. "github.com/onsi/gomega"
)

var _ = Describe("some isolated testing", func() {

	It("creates a transient MACVLAN with a dummy parent inside a throw-away netns", func() {
		defer netns.EnterTransient()()
		mcvlan := macvlan.NewTransient(dummy.NewTransient())
	})

})

Please pay attention to the double “()()” when deferring github.com/thediveo/notwork/netns.EnterTransient.

VETH Pair Ends in Different Network Namespaces

With the previous examples under our black notwork belts, let's create a VETH pair of network interfaces that connect two transient network namespaces.

import (
	"github.com/notwork/netns"
	"github.com/notwork/veth"
)

It("connects two temporary network namespaces", func() {
	dupondNetns := netns.NewTransient()
	dupontNetns := netns.NewTransient()
	var dupond, dupont netlink.Link
	netns.Execute(dupondNetns, func() {
		dupond, dupont = veth.NewTransient(WithPeerNamespace(dupontNetns))
	})
})

As for the names of the VETH pair end variables, please refer to Dupond et Dupont.

Known Limitations

This module suffers from overzealous sub-packaging.