Skip to content

Commit 132feaf

Browse files
stephenplusplusstephenplusplus
committed
use options object + role constants
1 parent ea528a8 commit 132feaf

File tree

5 files changed

+200
-149
lines changed

5 files changed

+200
-149
lines changed

‎docs/components/docs/docs.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -154,7 +154,7 @@ angular
154154
})
155155
.map(function(tag) {
156156
tag.description = $sce.trustAsHtml(
157-
formatHtml(detectLinks(tag.description.replace(/^- /, ''))));
157+
formatHtml(detectLinks(detectModules(tag.description.replace(/^- /, '')))));
158158
tag.types = $sce.trustAsHtml(tag.types.reduceRight(
159159
reduceModules, []).join(', '));
160160
tag.optional = tag.types.toString().indexOf('=') > -1;

‎lib/storage/acl.js

+89-95
Original file line numberDiff line numberDiff line change
@@ -50,43 +50,44 @@ function Acl(options) {
5050
/**
5151
* Add access controls on a {module:storage/bucket} or {module:storage/file}.
5252
*
53-
* @param {string} scope - Whose permissions will be updated.
54-
* @param {string} role - Permissions allowed for the defined scope.
55-
* @param {object=} options - Configuration object.
56-
* @param {int} options.generation - **File Objects Only** If present, selects a
57-
* specific revision of this object (as opposed to the latest version, the
58-
* default).
53+
* @param {object} options - Configuration object.
54+
* @param {string} options.scope - Whose permissions will be added.
55+
* @param {string} options.role - Permissions allowed for the defined scope. See
56+
* {module:storage#acl}.
57+
* @param {int=} options.generation - **File Objects Only** Select a specific
58+
* revision of this file (as opposed to the latest version, the default).
5959
* @param {function} callback - The callback function.
6060
*
6161
* @example
62-
* var scope = '[email protected]';
63-
* var role = 'owner';
64-
*
65-
* myBucket.acl.add(scope, role, function(err, aclObject) {});
62+
* myBucket.acl.add({
63+
* scope: 'user-useremail@example.com',
64+
* role: storage.acl.OWNER_ROLE
65+
* }, function(err, aclObject) {});
6666
*
6767
* //-
68-
* // For file ACL operations, an options object is also accepted.
68+
* // For file ACL operations, you can also specify a `generation` property.
6969
* //-
70-
* var options = {
70+
* myFile.acl.add({
71+
* scope: 'user-useremail@example.com',
72+
* role: storage.acl.OWNER_ROLE,
7173
* generation: 1
72-
* };
73-
*
74-
* myFile.acl.add(scope, role, options, function(err, aclObject) {});
74+
* }, function(err, aclObject) {});
7575
*/
76-
Acl.prototype.add = function(scope, role, options, callback) {
76+
Acl.prototype.add = function(options, callback) {
7777
var that = this;
7878

7979
var body = {
80-
entity: scope,
81-
role: role.toUpperCase()
80+
entity: options.scope,
81+
role: options.role.toUpperCase()
8282
};
8383

84-
if (util.is(options, 'function')) {
85-
callback = options;
86-
options = null;
87-
}
84+
var query = null;
8885

89-
var query = options || null;
86+
if (options.generation) {
87+
query = {
88+
generation: options.generation
89+
};
90+
}
9091

9192
this.makeReq_('POST', '', query, body, function(err, resp) {
9293
if (err) {
@@ -101,56 +102,54 @@ Acl.prototype.add = function(scope, role, options, callback) {
101102
/**
102103
* Delete access controls on a {module:storage/bucket} or {module:storage/file}.
103104
*
104-
* @param {string} scope - Whose permissions will be revoked.
105105
* @param {object=} options - Configuration object.
106-
* @param {int} options.generation - **File Objects Only** If present, selects a
107-
* specific revision of this object (as opposed to the latest version, the
108-
* default).
106+
* @param {string} options.scope - Whose permissions will be revoked.
107+
* @param {int=} options.generation - **File Objects Only** Select a specific
108+
* revision of this file (as opposed to the latest version, the default).
109109
* @param {function} callback - The callback function.
110110
*
111111
* @example
112-
* var scope = '[email protected]';
113-
*
114-
* myBucket.acl.delete(scope, function(err) {});
112+
* myBucket.acl.delete({
113+
* scope: 'user-useremail@example.com'
114+
* }, function(err) {});
115115
*
116116
* //-
117117
* // For file ACL operations, an options object is also accepted.
118118
* //-
119-
* var options = {
119+
* myFile.acl.delete({
120+
* scope: 'user-useremail@example.com',
120121
* generation: 1
121-
* };
122-
*
123-
* myFile.acl.delete(scope, options, function(err) {});
122+
* }, function(err) {});
124123
*/
125-
Acl.prototype.delete = function(scope, options, callback) {
126-
var path = '/' + encodeURIComponent(scope);
127-
128-
if (util.is(options, 'function')) {
129-
callback = options;
130-
options = null;
124+
Acl.prototype.delete = function(options, callback) {
125+
var path = '/' + encodeURIComponent(options.scope);
126+
var query = null;
127+
128+
if (options.generation) {
129+
query = {
130+
generation: options.generation
131+
};
131132
}
132133

133-
var query = options || null;
134-
135134
this.makeReq_('DELETE', path, query, null, callback);
136135
};
137136

138137
/**
139138
* Get access controls on a {module:storage/bucket} or {module:storage/file}. If
140-
* an scope is omitted, you will receive an array of all applicable access
139+
* a scope is omitted, you will receive an array of all applicable access
141140
* controls.
142141
*
143-
* @param {string=} scope - Whose permissions will be fetched.
144-
* @param {object=} options - Configuration object.
145-
* @param {int} options.generation - **File Objects Only** If present, selects a
146-
* specific revision of this object (as opposed to the latest version, the
147-
* default).
148-
* @param {function} callback - The callback function.
142+
* @param {object|function} options - Configuration object. If you want to
143+
* receive a list of all access controls, pass the callback function as the
144+
* only argument.
145+
* @param {string=} options.scope - Whose permissions will be fetched.
146+
* @param {int=} options.generation - **File Objects Only** Select a specific
147+
* revision of this file (as opposed to the latest version, the default).
149148
*
150149
* @example
151-
* var scope = '[email protected]';
152-
*
153-
* myBucket.acl.get(scope, function(err, aclObject) {});
150+
* myBucket.acl.get({
151+
* scope: 'user-useremail@example.com'
152+
* }, function(err, aclObject) {});
154153
*
155154
* //-
156155
* // Get all access controls.
@@ -167,35 +166,28 @@ Acl.prototype.delete = function(scope, options, callback) {
167166
* //-
168167
* // For file ACL operations, an options object is also accepted.
169168
* //-
170-
* var options = {
169+
* myFile.acl.get({
170+
* scope: 'user-useremail@example.com',
171171
* generation: 1
172-
* };
173-
*
174-
* myFile.acl.get(options, function(err, aclObjects) {});
175-
* myFile.acl.get(scope, options, function(err, aclObject) {});
172+
* } function(err, aclObject) {});
176173
*/
177-
Acl.prototype.get = function(scope, options, callback) {
174+
Acl.prototype.get = function(options, callback) {
178175
var that = this;
179176
var path = '';
180-
181-
switch (typeof scope) {
182-
case 'function':
183-
callback = scope;
184-
break;
185-
case 'string':
186-
path = '/' + encodeURIComponent(scope);
187-
break;
188-
case 'object':
189-
options = scope;
190-
break;
191-
}
177+
var query = null;
192178

193179
if (util.is(options, 'function')) {
194180
callback = options;
195181
options = null;
196-
}
182+
} else {
183+
path = '/' + encodeURIComponent(options.scope);
197184

198-
var query = options || null;
185+
if (options.generation) {
186+
query = {
187+
generation: options.generation
188+
};
189+
}
190+
}
199191

200192
this.makeReq_('GET', path, query, null, function(err, resp) {
201193
if (err) {
@@ -218,43 +210,45 @@ Acl.prototype.get = function(scope, options, callback) {
218210
/**
219211
* Update access controls on a {module:storage/bucket} or {module:storage/file}.
220212
*
221-
* @param {string} scope - Whose permissions will be updated.
222-
* @param {string} role - Permissions allowed for the defined scope.
223213
* @param {object=} options - Configuration object.
224-
* @param {int} options.generation - **File Objects Only** If present, selects a
225-
* specific revision of this object (as opposed to the latest version, the
226-
* default).
214+
* @param {string} options.scope - Whose permissions will be added.
215+
* @param {string} options.role - Permissions allowed for the defined scope. See
216+
* {module:storage#acl}.
217+
* @param {int=} options.generation - **File Objects Only** Select a specific
218+
* revision of this file (as opposed to the latest version, the default).
227219
* @param {function} callback - The callback function.
228220
*
229221
* @example
230-
* var scope = '[email protected]';
231-
* var role = 'writer';
222+
* var storage = gcloud.storage();
232223
*
233-
* myBucket.acl.update(scope, role, function(err) {});
224+
* myBucket.acl.update({
225+
* scope: 'user-useremail@example.com',
226+
* role: storage.acl.WRITER_ROLE
227+
* }, function(err) {});
234228
*
235229
* //-
236230
* // For file ACL operations, an options object is also accepted.
237231
* //-
238-
* var options = {
232+
* myFile.acl.update({
233+
* scope: 'user-useremail@example.com',
234+
* role: storage.acl.WRITER_ROLE,
239235
* generation: 1
240-
* };
241-
*
242-
* myFile.acl.update(scope, role, options, function(err) {});
236+
* }, function(err) {});
243237
*/
244-
Acl.prototype.update = function(scope, role, options, callback) {
238+
Acl.prototype.update = function(options, callback) {
245239
var that = this;
246-
var path = '/' + encodeURIComponent(scope);
240+
var path = '/' + encodeURIComponent(options.scope);
241+
var query = null;
247242

248-
var body = {
249-
role: role.toUpperCase()
250-
};
251-
252-
if (util.is(options, 'function')) {
253-
callback = options;
254-
options = null;
243+
if (options.generation) {
244+
query = {
245+
generation: options.generation
246+
};
255247
}
256248

257-
var query = options || null;
249+
var body = {
250+
role: options.role.toUpperCase()
251+
};
258252

259253
this.makeReq_('PUT', path, query, body, function(err, resp) {
260254
if (err) {
@@ -274,7 +268,7 @@ Acl.prototype.update = function(scope, role, options, callback) {
274268
Acl.prototype.makeAclObject_ = function(accessControlObject) {
275269
var obj = {
276270
scope: accessControlObject.scope,
277-
role: accessControlObject.role.toLowerCase()
271+
role: accessControlObject.role
278272
};
279273

280274
if (accessControlObject.projectTeam) {

‎lib/storage/index.js

+34
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,40 @@ function Storage(config) {
110110
this.projectId = config.projectId;
111111
}
112112

113+
/**
114+
* Google Cloud Storage uses access control lists (ACLs) to manage object and
115+
* bucket access. ACLs are the mechanism you use to share objects with other
116+
* users and allow other users to access your buckets and objects.
117+
*
118+
* This object provides constants to refer to the three permission levels that
119+
* can be granted to a scope:
120+
*
121+
* - `Storage.acl.OWNER_ROLE` - ("OWNER")
122+
* - `Storage.acl.READER_ROLE` - ("READER")
123+
* - `Storage.acl.WRITER_ROLE` - ("WRITER")
124+
*
125+
* For more detailed information, see
126+
* [About Access Control Lists](http://goo.gl/6qBBPO).
127+
*
128+
* @type {object}
129+
*
130+
* @example
131+
* var storage = gcloud.storage();
132+
* var albums = storage.bucket('albums');
133+
*
134+
* albums.acl.add({
135+
* scope: 'user-useremail@example.com',
136+
* permission: Storage.acl.OWNER_ROLE
137+
* }, function(err, aclObject) {});
138+
*/
139+
Storage.acl = {
140+
OWNER_ROLE: 'OWNER',
141+
READER_ROLE: 'READER',
142+
WRITER_ROLE: 'WRITER'
143+
};
144+
145+
Storage.prototype.acl = Storage.acl;
146+
113147
/**
114148
* Get a reference to a Google Cloud Storage bucket.
115149
*

0 commit comments

Comments
 (0)