chore: plugins godocs + refactor/cleanup (microsoft#39)

Adding godocs + cleaning up the plugins pkg

pkg/bpf/setup.go

@@ -7,21 +7,21 @@ import (
 	"fmt"
 	"os"
 
+	"github.com/cilium/cilium/pkg/mountinfo"
 	"github.com/microsoft/retina/pkg/log"
-	"github.com/microsoft/retina/pkg/plugin/constants"
+	plugincommon "github.com/microsoft/retina/pkg/plugin/common"
 	"github.com/microsoft/retina/pkg/plugin/filter"
-	"github.com/cilium/cilium/pkg/mountinfo"
 	"go.uber.org/zap"
 	"golang.org/x/sys/unix"
 )
 
 func __mount() error {
 	// Check if the path exists.
-	_, err := os.Stat(constants.FilterMapPath)
+	_, err := os.Stat(plugincommon.FilterMapPath)
 	if err != nil {
 		if os.IsNotExist(err) {
 			// Path does not exist. Create it.
-			err = os.MkdirAll(constants.FilterMapPath, 0o755)
+			err = os.MkdirAll(plugincommon.FilterMapPath, 0o755)
 			if err != nil {
 				return err
 			}
@@ -30,13 +30,13 @@ func __mount() error {
 			return err
 		}
 	}
-	err = unix.Mount(constants.FilterMapPath, constants.FilterMapPath, "bpf", 0, "")
+	err = unix.Mount(plugincommon.FilterMapPath, plugincommon.FilterMapPath, "bpf", 0, "")
 	return err
 }
 
 func mountBpfFs() error {
 	// Check if /sys/fs/bpf is already mounted.
-	mounted, bpfMount, err := mountinfo.IsMountFS(mountinfo.FilesystemTypeBPFFS, constants.FilterMapPath)
+	mounted, bpfMount, err := mountinfo.IsMountFS(mountinfo.FilesystemTypeBPFFS, plugincommon.FilterMapPath)
 	if err != nil {
 		return err
 	}
@@ -49,7 +49,7 @@ func mountBpfFs() error {
 	// Else mounted. Check the type of mount.
 	if !bpfMount {
 		// Custom mount of /sys/fs/bpf. Unknown setup. Exit.
-		return fmt.Errorf("%+s is already mounted but not as bpf. Not supported", constants.FilterMapPath)
+		return fmt.Errorf("%+s is already mounted but not as bpf. Not supported", plugincommon.FilterMapPath)
 	}
 	return nil
 }
@@ -59,20 +59,20 @@ func Setup(l *log.ZapLogger) {
 	if err != nil {
 		l.Panic("Failed to mount bpf filesystem", zap.Error(err))
 	}
-	l.Info("BPF filesystem mounted successfully", zap.String("path", constants.FilterMapPath))
+	l.Info("BPF filesystem mounted successfully", zap.String("path", plugincommon.FilterMapPath))
 
 	// Delete existing filter map file.
-	err = os.Remove(constants.FilterMapPath + "/" + constants.FilterMapName)
+	err = os.Remove(plugincommon.FilterMapPath + "/" + plugincommon.FilterMapName)
 	if err != nil && !os.IsNotExist(err) {
 		l.Panic("Failed to delete existing filter map file", zap.Error(err))
 	}
-	l.Info("Deleted existing filter map file", zap.String("path", constants.FilterMapPath), zap.String("Map name", constants.FilterMapName))
+	l.Info("Deleted existing filter map file", zap.String("path", plugincommon.FilterMapPath), zap.String("Map name", plugincommon.FilterMapName))
 
 	// Initialize the filter map.
 	// This will create the filter map in kernel and pin it to /sys/fs/bpf.
 	_, err = filter.Init()
 	if err != nil {
 		l.Panic("Failed to initialize filter map", zap.Error(err))
 	}
-	l.Info("Filter map initialized successfully", zap.String("path", constants.FilterMapPath), zap.String("Map name", constants.FilterMapName))
+	l.Info("Filter map initialized successfully", zap.String("path", plugincommon.FilterMapPath), zap.String("Map name", plugincommon.FilterMapName))
 }

pkg/managers/controllermanager/controllermanager_test.go

@@ -8,12 +8,13 @@ import (
 	"testing"
 	"time"
 
+	"github.com/golang/mock/gomock"
 	kcfg "github.com/microsoft/retina/pkg/config"
 	"github.com/microsoft/retina/pkg/log"
 	pm "github.com/microsoft/retina/pkg/managers/pluginmanager"
 	"github.com/microsoft/retina/pkg/plugin/api"
+	"github.com/microsoft/retina/pkg/plugin/api/mock"
 	"github.com/microsoft/retina/pkg/telemetry"
-	"github.com/golang/mock/gomock"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	k8sfake "k8s.io/client-go/kubernetes/fake"
@@ -89,7 +90,7 @@ func TestControllerPluginManagerStartFail(t *testing.T) {
 	mgr, err := pm.NewPluginManager(cfg, telemetry.NewNoopTelemetry(), api.PluginName(pluginName))
 	require.NoError(t, err, "Expected no error, instead got %+v", err)
 
-	mockPlugin := api.NewMockPlugin(ctl)
+	mockPlugin := mock.NewMockPlugin(ctl)
 	mockPlugin.EXPECT().Generate(gomock.Any()).Return(nil).AnyTimes()
 	mockPlugin.EXPECT().Compile(gomock.Any()).Return(nil).AnyTimes()
 	mockPlugin.EXPECT().Stop().Return(nil).AnyTimes()

pkg/managers/pluginmanager/pluginmanager_test.go

@@ -8,13 +8,14 @@ import (
 	"testing"
 	"time"
 
+	"github.com/golang/mock/gomock"
 	kcfg "github.com/microsoft/retina/pkg/config"
 	"github.com/microsoft/retina/pkg/log"
 	watchermock "github.com/microsoft/retina/pkg/managers/watchermanager/mocks"
 	"github.com/microsoft/retina/pkg/metrics"
 	"github.com/microsoft/retina/pkg/plugin/api"
+	pluginmock "github.com/microsoft/retina/pkg/plugin/api/mock"
 	"github.com/microsoft/retina/pkg/telemetry"
-	"github.com/golang/mock/gomock"
 	dto "github.com/prometheus/client_model/go"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -153,7 +154,7 @@ func TestNewManagerWithPluginStartFailure(t *testing.T) {
 		watcherManager: setupWatcherManagerMock(ctl),
 	}
 
-	mockPlugin := api.NewMockPlugin(ctl)
+	mockPlugin := pluginmock.NewMockPlugin(ctl)
 	mockPlugin.EXPECT().Generate(gomock.Any()).Return(nil).AnyTimes()
 	mockPlugin.EXPECT().Compile(gomock.Any()).Return(nil).AnyTimes()
 	mockPlugin.EXPECT().Stop().Return(nil).AnyTimes()
@@ -191,7 +192,7 @@ func TestNewManagerWithPluginReconcileFailure(t *testing.T) {
 		watcherManager: setupWatcherManagerMock(ctl),
 	}
 
-	mockPlugin := api.NewMockPlugin(ctl)
+	mockPlugin := pluginmock.NewMockPlugin(ctl)
 	mockPlugin.EXPECT().Generate(gomock.Any()).Return(nil).AnyTimes()
 	mockPlugin.EXPECT().Compile(gomock.Any()).Return(nil).AnyTimes()
 	mockPlugin.EXPECT().Stop().Return(errors.New("Plugin failed to stop")).AnyTimes()
@@ -409,7 +410,7 @@ func TestStopPluginManagerGracefully(t *testing.T) {
 		watcherManager: setupWatcherManagerMock(ctl),
 	}
 
-	mockPlugin := api.NewMockPlugin(ctl)
+	mockPlugin := pluginmock.NewMockPlugin(ctl)
 	mockPlugin.EXPECT().Generate(gomock.Any()).Return(nil).AnyTimes()
 	mockPlugin.EXPECT().Compile(gomock.Any()).Return(nil).AnyTimes()
 	mockPlugin.EXPECT().Stop().Return(nil).AnyTimes()

pkg/plugin/api/types.go

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
+
+// Package api provides the api for all Retina eBPF plugins.
 package api
 
 import (
@@ -8,36 +10,33 @@ import (
 	v1 "github.com/cilium/cilium/pkg/hubble/api/v1"
 )
 
+//go:generate go run github.com/golang/mock/mockgen@v1.6.0 -destination=mock/mock_plugin.go -copyright_file=../../lib/ignore_headers.txt -package=mock github.com/microsoft/retina/pkg/plugin/api Plugin
+
 const (
 	Meter       string = "retina-meter"
 	ServiceName string = "retina"
 )
 
+// PluginName provides the type for the name of the plugin.
 type PluginName string
 
-// PluginEvent - Generic plugin event structure to receive data from plugin
-type PluginEvent struct {
-	Name PluginName
-}
-
-//go:generate go run github.com/golang/mock/mockgen@v1.6.0 -destination=mock_plugin.go -copyright_file=../../lib/ignore_headers.txt -package=api github.com/microsoft/retina/pkg/plugin/api Plugin
-
-// All functions should be idempotent.
+// Plugin provides the interface that all Retina eBPF plugins must implement.
 type Plugin interface {
+	// Name returns the name of the plugin
 	Name() string
-	// Generate the plugin specific header files.
+	// Generate generates the plugin specific header files.
 	// This maybe no-op for plugins that don't use eBPF.
 	Generate(ctx context.Context) error
-	// Compile the ebpf to generate bpf object.
+	// Compile compiles the eBPF code to generate bpf object.
 	// This maybe no-op for plugins that don't use eBPF.
 	Compile(ctx context.Context) error
-	// Init initializes plugin specific objects. Plugin has to send data through the channel passed in arg.
+	// Init initializes plugin specific objects. Depend on a given configuration, it may initialize eBPF maps, etc.
 	Init() error
-	// Start The plugin has to start its execution in collecting traces
+	// Start starts the plugin. The plugin should start its main loop and return.
 	Start(ctx context.Context) error
-	// Stop The plugin has to stop its job
+	// Stop stops the plugin. The plugin should clean up all resources and exit.
 	Stop() error
-	// Allow adding external channels that clients can use
-	// to get data from the plugin. This allows custom post processing of plugin data.
+	// SetupChannel allows external components to setup a channel to the plugin to receive its events.
+	// This can be useful for plugins that need to send data to other components for post-processing.
 	SetupChannel(chan *v1.Event) error
 }

pkg/plugin/common/common_linux.go

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
+
+// package common contains common functions and types used by all Retina plugins.
 package common
 
 import (

pkg/plugin/constants/constants.go → pkg/plugin/common/constants.go

@@ -1,13 +1,10 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
-package constants
+package common
 
 const (
-	TCP         = "IPPROTO_TCP"
-	UDP         = "IPPROTO_UDP"
-	LocalhostIP = "127.0.0.1"
-	ZeroIP      = "0.0.0.0"
-
+	// FilterMapPath is the path to the BPF filter map.
 	FilterMapPath = "/sys/fs/bpf"
+	// FilterMapName is the name of the BPF filter map
 	FilterMapName = "retina_filter_map"
 )

pkg/plugin/dns/dns_linux.go

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
+
+// Package dns contains the Retina DNS plugin. It uses the Inspektor Gadget DNS tracer to capture DNS events.
 package dns
 
 import (
@@ -9,18 +11,18 @@ import (
 	"os"
 	"strings"
 
+	v1 "github.com/cilium/cilium/pkg/hubble/api/v1"
+	"github.com/cilium/ebpf/rlimit"
+	"github.com/inspektor-gadget/inspektor-gadget/pkg/gadgets/trace/dns/tracer"
+	"github.com/inspektor-gadget/inspektor-gadget/pkg/gadgets/trace/dns/types"
+	"github.com/inspektor-gadget/inspektor-gadget/pkg/utils/host"
 	kcfg "github.com/microsoft/retina/pkg/config"
 	"github.com/microsoft/retina/pkg/enricher"
 	"github.com/microsoft/retina/pkg/log"
 	"github.com/microsoft/retina/pkg/metrics"
 	"github.com/microsoft/retina/pkg/plugin/api"
 	"github.com/microsoft/retina/pkg/plugin/common"
 	"github.com/microsoft/retina/pkg/utils"
-	v1 "github.com/cilium/cilium/pkg/hubble/api/v1"
-	"github.com/cilium/ebpf/rlimit"
-	"github.com/inspektor-gadget/inspektor-gadget/pkg/gadgets/trace/dns/tracer"
-	"github.com/inspektor-gadget/inspektor-gadget/pkg/gadgets/trace/dns/types"
-	"github.com/inspektor-gadget/inspektor-gadget/pkg/utils/host"
 	"go.uber.org/zap"
 )
 

pkg/plugin/dropreason/dropreason_linux.go

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
+
+// Package dropreason contains the Retina DropReason plugin. It measures the number of packets/bytes dropped and the reason and the direction of the drop.
 package dropreason
 
 import (
@@ -27,7 +29,6 @@ import (
 	"github.com/microsoft/retina/pkg/metrics"
 	"github.com/microsoft/retina/pkg/plugin/api"
 	plugincommon "github.com/microsoft/retina/pkg/plugin/common"
-	"github.com/microsoft/retina/pkg/plugin/constants"
 	"go.uber.org/zap"
 
 	_ "github.com/microsoft/retina/pkg/plugin/dropreason/_cprog" // nolint
@@ -148,7 +149,7 @@ func (dr *dropReason) Init() error {
 			LogLevel: 2,
 		},
 		Maps: ebpf.MapOptions{
-			PinPath: constants.FilterMapPath,
+			PinPath: plugincommon.FilterMapPath,
 		},
 	}); err != nil {
 		dr.l.Error("Error loading objects: %w", zap.Error(err))

pkg/plugin/dropreason/types_linux.go

@@ -5,15 +5,15 @@ package dropreason
 import (
 	"sync"
 
+	hubblev1 "github.com/cilium/cilium/pkg/hubble/api/v1"
+	"github.com/cilium/ebpf"
+	"github.com/cilium/ebpf/link"
+	"github.com/cilium/ebpf/perf"
 	kcfg "github.com/microsoft/retina/pkg/config"
 	"github.com/microsoft/retina/pkg/enricher"
 	"github.com/microsoft/retina/pkg/log"
 	"github.com/microsoft/retina/pkg/metrics"
 	"github.com/microsoft/retina/pkg/plugin/api"
-	hubblev1 "github.com/cilium/cilium/pkg/hubble/api/v1"
-	"github.com/cilium/ebpf"
-	"github.com/cilium/ebpf/link"
-	"github.com/cilium/ebpf/perf"
 )
 
 const (
@@ -43,7 +43,6 @@ type dropReason struct {
 	KNfConntrackConfirm    link.Link
 	KRetNfConntrackConfirm link.Link
 	metricsMapData         IMap
-	event                  chan<- api.PluginEvent
 	isRunning              bool
 	reader                 IPerfReader
 	enricher               enricher.EnricherInterface