sync: resync vendor folder

vendor/github.com/gophercloud/gophercloud/FAQ.md

@@ -0,0 +1,148 @@
+# Tips
+
+## Implementing default logging and re-authentication attempts
+
+You can implement custom logging and/or limit re-auth attempts by creating a custom HTTP client
+like the following and setting it as the provider client's HTTP Client (via the
+`gophercloud.ProviderClient.HTTPClient` field):
+
+```go
+//...
+
+// LogRoundTripper satisfies the http.RoundTripper interface and is used to
+// customize the default Gophercloud RoundTripper to allow for logging.
+type LogRoundTripper struct {
+	rt                http.RoundTripper
+	numReauthAttempts int
+}
+
+// newHTTPClient return a custom HTTP client that allows for logging relevant
+// information before and after the HTTP request.
+func newHTTPClient() http.Client {
+	return http.Client{
+		Transport: &LogRoundTripper{
+			rt: http.DefaultTransport,
+		},
+	}
+}
+
+// RoundTrip performs a round-trip HTTP request and logs relevant information about it.
+func (lrt *LogRoundTripper) RoundTrip(request *http.Request) (*http.Response, error) {
+	glog.Infof("Request URL: %s\n", request.URL)
+
+	response, err := lrt.rt.RoundTrip(request)
+	if response == nil {
+		return nil, err
+	}
+
+	if response.StatusCode == http.StatusUnauthorized {
+		if lrt.numReauthAttempts == 3 {
+			return response, fmt.Errorf("Tried to re-authenticate 3 times with no success.")
+		}
+		lrt.numReauthAttempts++
+	}
+
+	glog.Debugf("Response Status: %s\n", response.Status)
+
+	return response, nil
+}
+
+endpoint := "https://127.0.0.1/auth"
+pc := openstack.NewClient(endpoint)
+pc.HTTPClient = newHTTPClient()
+
+//...
+```
+
+
+## Implementing custom objects
+
+OpenStack request/response objects may differ among variable names or types.
+
+### Custom request objects
+
+To pass custom options to a request, implement the desired `<ACTION>OptsBuilder` interface. For
+example, to pass in
+
+```go
+type MyCreateServerOpts struct {
+	Name string
+	Size int
+}
+```
+
+to `servers.Create`, simply implement the `servers.CreateOptsBuilder` interface:
+
+```go
+func (o MyCreateServeropts) ToServerCreateMap() (map[string]interface{}, error) {
+	return map[string]interface{}{
+		"name": o.Name,
+		"size": o.Size,
+	}, nil
+}
+```
+
+create an instance of your custom options object, and pass it to `servers.Create`:
+
+```go
+// ...
+myOpts := MyCreateServerOpts{
+	Name: "s1",
+	Size: "100",
+}
+server, err := servers.Create(computeClient, myOpts).Extract()
+// ...
+```
+
+### Custom response objects
+
+Some OpenStack services have extensions. Extensions that are supported in Gophercloud can be
+combined to create a custom object:
+
+```go
+// ...
+type MyVolume struct {
+  volumes.Volume
+  tenantattr.VolumeExt
+}
+
+var v struct {
+  MyVolume `json:"volume"`
+}
+
+err := volumes.Get(client, volID).ExtractInto(&v)
+// ...
+```
+
+## Overriding default `UnmarshalJSON` method
+
+For some response objects, a field may be a custom type or may be allowed to take on
+different types. In these cases, overriding the default `UnmarshalJSON` method may be
+necessary. To do this, declare the JSON `struct` field tag as "-" and create an `UnmarshalJSON`
+method on the type:
+
+```go
+// ...
+type MyVolume struct {
+	ID string `json: "id"`
+	TimeCreated time.Time `json: "-"`
+}
+
+func (r *MyVolume) UnmarshalJSON(b []byte) error {
+	type tmp MyVolume
+	var s struct {
+		tmp
+		TimeCreated gophercloud.JSONRFC3339MilliNoZ `json:"created_at"`
+	}
+	err := json.Unmarshal(b, &s)
+	if err != nil {
+		return err
+	}
+	*r = Volume(s.tmp)
+
+	r.TimeCreated = time.Time(s.CreatedAt)
+
+	return err
+}
+// ...
+```

vendor/github.com/gophercloud/gophercloud/README.md

