google.golang.org/api v0.1.0: iterator.Done, iterator.NewPageInfo, iterator.NewPager

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 pkg:golang/google.golang.org/api@v0.1.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/google.golang.org/api@v0.1.0

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:948b7290f0e98f91efe8ac53e5c3c4d482aeb0959c12233bb0cfd79dee247024","contract":["iterator.NewPageInfo creates a functional PageInfo that supports sequential iteration terminated by iterator.Done","iterator.NewPager creates a pager that paginates through items page by page using page tokens","bundler.NewBundler groups added items into bundles and flushes them to the handler","bundler.Bundler rejects oversized items exceeding BundleByteLimit"],"goal":"verify pkg:golang/google.golang.org/api@v0.1.0","kind":"HOW","packages":["pkg:golang/google.golang.org/api@v0.1.0"],"schemaVersion":1,"symbols":["google.golang.org/api/iterator.Done","google.golang.org/api/iterator.NewPageInfo","google.golang.org/api/iterator.NewPager","google.golang.org/api/support/bundler.NewBundler"]},"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.1.0"],"schemaVersion":1,"subject":"pkg:golang/google.golang.org/api@v0.1.0","symbols":["google.golang.org/api/iterator.Done","google.golang.org/api/iterator.NewPageInfo","google.golang.org/api/iterator.NewPager","google.golang.org/api/support/bundler.NewBundler"],"verifierAdapter":"golang@1"}

module example.com/google-api-sample

go 1.26.6

require google.golang.org/api v0.1.0

require golang.org/x/sync v0.0.0-20181108010431-42b317875d0f // indirect

cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
git.apache.org/thrift.git v0.0.0-20180902110319-2566ecd5d999/go.mod h1:fPE2ZNJGynbRyZ4dJvy6G277gSllfV2HJqblrnkyeyg=
github.com/beorn7/perks v0.0.0-20180321164747-3a771d992973/go.mod h1:Dwedo/Wpr24TaqPxmxbtue+5NUziq4I4S80YR8gNf3Q=
github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
github.com/ghodss/yaml v1.0.0/go.mod h1:4dBDuWmgqj2HViK6kFavaiC9ZROes6MMH2rRYeMEF04=
github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q=
github.com/golang/lint v0.0.0-20180702182130-06c8688daad7/go.mod h1:tluoj9z5200jBnyusfRPU2LqT6J+DAorxEvtC7LHB+E=
github.com/golang/mock v1.1.1/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfbm0A=
github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5aqRK0M=
github.com/grpc-ecosystem/grpc-gateway v1.5.0/go.mod h1:RSKVYQBd5MCa4OVpNdGskqpgL2+G+NZTnrVHpWWfpdw=
github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
github.com/matttproud/golang_protobuf_extensions v1.0.1/go.mod h1:D8He9yQNgCq6Z5Ld7szi9bcBfOoFv/3dc6xSMkL2PC0=
github.com/openzipkin/zipkin-go v0.1.1/go.mod h1:NtoC/o8u3JlF1lSlyPNswIbeQH9bJTmOf0Erfk+hxe8=
github.com/prometheus/client_golang v0.8.0/go.mod h1:7SWBe2y4D6OKWSNQJUaRYU/AaXPKyh/dDVn+NZz0KFw=
github.com/prometheus/client_model v0.0.0-20180712105110-5c3871d89910/go.mod h1:MbSGuTsp3dbXC40dX6PRTWyKYBIrTGTE9sqQNg2J8bo=
github.com/prometheus/common v0.0.0-20180801064454-c7de2306084e/go.mod h1:daVV7qP5qjZbuso7PdcryaAu0sAZbrN9i7WWcTMWvro=
github.com/prometheus/procfs v0.0.0-20180725123919-05ee40e3a273/go.mod h1:c3At6R/oaqEKCNdg8wHV1ftS6bRYblBhIjjI8uT2IGk=
go.opencensus.io v0.18.0/go.mod h1:vKdFvxhtzZ9onBp9VKHK8z/sRpBMnKAsufL7wlDrCOA=
golang.org/x/lint v0.0.0-20180702182130-06c8688daad7/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/net v0.0.0-20181106065722-10aee1819953/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
golang.org/x/oauth2 v0.0.0-20181203162652-d668ce993890/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20181108010431-42b317875d0f h1:Bl/8QSvNqXvPGPGXa2z5xUTmV7VDcZyvRZ+QQXkXTZQ=
golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
golang.org/x/tools v0.0.0-20180828015842-6cd1fcedba52/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
google.golang.org/api v0.0.0-20180910000450-7ca32eb868bf/go.mod h1:4mhQ8q/RsB7i+udVvVy5NUi08OU8ZlA0gRVgrF7VFY0=
google.golang.org/api v0.1.0 h1:K6z2u68e86TPdSdefXdzvXgR1zEMa+459vBSfWYAZkI=
google.golang.org/api v0.1.0/go.mod h1:UGEZY7KEX120AnNLIHFMKIo4obdJhkp2tPbaPlQx13Y=
google.golang.org/appengine v1.1.0/go.mod h1:EbEs0AVv82hx2wNQdGPgUI5lhzA/G0D9YwlJXL52JkM=
google.golang.org/appengine v1.3.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7/EB5XEv4=
google.golang.org/genproto v0.0.0-20180817151627-c66870c02cf8/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc=
google.golang.org/genproto v0.0.0-20180831171423-11092d34479b/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc=
google.golang.org/genproto v0.0.0-20181202183823-bd91e49a0898/go.mod h1:7Ep/1NZk928CDR8SjdVbjWNpdIf6nzjE3BTgJDr2Atg=
google.golang.org/grpc v1.14.0/go.mod h1:yo6s7OP7yaDglbqo1J04qKzAhqBH6lvTonzMVmEdcZw=
google.golang.org/grpc v1.16.0/go.mod h1:0JHn/cJsOMiMfNA9+DeHDlAU7KAAB5GDlYFpa9MZMio=
google.golang.org/grpc v1.17.0/go.mod h1:6QZJwpn2B+Zp71q/5VxRsJ6NXXVCE5NRUHRo+f3cWCs=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
honnef.co/go/tools v0.0.0-20180728063816-88497007e858/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=

package sample

import (
	"strconv"
	"time"

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

// StringIterator wraps a slice of strings into a pageable iterator using iterator.NewPageInfo.
type StringIterator struct {
	items []string
	buf   []string
	pi    *iterator.PageInfo
	next  func() error
}

// NewStringIterator initializes a new StringIterator.
func NewStringIterator(items []string) *StringIterator {
	it := &StringIterator{
		items: items,
	}
	it.pi, it.next = iterator.NewPageInfo(
		func(pageSize int, pageToken string) (string, error) {
			if pageSize <= 0 {
				pageSize = 2
			}
			start := 0
			if pageToken != "" {
				idx, err := strconv.Atoi(pageToken)
				if err != nil {
					return "", err
				}
				start = idx
			}
			if start >= len(it.items) {
				return "", nil
			}
			end := start + pageSize
			nextTok := ""
			if end < len(it.items) {
				nextTok = strconv.Itoa(end)
			} else {
				end = len(it.items)
			}
			it.buf = append(it.buf, it.items[start:end]...)
			return nextTok, nil
		},
		func() int {
			return len(it.buf)
		},
		func() interface{} {
			b := it.buf
			it.buf = nil
			return b
		},
	)
	return it
}

// PageInfo returns the PageInfo associated with the iterator.
func (it *StringIterator) PageInfo() *iterator.PageInfo {
	return it.pi
}

// Next returns the next item in the iterator or iterator.Done when exhausted.
func (it *StringIterator) Next() (string, error) {
	if err := it.next(); err != nil {
		return "", err
	}
	item := it.buf[0]
	it.buf = it.buf[1:]
	return item, nil
}

// CreateMessageBundler creates a new Bundler with custom threshold and handler.
func CreateMessageBundler(threshold int, handler func([]string)) *bundler.Bundler {
	b := bundler.NewBundler("", func(items interface{}) {
		handler(items.([]string))
	})
	b.DelayThreshold = 50 * time.Millisecond
	b.BundleCountThreshold = threshold
	return b
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/google.golang.org/api@v0.1.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/google.golang.org/api@v0.1.0"
  ],
  "symbols": [
    "google.golang.org/api/iterator.Done",
    "google.golang.org/api/iterator.NewPageInfo",
    "google.golang.org/api/iterator.NewPager",
    "google.golang.org/api/support/bundler.NewBundler"
  ],
  "runtimeConditions": {
    "ecosystem": "golang",
    "language": "go",
    "packageManager": "go@1.26.6",
    "runtime": "go@1.26.6"
  }
}

