rename iterator method

Author: rosstimothy

lib/backend/backend.go

@@ -23,6 +23,7 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"iter"
 	"sort"
 	"time"
 
@@ -113,6 +114,29 @@ type Backend interface {
 	CloseWatchers()
 }
 
+// IterateParams are parameters that are provided to
+// [Itemser.Items] to alter the iteration behavior.
+type IterateParams struct {
+	// StartKey is the key at which to begin iteration. This key
+	// will be included in the results if it exists.
+	StartKey Key
+	// EndKey is the key at which to end iteration. This key
+	// will be included in the results if it exists.
+	EndKey Key
+	// Descending indicates which direction the items should be produced,
+	// by default from [StartKey] to [EndKey].
+	Descending bool
+}
+
+// Itemser is a temporary interface that will be added to [backend.Backend]
+// once all concrete backend implementations satisfy the new interface.
+// TODO(tross): REMEMBER TO DELETE THIS
+type Itemser interface {
+	// Items produce an iterator of backend items in the range, and order
+	// described in the provided [IterateParams].
+	Items(ctx context.Context, params IterateParams) iter.Seq2[Item, error]
+}
+
 // New initializes a new [Backend] implementation based on the service config.
 func New(ctx context.Context, backend string, params Params) (Backend, error) {
 	registryMu.RLock()
@@ -248,19 +272,6 @@ type Event struct {
 	Item Item
 }
 
-// IterationOrder dictates the order in which iteration should
-// return items.
-type IterationOrder int
-
-const (
-	// IterateAscending indicates to [backend.Iterate] that items should be
-	// returned in ascending lexicographical order of the queried key range.
-	IterateAscending IterationOrder = iota
-	// IterateDescending indicates to [backend.Iterate] that items should be
-	// returned in descending lexicographical order of the queried key range.
-	IterateDescending
-)
-
 // Item is a key value item
 type Item struct {
 	// Key is a key of the key value item

lib/backend/etcdbk/etcd.go

@@ -649,30 +649,32 @@ func (b *EtcdBackend) NewWatcher(ctx context.Context, watch backend.Watch) (back
 	return b.buf.NewWatcher(ctx, watch)
 }
 
-func (b *EtcdBackend) Iterate(ctx context.Context, startKey, endKey backend.Key, order backend.IterationOrder) (iter.Seq2[backend.Item, error], error) {
-	if startKey.IsZero() {
-		return nil, trace.BadParameter("missing parameter startKey")
+func (b *EtcdBackend) Items(ctx context.Context, params backend.IterateParams) iter.Seq2[backend.Item, error] {
+	if params.StartKey.IsZero() {
+		err := trace.BadParameter("missing parameter startKey")
+		return func(yield func(backend.Item, error) bool) { yield(backend.Item{}, err) }
 	}
-	if endKey.IsZero() {
-		return nil, trace.BadParameter("missing parameter endKey")
+	if params.EndKey.IsZero() {
+		err := trace.BadParameter("missing parameter endKey")
+		return func(yield func(backend.Item, error) bool) { yield(backend.Item{}, err) }
 	}
 
 	sort := clientv3.SortAscend
-	if order == backend.IterateDescending {
+	if params.Descending {
 		sort = clientv3.SortDescend
 	}
 
 	const defaultPageSize = int64(1000)
 	return func(yield func(backend.Item, error) bool) {
-		inclusiveStartKey := b.prependPrefix(startKey)
+		inclusiveStartKey := b.prependPrefix(params.StartKey)
 		for {
 			start := b.clock.Now()
 			re, err := b.clients.Next().Get(ctx, inclusiveStartKey,
 				// etcd's range query includes the start point and excludes the end point,
 				// but Backend.GetRange is supposed to be inclusive at both ends, so we
 				// query until the very next key in lexicographic order (i.e., the same key
 				// followed by a 0 byte)
-				clientv3.WithRange(b.prependPrefix(endKey)+"\x00"),
+				clientv3.WithRange(b.prependPrefix(params.EndKey)+"\x00"),
 				clientv3.WithSort(clientv3.SortByKey, sort),
 				clientv3.WithLimit(defaultPageSize),
 			)
@@ -705,13 +707,13 @@ func (b *EtcdBackend) Iterate(ctx context.Context, startKey, endKey backend.Key,
 				}
 			}
 
-			if order == backend.IterateDescending {
+			if params.Descending {
 				inclusiveStartKey = backend.RangeEnd(backend.KeyFromString(string(re.Kvs[0].Key))).String()
 			} else {
 				inclusiveStartKey = backend.RangeEnd(backend.KeyFromString(string(re.Kvs[len(re.Kvs)-1].Key))).String()
 			}
 		}
-	}, nil
+	}
 }
 
 // GetRange returns query range
@@ -723,13 +725,8 @@ func (b *EtcdBackend) GetRange(ctx context.Context, startKey, endKey backend.Key
 		return nil, trace.BadParameter("missing parameter endKey")
 	}
 
-	iter, err := b.Iterate(ctx, startKey, endKey, backend.IterateAscending)
-	if err != nil {
-		return nil, trace.Wrap(err)
-	}
-
 	var result backend.GetResult
-	for item, err := range iter {
+	for item, err := range b.Items(ctx, backend.IterateParams{StartKey: startKey, EndKey: endKey}) {
 		if err != nil {
 			return nil, trace.Wrap(err)
 		}

lib/backend/test/suite.go

@@ -26,7 +26,6 @@ import (
 	"encoding/hex"
 	"errors"
 	"fmt"
-	"iter"
 	"os"
 	"strconv"
 	"sync"
@@ -144,8 +143,8 @@ func RunBackendComplianceSuite(t *testing.T, newBackend Constructor) {
 		testQueryRange(t, newBackend)
 	})
 
-	t.Run("Iterate", func(t *testing.T) {
-		testIterate(t, newBackend)
+	t.Run("Items", func(t *testing.T) {
+		testItems(t, newBackend)
 	})
 
 	t.Run("DeleteRange", func(t *testing.T) {
@@ -363,14 +362,12 @@ func testQueryRange(t *testing.T, newBackend Constructor) {
 	require.Empty(t, result.Items)
 }
 
-func testIterate(t *testing.T, newBackend Constructor) {
+func testItems(t *testing.T, newBackend Constructor) {
 	uut, _, err := newBackend()
 	require.NoError(t, err)
 	defer func() { require.NoError(t, uut.Close()) }()
 
-	it, ok := uut.(interface {
-		Iterate(ctx context.Context, startKey, endKey backend.Key, order backend.IterationOrder) (iter.Seq2[backend.Item, error], error)
-	})
+	it, ok := uut.(backend.Itemser)
 	if !ok {
 		t.Skip("Backend does not support iteration")
 	}
@@ -443,11 +440,8 @@ func testIterate(t *testing.T, newBackend Constructor) {
 
 		for _, test := range cases {
 			t.Run(test.name, func(t *testing.T) {
-				iterator, err := it.Iterate(ctx, test.startKey, test.endKey, backend.IterateAscending)
-				require.NoError(t, err)
-
 				i := 0
-				for item, err := range iterator {
+				for item, err := range it.Items(ctx, backend.IterateParams{StartKey: test.startKey, EndKey: test.endKey}) {
 					require.NoError(t, err)
 
 					if len(test.expected) == 0 {
@@ -520,11 +514,8 @@ func testIterate(t *testing.T, newBackend Constructor) {
 
 		for _, test := range cases {
 			t.Run(test.name, func(t *testing.T) {
-				iterator, err := it.Iterate(ctx, test.startKey, test.endKey, backend.IterateDescending)
-				require.NoError(t, err)
-
 				i := 0
-				for item, err := range iterator {
+				for item, err := range it.Items(ctx, backend.IterateParams{StartKey: test.startKey, EndKey: test.endKey, Descending: true}) {
 					require.NoError(t, err)
 
 					if len(test.expected) == 0 {