github.com/vishvananda/netns v0.0.0-20211101163701-50045581ed74: NsHandle

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify github.com/vishvananda/netns.NsHandle in pkg:golang/github.com/vishvananda/netns@v0.0.0-20211101163701-50045581ed74
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/vishvananda/netns@v0.0.0-20211101163701-50045581ed74
Demonstrate these symbols/APIs:
  - github.com/vishvananda/netns.NsHandle

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:e95b8369794e0160a7ce172c9af9d657268eaa6a1961a507d3c6797b860dbcdc","contract":["netns.None returns an unopened NsHandle with descriptor -1 that reports IsOpen false and expected string and unique id representations","netns.Get retrieves the active network namespace NsHandle for the current process thread with IsOpen true and valid descriptor","netns.NsHandle Equal returns true for handles pointing to the same network namespace and false for different or invalid handles","netns.NsHandle Close releases the underlying descriptor and resets the handle to -1","netns.NsHandle UniqueId and String formats produce non-empty namespace identifiers for active handles"],"goal":"verify github.com/vishvananda/netns.NsHandle in pkg:golang/github.com/vishvananda/netns@v0.0.0-20211101163701-50045581ed74","kind":"HOW","packages":["pkg:golang/github.com/vishvananda/netns@v0.0.0-20211101163701-50045581ed74"],"schemaVersion":1,"symbols":["github.com/vishvananda/netns.NsHandle"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/vishvananda/netns@v0.0.0-20211101163701-50045581ed74"],"schemaVersion":1,"subject":"pkg:golang/github.com/vishvananda/netns@v0.0.0-20211101163701-50045581ed74","symbols":["github.com/vishvananda/netns.NsHandle"],"verifierAdapter":"golang@1"}

module sample

go 1.22.0

require github.com/vishvananda/netns v0.0.0-20211101163701-50045581ed74

require golang.org/x/sys v0.0.0-20200217220822-9197077df867 // indirect

github.com/vishvananda/netns v0.0.0-20211101163701-50045581ed74 h1:gga7acRE695APm9hlsSMoOoE65U4/TcqNj90mc69Rlg=
github.com/vishvananda/netns v0.0.0-20211101163701-50045581ed74/go.mod h1:DD4vA1DwXk04H54A1oHXtwZmA0grkVMdPxx/VGLCah0=
golang.org/x/sys v0.0.0-20200217220822-9197077df867 h1:JoRuNIf+rpHl+VhScRQQvzbHed86tKkqwPMV34T8myw=
golang.org/x/sys v0.0.0-20200217220822-9197077df867/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=

package sample

import (
	"fmt"

	"github.com/vishvananda/netns"
)

// NamespaceInspector provides helper methods for operating on network namespace handles.
type NamespaceInspector struct{}

// NewNamespaceInspector creates and initializes a NamespaceInspector.
func NewNamespaceInspector() *NamespaceInspector {
	return &NamespaceInspector{}
}

// Current returns the NsHandle for the current process thread.
func (ni *NamespaceInspector) Current() (netns.NsHandle, error) {
	return netns.Get()
}

// FromPid returns the NsHandle for a specific process identifier.
func (ni *NamespaceInspector) FromPid(pid int) (netns.NsHandle, error) {
	return netns.GetFromPid(pid)
}

// None returns an empty, closed NsHandle with descriptor -1.
func (ni *NamespaceInspector) None() netns.NsHandle {
	return netns.None()
}

// AreEqual checks whether two NsHandle instances point to the same network namespace.
func (ni *NamespaceInspector) AreEqual(a, b netns.NsHandle) bool {
	return a.Equal(b)
}

// Describe returns string and unique ID representations of the given NsHandle.
func (ni *NamespaceInspector) Describe(h netns.NsHandle) (string, string) {
	return h.String(), h.UniqueId()
}

// Close closes an active NsHandle and resets its descriptor to -1.
func (ni *NamespaceInspector) Close(h *netns.NsHandle) error {
	if h == nil {
		return fmt.Errorf("handle cannot be nil")
	}
	return h.Close()
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/vishvananda/netns.NsHandle in pkg:golang/github.com/vishvananda/netns@v0.0.0-20211101163701-50045581ed74",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/vishvananda/netns@v0.0.0-20211101163701-50045581ed74"
  ],
  "symbols": [
    "github.com/vishvananda/netns.NsHandle"
  ]
}

