pubsub: implemented iam methods

[callmehiphop]

Closes #758

• Add support for IAM methods within Topic and Subscription
• IAM#getPolicy
  • unit tested
  • system tested
  • documented
• IAM#setPolicy
  • unit tested
  • system tested
  • documented
• IAM#testPermissions
  • unit tested
  • system tested
  • documented

I'm getting a 503 for my testPermissions system test -- not sure if it's a problem upstream or implementation/user error.

documentation preview

[callmehiphop]

Couple of questions around testPermissions

1. I can't get that API call to go through, however per the discovery docs it's supposed to return a subset of the permissions you're testing for. Would it be better to return a hash so the user doesn't have to do a bunch of indexOf checks? (assuming that's how they'd use it)

   var tests = [
     'storage.bucket.list',
     'storage.bucket.insert'
   ];
   iam.testPermissions(tests, function(err, permissions) {
     console.log(permissions);
     // => {
     //   "storage.bucket.list": true,
     //   "storage.bucket.insert": false
     // }
   });

2. If we do want to go with the hash, then should we rename the method to hasPermissions?

3. If we don't want to go with the hash and the user provides a single permission, should we return a boolean instead of an array?

   iam.testPermissions('storage.bucket.list', function(err, hasPermission) {
     console.log(hasPermission);
     // => true
   });

[callmehiphop]

@tmatsuo - any insight you could provide would be greatly appreciated!

[tmatsuo]

1 sounds good.
2 sounds like the method is supposed to return boolean, but actually not. I would keep testPermissions.
3 seems confusing to me.

BTW, the example is using storage permissions. You can use permissions like pubsub.topics.publish and pubsub.subscriptions.consume. Also I would like to see the pubsub specific example, like testing permissions on topics/subscriptions.

[callmehiphop]

The pubsub specific way is the same, I decided to treat the iam object in the same fasion as an acl (property and not subclass). A more complete example would look like this

var topic = pubsub.topic('my-topic');
var tests = ['pubsub.topics.publish'];

topic.iam.testPermissions(tests, function(err, permissions, apiResponse) {});

[callmehiphop]

Updated post to include a link for a documentation preview.

[callmehiphop]

Now that Pub/Sub is out of beta (https://github.com/GoogleCloudPlatform/gcloud-common/issues/15) and IAM has official documentation. I've updated the system tests and documentation/code examples and everything looks good to go!

[callmehiphop]

Maybe we can add some convenience methods

It looks like there are 5 roles currently. Would you want methods for each one?