Add the paginator utility for retrieving Voice objects

Author: polyfloyd

voice/callflow.go

@@ -3,22 +3,12 @@ package voice
 import (
 	"encoding/json"
 	"fmt"
+	"reflect"
 	"time"
 
 	"github.com/messagebird/go-rest-api"
 )
 
-// CallFlowList is a single page from the total collection of call flows.
-type CallFlowList struct {
-	Items      []CallFlow `json:"data"`
-	Pagination struct {
-		TotalCount  int `json:"totalCount"`
-		PageCount   int `json:"pageCount"`
-		CurrentPage int `json:"currentPage"`
-		PerPage     int `json:"perPage"`
-	} `json:"pagination"`
-}
-
 // A CallFlow describes the flow of operations (steps) to be executed when
 // handling an incoming call.
 type CallFlow struct {
@@ -119,15 +109,9 @@ func CallFlowByID(client *messagebird.Client, id string) (*CallFlow, error) {
 	return callflow, err
 }
 
-// CallFlows lists the callflows on the specified page.
-//
-// Page indices start at 1.
-//
-// Typically, a page contains 10 callflows.
-func CallFlows(client *messagebird.Client, page int) (*CallFlowList, error) {
-	list := &CallFlowList{}
-	err := client.Request(list, "GET", fmt.Sprintf("call-flow/?page=%d", page), nil)
-	return list, err
+// CallFlows returns a Paginator which iterates over all CallFlows.
+func CallFlows(client *messagebird.Client) *Paginator {
+	return newPaginator(client, "call-flow/", reflect.TypeOf(CallFlow{}))
 }
 
 // CreateCallFlow creates the callflow remotely.

voice/paginator.go

@@ -0,0 +1,108 @@
+package voice
+
+import (
+	"fmt"
+	"io"
+	"reflect"
+
+	messagebird "github.com/messagebird/go-rest-api"
+)
+
+// A Paginator is used to stream the contents of a collection of some type from
+// the MessageBird API.
+//
+// Paginators are single use and can therefore not be reset.
+type Paginator struct {
+	endpoint   string
+	nextPage   int
+	structType reflect.Type
+	client     *messagebird.Client
+}
+
+// newPaginator creates a new paginator.
+//
+// endpoint is called with the `page` query parameter until no more pages are
+// available.
+//
+// typ is the non-pointer type of a single element returned by a page.
+func newPaginator(client *messagebird.Client, endpoint string, typ reflect.Type) *Paginator {
+	return &Paginator{
+		endpoint:   endpoint,
+		nextPage:   1, // Page indices start at 1.
+		structType: typ,
+		client:     client,
+	}
+}
+
+// NextPage queries the next page from the MessageBird API.
+//
+// The interface{} contains a slice of the type this paginator handles.
+//
+// When no more items are available, an empty slice and io.EOF are returned.
+// If another kind of error occurs, nil and and the error are returned.
+func (pag *Paginator) NextPage() (interface{}, error) {
+	type pagination struct {
+		TotalCount  int `json:"totalCount"`
+		PageCount   int `json:"pageCount"`
+		CurrentPage int `json:"currentPage"`
+		PerPage     int `json:"perPage"`
+	}
+	rawType := reflect.StructOf([]reflect.StructField{
+		{
+			Name: "Data",
+			Type: reflect.SliceOf(pag.structType),
+			Tag:  "json:\"data\"",
+		},
+		{
+			Name: "Pagination",
+			Type: reflect.TypeOf(pagination{}),
+			Tag:  "json:\"pagination\"",
+		},
+	})
+	rawVal := reflect.New(rawType)
+
+	if err := pag.client.Request(rawVal.Interface(), "GET", fmt.Sprintf("%s?page=%d", pag.endpoint, pag.nextPage), nil); err != nil {
+		return nil, err
+	}
+
+	data := rawVal.Elem().FieldByName("Data").Interface()
+	pageInfo := rawVal.Elem().FieldByName("Pagination").Interface().(pagination)
+
+	// If no more items are available, a page with 0 elements is returned.
+	if pag.nextPage > pageInfo.PageCount {
+		return data, io.EOF
+	}
+
+	pag.nextPage++
+	return data, nil
+}
+
+// Stream creates a channel which streams the contents of all remaining pages
+// ony by one.
+//
+// The Paginator is consumed in the process, meaning that after elements have
+// been received, NextPage will return EOF. It is invalid to mix calls to
+// NextPage an Stream, even after the stream channel was closed.
+//
+// If an error occurs, the next item sent over the channel will be an error
+// instead of a regular value. The channel is closed directly after this.
+func (pag *Paginator) Stream() <-chan interface{} {
+	out := make(chan interface{})
+	go func() {
+		defer close(out)
+		for {
+			page, err := pag.NextPage()
+			if err != nil {
+				if err != io.EOF {
+					out <- err
+				}
+				break
+			}
+			v := reflect.ValueOf(page)
+			for i, l := 0, v.Len(); i < l; i++ {
+				out <- v.Index(i).Interface()
+			}
+		}
+	}()
+	return out
+}

voice/paginator_test.go

@@ -0,0 +1,41 @@
+package voice
+
+import (
+	"net/http"
+	"reflect"
+	"testing"
+)
+
+func TestPaginatorStream(t *testing.T) {
+	type myStruct struct {
+		Val int
+	}
+	mbClient, stop := testClient(http.StatusOK, []byte(`{
+		"data": [
+			{ "Val": 1 },
+			{ "Val": 2 },
+			{ "Val": 3 }
+		],
+		"pagination": {
+			"totalCount": 3,
+			"pageCount": 1,
+			"currentPage": 1,
+			"perPage": 10
+		}
+	}`))
+	defer stop()
+
+	pag := newPaginator(mbClient, "", reflect.TypeOf(myStruct{}))
+
+	i := 0
+	for val := range pag.Stream() {
+		t.Logf("%d, %v", i+1, val)
+		if v, ok := val.(myStruct); !ok || v.Val != i+1 {
+			t.Fatalf("unexpected item at index %d: %#v", i, val)
+		}
+		i++
+	}
+	if i != 3 {
+		t.Fatalf("unexpected number of elements: %d", i)
+	}
+}