google.golang.org/api v0.287.1: bundler.Bundler

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 google.golang.org/api/support/bundler.Bundler in pkg:golang/google.golang.org/api@v0.287.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/google.golang.org/api@v0.287.1
Demonstrate these symbols/APIs:
  - google.golang.org/api/support/bundler.Bundler

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:eee486d1ed67052a836a61a7a04a9c17efb9d684510e608f6950a9e0ae7a6b7f","contract":["Bundler batches items and invokes handler when BundleCountThreshold is reached","Bundler invokes handler when bundle bytes reach BundleByteThreshold","Bundler.Flush forces processing of all pending buffered items and blocks until handler completes","Bundler.Add returns ErrOversizedItem when item size exceeds BundleByteLimit","Bundler.Add returns ErrOverflow when total buffered bytes exceed BufferedByteLimit","Bundler prevents mixing calls to Add and AddWait"],"goal":"verify google.golang.org/api/support/bundler.Bundler in pkg:golang/google.golang.org/api@v0.287.1","kind":"HOW","packages":["pkg:golang/google.golang.org/api@v0.287.1"],"schemaVersion":1,"symbols":["google.golang.org/api/support/bundler.Bundler"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","moduleSystem":"go.mod","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/google.golang.org/api@v0.287.1"],"schemaVersion":1,"subject":"pkg:golang/google.golang.org/api@v0.287.1","symbols":["google.golang.org/api/support/bundler.Bundler"],"verifierAdapter":"golang@1"}

module example.com/bundler-sample

go 1.26.6

require google.golang.org/api v0.287.1

require golang.org/x/sync v0.21.0 // indirect

golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
google.golang.org/api v0.287.1 h1:LiyJx32VU3cwQfLchn/513qKhc25hq0pEANYJoWNnnI=
google.golang.org/api v0.287.1/go.mod h1:lM2kYRzYUCBY91P9h6VF1PYmvhxii3O5hji37qRvIcY=

package sample

import (
	"context"
	"time"

	"google.golang.org/api/support/bundler"
)

// ItemBundler wraps bundler.Bundler for string items.
type ItemBundler struct {
	*bundler.Bundler
}

// NewItemBundler creates a Bundler for string items with a specified count threshold.
func NewItemBundler(countThreshold int, handler func([]string)) *ItemBundler {
	b := bundler.NewBundler("", func(items interface{}) {
		handler(items.([]string))
	})
	b.BundleCountThreshold = countThreshold
	b.DelayThreshold = 10 * time.Minute
	return &ItemBundler{Bundler: b}
}

// NewByteBundler creates a Bundler configured with byte limit and byte threshold.
func NewByteBundler(byteLimit, byteThreshold int, handler func([]string)) *ItemBundler {
	b := bundler.NewBundler("", func(items interface{}) {
		handler(items.([]string))
	})
	b.BundleByteLimit = byteLimit
	b.BundleByteThreshold = byteThreshold
	b.DelayThreshold = 10 * time.Minute
	return &ItemBundler{Bundler: b}
}

// NewMemoryLimitedBundler creates a Bundler configured with BufferedByteLimit.
func NewMemoryLimitedBundler(bufferedByteLimit int, handler func([]string)) *ItemBundler {
	b := bundler.NewBundler("", func(items interface{}) {
		handler(items.([]string))
	})
	b.BufferedByteLimit = bufferedByteLimit
	b.DelayThreshold = 10 * time.Minute
	return &ItemBundler{Bundler: b}
}

// AddString adds a string item with given byte weight.
func (b *ItemBundler) AddString(item string, size int) error {
	return b.Add(item, size)
}

// AddWaitString adds a string item with given byte weight waiting for space.
func (b *ItemBundler) AddWaitString(ctx context.Context, item string, size int) error {
	return b.AddWait(ctx, item, size)
}

{
  "schemaVersion": 1,
  "goal": "verify google.golang.org/api/support/bundler.Bundler in pkg:golang/google.golang.org/api@v0.287.1",
  "kind": "HOW",
  "packages": [
    "pkg:golang/google.golang.org/api@v0.287.1"
  ],
  "symbols": [
    "google.golang.org/api/support/bundler.Bundler"
  ]
}

package main

import (
	"context"
	"fmt"
	"os"
	"reflect"
	"strings"
	"sync"
	"time"

	sample "example.com/bundler-sample"
	"google.golang.org/api/support/bundler"
)

