breaking changes to storage package coming soon

[Jonathan Amsterdam]

As part of our effort to bring the Google Cloud Client Libraries for Go to beta, we'll be making some breaking changes to the Cloud Storage client (cloud.google.com/go/storage) in about a week. If any of these affect you, you should vendor this package until you're ready to change your code.

We expect these to be the last major changes to the client before it becomes stable.

Here's a list of what's changing:

BucketHandle.List is going away, replaced by an iterator that conforms to the standard pattern for these libraries. You'll find an example of the translation at the end of this message. The Cursor and MaxResults fields of Query will also be removed; use the PageInfo method on the iterator instead.

You can make these changes right now. The new methods are already available and the old ones are deprecated. The breaking change will be to remove the deprecated method and fields.

ObjectHandle.CopyTo will be removed. We've enhanced object copying to use the underlying API's rewrite method, which supports multi-RPC, resumable copies. Instead of

attrs, err := src.CopyTo(ctx, dst, nil)

you'll write

attrs, err := dst.CopierFrom(src).Run(ctx)

To set object attributes and other parameters, store the Copier in a variable first:

c := dst.CopierFrom(src)

c.ContentType = "text/html"

attrs, err := c.Run(ctx)

We reversed the direction of copying to conform to the other methods that change an object's contents, like NewWriter and ComposeFrom.

Speaking of which, ObjectHandle.ComposeFrom is undergoing the same transformation, to 

attrs, err := dst.ComposerFrom(src1, src2).Run(ctx)

You can make these changes right now. The new methods are already available and the old ones are deprecated. The breaking change will be to remove the deprecated methods.

AdminClient will be removed, its two methods CreateBucket and DeleteBucket replaced by BucketHandle.Create and BucketHandle.Delete.

You can also make this change now.

The ObjectAttrs argument of ObjectHandle.Update will be replaced by a different type that supports deletion of attributes. That change is not submitted yet, but you can see what it will look like by reading the CL. The change to existing code will be trivial.

Lastly, we're simplifying Conditions. The new design can be viewed at the CL. The changes you'll need to make are minor, but there is one important change in semantics: if you've been testing for the non-existence of an object using

obj.WithConditions(storage.IfGenerationMatch(0))

you'll instead write

obj.If(storage.Conditions{DoesNotExist: true})

Let us know if you have any questions or concerns about these changes. The best way to reach us is by filing an issue.

------

Translating BucketHandle.List to the new iterator: instead of writing

for query != nil {

objs, err := bucket.List(ctx, query)

if err != nil { ... }

query = objs.Next

for _, obj := range objs.Results {

fmt.Println(obj)

}

}

you'll need to write

iter := bucket.Objects(ctx, query)

for {

obj, err := iter.Next()

if err == iterator.Done {

break

}

if err != nil { ... }

fmt.Println(obj)

}

where "iterator" is the package google.golang.org/api/iterator.

[Jonathan Amsterdam]

These changes have happened. See the README for details on how to migrate.