Move pagination to its own package.
diff --git a/pagination/http.go b/pagination/http.go
new file mode 100644
index 0000000..31cde49
--- /dev/null
+++ b/pagination/http.go
@@ -0,0 +1,58 @@
+package pagination
+
+import (
+ "encoding/json"
+ "io/ioutil"
+ "net/http"
+ "net/url"
+
+ "github.com/racker/perigee"
+ "github.com/rackspace/gophercloud"
+)
+
+// LastHTTPResponse stores generic information derived from an HTTP response.
+type LastHTTPResponse struct {
+ url.URL
+ http.Header
+ Body interface{}
+}
+
+// RememberHTTPResponse parses an HTTP response as JSON and returns a LastHTTPResponse containing the results.
+// The main reason to do this instead of holding the response directly is that a response body can only be read once.
+// Also, this centralizes the JSON decoding.
+func RememberHTTPResponse(resp http.Response) (LastHTTPResponse, error) {
+ var parsedBody interface{}
+
+ defer resp.Body.Close()
+ rawBody, err := ioutil.ReadAll(resp.Body)
+ if err != nil {
+ return LastHTTPResponse{}, err
+ }
+
+ if resp.Header.Get("Content-Type") == "application/json" {
+ err = json.Unmarshal(rawBody, &parsedBody)
+ if err != nil {
+ return LastHTTPResponse{}, err
+ }
+ } else {
+ parsedBody = rawBody
+ }
+
+ return LastHTTPResponse{
+ URL: *resp.Request.URL,
+ Header: resp.Header,
+ Body: parsedBody,
+ }, err
+}
+
+// Request performs a Perigee request and extracts the http.Response from the result.
+func Request(client *gophercloud.ServiceClient, url string) (http.Response, error) {
+ resp, err := perigee.Request("GET", url, perigee.Options{
+ MoreHeaders: client.Provider.AuthenticatedHeaders(),
+ OkCodes: []int{200, 204},
+ })
+ if err != nil {
+ return http.Response{}, err
+ }
+ return resp.HttpResponse, nil
+}
diff --git a/pagination/linked.go b/pagination/linked.go
new file mode 100644
index 0000000..3b26013
--- /dev/null
+++ b/pagination/linked.go
@@ -0,0 +1,54 @@
+package pagination
+
+import (
+ "github.com/mitchellh/mapstructure"
+ "github.com/rackspace/gophercloud"
+)
+
+// LinkedPageBase may be embedded to implement a page that provides navigational "Next" and "Previous" links within its result.
+type LinkedPageBase LastHTTPResponse
+
+// NextPageURL extracts the pagination structure from a JSON response and returns the "next" link, if one is present.
+// It assumes that the links are available in a "links" element of the top-level response object.
+// If this is not the case, override NextPageURL on your result type.
+func (current LinkedPageBase) NextPageURL() (string, error) {
+ type response struct {
+ Links struct {
+ Next *string `mapstructure:"next,omitempty"`
+ } `mapstructure:"links"`
+ }
+
+ var r response
+ err := mapstructure.Decode(current.Body, &r)
+ if err != nil {
+ return "", err
+ }
+
+ if r.Links.Next == nil {
+ return "", nil
+ }
+
+ return *r.Links.Next, nil
+}
+
+// NewLinkedPager creates a Pager that uses a "links" element in the JSON response to locate the next page.
+func NewLinkedPager(client *gophercloud.ServiceClient, initialURL string, createPage func(resp LastHTTPResponse) Page) Pager {
+ fetchNextPage := func(url string) (Page, error) {
+ resp, err := Request(client, url)
+ if err != nil {
+ return nil, err
+ }
+
+ cp, err := RememberHTTPResponse(resp)
+ if err != nil {
+ return nil, err
+ }
+
+ return createPage(cp), nil
+ }
+
+ return Pager{
+ initialURL: initialURL,
+ fetchNextPage: fetchNextPage,
+ }
+}
diff --git a/pagination/linked_test.go b/pagination/linked_test.go
new file mode 100644
index 0000000..6346126
--- /dev/null
+++ b/pagination/linked_test.go
@@ -0,0 +1,107 @@
+package pagination
+
+import (
+ "fmt"
+ "net/http"
+ "reflect"
+ "testing"
+
+ "github.com/mitchellh/mapstructure"
+ "github.com/rackspace/gophercloud/testhelper"
+)
+
+// LinkedPager sample and test cases.
+
+type LinkedPageResult struct {
+ LinkedPageBase
+}
+
+func (r LinkedPageResult) IsEmpty() (bool, error) {
+ is, err := ExtractLinkedInts(r)
+ if err != nil {
+ return true, nil
+ }
+ return len(is) == 0, nil
+}
+
+func ExtractLinkedInts(page Page) ([]int, error) {
+ var response struct {
+ Ints []int `mapstructure:"ints"`
+ }
+
+ err := mapstructure.Decode(page.(LinkedPageResult).Body, &response)
+ if err != nil {
+ return nil, err
+ }
+
+ return response.Ints, nil
+}
+
+func createLinked(t *testing.T) Pager {
+ testhelper.SetupHTTP()
+
+ testhelper.Mux.HandleFunc("/page1", func(w http.ResponseWriter, r *http.Request) {
+ w.Header().Add("Content-Type", "application/json")
+ fmt.Fprintf(w, `{ "ints": [1, 2, 3], "links": { "next": "%s/page2" } }`, testhelper.Server.URL)
+ })
+
+ testhelper.Mux.HandleFunc("/page2", func(w http.ResponseWriter, r *http.Request) {
+ w.Header().Add("Content-Type", "application/json")
+ fmt.Fprintf(w, `{ "ints": [4, 5, 6], "links": { "next": "%s/page3" } }`, testhelper.Server.URL)
+ })
+
+ testhelper.Mux.HandleFunc("/page3", func(w http.ResponseWriter, r *http.Request) {
+ w.Header().Add("Content-Type", "application/json")
+ fmt.Fprintf(w, `{ "ints": [7, 8, 9], "links": { "next": null } }`)
+ })
+
+ client := createClient()
+
+ createPage := func(r LastHTTPResponse) Page {
+ return LinkedPageResult{LinkedPageBase(r)}
+ }
+
+ return NewLinkedPager(client, testhelper.Server.URL+"/page1", createPage)
+}
+
+func TestEnumerateLinked(t *testing.T) {
+ pager := createLinked(t)
+ defer testhelper.TeardownHTTP()
+
+ callCount := 0
+ err := pager.EachPage(func(page Page) (bool, error) {
+ actual, err := ExtractLinkedInts(page)
+ if err != nil {
+ return false, err
+ }
+
+ t.Logf("Handler invoked with %v", actual)
+
+ var expected []int
+ switch callCount {
+ case 0:
+ expected = []int{1, 2, 3}
+ case 1:
+ expected = []int{4, 5, 6}
+ case 2:
+ expected = []int{7, 8, 9}
+ default:
+ t.Fatalf("Unexpected call count: %d", callCount)
+ return false, nil
+ }
+
+ if !reflect.DeepEqual(expected, actual) {
+ t.Errorf("Call %d: Expected %#v, but was %#v", callCount, expected, actual)
+ }
+
+ callCount++
+ return true, nil
+ })
+ if err != nil {
+ t.Errorf("Unexpected error for page iteration: %v", err)
+ }
+
+ if callCount != 3 {
+ t.Errorf("Expected 3 calls, but was %d", callCount)
+ }
+}
diff --git a/pagination/marker.go b/pagination/marker.go
new file mode 100644
index 0000000..ad1fb89
--- /dev/null
+++ b/pagination/marker.go
@@ -0,0 +1,60 @@
+package pagination
+
+import "github.com/rackspace/gophercloud"
+
+// MarkerPage is a stricter Page interface that describes additional functionality required for use with NewMarkerPager.
+// For convenience, embed the MarkedPageBase struct.
+type MarkerPage interface {
+ Page
+
+ // LastMark returns the last "marker" value on this page.
+ LastMark() (string, error)
+}
+
+// MarkerPageBase is a page in a collection that's paginated by "limit" and "marker" query parameters.
+type MarkerPageBase struct {
+ LastHTTPResponse
+
+ // A reference to the embedding struct.
+ Self MarkerPage
+}
+
+// NextPageURL generates the URL for the page of results after this one.
+func (current MarkerPageBase) NextPageURL() (string, error) {
+ currentURL := current.URL
+
+ mark, err := current.Self.LastMark()
+ if err != nil {
+ return "", err
+ }
+
+ q := currentURL.Query()
+ q.Set("marker", mark)
+ currentURL.RawQuery = q.Encode()
+
+ return currentURL.String(), nil
+}
+
+// NewMarkerPager creates a Pager that iterates over successive pages by issuing requests with a "marker" parameter set to the
+// final element of the previous Page.
+func NewMarkerPager(client *gophercloud.ServiceClient, initialURL string, createPage func(resp LastHTTPResponse) MarkerPage) Pager {
+
+ fetchNextPage := func(currentURL string) (Page, error) {
+ resp, err := Request(client, currentURL)
+ if err != nil {
+ return nullPage{}, err
+ }
+
+ last, err := RememberHTTPResponse(resp)
+ if err != nil {
+ return nullPage{}, err
+ }
+
+ return createPage(last), nil
+ }
+
+ return Pager{
+ initialURL: initialURL,
+ fetchNextPage: fetchNextPage,
+ }
+}
diff --git a/pagination/marker_test.go b/pagination/marker_test.go
new file mode 100644
index 0000000..598118f
--- /dev/null
+++ b/pagination/marker_test.go
@@ -0,0 +1,113 @@
+package pagination
+
+import (
+ "fmt"
+ "net/http"
+ "strings"
+ "testing"
+
+ "github.com/rackspace/gophercloud/testhelper"
+)
+
+// MarkerPager sample and test cases.
+
+type MarkerPageResult struct {
+ MarkerPageBase
+}
+
+func (r MarkerPageResult) IsEmpty() (bool, error) {
+ results, err := ExtractMarkerStrings(r)
+ if err != nil {
+ return true, err
+ }
+ return len(results) == 0, err
+}
+
+func (r MarkerPageResult) LastMark() (string, error) {
+ results, err := ExtractMarkerStrings(r)
+ if err != nil {
+ return "", err
+ }
+ if len(results) == 0 {
+ return "", nil
+ }
+ return results[len(results)-1], nil
+}
+
+func createMarkerPaged(t *testing.T) Pager {
+ testhelper.SetupHTTP()
+
+ testhelper.Mux.HandleFunc("/page", func(w http.ResponseWriter, r *http.Request) {
+ r.ParseForm()
+ ms := r.Form["marker"]
+ switch {
+ case len(ms) == 0:
+ fmt.Fprintf(w, "aaa\nbbb\nccc")
+ case len(ms) == 1 && ms[0] == "ccc":
+ fmt.Fprintf(w, "ddd\neee\nfff")
+ case len(ms) == 1 && ms[0] == "fff":
+ fmt.Fprintf(w, "ggg\nhhh\niii")
+ case len(ms) == 1 && ms[0] == "iii":
+ w.WriteHeader(http.StatusNoContent)
+ default:
+ t.Errorf("Request with unexpected marker: [%v]", ms)
+ }
+ })
+
+ client := createClient()
+
+ createPage := func(r LastHTTPResponse) MarkerPage {
+ p := MarkerPageResult{MarkerPageBase{LastHTTPResponse: r}}
+ p.MarkerPageBase.Self = p
+ return p
+ }
+
+ return NewMarkerPager(client, testhelper.Server.URL+"/page", createPage)
+}
+
+func ExtractMarkerStrings(page Page) ([]string, error) {
+ content := page.(MarkerPageResult).Body.([]uint8)
+ parts := strings.Split(string(content), "\n")
+ results := make([]string, 0, len(parts))
+ for _, part := range parts {
+ if len(part) > 0 {
+ results = append(results, part)
+ }
+ }
+ return results, nil
+}
+
+func TestEnumerateMarker(t *testing.T) {
+ pager := createMarkerPaged(t)
+ defer testhelper.TeardownHTTP()
+
+ callCount := 0
+ err := pager.EachPage(func(page Page) (bool, error) {
+ actual, err := ExtractMarkerStrings(page)
+ if err != nil {
+ return false, err
+ }
+
+ t.Logf("Handler invoked with %v", actual)
+
+ var expected []string
+ switch callCount {
+ case 0:
+ expected = []string{"aaa", "bbb", "ccc"}
+ case 1:
+ expected = []string{"ddd", "eee", "fff"}
+ case 2:
+ expected = []string{"ggg", "hhh", "iii"}
+ default:
+ t.Fatalf("Unexpected call count: %d", callCount)
+ return false, nil
+ }
+
+ testhelper.CheckDeepEquals(t, expected, actual)
+
+ callCount++
+ return true, nil
+ })
+ testhelper.AssertNoErr(t, err)
+ testhelper.AssertEquals(t, callCount, 3)
+}
diff --git a/pagination/null.go b/pagination/null.go
new file mode 100644
index 0000000..ae57e18
--- /dev/null
+++ b/pagination/null.go
@@ -0,0 +1,20 @@
+package pagination
+
+// nullPage is an always-empty page that trivially satisfies all Page interfacts.
+// It's useful to be returned along with an error.
+type nullPage struct{}
+
+// NextPageURL always returns "" to indicate that there are no more pages to return.
+func (p nullPage) NextPageURL() (string, error) {
+ return "", nil
+}
+
+// IsEmpty always returns true to prevent iteration over nullPages.
+func (p nullPage) IsEmpty() (bool, error) {
+ return true, nil
+}
+
+// LastMark always returns "" because the nullPage contains no items to have a mark.
+func (p nullPage) LastMark() (string, error) {
+ return "", nil
+}
diff --git a/pagination/pager.go b/pagination/pager.go
new file mode 100644
index 0000000..c95d744
--- /dev/null
+++ b/pagination/pager.go
@@ -0,0 +1,76 @@
+package pagination
+
+import "errors"
+
+var (
+ // ErrPageNotAvailable is returned from a Pager when a next or previous page is requested, but does not exist.
+ ErrPageNotAvailable = errors.New("The requested page does not exist.")
+)
+
+// Page must be satisfied by the result type of any resource collection.
+// It allows clients to interact with the resource uniformly, regardless of whether or not or how it's paginated.
+// Generally, rather than implementing this interface directly, implementors should embed one of the concrete PageBase structs,
+// instead.
+// Depending on the pagination strategy of a particular resource, there may be an additional subinterface that the result type
+// will need to implement.
+type Page interface {
+
+ // NextPageURL generates the URL for the page of data that follows this collection.
+ // Return "" if no such page exists.
+ NextPageURL() (string, error)
+
+ // IsEmpty returns true if this Page has no items in it.
+ IsEmpty() (bool, error)
+}
+
+// Pager knows how to advance through a specific resource collection, one page at a time.
+type Pager struct {
+ initialURL string
+
+ fetchNextPage func(string) (Page, error)
+}
+
+// NewPager constructs a manually-configured pager.
+// Supply the URL for the first page, a function that requests a specific page given a URL, and a function that counts a page.
+func NewPager(initialURL string, fetchNextPage func(string) (Page, error)) Pager {
+ return Pager{
+ initialURL: initialURL,
+ fetchNextPage: fetchNextPage,
+ }
+}
+
+// EachPage iterates over each page returned by a Pager, yielding one at a time to a handler function.
+// Return "false" from the handler to prematurely stop iterating.
+func (p Pager) EachPage(handler func(Page) (bool, error)) error {
+ currentURL := p.initialURL
+ for {
+ currentPage, err := p.fetchNextPage(currentURL)
+ if err != nil {
+ return err
+ }
+
+ empty, err := currentPage.IsEmpty()
+ if err != nil {
+ return err
+ }
+ if empty {
+ return nil
+ }
+
+ ok, err := handler(currentPage)
+ if err != nil {
+ return err
+ }
+ if !ok {
+ return nil
+ }
+
+ currentURL, err = currentPage.NextPageURL()
+ if err != nil {
+ return err
+ }
+ if currentURL == "" {
+ return nil
+ }
+ }
+}
diff --git a/pagination/pagination_test.go b/pagination/pagination_test.go
new file mode 100644
index 0000000..779bd79
--- /dev/null
+++ b/pagination/pagination_test.go
@@ -0,0 +1,13 @@
+package pagination
+
+import (
+ "github.com/rackspace/gophercloud"
+ "github.com/rackspace/gophercloud/testhelper"
+)
+
+func createClient() *gophercloud.ServiceClient {
+ return &gophercloud.ServiceClient{
+ Provider: &gophercloud.ProviderClient{TokenID: "abc123"},
+ Endpoint: testhelper.Endpoint(),
+ }
+}
diff --git a/pagination/pkg.go b/pagination/pkg.go
new file mode 100644
index 0000000..912daea
--- /dev/null
+++ b/pagination/pkg.go
@@ -0,0 +1,4 @@
+/*
+Package pagination contains utilities and convenience structs that implement common pagination idioms within OpenStack APIs.
+*/
+package pagination
diff --git a/pagination/single.go b/pagination/single.go
new file mode 100644
index 0000000..0b5ce09
--- /dev/null
+++ b/pagination/single.go
@@ -0,0 +1,38 @@
+package pagination
+
+import "github.com/rackspace/gophercloud"
+
+// SinglePageBase may be embedded in a Page that contains all of the results from an operation at once.
+type SinglePageBase LastHTTPResponse
+
+// NextPageURL always returns "" to indicate that there are no more pages to return.
+func (current SinglePageBase) NextPageURL() (string, error) {
+ return "", nil
+}
+
+// NewSinglePager constructs a Pager that "iterates" over a single Page.
+// Supply the URL to request and a function that creates a Page of the appropriate type.
+func NewSinglePager(client *gophercloud.ServiceClient, onlyURL string, createPage func(resp LastHTTPResponse) Page) Pager {
+ consumed := false
+ single := func(_ string) (Page, error) {
+ if !consumed {
+ consumed = true
+ resp, err := Request(client, onlyURL)
+ if err != nil {
+ return nullPage{}, err
+ }
+
+ cp, err := RememberHTTPResponse(resp)
+ if err != nil {
+ return nullPage{}, err
+ }
+ return createPage(cp), nil
+ }
+ return nullPage{}, ErrPageNotAvailable
+ }
+
+ return Pager{
+ initialURL: "",
+ fetchNextPage: single,
+ }
+}
diff --git a/pagination/single_test.go b/pagination/single_test.go
new file mode 100644
index 0000000..a470b6b
--- /dev/null
+++ b/pagination/single_test.go
@@ -0,0 +1,71 @@
+package pagination
+
+import (
+ "fmt"
+ "net/http"
+ "testing"
+
+ "github.com/mitchellh/mapstructure"
+ "github.com/rackspace/gophercloud/testhelper"
+)
+
+// SinglePage sample and test cases.
+
+type SinglePageResult struct {
+ SinglePageBase
+}
+
+func (r SinglePageResult) IsEmpty() (bool, error) {
+ is, err := ExtractSingleInts(r)
+ if err != nil {
+ return true, err
+ }
+ return len(is) == 0, nil
+}
+
+func ExtractSingleInts(page Page) ([]int, error) {
+ var response struct {
+ Ints []int `mapstructure:"ints"`
+ }
+
+ err := mapstructure.Decode(page.(SinglePageResult).Body, &response)
+ if err != nil {
+ return nil, err
+ }
+
+ return response.Ints, nil
+}
+
+func setupSinglePaged() Pager {
+ testhelper.SetupHTTP()
+ client := createClient()
+
+ testhelper.Mux.HandleFunc("/only", func(w http.ResponseWriter, r *http.Request) {
+ w.Header().Add("Content-Type", "application/json")
+ fmt.Fprintf(w, `{ "ints": [1, 2, 3] }`)
+ })
+
+ createPage := func(r LastHTTPResponse) Page {
+ return SinglePageResult{SinglePageBase(r)}
+ }
+
+ return NewSinglePager(client, testhelper.Server.URL+"/only", createPage)
+}
+
+func TestEnumerateSinglePaged(t *testing.T) {
+ callCount := 0
+ pager := setupSinglePaged()
+ defer testhelper.TeardownHTTP()
+
+ err := pager.EachPage(func(page Page) (bool, error) {
+ callCount++
+
+ expected := []int{1, 2, 3}
+ actual, err := ExtractSingleInts(page)
+ testhelper.AssertNoErr(t, err)
+ testhelper.CheckDeepEquals(t, expected, actual)
+ return true, nil
+ })
+ testhelper.CheckNoErr(t, err)
+ testhelper.CheckEquals(t, 1, callCount)
+}