func main() {
	if err := runTests(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract test failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("PASS: google.golang.org/api/support/bundler.Bundler contract passed")
}

func runTests() error {
	// 1. Bundler batches items and invokes handler when BundleCountThreshold is reached
	{
		var mu sync.Mutex
		var batches [][]string
		batchChan := make(chan []string, 1)

		b := sample.NewItemBundler(3, func(items []string) {
			mu.Lock()
			copied := append([]string(nil), items...)
			batches = append(batches, copied)
			mu.Unlock()
			batchChan <- copied
		})

		if err := b.AddString("item-1", 1); err != nil {
			return fmt.Errorf("test 1: AddString item-1: %w", err)
		}
		if err := b.AddString("item-2", 1); err != nil {
			return fmt.Errorf("test 1: AddString item-2: %w", err)
		}

		select {
		case <-batchChan:
			return fmt.Errorf("test 1: handler called before BundleCountThreshold reached")
		case <-time.After(50 * time.Millisecond):
		}

		if err := b.AddString("item-3", 1); err != nil {
			return fmt.Errorf("test 1: AddString item-3: %w", err)
		}

		select {
		case batch := <-batchChan:
			expected := []string{"item-1", "item-2", "item-3"}
			if !reflect.DeepEqual(batch, expected) {
				return fmt.Errorf("test 1: expected batch %v, got %v", expected, batch)
			}
		case <-time.After(2 * time.Second):
			return fmt.Errorf("test 1: timed out waiting for batch handler")
		}
	}

	// 2. Bundler invokes handler when bundle bytes reach BundleByteThreshold
	{
		batchChan := make(chan []string, 1)
		b := sample.NewByteBundler(0, 10, func(items []string) {
			batchChan <- append([]string(nil), items...)
		})

		if err := b.AddString("short-1", 4); err != nil {
			return fmt.Errorf("test 2: AddString short-1: %w", err)
		}

		select {
		case <-batchChan:
			return fmt.Errorf("test 2: handler called before BundleByteThreshold reached")
		case <-time.After(50 * time.Millisecond):
		}

		if err := b.AddString("short-2", 6); err != nil {
			return fmt.Errorf("test 2: AddString short-2: %w", err)
		}

		select {
		case batch := <-batchChan:
			expected := []string{"short-1", "short-2"}
			if !reflect.DeepEqual(batch, expected) {
				return fmt.Errorf("test 2: expected batch %v, got %v", expected, batch)
			}
		case <-time.After(2 * time.Second):
			return fmt.Errorf("test 2: timed out waiting for byte-triggered batch")
		}
	}

	// 3. Bundler.Flush forces processing of all pending buffered items and blocks until handler completes
	{
		var mu sync.Mutex
		var flushed []string
		handlerDone := false

		b := sample.NewItemBundler(10, func(items []string) {
			time.Sleep(50 * time.Millisecond)
			mu.Lock()
			flushed = append(flushed, items...)
			handlerDone = true
			mu.Unlock()
		})

		if err := b.AddString("pending-1", 1); err != nil {
			return fmt.Errorf("test 3: AddString pending-1: %w", err)
		}
		if err := b.AddString("pending-2", 1); err != nil {
			return fmt.Errorf("test 3: AddString pending-2: %w", err)
		}

		b.Flush()

		mu.Lock()
		done := handlerDone
		count := len(flushed)
		mu.Unlock()

		if !done || count != 2 {
			return fmt.Errorf("test 3: expected handler to complete synchronously on Flush, done=%v, count=%d", done, count)
		}
	}

	// 4. Bundler.Add returns ErrOversizedItem when item size exceeds BundleByteLimit
	{
		b := sample.NewByteBundler(8, 5, func(items []string) {})
		err := b.AddString("oversized", 9)
		if err != bundler.ErrOversizedItem {
			return fmt.Errorf("test 4: expected ErrOversizedItem, got %v", err)
		}
	}

	// 5. Bundler.Add returns ErrOverflow when total buffered bytes exceed BufferedByteLimit
	{
		b := sample.NewMemoryLimitedBundler(10, func(items []string) {})
		err := b.AddString("overflowing", 15)
		if err != bundler.ErrOverflow {
			return fmt.Errorf("test 5: expected ErrOverflow, got %v", err)
		}
	}

	// 6. Bundler prevents mixing calls to Add and AddWait
	{
		b := sample.NewItemBundler(5, func(items []string) {})
		if err := b.AddString("normal-add", 1); err != nil {
			return fmt.Errorf("test 6: initial Add failed: %w", err)
		}

		ctx := context.Background()
		err := b.AddWaitString(ctx, "wait-add", 1)
		if err == nil {
			return fmt.Errorf("test 6: expected error when calling AddWait after Add, got nil")
		}
		if !strings.Contains(err.Error(), "calls to Add and AddWait cannot be mixed") {
			return fmt.Errorf("test 6: unexpected error message: %v", err)
		}
	}

	return nil
}