google.golang.org/api v0.287.1: 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.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/iterator.Done
  - google.golang.org/api/iterator.NewPageInfo
  - google.golang.org/api/iterator.NewPager
  - google.golang.org/api/support/bundler.NewBundler

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:859cb8ed1582c9627b07281205e9dee9b126cf0075d2af2cc075b6a110d3b0fa","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.287.1","kind":"HOW","packages":["pkg:golang/google.golang.org/api@v0.287.1"],"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","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/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.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 (
	"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.287.1",
  "kind": "HOW",
  "packages": [
    "pkg:golang/google.golang.org/api@v0.287.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"
  ]
}

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.287.1 contract passed")
}