pubsub: docs: correct links & add options.pushEndpoint

packages/pubsub/src/iam.js

@@ -89,11 +89,11 @@ util.inherits(IAM, common.GrpcService);
  *
  * @param {function} callback - The callback function.
  * @param {?error} callback.err - An error returned while making this request.
- * @param {object} callback.policy - The [policy](https://cloud.google.com/pubsub/reference/rest/Shared.Types/Policy).
+ * @param {object} callback.policy - The [policy](https://cloud.google.com/pubsub/docs/reference/rest/Shared.Types/Policy).
  * @param {object} callback.apiResponse - The full API response.
  *
- * @resource [Topics: getIamPolicy API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.topics/getIamPolicy}
- * @resource [Subscriptions: getIamPolicy API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/getIamPolicy}
+ * @resource [Topics: getIamPolicy API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/getIamPolicy}
+ * @resource [Subscriptions: getIamPolicy API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/getIamPolicy}
  *
  * @example
  * topic.iam.getPolicy(function(err, policy, apiResponse) {});
@@ -126,7 +126,7 @@ IAM.prototype.getPolicy = function(callback) {
  *
  * @throws {Error} If no policy is provided.
  *
- * @param {object} policy - The [policy](https://cloud.google.com/pubsub/reference/rest/Shared.Types/Policy).
+ * @param {object} policy - The [policy](https://cloud.google.com/pubsub/docs/reference/rest/Shared.Types/Policy).
  * @param {array=} policy.bindings - Bindings associate members with roles.
  * @param {object[]=} policy.rules - Rules to be applied to the policy.
  * @param {string=} policy.etag - Etags are used to perform a read-modify-write.
@@ -135,9 +135,9 @@ IAM.prototype.getPolicy = function(callback) {
  * @param {object} callback.policy - The updated policy.
  * @param {object} callback.apiResponse - The full API response.
  *
- * @resource [Topics: setIamPolicy API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.topics/setIamPolicy}
- * @resource [Subscriptions: setIamPolicy API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/setIamPolicy}
- * @resource [Policy]{@link https://cloud.google.com/pubsub/reference/rest/Shared.Types/Policy}
+ * @resource [Topics: setIamPolicy API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/setIamPolicy}
+ * @resource [Subscriptions: setIamPolicy API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/setIamPolicy}
+ * @resource [Policy]{@link https://cloud.google.com/pubsub/docs/reference/rest/Shared.Types/Policy}
  *
  * @example
  * var myPolicy = {
@@ -193,8 +193,8 @@ IAM.prototype.setPolicy = function(policy, callback) {
  *     is allowed
  * @param {object} callback.apiResponse - The full API response.
  *
- * @resource [Topics: testIamPermissions API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.topics/testIamPermissions}
- * @resource [Subscriptions: testIamPermissions API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/testIamPermissions}
+ * @resource [Topics: testIamPermissions API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/testIamPermissions}
+ * @resource [Subscriptions: testIamPermissions API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/testIamPermissions}
  * @resource [Permissions Reference]{@link https://cloud.google.com/pubsub/access_control#permissions}
  *
  * @example

packages/pubsub/src/index.js

@@ -84,7 +84,7 @@ util.inherits(PubSub, common.GrpcService);
 /**
  * Create a topic with the given name.
  *
- * @resource [Topics: create API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.topics/create}
+ * @resource [Topics: create API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/create}
  *
  * @param {string} name - Name of the topic.
  * @param {function=} callback - The callback function.
@@ -145,7 +145,7 @@ PubSub.prototype.createTopic = function(name, callback) {
  *
  * To get subscriptions for a topic, see {module:pubsub/topic}.
  *
- * @resource [Subscriptions: list API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/list}
+ * @resource [Subscriptions: list API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/list}
  *
  * @param {object=} options - Configuration object.
  * @param {boolean} options.autoPaginate - Have pagination handled
@@ -287,7 +287,7 @@ PubSub.prototype.getSubscriptionsStream =
  * Get a list of the topics registered to your project. You may optionally
  * provide a query object as the first argument to customize the response.
  *
- * @resource [Topics: list API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.topics/list}
+ * @resource [Topics: list API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/list}
  *
  * @param {object=} query - Query object.
  * @param {boolean} options.autoPaginate - Have pagination handled
@@ -407,13 +407,9 @@ PubSub.prototype.getTopics = function(query, callback) {
 PubSub.prototype.getTopicsStream = common.paginator.streamify('getTopics');
 
 /**
- * Create a subscription to a topic. You may optionally provide an object to
- * customize the subscription.
+ * Create a subscription to a topic.
  *
- * Your provided callback will be invoked with an error object if an API error
- * occurred or a {module:pubsub/subscription} object.
- *
- * @resource [Subscriptions: create API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/create}
+ * @resource [Subscriptions: create API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/create}
  *
  * @throws {Error} If a Topic instance or topic name is not provided.
  * @throws {Error} If a subName is not provided.
@@ -422,7 +418,7 @@ PubSub.prototype.getTopicsStream = common.paginator.streamify('getTopics');
  *     subscription to.
  * @param {string} subName - The name of the subscription.
  * @param {object=} options - See a
- *     [Subscription resource](https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions)
+ *     [Subscription resource](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions)
  * @param {number} options.ackDeadlineSeconds - The maximum time after receiving
  *     a message that you must ack a message before it is redelivered.
  * @param {boolean} options.autoAck - Automatically acknowledge the message once
@@ -433,6 +429,8 @@ PubSub.prototype.getTopicsStream = common.paginator.streamify('getTopics');
  *     messages. (default: 10)
  * @param {number} options.maxInProgress - Maximum messages to consume
  *     simultaneously.
+ * @param {string} options.pushEndpoint - A URL to a custom endpoint that
+ *     messages should be pushed to.
  * @param {boolean} options.reuseExisting - If the subscription already exists,
  *     reuse it. The options of the existing subscription are not changed. If
  *     false, attempting to create a subscription that already exists will fail.
@@ -504,10 +502,17 @@ PubSub.prototype.subscribe = function(topic, subName, options, callback) {
     name: subscription.name
   });
 
+  if (reqOpts.pushEndpoint) {
+    reqOpts.pushConfig = {
+      pushEndpoint: reqOpts.pushEndpoint
+    };
+  }
+
   delete reqOpts.autoAck;
   delete reqOpts.encoding;
   delete reqOpts.interval;
   delete reqOpts.maxInProgress;
+  delete reqOpts.pushEndpoint;
   delete reqOpts.reuseExisting;
   delete reqOpts.timeout;
 

packages/pubsub/src/subscription.js

@@ -197,7 +197,7 @@ function Subscription(pubsub, options) {
     /**
      * Get the metadata for the subscription.
      *
-     * @resource [Subscriptions: get API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/get}
+     * @resource [Subscriptions: get API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/get}
      *
      * @param {function} callback - The callback function.
      * @param {?error} callback.err - An error returned while making this
@@ -378,7 +378,7 @@ Subscription.formatName_ = function(projectId, name) {
  * Acknowledge to the backend that the message was retrieved. You must provide
  * either a single ackId or an array of ackIds.
  *
- * @resource [Subscriptions: acknowledge API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/acknowledge}
+ * @resource [Subscriptions: acknowledge API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/acknowledge}
  *
  * @throws {Error} If at least one ackId is not provided.
  *
@@ -467,7 +467,7 @@ Subscription.prototype.decorateMessage_ = function(message) {
  * Delete the subscription. Pull requests from the current subscription will be
  * errored once unsubscription is complete.
  *
- * @resource [Subscriptions: delete API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/delete}
+ * @resource [Subscriptions: delete API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/delete}
  *
  * @param {function=} callback - The callback function.
  * @param {?error} callback.err - An error returned while making this
@@ -522,7 +522,7 @@ Subscription.prototype.delete = function(callback) {
  *
  * @todo Should not be racing with other pull.
  *
- * @resource [Subscriptions: pull API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/pull}
+ * @resource [Subscriptions: pull API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/pull}
  *
  * @param {object=} options - Configuration object.
  * @param {number} options.maxResults - Limit the amount of messages pulled.
@@ -634,7 +634,7 @@ Subscription.prototype.pull = function(options, callback) {
  * to make the message available for redelivery if the processing was
  * interrupted.
  *
- * @resource [Subscriptions: modifyAckDeadline API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/modifyAckDeadline}
+ * @resource [Subscriptions: modifyAckDeadline API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/modifyAckDeadline}
  *
  * @param {object} options - The configuration object.
  * @param {string|string[]} options.ackIds - The ack id(s) to change.

packages/pubsub/src/topic.js

@@ -76,7 +76,7 @@ function Topic(pubsub, name) {
     /**
      * Delete the topic. This will not delete subscriptions to this topic.
      *
-     * @resource [Topics: delete API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.topics/delete}
+     * @resource [Topics: delete API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/delete}
      *
      * @param {function=} callback - The callback function.
      *
@@ -150,7 +150,7 @@ function Topic(pubsub, name) {
     /**
      * Get the official representation of this topic from the API.
      *
-     * @resource [Topics: get API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.topics/get}
+     * @resource [Topics: get API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/get}
      *
      * @param {function} callback - The callback function.
      * @param {?error} callback.err - An error returned while making this
@@ -266,7 +266,7 @@ Topic.formatName_ = function(projectId, name) {
  * Your provided callback will be invoked with an error object if an API error
  * occurred or an array of {module:pubsub/subscription} objects.
  *
- * @resource [Subscriptions: list API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.topics.subscriptions/list}
+ * @resource [Subscriptions: list API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics.subscriptions/list}
  *
  * @param {object=} options - Configuration object.
  * @param {boolean} options.autoPaginate - Have pagination handled
@@ -359,7 +359,7 @@ Topic.prototype.getSubscriptionsStream = function(options) {
  * Publish the provided message or array of messages. On success, an array of
  * messageIds is returned in the response.
  *
- * @resource [Topics: publish API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.topics/publish}
+ * @resource [Topics: publish API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/publish}
  *
  * @throws {Error} If no message is provided.
  *
@@ -475,26 +475,25 @@ Topic.prototype.publish = function(messages, options, callback) {
 };
 
 /**
- * Create a subscription to this topic. You may optionally provide an object to
- * customize the subscription.
+ * Create a subscription to this topic.
  *
- * Your provided callback will be invoked with an error object if an API error
- * occurred or a {module:pubsub/subscription} object.
- *
- * @resource [Subscriptions: create API Documentation]{@link https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions/create}
+ * @resource [Subscriptions: create API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/create}
  *
  * @param {string} subName - The name of the subscription.
- * @param {object=} options - Configuration object.
- * @param {number=} options.ackDeadlineSeconds - The maximum time after
+ * @param {object=} options - See a
+ *     [Subscription resource](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions)
+ * @param {number} options.ackDeadlineSeconds - The maximum time after
  *     receiving a message that you must ack a message before it is redelivered.
  * @param {boolean=} options.autoAck - Automatically acknowledge the message
  *     once it's pulled. (default: false)
  * @param {string} options.encoding - When pulling for messages, this type is
  *     used when converting a message's data to a string. (default: 'utf-8')
- * @param {number=} options.interval - Interval in milliseconds to check for new
+ * @param {number} options.interval - Interval in milliseconds to check for new
  *     messages. (default: 10)
  * @param {number} options.maxInProgress - Maximum messages to consume
  *     simultaneously.
+ * @param {string} options.pushEndpoint - A URL to a custom endpoint that
+ *     messages should be pushed to.
  * @param {boolean=} options.reuseExisting - If the subscription already exists,
  *     reuse it. The options of the existing subscription are not changed. If
  *     false, attempting to create a subscription that already exists will fail.

packages/pubsub/test/index.js

@@ -572,22 +572,25 @@ describe('PubSub', function() {
         encoding: 'utf-8',
         interval: 3,
         maxInProgress: 5,
-        pushConfig: {
-          pushEndpoint: 'https://domain/push'
-        },
+        pushEndpoint: 'https://domain/push',
         reuseExisting: false,
         timeout: 30000
       };
 
       var expectedBody = extend({
         topic: TOPIC_NAME,
         name: SUB_NAME
-      }, options);
+      }, options, {
+        pushConfig: {
+          pushEndpoint: options.pushEndpoint
+        }
+      });
 
       delete expectedBody.autoAck;
       delete expectedBody.encoding;
       delete expectedBody.interval;
       delete expectedBody.maxInProgress;
+      delete expectedBody.pushEndpoint;
       delete expectedBody.reuseExisting;
       delete expectedBody.timeout;