go.etcd.io/bbolt v1.4.3: Cursor

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 go.etcd.io/bbolt.Cursor in pkg:golang/go.etcd.io/bbolt@v1.4.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.etcd.io/bbolt@v1.4.3
Demonstrate these symbols/APIs:
  - go.etcd.io/bbolt.Cursor

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:393c9fd71ef1d1242fa8a7e78caa7a679c282d7e03a3c66b4a61e74cd3f62bfa","contract":["Cursor.First and Cursor.Last navigate to the first and last key-value pairs in a bucket","Cursor.Next and Cursor.Prev traverse key-value pairs sequentially in ascending and descending order","Cursor.Seek positions at the first key greater than or equal to a target key","Cursor.Delete removes current key-value pair in a writable transaction and returns ErrTxNotWritable in a read-only transaction","Cursor.Bucket returns the parent bucket being traversed"],"goal":"verify go.etcd.io/bbolt.Cursor in pkg:golang/go.etcd.io/bbolt@v1.4.3","kind":"HOW","packages":["pkg:golang/go.etcd.io/bbolt@v1.4.3"],"schemaVersion":1,"symbols":["go.etcd.io/bbolt.Cursor"]},"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/go.etcd.io/bbolt@v1.4.3"],"schemaVersion":1,"subject":"pkg:golang/go.etcd.io/bbolt@v1.4.3","symbols":["go.etcd.io/bbolt.Cursor"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require go.etcd.io/bbolt v1.4.3

require golang.org/x/sys v0.29.0 // indirect

github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
go.etcd.io/bbolt v1.4.3 h1:dEadXpI6G79deX5prL3QRNP6JB8UxVkqo4UPnHaNXJo=
go.etcd.io/bbolt v1.4.3/go.mod h1:tKQlpPaYCVFctUIgFKFnAlvbmB3tpy1vkTnDWohtc0E=
golang.org/x/sync v0.10.0 h1:3NQrjDixjgGwUOCaF8w2+VYHv0Ve/vGYSbdkTa98gmQ=
golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
golang.org/x/sys v0.29.0 h1:TPYlXGxvx1MGTn2GiZDhnjPA9wZzZeGKHHmKhHYvgaU=
golang.org/x/sys v0.29.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package sample

import (
	"bytes"
	"fmt"

	bolt "go.etcd.io/bbolt"
)

// Item represents a key-value pair.
type Item struct {
	Key   []byte
	Value []byte
}

// OpenDB opens or creates a Bolt database at the specified path.
func OpenDB(path string) (*bolt.DB, error) {
	db, err := bolt.Open(path, 0600, nil)
	if err != nil {
		return nil, fmt.Errorf("failed to open bolt db: %w", err)
	}
	return db, nil
}

// ScanPrefix scans all key-value pairs matching the given prefix in the specified bucket using a Cursor.
func ScanPrefix(tx *bolt.Tx, bucketName, prefix []byte) ([]Item, error) {
	b := tx.Bucket(bucketName)
	if b == nil {
		return nil, bolt.ErrBucketNotFound
	}

	c := b.Cursor()
	var results []Item

	for k, v := c.Seek(prefix); k != nil && bytes.HasPrefix(k, prefix); k, v = c.Next() {
		keyCopy := make([]byte, len(k))
		copy(keyCopy, k)

		var valCopy []byte
		if v != nil {
			valCopy = make([]byte, len(v))
			copy(valCopy, v)
		}
		results = append(results, Item{Key: keyCopy, Value: valCopy})
	}

	return results, nil
}

// CollectAll returns all key-value pairs in the specified bucket using a Cursor.
func CollectAll(tx *bolt.Tx, bucketName []byte) ([]Item, error) {
	b := tx.Bucket(bucketName)
	if b == nil {
		return nil, bolt.ErrBucketNotFound
	}

	c := b.Cursor()
	var results []Item

	for k, v := c.First(); k != nil; k, v = c.Next() {
		keyCopy := make([]byte, len(k))
		copy(keyCopy, k)

		var valCopy []byte
		if v != nil {
			valCopy = make([]byte, len(v))
			copy(valCopy, v)
		}
		results = append(results, Item{Key: keyCopy, Value: valCopy})
	}

	return results, nil
}

