diff options
| -rw-r--r-- | backend.go | 2 | ||||
| -rw-r--r-- | doc.go | 66 | ||||
| -rw-r--r-- | gopherschwift/package.go | 13 |
3 files changed, 65 insertions, 16 deletions
@@ -24,8 +24,6 @@ import ( //Backend is the interface between Schwift and the libraries providing //authentication for it. -// -//TODO list implementations type Backend interface { //EndpointURL returns the endpoint URL from the Keystone catalog for the //Swift account that this backend operates on. It should look like @@ -21,27 +21,49 @@ Package schwift is a client library for OpenStack Swift (https://github.com/openstack/swift, https://openstack.org). -TODO update doc for changed auth workflow +Authentication with Gophercloud -It uses Gophercloud (https://github.com/gophercloud/gophercloud) for -authentication, so you usually start by obtaining a gophercloud.ServiceClient -for Swift like so: +Schwift does not implement authentication (neither Keystone nor Swift v1), but +can be plugged into any library that does. The most common choice is +Gophercloud (https://github.com/gophercloud/gophercloud). - authOptions, err := openstack.AuthOptionsFromEnv() // or build a gophercloud.AuthOptions instance yourself +When using Gophercloud, you usually start by obtaining a +gophercloud.ServiceClient for Swift like so: + + import ( + "github.com/gophercloud/gophercloud/openstack" + "github.com/gophercloud/utils/openstack/clientconfig" + ) + + //option 1: build a gophercloud.AuthOptions instance yourself provider, err := openstack.AuthenticatedClient(authOptions) client, err := openstack.NewObjectStorageV1(provider, gophercloud.EndpointOpts{}) -Or, if you use Swift's built-in authentication instead of Keystone: + //option 2: have Gophercloud read the standard OS_* environment variables + provider, err := clientConfig.AuthenticatedClient(nil) + client, err := openstack.NewObjectStorageV1(provider, gophercloud.EndpointOpts{}) + //option 3: if you're using Swift's builtin authentication instead of Keystone provider, err := openstack.NewClient("http://swift.example.com:8080") client, err := swauth.NewObjectStorageV1(provider, swauth.AuthOpts { User: "project:user", Key: "password", }) -Then, in both cases, you use Wrap() from the subpackage gopherschwift to obtain -a schwift.Account instance, from which point you have access to all of -schwift's API. +Then, in all these cases, you use gopherschwift to convert the +gophercloud.ServiceClient into a schwift.Account instance, from which point you +have access to all of schwift's API: + + import "github.com/majewsky/schwift/gopherschwift" + + account, err := gopherschwift.Wrap(client) + +Authentication with a different OpenStack library + +If you use a different Go library to handle Keystone/Swift authentication, take +the client object that it provides and wrap it into something that implements +the schwift.Backend interface. Then use schwift.InitializeAccount() to obtain a +schwift.Account. Caching @@ -56,7 +78,31 @@ retrieved again. hdr, err = obj.Headers() //returns cached values immediately If this behavior is not desired, the Invalidate() method can be used to clear -caches on any Account, Container or Object instance. +caches on any Account, Container or Object instance. Some methods that modify +the instance on the server call Invalidate() automatically, e.g. Object.Upload(), +Update() or Delete(). This will be indicated in the method's documentation. + +Error handling + +When a method on an Account, Container or Object instance makes a HTTP request +to Swift and Swift returns an unexpected status code, a +schwift.UnexpectedStatusCodeError will be returned. Schwift provides the +convenience function Is() to check the status code of these errors to detect +common failure situations: + + obj := account.Container("foo").Object("bar") + err := obj.Upload(bytes.NewReader(data), nil) + + if schwift.Is(err, http.StatusRequestEntityTooLarge) { + log.Print("quota exceeded for container foo!") + } else if err != nil { + log.Fatal("unexpected error: " + err.Error()) + } + +The documentation for a method may indicate certain common error conditions +that can be detected this way by stating that "This method fails with +http.StatusXXX if ...". Because of the wide variety of failure modes in Swift, +this information is not guaranteed to be exhaustive. */ package schwift diff --git a/gopherschwift/package.go b/gopherschwift/package.go index 7c66b16..bd47b8d 100644 --- a/gopherschwift/package.go +++ b/gopherschwift/package.go @@ -25,13 +25,18 @@ you can use the Wrap() function in this package as an entrypoint to Schwift. A schwift.Account created this way will re-use Gophercloud's authentication code, so you only need to obtain a client token once using Gophercloud. For example: - authOptions, err := openstack.AuthOptionsFromEnv() // or build a gophercloud.AuthOptions instance yourself - provider, err := openstack.AuthenticatedClient(authOptions) - client, err := openstack.NewObjectStorageV1(provider, gophercloud.EndpointOpts{}) + import ( + "github.com/gophercloud/gophercloud/openstack" + "github.com/gophercloud/utils/openstack/clientconfig" + "github.com/majewsky/schwift/gopherschwift" + ) - account, err := gopherschwift.Wrap(client) + provider, err := clientconfig.AuthenticatedClient(nil) + client, err := openstack.NewObjectStorageV1(provider, gophercloud.EndpointOpts{}) + account, err := gopherschwift.Wrap(client) Using this schwift.Account instance, you have access to all of schwift's API. +Refer to the documentation in the parent package for details. */ package gopherschwift |