handle: add NewHandleWithOptions(), deprecate DisableVFInfoCollection()

This commit repurposes HandleOptions as a declarative configuration mechanism
for Handle. It can be passed to NewHandleWithOptions.

It also removes the unreleased Handle.RetryInterrupted and deprecates
DisableVFInfoCollection in favor of its HandleOptions counterpart.

Signed-off-by: Timo Beckers <timo@incline.eu>

Author: ti-mo

handle_linux.go

@@ -12,9 +12,22 @@ import (
 // Empty handle used by the netlink package methods
 var pkgHandle = &Handle{}
 
+// HandleOptions defines the options for creating a netlink Handle, allowing the
+// caller to customize its behaviour.
 type HandleOptions struct {
-	collectVFInfo    bool
-	retryInterrupted bool
+	// DisableVFInfoCollection controls whether to fetch VF information for each
+	// link. This is an expensive operation and should be disabled if the caller
+	// does not need the VF information.
+	DisableVFInfoCollection bool
+
+	// RetryInterrupted controls whether to automatically retry dump operations a
+	// number of times if they fail with EINTR before finally returning
+	// [ErrDumpInterrupted].
+	RetryInterrupted bool
+
+	// NetNS specifies the network namespace to operate on. If not set, the
+	// current network namespace will be used.
+	NetNS *netns.NsHandle
 }
 
 // Handle is a handle for the netlink requests on a
@@ -29,16 +42,11 @@ type Handle struct {
 }
 
 // DisableVFInfoCollection configures the handle to skip VF information fetching
+//
+// Deprecated: Use [NewHandleWithOptions] and set
+// [HandleOptions.DisableVFInfoCollection] instead.
 func (h *Handle) DisableVFInfoCollection() *Handle {
-	h.options.collectVFInfo = false
-	return h
-}
-
-// RetryInterrupted configures the Handle to automatically retry dump operations
-// a number of times if they fail with EINTR before finally returning
-// [ErrDumpInterrupted].
-func (h *Handle) RetryInterrupted() *Handle {
-	h.options.retryInterrupted = true
+	h.options.DisableVFInfoCollection = true
 	return h
 }
 
@@ -69,7 +77,8 @@ func (h *Handle) SupportsNetlinkFamily(nlFamily int) bool {
 // If no families are specified, all the families the netlink package
 // supports will be automatically added.
 func NewHandle(nlFamilies ...int) (*Handle, error) {
-	return newHandle(netns.None(), netns.None(), nlFamilies...)
+	none := netns.None()
+	return newHandle(none, HandleOptions{NetNS: &none}, nlFamilies...)
 }
 
 // SetSocketTimeout sets the send and receive timeout for each socket in the
@@ -147,24 +156,36 @@ func (h *Handle) SetStrictCheck(state bool) error {
 // specified by ns. If ns=netns.None(), current network namespace
 // will be assumed
 func NewHandleAt(ns netns.NsHandle, nlFamilies ...int) (*Handle, error) {
-	return newHandle(ns, netns.None(), nlFamilies...)
+	return newHandle(netns.None(), HandleOptions{NetNS: &ns}, nlFamilies...)
 }
 
 // NewHandleAtFrom works as NewHandle but allows client to specify the
 // new and the origin netns Handle.
 func NewHandleAtFrom(newNs, curNs netns.NsHandle) (*Handle, error) {
-	return newHandle(newNs, curNs)
+	return newHandle(curNs, HandleOptions{NetNS: &newNs})
 }
 
-func newHandle(newNs, curNs netns.NsHandle, nlFamilies ...int) (*Handle, error) {
+// NewHandleWithOptions returns a Handle created using the specified options. If
+// opts is nil, default options will be used.
+func NewHandleWithOptions(opts HandleOptions, nlFamilies ...int) (*Handle, error) {
+	return newHandle(netns.None(), opts, nlFamilies...)
+}
+
+func newHandle(curNs netns.NsHandle, opts HandleOptions, nlFamilies ...int) (*Handle, error) {
 	h := &Handle{
 		sockets: map[int]*nl.SocketHandle{},
-		options: HandleOptions{collectVFInfo: true},
+		options: opts,
 	}
 	fams := nl.SupportedNlFamilies
 	if len(nlFamilies) != 0 {
 		fams = nlFamilies
 	}
+
+	newNs := netns.None()
+	if opts.NetNS != nil {
+		newNs = *opts.NetNS
+	}
+
 	for _, f := range fams {
 		s, err := nl.GetNetlinkSocketAt(newNs, curNs, f)
 		if err != nil {
@@ -208,6 +229,6 @@ func (h *Handle) newNetlinkRequest(proto, flags int) *nl.NetlinkRequest {
 		},
 		Sockets: h.sockets,
 
-		RetryInterrupted: h.options.retryInterrupted,
+		RetryInterrupted: h.options.RetryInterrupted,
 	}
 }

link_linux.go

@@ -2029,7 +2029,7 @@ func (h *Handle) LinkByName(name string) (Link, error) {
 	msg := nl.NewIfInfomsg(unix.AF_UNSPEC)
 	req.AddData(msg)
 
-	if h.options.collectVFInfo {
+	if !h.options.DisableVFInfoCollection {
 		attr := nl.NewRtAttr(unix.IFLA_EXT_MASK, nl.Uint32Attr(nl.RTEXT_FILTER_VF))
 		req.AddData(attr)
 	}
@@ -2077,7 +2077,7 @@ func (h *Handle) LinkByAlias(alias string) (Link, error) {
 	msg := nl.NewIfInfomsg(unix.AF_UNSPEC)
 	req.AddData(msg)
 
-	if h.options.collectVFInfo {
+	if !h.options.DisableVFInfoCollection {
 		attr := nl.NewRtAttr(unix.IFLA_EXT_MASK, nl.Uint32Attr(nl.RTEXT_FILTER_VF))
 		req.AddData(attr)
 	}
@@ -2108,7 +2108,7 @@ func (h *Handle) LinkByIndex(index int) (Link, error) {
 	msg := nl.NewIfInfomsg(unix.AF_UNSPEC)
 	msg.Index = int32(index)
 	req.AddData(msg)
-	if h.options.collectVFInfo {
+	if !h.options.DisableVFInfoCollection {
 		attr := nl.NewRtAttr(unix.IFLA_EXT_MASK, nl.Uint32Attr(nl.RTEXT_FILTER_VF))
 		req.AddData(attr)
 	}