/*!
* Copyright 2015 Google Inc. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
'use strict';
const common = require('@google-cloud/common');
const format = require('string-format-obj');
const is = require('is');
const {promisifyAll} = require('@google-cloud/promisify');
/**
* A Network object allows you to interact with a Google Compute Engine network.
*
* @see [Networks Overview]{@link https://cloud.google.com/compute/docs/networking#networks}
* @see [Network Resource]{@link https://cloud.google.com/compute/docs/reference/v1/networks}
*
* @class
* @param {Compute} compute
* @param {strign} name
*
* @example
* const Compute = require('@google-cloud/compute');
* const compute = new Compute();
* const network = compute.network('network-name');
*/
class Network extends common.ServiceObject {
constructor(compute, name) {
const methods = {
/**
* Create a network.
*
* @method Network#create
* @param {object} config - See {@link Compute#createNetwork}.
*
* @example
* const Compute = require('@google-cloud/compute');
* const compute = new Compute();
* const network = compute.network('network-name');
*
* const config = {
* // ...
* };
*
* network.create(config, function(err, network, operation, apiResponse) {
* // `network` is a Network object.
*
* // `operation` is an Operation object that can be used to check the
* // status of network creation.
* });
*
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* network.create(config).then(function(data) {
* const network = data[0];
* const operation = data[1];
* const apiResponse = data[2];
* });
*/
create: true,
/**
* Check if the network exists.
*
* @method Network#exists
* @param {function} callback - The callback function.
* @param {?error} callback.err - An error returned while making this
* request.
* @param {boolean} callback.exists - Whether the network exists or not.
*
* @example
* const Compute = require('@google-cloud/compute');
* const compute = new Compute();
* const network = compute.network('network-name');
*
* network.exists(function(err, exists) {});
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* network.exists().then(function(data) {
* const exists = data[0];
* });
*/
exists: true,
/**
* Get a network if it exists.
*
* You may optionally use this to "get or create" an object by providing an
* object with `autoCreate` set to `true`. Any extra configuration that is
* normally required for the `create` method must be contained within this
* object as well.
*
* @method Network#get
* @param {options=} options - Configuration object.
* @param {boolean} options.autoCreate - Automatically create the object if
* it does not exist. Default: `false`
*
* @example
* const Compute = require('@google-cloud/compute');
* const compute = new Compute();
* const network = compute.network('network-name');
*
* network.get(function(err, network, apiResponse) {
* // `network` is a Network object.
* });
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* network.get().then(function(data) {
* const network = data[0];
* const apiResponse = data[1];
* });
*/
get: true,
/**
* Get the network's metadata.
*
* @see [Network Resource]{@link https://cloud.google.com/compute/docs/reference/v1/networks}
* @see [Networks: get API Documentation]{@link https://cloud.google.com/compute/docs/reference/v1/networks/delete}
*
* @method Network#getMetadata
* @param {function=} callback - The callback function.
* @param {?error} callback.err - An error returned while making this
* request.
* @param {object} callback.metadata - The network's metadata.
* @param {object} callback.apiResponse - The full API response.
*
* @example
* const Compute = require('@google-cloud/compute');
* const compute = new Compute();
* const network = compute.network('network-name');
*
* network.getMetadata(function(err, metadata, apiResponse) {});
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* network.getMetadata().then(function(data) {
* const metadata = data[0];
* const apiResponse = data[1];
* });
*/
getMetadata: true,
};
super({
parent: compute,
baseUrl: '/global/networks',
/**
* @name Network#id
* @type {string}
*/
id: name,
createMethod: compute.createNetwork.bind(compute),
methods: methods,
});
/**
* The parent {@link Compute} instance of this {@link Network} instance.
* @name Network#compute
* @type {Compute}
*/
this.compute = compute;
/**
* @name Network#formattedName
* @type {string}
*/
this.formattedName = Network.formatName_(compute, name);
/**
* @name Network#name
* @type {string}
*/
this.name = name;
}
/**
* Create a firewall for this network.
*
* @see [Firewalls Overview]{@link https://cloud.google.com/compute/docs/networking#firewalls}
* @see [Firewalls: insert API Documentation]{@link https://cloud.google.com/compute/docs/reference/v1/firewalls/insert}
*
* @param {string} name - Name of the firewall.
* @param {object} config - See a
* [Firewall resource](https://cloud.google.com/compute/docs/reference/v1/firewalls#resource).
* @param {object} config.protocols - A map of protocol to port range. The keys
* of the object refer to a protocol (e.g. `tcp`, `udp`) and the value for
* the key are the ports/port-ranges that are allowed to make a connection.
* @param {string[]} config.ranges - The IP address blocks that this rule
* applies to, expressed in
* [CIDR](http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing)
* format.
* @param {function} callback - The callback function.
* @param {?error} callback.err - An error returned while making this request.
* @param {Firewall} callback.firewall - The created Firewall
* object.
* @param {Operation} callback.operation - An operation object
* that can be used to check the status of the request.
* @param {object} callback.apiResponse - The full API response.
*
* @example
* const Compute = require('@google-cloud/compute');
* const compute = new Compute();
* const network = compute.network('network-name');
*
* const config = {
* protocols: {
* tcp: [3000],
* udp: [] // An empty array means all ports are allowed.
* },
*
* ranges: ['0.0.0.0/0']
* };
*
* function callback(err, firewall, operation, apiResponse) {
* // `firewall` is a Firewall object.
*
* // `operation` is an Operation object that can be used to check the status
* // of the request.
* }
*
* network.createFirewall('new-firewall-name', config, callback);
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* network.createFirewall('new-firewall-name', config).then(function(data) {
* const firewall = data[0];
* const operation = data[1];
* const apiResponse = data[2];
* });
*/
createFirewall(name, config, callback) {
config = Object.assign({}, config, {
network: this.formattedName,
});
this.compute.createFirewall(name, config, callback);
}
/**
* Create a subnetwork in this network.
*
* @see [Subnetwork Resource]{@link https://cloud.google.com/compute/docs/reference/v1/subnetworks#resource}
* @see [Subnetwork: insert API Documentation]{@link https://cloud.google.com/compute/docs/reference/v1/subnetworks/insert}
*
* @param {string} name - Name of the subnetwork.
* @param {object} config - See a
* [Subnetwork resource](https://cloud.google.com/compute/docs/reference/v1/subnetworks#resource).
* @param {Region|string} config.region - The region where the
* Subnetwork resides.
* @param {string} config.range - The range of internal addresses that
* are owned by this subnetwork.
* [CIDR](http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) range
* of addresses that are legal on this network. (Alias for
* `config.ipCidrRange`)
* @param {function} callback - The callback function.
* @param {?error} callback.err - An error returned while making this request.
* @param {Subnetwork} callback.subnetwork - The created
* Subnetwork object.
* @param {Operation} callback.operation - An operation object
* that can be used to check the status of the request.
* @param {object} callback.apiResponse - The full API response.
*
* @example
* const Compute = require('@google-cloud/compute');
* const compute = new Compute();
* const network = compute.network('network-name');
* const region = compute.region('us-east1');
*
* const config = {
* region: region,
* range: '10.0.1.0/24'
* };
*
* function callback(err, subnetwork, operation, apiResponse) {
* // `subnetwork` is a Subnetwork object.
*
* // `operation` is an Operation object that can be used to check the status
* // of the request.
* }
*
* network.createSubnetwork('new-subnetwork-name', config, callback);
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* network.createSubnetwork('new-subnetwork-name', config).then(function(data) {
* const subnetwork = data[0];
* const operation = data[1];
* const apiResponse = data[2];
* });
*/
createSubnetwork(name, config, callback) {
config = Object.assign({}, config, {
network: this.formattedName,
});
let region = config.region;
if (is.string(region)) {
region = this.compute.region(region);
}
delete config.region;
region.createSubnetwork(name, config, callback);
}
/**
* Get a list of subnetworks in this network.
*
* @see [Subnetworks Overview]{@link https://cloud.google.com/compute/docs/subnetworks}
* @see [Subnetworks: list API Documentation]{@link https://cloud.google.com/compute/docs/reference/v1/subnetworks}
*
* @param {object=} options - Subnetwork search options.
* @param {boolean} options.autoPaginate - Have pagination handled
* automatically. Default: true.
* @param {string} options.filter - Search filter in the format of
* `{name} {comparison} {filterString}`.
* - **`name`**: the name of the field to compare
* - **`comparison`**: the comparison operator, `eq` (equal) or `ne`
* (not equal)
* - **`filterString`**: the string to filter to. For string fields, this
* can be a regular expression.
* @param {number} options.maxApiCalls - Maximum number of API calls to make.
* @param {number} options.maxResults - Maximum number of subnetworks to return.
* @param {string} options.pageToken - A previously-returned page token
* representing part of the larger set of results to view.
* @param {function} callback - The callback function.
* @param {?error} callback.err - An error returned while making this request.
* @param {Subnetwork[]} callback.subnetworks - Subnetwork
* objects from this network.
* @param {object} callback.apiResponse - The full API response.
*
* @example
* const Compute = require('@google-cloud/compute');
* const compute = new Compute();
* const network = compute.network('network-name');
*
* network.getSubnetworks(function(err, subnetworks) {
* // `subnetworks` is an array of `Subnetworks` objects.
* });
*
* //-
* // To control how many API requests are made and page through the results
* // manually, set `autoPaginate` to `false`.
* //-
* function callback(err, subnetworks, nextQuery, apiResponse) {
* if (nextQuery) {
* // More results exist.
* network.getSubnetworks(nextQuery, callback);
* }
* }
*
* network.getSubnetworks({
* autoPaginate: false
* }, callback);
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* network.getSubnetworks().then(function(data) {
* const subnetworks = data[0];
* });
*/
getSubnetworks(options, callback) {
if (is.fn(options)) {
callback = options;
options = {};
}
options = Object.assign({}, options, {
filter: 'network eq .*' + this.formattedName,
});
this.compute.getSubnetworks(options, callback);
}
/**
* Get a {@link Subnetwork} list within this network as a readable
* object stream.
*
* @param {object=} options - Configuration object. See
* {@link Network#getSubnetworks} for a complete list of options.
* @returns {stream}
*
* @example
* const Compute = require('@google-cloud/compute');
* const compute = new Compute();
* const network = compute.network('network-name');
*
* network.getSubnetworksStream()
* .on('error', console.error)
* .on('data', function(subnetwork) {
* // `subnetwork` is a `Subnetwork` object.
* })
* .on('end', function() {
* // All subnetworks retrieved.
* });
*
* //-
* // If you anticipate many results, you can end a stream early to prevent
* // unnecessary processing and API requests.
* //-
* network.getSubnetworksStream()
* .on('data', function(subnetwork) {
* this.end();
* });
*/
getSubnetworksStream(options) {
options = Object.assign({}, options, {
filter: 'network eq .*' + this.formattedName,
});
return this.compute.getSubnetworksStream(options);
}
/**
* Delete the network.
*
* @see [Networks: delete API Documentation]{@link https://cloud.google.com/compute/docs/reference/v1/networks/delete}
*
* @param {function=} callback - The callback function.
* @param {?error} callback.err - An error returned while making this request.
* @param {Operation} callback.operation - An operation object
* that can be used to check the status of the request.
* @param {object} callback.apiResponse - The full API response.
*
* @example
* const Compute = require('@google-cloud/compute');
* const compute = new Compute();
* const network = compute.network('network-name');
*
* network.delete(function(err, operation, apiResponse) {
* // `operation` is an Operation object that can be used to check the status
* // of the request.
* });
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* network.delete().then(function(data) {
* const operation = data[0];
* const apiResponse = data[1];
* });
*/
delete(callback) {
const compute = this.compute;
callback = callback || common.util.noop;
super.delete(function(err, resp) {
if (err) {
callback(err, null, resp);
return;
}
const operation = compute.operation(resp.name);
operation.metadata = resp;
callback(null, operation, resp);
});
}
/**
* Get a reference to a Google Compute Engine firewall in this network.
*
* @see [Firewalls Overview]{@link https://cloud.google.com/compute/docs/networking#firewalls}
*
* @param {string} name - Name of the firewall.
*
* @example
* const Compute = require('@google-cloud/compute');
* const compute = new Compute();
* const network = compute.network('network-name');
* const firewall = network.firewall('firewall-name');
*/
firewall(name) {
const firewall = this.compute.firewall(name);
firewall.metadata = {
network: this.formattedName,
};
return firewall;
}
/**
* Get a list of firewalls for this network.
*
* @see [Firewalls Overview]{@link https://cloud.google.com/compute/docs/networking#firewalls}
* @see [Firewalls: list API Documentation]{@link https://cloud.google.com/compute/docs/reference/v1/firewalls/list}
*
* @param {object=} options - Firewall search options.
* @param {boolean} options.autoPaginate - Have pagination handled
* automatically. Default: true.
* @param {number} options.maxApiCalls - Maximum number of API calls to make.
* @param {number} options.maxResults - Maximum number of firewalls to return.
* @param {string} options.pageToken - A previously-returned page token
* representing part of the larger set of results to view.
* @param {function} callback - The callback function.
* @param {?error} callback.err - An error returned while making this request.
* @param {Firewall[]} callback.firewalls - Firewall objects from
* this network.
* @param {object} callback.apiResponse - The full API response.
*
* @example
* const Compute = require('@google-cloud/compute');
* const compute = new Compute();
* const network = compute.network('network-name');
*
* network.getFirewalls(function(err, firewalls) {
* // `firewalls` is an array of `Firewall` objects.
* });
*
* //-
* // To control how many API requests are made and page through the results
* // manually, set `autoPaginate` to `false`.
* //-
* function callback(err, firewalls, nextQuery, apiResponse) {
* if (nextQuery) {
* // More results exist.
* network.getFirewalls(nextQuery, callback);
* }
* }
*
* network.getFirewalls({
* autoPaginate: false
* }, callback);
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* network.getFirewalls().then(function(data) {
* const firewalls = data[0];
* });
*/
getFirewalls(options, callback) {
if (is.fn(options)) {
callback = options;
options = {};
}
options = Object.assign({}, options, {
filter: 'network eq .*' + this.formattedName,
});
this.compute.getFirewalls(options, callback);
}
/**
* Get a list of {@link Firewall} objects for this network as a
* readable object stream.
*
* @param {object=} options - Configuration object. See
* {@link Network#getFirewalls} for a complete list of options.
* @returns {stream}
*
* @example
* const Compute = require('@google-cloud/compute');
* const compute = new Compute();
* const network = compute.network('network-name');
*
* network.getFirewallsStream()
* .on('error', console.error)
* .on('data', function(firewall) {
* // `firewall` is a `Firewall` object.
* })
* .on('end', function() {
* // All firewalls retrieved.
* });
*
* //-
* // If you anticipate many results, you can end a stream early to prevent
* // unnecessary processing and API requests.
* //-
* network.getFirewallsStream()
* .on('data', function(firewall) {
* this.end();
* });
*/
getFirewallsStream(options) {
options = Object.assign({}, options, {
filter: 'network eq .*' + this.formattedName,
});
return this.compute.getFirewallsStream(options);
}
/**
* Format a network's name how the API expects.
*
* @private
*
* @param {Compute} compute - The Compute object this network belongs to.
* @param {string} name - The name of the network.
* @returns {string} - The formatted name.
*/
static formatName_(compute, name) {
return format('projects/{projectId}/global/networks/{name}', {
projectId: compute.projectId,
name: name,
});
}
}
/*! Developer Documentation
*
* All async methods (except for streams) will return a Promise in the event
* that a callback is omitted.
*/
promisifyAll(Network, {
exclude: ['firewall'],
});
/**
* Reference to the {@link Network} class.
* @name module:@google-cloud/compute.Network
* @see Network
*/
module.exports = Network;