@@ -125,6 +125,10 @@ The above code sample creates a new server with the parameters, and embodies the
 new resource in the `server` variable (a
 [`servers.Server`](http://godoc.org/github.com/gophercloud/gophercloud) struct).
 
+## Advanced Usage
+
+Have a look at the [FAQ](./FAQ.md) for some tips on customizing the way Gophercloud works.
+
 ## Backwards-Compatibility Guarantees
 
 None. Vendor it and write tests covering the parts you use.

vendor/github.com/gophercloud/gophercloud/STYLEGUIDE.md

@@ -20,6 +20,12 @@
 - A PR that is in-progress should have `[wip]` in front of the PR's title. When
   ready for review, remove the `[wip]` and ping a core contributor with an `@`.
 
+- Forcing PRs to be small can have the effect of users submitting PRs in a hierarchical chain, with
+  one depending on the next. If a PR depends on another one, it should have a [Pending #PRNUM]
+  prefix in the PR title. In addition, it will be the PR submitter's responsibility to remove the
+  [Pending #PRNUM] tag once the PR has been updated with the merged, dependent PR. That will
+  let reviewers know it is ready to review.
+
 - A PR should be small. Even if you intend on implementing an entire
   service, a PR should only be one route of that service
   (e.g. create server or get server, but not both).

vendor/github.com/gophercloud/gophercloud/openstack/identity/v2/tokens/results.go

@@ -132,11 +132,6 @@ func (r CreateResult) ExtractServiceCatalog() (*ServiceCatalog, error) {
 	return &ServiceCatalog{Entries: s.Access.Entries}, err
 }
 
-// createErr quickly packs an error in a CreateResult.
-func createErr(err error) CreateResult {
-	return CreateResult{gophercloud.Result{Err: err}}
-}
-
 // ExtractUser returns the User from a GetResult.
 func (r GetResult) ExtractUser() (*User, error) {
 	var s struct {

vendor/github.com/gophercloud/gophercloud/openstack/identity/v3/tokens/results.go

@@ -1,7 +1,10 @@
 package tokens
 
-import "errors"
+import (
-import "github.com/gophercloud/gophercloud"
+	"time"
+
+	"github.com/gophercloud/gophercloud"
+)
 
 // Endpoint represents a single API endpoint offered by a service.
 // It matches either a public, internal or admin URL.
@@ -35,7 +38,7 @@ type CatalogEntry struct {
 
 // ServiceCatalog provides a view into the service catalog from a previous, successful authentication.
 type ServiceCatalog struct {
-	Entries []CatalogEntry
+	Entries []CatalogEntry `json:"catalog"`
 }
 
 // commonResult is the deferred result of a Create or a Get call.
@@ -51,34 +54,23 @@ func (r commonResult) Extract() (*Token, error) {
 
 // ExtractToken interprets a commonResult as a Token.
 func (r commonResult) ExtractToken() (*Token, error) {
-	var s struct {
+	var s Token
-		Token *Token `json:"token"`
-	}
-
 	err := r.ExtractInto(&s)
 	if err != nil {
 		return nil, err
 	}
 
-	if s.Token == nil {
-		return nil, errors.New("'token' missing in JSON response")
-	}
-
 	// Parse the token itself from the stored headers.
-	s.Token.ID = r.Header.Get("X-Subject-Token")
+	s.ID = r.Header.Get("X-Subject-Token")
 
-	return s.Token, err
+	return &s, err
 }
 
 // ExtractServiceCatalog returns the ServiceCatalog that was generated along with the user's Token.
 func (r CreateResult) ExtractServiceCatalog() (*ServiceCatalog, error) {
-	var s struct {
+	var s ServiceCatalog
-		Token struct {
-			Entries []CatalogEntry `json:"catalog"`
-		} `json:"token"`
-	}
 	err := r.ExtractInto(&s)
-	return &ServiceCatalog{Entries: s.Token.Entries}, err
+	return &s, err
 }
 
 // CreateResult defers the interpretation of a created token.
@@ -87,13 +79,6 @@ type CreateResult struct {
 	commonResult
 }
 
-// createErr quickly creates a CreateResult that reports an error.
-func createErr(err error) CreateResult {
-	return CreateResult{
-		commonResult: commonResult{Result: gophercloud.Result{Err: err}},
-	}
-}
-
 // GetResult is the deferred response from a Get call.
 type GetResult struct {
 	commonResult
@@ -110,5 +95,9 @@ type Token struct {
 	// ID is the issued token.
 	ID string `json:"id"`
 	// ExpiresAt is the timestamp at which this token will no longer be accepted.
-	ExpiresAt gophercloud.JSONRFC3339Milli `json:"expires_at"`
+	ExpiresAt time.Time `json:"expires_at"`
+}
+
+func (r commonResult) ExtractInto(v interface{}) error {
+	return r.ExtractIntoStructPtr(v, "token")
 }

vendor/github.com/gophercloud/gophercloud/results.go

@@ -3,8 +3,10 @@ package gophercloud
 import (
 	"bytes"
 	"encoding/json"
+	"fmt"
 	"io"
 	"net/http"
+	"reflect"
 	"strconv"
 	"time"
 )
@@ -60,6 +62,78 @@ func (r Result) ExtractInto(to interface{}) error {
 	return err
 }
 
+func (r Result) extractIntoPtr(to interface{}, label string) error {
+	if label == "" {
+		return r.ExtractInto(&to)
+	}
+
+	var m map[string]interface{}
+	err := r.ExtractInto(&m)
+	if err != nil {
+		return err
+	}
+
+	b, err := json.Marshal(m[label])
+	if err != nil {
+		return err
+	}
+
+	err = json.Unmarshal(b, &to)
+	return err
+}
+
+// ExtractIntoStructPtr will unmarshal the Result (r) into the provided
+// interface{} (to).
+//
+// NOTE: For internal use only
+//
+// `to` must be a pointer to an underlying struct type
+//
+// If provided, `label` will be filtered out of the response
+// body prior to `r` being unmarshalled into `to`.
+func (r Result) ExtractIntoStructPtr(to interface{}, label string) error {
+	if r.Err != nil {
+		return r.Err
+	}
+
+	t := reflect.TypeOf(to)
+	if k := t.Kind(); k != reflect.Ptr {
+		return fmt.Errorf("Expected pointer, got %v", k)
+	}
+	switch t.Elem().Kind() {
+	case reflect.Struct:
+		return r.extractIntoPtr(to, label)
+	default:
+		return fmt.Errorf("Expected pointer to struct, got: %v", t)
+	}
+}
+
+// ExtractIntoSlicePtr will unmarshal the Result (r) into the provided
+// interface{} (to).
+//
+// NOTE: For internal use only
+//
+// `to` must be a pointer to an underlying slice type
+//
+// If provided, `label` will be filtered out of the response
+// body prior to `r` being unmarshalled into `to`.
+func (r Result) ExtractIntoSlicePtr(to interface{}, label string) error {
+	if r.Err != nil {
+		return r.Err
+	}
+
+	t := reflect.TypeOf(to)
+	if k := t.Kind(); k != reflect.Ptr {
+		return fmt.Errorf("Expected pointer, got %v", k)
+	}
+	switch t.Elem().Kind() {
+	case reflect.Slice:
+		return r.extractIntoPtr(to, label)
+	default:
+		return fmt.Errorf("Expected pointer to slice, got: %v", t)
+	}
+}
+
 // PrettyPrintJSON creates a string containing the full response body as
 // pretty-printed JSON. It's useful for capturing test fixtures and for
 // debugging extraction bugs. If you include its output in an issue related to

vendor/github.com/gophercloud/gophercloud/util.go

@@ -1,7 +1,7 @@
 package gophercloud
 
 import (
-	"errors"
+	"fmt"
 	"net/url"
 	"path/filepath"
 	"strings"
@@ -9,27 +9,47 @@ import (
 )
 
 // WaitFor polls a predicate function, once per second, up to a timeout limit.
-// It usually does this to wait for a resource to transition to a certain state.
+// This is useful to wait for a resource to transition to a certain state.
+// To handle situations when the predicate might hang indefinitely, the
+// predicate will be prematurely cancelled after the timeout.
 // Resource packages will wrap this in a more convenient function that's
 // specific to a certain resource, but it can also be useful on its own.
 func WaitFor(timeout int, predicate func() (bool, error)) error {
-	start := time.Now().Second()
+	type WaitForResult struct {
+		Success bool
+		Error   error
+	}
+
+	start := time.Now().Unix()
+
 	for {
-		// Force a 1s sleep
+		// If a timeout is set, and that's been exceeded, shut it down.
+		if timeout >= 0 && time.Now().Unix()-start >= int64(timeout) {
+			return fmt.Errorf("A timeout occurred")
+		}
+
 		time.Sleep(1 * time.Second)
 
-		// If a timeout is set, and that's been exceeded, shut it down
+		var result WaitForResult
-		if timeout >= 0 && time.Now().Second()-start >= timeout {
+		ch := make(chan bool, 1)
-			return errors.New("A timeout occurred")
+		go func() {
-		}
+			defer close(ch)
+			satisfied, err := predicate()
+			result.Success = satisfied
+			result.Error = err
+		}()
 
-		// Execute the function
+		select {
-		satisfied, err := predicate()
+		case <-ch:
-		if err != nil {
+			if result.Error != nil {
-			return err
+				return result.Error
-		}
+			}
-		if satisfied {
+			if result.Success {
-			return nil
+				return nil
+			}
+		// If the predicate has not finished by the timeout, cancel it.
+		case <-time.After(time.Duration(timeout) * time.Second):
+			return fmt.Errorf("A timeout occurred")
 		}
 	}
 }