{
  "schemaVersion": 1,
  "goal": "verify go.etcd.io/bbolt.Cursor in pkg:golang/go.etcd.io/bbolt@v1.4.3",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.etcd.io/bbolt@v1.4.3"
  ],
  "symbols": [
    "go.etcd.io/bbolt.Cursor"
  ]
}

package main

import (
	"bytes"
	"errors"
	"fmt"
	"os"
	"path/filepath"

	bolt "go.etcd.io/bbolt"
	"sample"
)

func main() {
	tmpDir, err := os.MkdirTemp("", "bbolt-cursor-test-*")
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: failed to create temp dir: %v\n", err)
		os.Exit(1)
	}
	defer os.RemoveAll(tmpDir)

	dbPath := filepath.Join(tmpDir, "test.db")
	db, err := sample.OpenDB(dbPath)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: failed to open db: %v\n", err)
		os.Exit(1)
	}
	defer db.Close()

	bucketName := []byte("users")
	emptyBucketName := []byte("empty")

	// Seed test data
	err = db.Update(func(tx *bolt.Tx) error {
		b, err := tx.CreateBucket(bucketName)
		if err != nil {
			return err
		}
		if _, err := tx.CreateBucket(emptyBucketName); err != nil {
			return err
		}
		// Insert keys in non-sorted order to verify bbolt sorts them
		items := map[string]string{
			"user:20": "bob",
			"user:10": "alice",
			"user:30": "charlie",
		}
		for k, v := range items {
			if err := b.Put([]byte(k), []byte(v)); err != nil {
				return err
			}
		}
		return nil
	})
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: seeding data failed: %v\n", err)
		os.Exit(1)
	}

	// Assertion 1: Cursor.First and Cursor.Last navigate to the first and last key-value pairs in a bucket
	err = db.View(func(tx *bolt.Tx) error {
		b := tx.Bucket(bucketName)
		c := b.Cursor()

		k1, v1 := c.First()
		if !bytes.Equal(k1, []byte("user:10")) || !bytes.Equal(v1, []byte("alice")) {
			return fmt.Errorf("c.First() expected (user:10, alice), got (%s, %s)", string(k1), string(v1))
		}

		kLast, vLast := c.Last()
		if !bytes.Equal(kLast, []byte("user:30")) || !bytes.Equal(vLast, []byte("charlie")) {
			return fmt.Errorf("c.Last() expected (user:30, charlie), got (%s, %s)", string(kLast), string(vLast))
		}

		// Empty bucket behavior
		bEmpty := tx.Bucket(emptyBucketName)
		cEmpty := bEmpty.Cursor()
		if k, v := cEmpty.First(); k != nil || v != nil {
			return fmt.Errorf("cEmpty.First() expected (nil, nil), got (%s, %s)", string(k), string(v))
		}
		if k, v := cEmpty.Last(); k != nil || v != nil {
			return fmt.Errorf("cEmpty.Last() expected (nil, nil), got (%s, %s)", string(k), string(v))
		}
		return nil
	})
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL Assertion 1: %v\n", err)
		os.Exit(1)
	}

	// Assertion 2: Cursor.Next and Cursor.Prev traverse key-value pairs sequentially in ascending and descending order
	err = db.View(func(tx *bolt.Tx) error {
		b := tx.Bucket(bucketName)
		c := b.Cursor()

		// Ascending traversal
		var keysAsc []string
		for k, _ := c.First(); k != nil; k, _ = c.Next() {
			keysAsc = append(keysAsc, string(k))
		}
		if len(keysAsc) != 3 || keysAsc[0] != "user:10" || keysAsc[1] != "user:20" || keysAsc[2] != "user:30" {
			return fmt.Errorf("ascending traversal mismatch: %v", keysAsc)
		}

		// Descending traversal
		var keysDesc []string
		for k, _ := c.Last(); k != nil; k, _ = c.Prev() {
			keysDesc = append(keysDesc, string(k))
		}
		if len(keysDesc) != 3 || keysDesc[0] != "user:30" || keysDesc[1] != "user:20" || keysDesc[2] != "user:10" {
			return fmt.Errorf("descending traversal mismatch: %v", keysDesc)
		}

		// Next beyond last returns nil
		c.Last()
		if k, v := c.Next(); k != nil || v != nil {
			return fmt.Errorf("c.Next() after Last expected (nil, nil), got (%s, %s)", string(k), string(v))
		}

		// Prev before first returns nil
		c.First()
		if k, v := c.Prev(); k != nil || v != nil {
			return fmt.Errorf("c.Prev() after First expected (nil, nil), got (%s, %s)", string(k), string(v))
		}
		return nil
	})
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL Assertion 2: %v\n", err)
		os.Exit(1)
	}

	// Assertion 3: Cursor.Seek positions at the first key greater than or equal to a target key
	err = db.View(func(tx *bolt.Tx) error {
		b := tx.Bucket(bucketName)
		c := b.Cursor()

		// Seek exact match
		k, v := c.Seek([]byte("user:20"))
		if !bytes.Equal(k, []byte("user:20")) || !bytes.Equal(v, []byte("bob")) {
			return fmt.Errorf("c.Seek exact expected (user:20, bob), got (%s, %s)", string(k), string(v))
		}

		// Seek inexact (between 10 and 20)
		k, v = c.Seek([]byte("user:15"))
		if !bytes.Equal(k, []byte("user:20")) || !bytes.Equal(v, []byte("bob")) {
			return fmt.Errorf("c.Seek inexact expected (user:20, bob), got (%s, %s)", string(k), string(v))
		}

		// Seek beyond all keys
		k, v = c.Seek([]byte("user:99"))
		if k != nil || v != nil {
			return fmt.Errorf("c.Seek beyond all keys expected (nil, nil), got (%s, %s)", string(k), string(v))
		}

		// Prefix scan using helper
		prefixResults, err := sample.ScanPrefix(tx, bucketName, []byte("user:"))
		if err != nil {
			return fmt.Errorf("ScanPrefix failed: %w", err)
		}
		if len(prefixResults) != 3 {
			return fmt.Errorf("ScanPrefix expected 3 items, got %d", len(prefixResults))
		}
		return nil
	})
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL Assertion 3: %v\n", err)
		os.Exit(1)
	}

	// Assertion 4: Cursor.Delete removes current key-value pair in a writable transaction and returns ErrTxNotWritable in a read-only transaction
	roTx, err := db.Begin(false)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: db.Begin(false) failed: %v\n", err)
		os.Exit(1)
	}
	roCursor := roTx.Bucket(bucketName).Cursor()
	roCursor.First()
	if err := roCursor.Delete(); !errors.Is(err, bolt.ErrTxNotWritable) {
		fmt.Fprintf(os.Stderr, "FAIL Assertion 4: expected ErrTxNotWritable on read-only Delete, got: %v\n", err)
		os.Exit(1)
	}
	_ = roTx.Rollback()

	rwTx, err := db.Begin(true)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: db.Begin(true) failed: %v\n", err)
		os.Exit(1)
	}
	rwCursor := rwTx.Bucket(bucketName).Cursor()
	rwCursor.Seek([]byte("user:20"))
	if err := rwCursor.Delete(); err != nil {
		fmt.Fprintf(os.Stderr, "FAIL Assertion 4: rwCursor.Delete() failed: %v\n", err)
		os.Exit(1)
	}
	if err := rwTx.Commit(); err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: rwTx.Commit failed: %v\n", err)
		os.Exit(1)
	}

	// Verify deletion
	err = db.View(func(tx *bolt.Tx) error {
		b := tx.Bucket(bucketName)
		if v := b.Get([]byte("user:20")); v != nil {
			return fmt.Errorf("user:20 was not deleted")
		}
		all, err := sample.CollectAll(tx, bucketName)
		if err != nil {
			return err
		}
		if len(all) != 2 {
			return fmt.Errorf("expected 2 items after delete, got %d", len(all))
		}
		return nil
	})
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL Assertion 4 verification: %v\n", err)
		os.Exit(1)
	}

	// Assertion 5: Cursor.Bucket returns the parent bucket being traversed
	err = db.View(func(tx *bolt.Tx) error {
		b := tx.Bucket(bucketName)
		c := b.Cursor()
		if c.Bucket() != b {
			return fmt.Errorf("c.Bucket() did not return parent bucket")
		}
		return nil
	})
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL Assertion 5: %v\n", err)
		os.Exit(1)
	}

	fmt.Println("PASS: go.etcd.io/bbolt.Cursor contract assertions passed")
}