package main

import (
	"fmt"
	"os"
	"strings"

	"sample"

	"github.com/vishvananda/netns"
)

func main() {
	if err := runContract(); err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("PASS: netns.NsHandle contract verified")
}

func runContract() error {
	inspector := sample.NewNamespaceInspector()

	// Assertion 1: netns.None returns an unopened NsHandle with descriptor -1 that reports IsOpen false and expected string and unique id representations
	none := inspector.None()
	if int(none) != -1 {
		return fmt.Errorf("expected None handle descriptor -1, got %d", int(none))
	}
	if none.IsOpen() {
		return fmt.Errorf("expected None.IsOpen() to be false, got true")
	}
	if str := none.String(); str != "NS(None)" {
		return fmt.Errorf("expected None.String() to be 'NS(None)', got %q", str)
	}
	if uid := none.UniqueId(); uid != "NS(none)" {
		return fmt.Errorf("expected None.UniqueId() to be 'NS(none)', got %q", uid)
	}

	// Assertion 2: netns.Get retrieves the active network namespace NsHandle for the current process thread with IsOpen true and valid descriptor
	current, err := inspector.Current()
	if err != nil {
		return fmt.Errorf("failed to get current netns handle: %w", err)
	}
	defer current.Close()

	if int(current) < 0 {
		return fmt.Errorf("expected valid non-negative descriptor for current netns, got %d", int(current))
	}
	if !current.IsOpen() {
		return fmt.Errorf("expected current.IsOpen() to be true, got false")
	}

	// Assertion 3: netns.NsHandle Equal returns true for handles pointing to the same network namespace and false for different or invalid handles
	pidHandle, err := inspector.FromPid(os.Getpid())
	if err != nil {
		return fmt.Errorf("failed to get netns handle for pid: %w", err)
	}
	defer pidHandle.Close()

	if !inspector.AreEqual(current, pidHandle) {
		return fmt.Errorf("expected current handle and pid handle to be Equal")
	}
	if !inspector.AreEqual(pidHandle, current) {
		return fmt.Errorf("expected pid handle and current handle to be symmetric Equal")
	}
	if inspector.AreEqual(current, none) {
		return fmt.Errorf("expected active handle and None handle to not be Equal")
	}
	if !none.Equal(netns.None()) {
		return fmt.Errorf("expected two None handles to be Equal")
	}

	// Assertion 4: netns.NsHandle Close releases the underlying descriptor and resets the handle to -1
	tempHandle, err := inspector.Current()
	if err != nil {
		return fmt.Errorf("failed to get temp netns handle for close assertion: %w", err)
	}
	if !tempHandle.IsOpen() {
		return fmt.Errorf("expected tempHandle.IsOpen() to be true before close")
	}
	if err := inspector.Close(&tempHandle); err != nil {
		return fmt.Errorf("failed to close temp netns handle: %w", err)
	}
	if tempHandle.IsOpen() {
		return fmt.Errorf("expected tempHandle.IsOpen() to be false after close")
	}
	if int(tempHandle) != -1 {
		return fmt.Errorf("expected tempHandle to reset to -1 after close, got %d", int(tempHandle))
	}

	// Assertion 5: netns.NsHandle UniqueId and String formats produce non-empty namespace identifiers for active handles
	str, uid := inspector.Describe(current)
	if !strings.HasPrefix(str, "NS(") || !strings.HasSuffix(str, ")") {
		return fmt.Errorf("expected current.String() to match format 'NS(...)', got %q", str)
	}
	if !strings.HasPrefix(uid, "NS(") || !strings.HasSuffix(uid, ")") {
		return fmt.Errorf("expected current.UniqueId() to match format 'NS(...)', got %q", uid)
	}
	if uid == "NS(none)" || uid == "NS(unknown)" {
		return fmt.Errorf("expected valid resolved unique ID for active handle, got %q", uid)
	}

	return nil
}