makePublic and makePrivate for buckets and files.

Breaking down #360 into this issue. We should add makePublic and makePrivate methods to buckets and files in the Storage API.

Can you remind me how the gcloud CLI does it?

gsutil doesn't really do it automatically. You have to specify certain flags, including -R for recursive to set all objects in the bucket to be publicly readable, and then once you have changed every object, you can then change the bucket itself to have a ~~predefined acl of publicRead~~ default object acl of allUsers = READER. This is an O(N) operation where N is the number of objects in your bucket, requires N + 1 API calls in the best case, must be capable of returning N + 1 possible errors in the worst case, and if we want to consider rolling back changes, the complexity will grow.

This issue / feature does not sit well with me. For one, it can have a bad effect if improperly documented and understood. Making an entire bucket's contents public is not something that is one-click away anywhere within the developer console. If the developer wants to do this, it should be possible to do with our API but not something that is suggested or promoted.

Now, making a single file public is, and that's a one-API-call thing away. We should support that.
Making a bucket's new content public by default is also one-API-call away. We should support that too.
Making a new, public bucket is one or two API calls, we can even support that.

But retroactively applying public to every file to a bucket introduces a lot of room for errors, it can be a slow operation which might confuse people and they might panic, kill it and then have half their bucket public and the other half private if they don't understand what it's doing behind-the-scenes. Just seems chaotic.

My proposal is to add the 2-3 methods suggested in paragraph 2, and then provide an example in the docs to make their entire bucket's contents public, assuming best case no-errors, no-pagination kinda situation.

/rant

+1

Does that leave us:

Make a single file public - file.acl.makePublic()
Make a bucket's new content public - bucket.acl.makePublic() + bucket.acl.default.makePublic()? What's the difference of these two, again?

We should have:

Make a single file public: file.acl.makePublic() (this api call)
Make a bucket's new content public: bucket.acl.default.makePublic() (this api call)
Make a bucket that is public by default createBucket('mybucket', { public : true }, cb) will just use predefinedDefaultObjectAcl: 'publicRead' on the createBucket metadata call. (I think this will work but if not, well we can scrap the idea as a result of the limitations of the API).