Making server action result types more consistent
diff --git a/_site/pagination/http.go b/_site/pagination/http.go
new file mode 100644
index 0000000..dd2c2d7
--- /dev/null
+++ b/_site/pagination/http.go
@@ -0,0 +1,65 @@
+package pagination
+
+import (
+ "encoding/json"
+ "io/ioutil"
+ "net/http"
+ "net/url"
+ "strings"
+
+ "github.com/racker/perigee"
+ "github.com/rackspace/gophercloud"
+)
+
+// LastHTTPResponse stores generic information derived from an HTTP response.
+// This exists primarily because the body of an http.Response can only be used once.
+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 strings.HasPrefix(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, headers map[string]string, url string) (http.Response, error) {
+ h := client.Provider.AuthenticatedHeaders()
+ for key, value := range headers {
+ h[key] = value
+ }
+
+ resp, err := perigee.Request("GET", url, perigee.Options{
+ MoreHeaders: h,
+ OkCodes: []int{200, 204},
+ })
+ if err != nil {
+ return http.Response{}, err
+ }
+ return resp.HttpResponse, nil
+}
diff --git a/_site/pagination/linked.go b/_site/pagination/linked.go
new file mode 100644
index 0000000..0376edb
--- /dev/null
+++ b/_site/pagination/linked.go
@@ -0,0 +1,63 @@
+package pagination
+
+import "fmt"
+
+// LinkedPageBase may be embedded to implement a page that provides navigational "Next" and "Previous" links within its result.
+type LinkedPageBase struct {
+ LastHTTPResponse
+
+ // LinkPath lists the keys that should be traversed within a response to arrive at the "next" pointer.
+ // If any link along the path is missing, an empty URL will be returned.
+ // If any link results in an unexpected value type, an error will be returned.
+ // When left as "nil", []string{"links", "next"} will be used as a default.
+ LinkPath []string
+}
+
+// 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) {
+ var path []string
+ var key string
+
+ if current.LinkPath == nil {
+ path = []string{"links", "next"}
+ } else {
+ path = current.LinkPath
+ }
+
+ submap, ok := current.Body.(map[string]interface{})
+ if !ok {
+ return "", fmt.Errorf("Expected an object, but was %#v", current.Body)
+ }
+
+ for {
+ key, path = path[0], path[1:len(path)]
+
+ value, ok := submap[key]
+ if !ok {
+ return "", nil
+ }
+
+ fmt.Printf("key = %#v, path = %#v, value = %#v\n", key, path, value)
+
+ if len(path) > 0 {
+ submap, ok = value.(map[string]interface{})
+ if !ok {
+ return "", fmt.Errorf("Expected an object, but was %#v", value)
+ }
+ } else {
+ if value == nil {
+ // Actual null element.
+ return "", nil
+ }
+
+ url, ok := value.(string)
+ if !ok {
+ return "", fmt.Errorf("Expected a string, but was %#v", value)
+ }
+
+ return url, nil
+ }
+ }
+}
diff --git a/_site/pagination/linked_test.go b/_site/pagination/linked_test.go
new file mode 100644
index 0000000..2621f98
--- /dev/null
+++ b/_site/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{LastHTTPResponse: r}}
+ }
+
+ return NewPager(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/_site/pagination/marker.go b/_site/pagination/marker.go
new file mode 100644
index 0000000..41b493a
--- /dev/null
+++ b/_site/pagination/marker.go
@@ -0,0 +1,34 @@
+package pagination
+
+// 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
+
+ // LastMarker returns the last "marker" value on this page.
+ LastMarker() (string, error)
+}
+
+// MarkerPageBase is a page in a collection that's paginated by "limit" and "marker" query parameters.
+type MarkerPageBase struct {
+ LastHTTPResponse
+
+ // Owner is a reference to the embedding struct.
+ Owner 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.Owner.LastMarker()
+ if err != nil {
+ return "", err
+ }
+
+ q := currentURL.Query()
+ q.Set("marker", mark)
+ currentURL.RawQuery = q.Encode()
+
+ return currentURL.String(), nil
+}
diff --git a/_site/pagination/marker_test.go b/_site/pagination/marker_test.go
new file mode 100644
index 0000000..e30264c
--- /dev/null
+++ b/_site/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) LastMarker() (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) Page {
+ p := MarkerPageResult{MarkerPageBase{LastHTTPResponse: r}}
+ p.MarkerPageBase.Owner = p
+ return p
+ }
+
+ return NewPager(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/_site/pagination/null.go b/_site/pagination/null.go
new file mode 100644
index 0000000..ae57e18
--- /dev/null
+++ b/_site/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/_site/pagination/pager.go b/_site/pagination/pager.go
new file mode 100644
index 0000000..75fe408
--- /dev/null
+++ b/_site/pagination/pager.go
@@ -0,0 +1,115 @@
+package pagination
+
+import (
+ "errors"
+
+ "github.com/rackspace/gophercloud"
+)
+
+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 {
+ client *gophercloud.ServiceClient
+
+ initialURL string
+
+ createPage func(r LastHTTPResponse) Page
+
+ Err error
+
+ // Headers supplies additional HTTP headers to populate on each paged request.
+ Headers map[string]string
+}
+
+// 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(client *gophercloud.ServiceClient, initialURL string, createPage func(r LastHTTPResponse) Page) Pager {
+ return Pager{
+ client: client,
+ initialURL: initialURL,
+ createPage: createPage,
+ }
+}
+
+// WithPageCreator returns a new Pager that substitutes a different page creation function. This is
+// useful for overriding List functions in delegation.
+func (p Pager) WithPageCreator(createPage func(r LastHTTPResponse) Page) Pager {
+ return Pager{
+ client: p.client,
+ initialURL: p.initialURL,
+ createPage: createPage,
+ }
+}
+
+func (p Pager) fetchNextPage(url string) (Page, error) {
+ resp, err := Request(p.client, p.Headers, url)
+ if err != nil {
+ return nil, err
+ }
+
+ remembered, err := RememberHTTPResponse(resp)
+ if err != nil {
+ return nil, err
+ }
+
+ return p.createPage(remembered), nil
+}
+
+// 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 {
+ if p.Err != nil {
+ return p.Err
+ }
+ 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/_site/pagination/pagination_test.go b/_site/pagination/pagination_test.go
new file mode 100644
index 0000000..779bd79
--- /dev/null
+++ b/_site/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/_site/pagination/pkg.go b/_site/pagination/pkg.go
new file mode 100644
index 0000000..912daea
--- /dev/null
+++ b/_site/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/_site/pagination/single.go b/_site/pagination/single.go
new file mode 100644
index 0000000..a7f6fde
--- /dev/null
+++ b/_site/pagination/single.go
@@ -0,0 +1,9 @@
+package pagination
+
+// 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
+}
diff --git a/_site/pagination/single_test.go b/_site/pagination/single_test.go
new file mode 100644
index 0000000..31003e5
--- /dev/null
+++ b/_site/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 NewPager(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)
+}