Merge pull request #64 from rackspace/update-docs
Update docs
diff --git a/acceptance/07-change-admin-password.go b/acceptance/07-change-admin-password.go
index e44bda0..6f078ee 100644
--- a/acceptance/07-change-admin-password.go
+++ b/acceptance/07-change-admin-password.go
@@ -13,7 +13,7 @@
func main() {
flag.Parse()
- withIdentity(func(acc gophercloud.AccessProvider) {
+ withIdentity(false, func(acc gophercloud.AccessProvider) {
withServerApi(acc, func(api gophercloud.CloudServersProvider) {
// If user doesn't explicitly provide a server ID, create one dynamically.
if *serverId == "" {
diff --git a/authenticate.go b/authenticate.go
index 07a5611..52bc1ab 100644
--- a/authenticate.go
+++ b/authenticate.go
@@ -51,9 +51,9 @@
Token Token
ServiceCatalog []CatalogEntry
User User
- provider Provider `json:"-"`
+ provider Provider `json:"-"`
options AuthOptions `json:"-"`
- context *Context `json:"-"`
+ context *Context `json:"-"`
}
// Token encapsulates an authentication token and when it expires. It also includes
diff --git a/flavors.go b/flavors.go
index 33c66d4..eb864d5 100644
--- a/flavors.go
+++ b/flavors.go
@@ -10,7 +10,7 @@
err := gsp.context.WithReauth(gsp.access, func() error {
url := gsp.endpoint + "/flavors/detail"
- return perigee.Get(url, perigee.Options{
+ return perigee.Get(url, perigee.Options{
CustomClient: gsp.context.httpClient,
Results: &struct{ Flavors *[]Flavor }{&fs},
MoreHeaders: map[string]string{
diff --git a/global_context.go b/global_context.go
index 9977aa8..5a3b162 100644
--- a/global_context.go
+++ b/global_context.go
@@ -59,4 +59,4 @@
return 0, ErrError
}
return err.Actual, nil
-}
\ No newline at end of file
+}
diff --git a/images.go b/images.go
index d0bd57e..38c73e1 100644
--- a/images.go
+++ b/images.go
@@ -74,4 +74,3 @@
Updated string `json:"updated"`
OsDcfDiskConfig string `json:"OS-DCF:diskConfig"`
}
-
diff --git a/interfaces.go b/interfaces.go
index 8e02fc3..c8a6f96 100644
--- a/interfaces.go
+++ b/interfaces.go
@@ -24,28 +24,108 @@
// CloudServersProvider instances encapsulate a Cloud Servers API, should one exist in the service catalog
// for your provider.
type CloudServersProvider interface {
- // Servers
+ // Servers
+ // ListServers provides a complete list of servers hosted by the user
+ // in a given region. This function differs from ListServersLinksOnly()
+ // in that it returns all available details for each server returned.
ListServers() ([]Server, error)
+
+ // ListServers provides a complete list of servers hosted by the user
+ // in a given region. This function differs from ListServers() in that
+ // it returns only IDs and links to each server returned.
+ //
+ // This function should be used only under certain circumstances.
+ // It's most useful for checking to see if a server with a given ID exists,
+ // or that you have permission to work with that server. It's also useful
+ // when the cost of retrieving the server link list plus the overhead of manually
+ // invoking ServerById() for each of the servers you're interested in is less than
+ // just calling ListServers() to begin with. This may be a consideration, for
+ // example, with mobile applications.
+ //
+ // In other cases, you probably should just call ListServers() and cache the
+ // results to conserve overall bandwidth and reduce your access rate on the API.
ListServersLinksOnly() ([]Server, error)
+
+ // ServerById will retrieve a detailed server description given the unique ID
+ // of a server. The ID can be returned by either ListServers() or by ListServersLinksOnly().
ServerById(id string) (*Server, error)
+
+ // CreateServer requests a new server to be created by the cloud server provider.
+ // The user must pass in a pointer to an initialized NewServerContainer structure.
+ // Please refer to the NewServerContainer documentation for more details.
+ //
+ // If the NewServer structure's AdminPass is empty (""), a password will be
+ // automatically generated by your OpenStack provider, and returned through the
+ // AdminPass field of the result. Take care, however; this will be the only time
+ // this happens. No other means exists in the public API to acquire a password
+ // for a pre-existing server. If you lose it, you'll need to call SetAdminPassword()
+ // to set a new one.
CreateServer(ns NewServer) (*NewServer, error)
+
+ // DeleteServerById requests that the server with the assigned ID be removed
+ // from your account. The delete happens asynchronously.
DeleteServerById(id string) error
+
+ // SetAdminPassword requests that the server with the specified ID have its
+ // administrative password changed. For Linux, BSD, or other POSIX-like
+ // system, this password corresponds to the root user. For Windows machines,
+ // the Administrator password will be affected instead.
SetAdminPassword(id string, pw string) error
+
+ // ResizeServer can be a short-hand for RebuildServer where only the size of the server
+ // changes. Note that after the resize operation is requested, you will need to confirm
+ // the resize has completed for changes to take effect permanently. Changes will assume
+ // to be confirmed even without an explicit confirmation after 24 hours from the initial
+ // request.
ResizeServer(id, newName, newFlavor, newDiskConfig string) error
+
+ // RevertResize will reject a server's resized configuration, thus
+ // rolling back to the original server.
RevertResize(id string) error
+
+ // ConfirmResizeServer will acknowledge a server's resized configuration.
ConfirmResize(id string) error
+
+ // RebootServer requests that the server with the specified ID be rebooted.
+ // Two reboot mechanisms exist.
+ //
+ // - Hard. This will physically power-cycle the unit.
+ // - Soft. This will attempt to use the server's software-based mechanisms to restart
+ // the machine. E.g., "shutdown -r now" on Linux.
RebootServer(id string, hard bool) error
+
+ // RescueServer requests that the server with the specified ID be placed into
+ // a state of maintenance. The server instance is replaced with a new instance,
+ // of the same flavor and image. This new image will have the boot volume of the
+ // original machine mounted as a secondary device, so that repair and administration
+ // may occur. Use UnrescueServer() to restore the server to its previous state.
+ // Note also that many providers will impose a time limit for how long a server may
+ // exist in rescue mode! Consult the API documentation for your provider for
+ // details.
RescueServer(id string) (string, error)
+
+ // UnrescueServer requests that a server in rescue state be placed into its nominal
+ // operating state.
UnrescueServer(id string) error
+
+ // UpdateServer alters one or more fields of the identified server's Server record.
+ // However, not all fields may be altered. Presently, only Name, AccessIPv4, and
+ // AccessIPv6 fields may be altered. If unspecified, or set to an empty or zero
+ // value, the corresponding field remains unaltered.
+ //
+ // This function returns the new set of server details if successful.
UpdateServer(id string, newValues NewServerSettings) (*Server, error)
- // Images
+ // Images
- ListImages() ([]Image, error)
+ // ListImages yields the list of available operating system images. This function
+ // returns full details for each image, if available.
+ ListImages() ([]Image, error)
- // Flavors
+ // Flavors
- ListFlavors() ([]Flavor, error)
+ // ListFlavors yields the list of available system flavors. This function
+ // returns full details for each flavor, if available.
+ ListFlavors() ([]Flavor, error)
}
-
diff --git a/reauth.go b/reauth.go
index 5637ea2..eb9ac1e 100644
--- a/reauth.go
+++ b/reauth.go
@@ -20,4 +20,4 @@
}
}
return err
-}
\ No newline at end of file
+}
diff --git a/reauth_test.go b/reauth_test.go
index e6ccb17..e3501b8 100644
--- a/reauth_test.go
+++ b/reauth_test.go
@@ -1,8 +1,8 @@
package gophercloud
import (
- "testing"
"github.com/racker/perigee"
+ "testing"
)
// This reauth-handler does nothing, and returns no error.
@@ -18,7 +18,7 @@
calls++
return &perigee.UnexpectedResponseCodeError{
Expected: []int{204},
- Actual: 404,
+ Actual: 404,
}
})
@@ -44,7 +44,7 @@
calls++
return &perigee.UnexpectedResponseCodeError{
Expected: []int{204},
- Actual: 401,
+ Actual: 401,
}
})
@@ -67,7 +67,7 @@
c.WithReauth(nil, func() error {
return &perigee.UnexpectedResponseCodeError{
Expected: []int{204},
- Actual: 401,
+ Actual: 401,
}
})
@@ -77,7 +77,8 @@
}
}
-type MyError struct {}
+type MyError struct{}
+
func (*MyError) Error() string {
return "MyError instance"
}
@@ -90,7 +91,7 @@
err := c.WithReauth(nil, func() error {
return &perigee.UnexpectedResponseCodeError{
Expected: []int{204},
- Actual: 401,
+ Actual: 401,
}
})
@@ -100,7 +101,8 @@
}
}
-type MyAccess struct {}
+type MyAccess struct{}
+
func (my *MyAccess) FirstEndpointUrlByCriteria(ApiCriteria) string {
return ""
}
@@ -125,7 +127,7 @@
c.WithReauth(fakeAccess, func() error {
return &perigee.UnexpectedResponseCodeError{
Expected: []int{204},
- Actual: 401,
+ Actual: 401,
}
})
}
diff --git a/servers.go b/servers.go
index 16d82c5..e127e05 100644
--- a/servers.go
+++ b/servers.go
@@ -4,8 +4,8 @@
package gophercloud
import (
- "github.com/racker/perigee"
"fmt"
+ "github.com/racker/perigee"
)
// genericServersProvider structures provide the implementation for generic OpenStack-compatible
@@ -134,21 +134,21 @@
// See the CloudServersProvider interface for details.
func (gsp *genericServersProvider) ResizeServer(id, newName, newFlavor, newDiskConfig string) error {
err := gsp.context.WithReauth(gsp.access, func() error {
- url := fmt.Sprintf("%s/servers/%s/action", gsp.endpoint, id)
- rr := ResizeRequest{
- Name: newName,
- FlavorRef: newFlavor,
- DiskConfig: newDiskConfig,
- }
- return perigee.Post(url, perigee.Options{
- ReqBody: &struct {
- Resize ResizeRequest `json:"resize"`
- }{rr},
- OkCodes: []int{202},
- MoreHeaders: map[string]string{
- "X-Auth-Token": gsp.access.AuthToken(),
- },
- })
+ url := fmt.Sprintf("%s/servers/%s/action", gsp.endpoint, id)
+ rr := ResizeRequest{
+ Name: newName,
+ FlavorRef: newFlavor,
+ DiskConfig: newDiskConfig,
+ }
+ return perigee.Post(url, perigee.Options{
+ ReqBody: &struct {
+ Resize ResizeRequest `json:"resize"`
+ }{rr},
+ OkCodes: []int{202},
+ MoreHeaders: map[string]string{
+ "X-Auth-Token": gsp.access.AuthToken(),
+ },
+ })
})
return err
}
@@ -193,7 +193,7 @@
url := fmt.Sprintf("%s/servers/%s/action", gsp.endpoint, id)
types := map[bool]string{false: "SOFT", true: "HARD"}
return perigee.Post(url, perigee.Options{
- ReqBody: &struct{
+ ReqBody: &struct {
Reboot struct {
Type string `json:"type"`
} `json:"reboot"`
@@ -217,13 +217,13 @@
err := gsp.context.WithReauth(gsp.access, func() error {
url := fmt.Sprintf("%s/servers/%s/action", gsp.endpoint, id)
return perigee.Post(url, perigee.Options{
- ReqBody: &struct{
+ ReqBody: &struct {
Rescue string `json:"rescue"`
}{"none"},
MoreHeaders: map[string]string{
"X-Auth-Token": gsp.access.AuthToken(),
},
- Results: &struct{
+ Results: &struct {
AdminPass **string `json:"adminPass"`
}{&pw},
})
@@ -236,7 +236,7 @@
return gsp.context.WithReauth(gsp.access, func() error {
url := fmt.Sprintf("%s/servers/%s/action", gsp.endpoint, id)
return perigee.Post(url, perigee.Options{
- ReqBody: &struct{
+ ReqBody: &struct {
Unrescue *int `json:"unrescue"`
}{nil},
MoreHeaders: map[string]string{
@@ -253,13 +253,13 @@
err := gsp.context.WithReauth(gsp.access, func() error {
url := fmt.Sprintf("%s/servers/%s", gsp.endpoint, id)
return perigee.Put(url, perigee.Options{
- ReqBody: &struct{
+ ReqBody: &struct {
Server NewServerSettings `json:"server"`
}{changes},
MoreHeaders: map[string]string{
"X-Auth-Token": gsp.access.AuthToken(),
},
- Results: &struct{
+ Results: &struct {
Server **Server `json:"server"`
}{&svr},
})
@@ -395,7 +395,7 @@
// NewServerSettings structures record those fields of the Server structure to change
// when updating a server (see UpdateServer method).
type NewServerSettings struct {
- Name string `json:"name,omitempty"`
+ Name string `json:"name,omitempty"`
AccessIPv4 string `json:"accessIPv4,omitempty"`
AccessIPv6 string `json:"accessIPv6,omitempty"`
}
@@ -462,7 +462,7 @@
// Client applications will not use this structure (no API accepts an instance of this structure).
// See the Region method ResizeServer() for more details on how to resize a server.
type ResizeRequest struct {
- Name string `json:"name,omitempty"`
- FlavorRef string `json:"flavorRef"`
- DiskConfig string `json:"OS-DCF:diskConfig,omitempty"`
+ Name string `json:"name,omitempty"`
+ FlavorRef string `json:"flavorRef"`
+ DiskConfig string `json:"OS-DCF:diskConfig,omitempty"`
}
diff --git a/transport_double.go b/transport_double.go
index e764c9a..ef7f19a 100644
--- a/transport_double.go
+++ b/transport_double.go
@@ -2,10 +2,10 @@
import (
"encoding/json"
+ "fmt"
"io/ioutil"
"net/http"
"strings"
- "fmt"
"testing"
)
@@ -14,7 +14,7 @@
response string
expectTenantId bool
tenantIdFound bool
- status int
+ status int
}
func (t *transport) RoundTrip(req *http.Request) (rsp *http.Response, err error) {
@@ -100,4 +100,4 @@
return err
}
return nil
-}
\ No newline at end of file
+}