package main

import (
	"fmt"
	"os"
	"sync"

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

func main() {
	items := []string{"item-1", "item-2", "item-3", "item-4"}

	// 1. iterator.NewPageInfo creates a functional PageInfo that supports sequential iteration terminated by iterator.Done
	it := sample.NewStringIterator(items)
	var collected []string
	for {
		val, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: unexpected iterator error: %v\n", err)
			os.Exit(1)
		}
		collected = append(collected, val)
	}
	if len(collected) != len(items) {
		fmt.Fprintf(os.Stderr, "FAIL: expected %d items, got %d\n", len(items), len(collected))
		os.Exit(1)
	}

	// 2. iterator.NewPager creates a pager that paginates through items page by page using page tokens
	it2 := sample.NewStringIterator(items)
	pager := iterator.NewPager(it2, 2, "")
	var page1 []string
	tok1, err := pager.NextPage(&page1)
	if err != nil || len(page1) != 2 || page1[0] != "item-1" || page1[1] != "item-2" || tok1 != "2" {
		fmt.Fprintf(os.Stderr, "FAIL: page1 mismatch: tok=%q, page=%v, err=%v\n", tok1, page1, err)
		os.Exit(1)
	}

	var page2 []string
	tok2, err := pager.NextPage(&page2)
	if err != nil || len(page2) != 2 || page2[0] != "item-3" || page2[1] != "item-4" || tok2 != "" {
		fmt.Fprintf(os.Stderr, "FAIL: page2 mismatch: tok=%q, page=%v, err=%v\n", tok2, page2, err)
		os.Exit(1)
	}

	// 3. bundler.NewBundler groups added items into bundles and flushes them to the handler
	var mu sync.Mutex
	var bundled []string
	b := sample.CreateMessageBundler(2, func(msgs []string) {
		mu.Lock()
		defer mu.Unlock()
		bundled = append(bundled, msgs...)
	})

	if err := b.Add("msg-a", 1); err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: b.Add failed: %v\n", err)
		os.Exit(1)
	}
	if err := b.Add("msg-b", 1); err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: b.Add failed: %v\n", err)
		os.Exit(1)
	}
	b.Flush()

	mu.Lock()
	if len(bundled) != 2 || bundled[0] != "msg-a" || bundled[1] != "msg-b" {
		fmt.Fprintf(os.Stderr, "FAIL: unexpected bundled results: %v\n", bundled)
		mu.Unlock()
		os.Exit(1)
	}
	mu.Unlock()

	// 4. bundler.Bundler rejects oversized items exceeding BundleByteLimit
	b.BundleByteLimit = 5
	if err := b.Add("oversized-message-content", 10); err != bundler.ErrOversizedItem {
		fmt.Fprintf(os.Stderr, "FAIL: expected ErrOversizedItem, got: %v\n", err)
		os.Exit(1)
	}

	fmt.Println("PASS: pkg:golang/google.golang.org/api@v0.1.0 contract passed")
}