Merge "Fix another race condition triggered when two vanadium runtimes authenticate at the same time (like on the tutorials)."
diff --git a/src/proxy/stream.js b/src/proxy/stream.js
index e07da67..fcb2b67 100644
--- a/src/proxy/stream.js
+++ b/src/proxy/stream.js
@@ -21,11 +21,25 @@
require('../gen-vdl/v.io/x/ref/services/wspr/internal/lib').ServerRpcReply;
/**
- * A stream that allows sending and receiving data for a streaming rpc. If
- * onmessage is set and a function, it will be called whenever there is data on.
- * the stream. The stream implements the promise api. When the rpc is complete,
- * the stream will be fulfilled. If there is an error, then the stream will be
- * rejected. This constructor should not be directly called.
+ * @summary
+ * A stream that allows sending and receiving data for a streaming rpc.
+ * @description
+ * <p>Stream is a
+ * [Duplex Node.js stream]{@link https://nodejs.org/api/stream.html}
+ * in 'objectMode'.
+ * This constructor should not be directly called.</p>
+ *
+ * <p>If a 'data' event handler is specified, it will be called with data as
+ * they become available.
+ * <pre>
+ * stream.on('data', function(obj) {
+ * console.log(obj);
+ * });
+ * </pre></p>
+ * <p>
+ * All other [Node.js stream]{@link https://nodejs.org/api/stream.html} events,
+ * properties and function are also available on this stream as well.
+ * </p>
* @constructor
* @inner
* @memberof module:vanadium.rpc
@@ -116,6 +130,7 @@
/**
* Queue the close signal onto the Duplex's queue.
+ * @private
*/
Stream.prototype._queueClose = function() {
this._queueData(null);
@@ -123,6 +138,7 @@
/**
* Queues the data onto the Duplex's queue.
+ * @private
*/
Stream.prototype._queueData = function(data) {
if (this.shouldQueue) {
@@ -137,9 +153,9 @@
/**
* Writes an object to the stream.
* @param {*} chunk The data to write to the stream.
- * @param {null} encoding ignored for object streams.
- * @param {function} cb if set, the function to call when the write
- * completes.
+ * @param {string} [encoding=null] ignored for object streams.
+ * @param {module:vanadium~voidCb} cb If set, the function to call when the
+ * write completes.
* @return {boolean} Returns false if the write buffer is full.
*/
Stream.prototype.write = function(chunk, encoding, cb) {
@@ -171,9 +187,9 @@
/**
* Writes an optional object to the stream and ends the stream.
* @param {*} chunk The data to write to the stream.
- * @param {null} encoding ignored for object streams.
- * @param {function} cb if set, the function to call when the write
- * completes.
+ * @param {string} [encoding=null] Ignored for object streams.
+ * @param {module:vanadium~voidCb} cb If set, the function to call when the
+ * end call completes.
*/
Stream.prototype.end = function(chunk, encoding, cb) {
if (this.isClient) {
diff --git a/src/rpc/client.js b/src/rpc/client.js
index 2096aa8..1a2d20f 100644
--- a/src/rpc/client.js
+++ b/src/rpc/client.js
@@ -336,11 +336,12 @@
'arguments. Expected format: {5}({6})');
/**
- * A callbacked that is called when
+ * A callback that is called when
* [bindTo]{@link module:vanadium.rpc~Client#bindTo} finishes.
* @callback module:vanadium.rpc~Client~bindToCb
- * @param {error} err If set the error that occured.
- * @param {object} service The service object containing the exported methods.
+ * @param {Error} err If set the error that occurred.
+ * @param {object} service The stub object containing the exported
+ * methods of the remote service.
*/
/**
* <p>Performs client side binding of a remote service to a native JavaScript
@@ -359,10 +360,11 @@
* });
* </pre>
* @param {module:vanadium.context.Context} ctx A context.
- * @param {string} name the vanadium name of the service to bind to.
- * @param {module:vanadium.rpc~Client~bindToCb} [cb] if given, this function
+ * @param {string} name The vanadium name of the service to bind to.
+ * @param {module:vanadium.rpc~Client~bindToCb} [cb] If given, this function
* will be called on completion of the bind.
- * @return {Promise} An object with methods that perform rpcs to service methods
+ * @return {Promise<object>} Promise that resolves to the stub object containing
+ * the exported methods of the remote service.
*/
Client.prototype.bindTo = function(ctx, name, cb) {
var client = this;
@@ -408,12 +410,15 @@
* });
* </pre>
*
- * @param {string} name the vanadium name of the service to bind to.
- * @param {module:vanadium.vdl.signature.Interface} signature the service
+ * @param {string} name The vanadium name of the service to bind to.
+ * @param {module:vanadium.vdl.signature.Interface} signature The service
* signature of a vanadium service.
- * @return {object} An object with methods that perform rpcs to service methods.
+ * @param {module:vanadium.rpc~Client~bindToCb} [cb] If given, this function
+ * will be called on completion of the bind.
+ * @return {Promise<object>} Promise that resolves to the stub object containing
+ * the exported methods of the remote service.
*/
-Client.prototype.bindWithSignature = function(name, signature) {
+Client.prototype.bindWithSignature = function(name, signature, cb) {
var client = this;
var boundObject = {};
@@ -554,20 +559,21 @@
};
/**
- * A callback that is called with either a signature or an error
+ * A callback that is called with either signature interfaces or an error.
* @callback module:vanadium.rpc~Client~signatureCb
- * @param {error} err If set, the error that occured.
- * @param {module:vanadium.vdl.signature.Interface} signature The signature
- * result.
+ * @param {Error} err If set, the error that occurred.
+ * @param {module:vanadium.vdl.signature.Interface[]} signature The signature
+ * interfaces.
*/
/**
* Returns the object signatures for a given object name.
* @param {module:vanadium.context.Context} ctx A context.
- * @param {string} name the vanadium name of the service to bind to.
- * @param {function} [cb] if given, this function will be called on
- * completion.
- * @return {Promise<module:vanadium.vdl.signature.Interface>} Promise that will
- * be resolved with the signatures or rejected with an error if there is one.
+ * @param {string} name The vanadium name of the service to bind to.
+ * @param {module:vanadium.rpc~Client~signatureCb} [cb] If given, this
+ * function will be called on completion.
+ * @return {Promise<module:vanadium.vdl.signature.Interface[]>} Promise that
+ * will be resolved with the signature interfaces or rejected with an error
+ * if there is one.
*/
Client.prototype.signature = function(ctx, name, cb) {
var last = arguments.length - 1;
@@ -604,21 +610,21 @@
* [remoteBlessings]{@link module:vanadium.rpc~Client#remoteBlessings}
* function.
* @callback module:vanadium.rpc~Client~remoteBlessingsCb
- * @param {error} err If set, the error that occured
- * @param {array<string>} blessingNames The blessings of the remote server.
+ * @param {Error} err If set, the error that occurred.
+ * @param {string[]} blessingNames The blessings of the remote server.
*/
/**
* Returns the remote blessings of a server at the given name.
* @param {module:vanadium.context.Context} ctx A context.
- * @param {string} name the vanadium name of the service to get the remote
+ * @param {string} name The vanadium name of the service to get the remote
* blessings of.
- * @param {string} [method] the name of the rpc method that will be started in
+ * @param {string} [method] The name of the rpc method that will be started in
* order to read the blessings. Defaults to 'Signature'. This only matters in
* the case when a server responds to different method calls with different
* blessings.
- * @param {module:vanadium.rpc~Client~remoteBlessingsCb} [cb] if given, this
+ * @param {module:vanadium.rpc~Client~remoteBlessingsCb} [cb] If given, this
* function will be called on completion.
- * @return {Promise<array<string>>} Promise that will be resolved with the
+ * @return {Promise<string[]>} Promise that will be resolved with the
* blessing names or rejected with an error if there is one.
*/
Client.prototype.remoteBlessings = function(ctx, name, method, cb) {
@@ -645,7 +651,7 @@
*
* Currently the only supported key is 'allowedServersPolicy'.
*
- * @param {Object} opts map of call options.
+ * @param {object} opts Map of call options.
* @param {string[]} opts.allowedServersPolicy Array of blessing patterns that
* the allowed server must match in order for the RPC to be initiated.
*/
diff --git a/src/rpc/index.js b/src/rpc/index.js
index ba71281..0f4a7ce 100644
--- a/src/rpc/index.js
+++ b/src/rpc/index.js
@@ -34,6 +34,7 @@
module.exports = {
/**
+ * @summary
* Namespace reserved defines interfaces for interacting with reserved RPC
* methods such as Signature, MethodSignature and Glob.
* @memberof module:vanadium.rpc
diff --git a/src/rpc/reserved/docs.js b/src/rpc/reserved/docs.js
index bb80e4a..8d32e4d 100644
--- a/src/rpc/reserved/docs.js
+++ b/src/rpc/reserved/docs.js
@@ -3,8 +3,9 @@
// license that can be found in the LICENSE file.
/**
+ * @summary
* GlobMaxRecursionReached indicates that the Glob
- * request exceeded the max recursion level
+ * request exceeded the max recursion level.
* @name GlobMaxRecursionReached
* @constructor
* @param {module:vanadium.context.Context} ctx The context the error was
@@ -14,6 +15,7 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
+ * @summary
* GlobMatchesOmitted indicates that some of the Glob results might
* have been omitted due to access restrictions.
* @name GlobMatchesOmitted
@@ -25,6 +27,7 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
+ * @summary
* GlobNotImplemented indicates that Glob is not implemented by the object.
* @name GlobNotImplemented
* @constructor
diff --git a/src/rpc/server.js b/src/rpc/server.js
index 31a694e..6f41879 100644
--- a/src/rpc/server.js
+++ b/src/rpc/server.js
@@ -37,7 +37,7 @@
* Server defines the interface for managing a collection of services.
* @description
* <p>Private Constructor, use
- * [Runtime#newServer]{@link module:vanadium~Runtime#newServer}</p>
+ * [Runtime#newServer]{@link module:vanadium~Runtime#newServer}.</p>
* @inner
* @constructor
* @memberof module:vanadium.rpc
@@ -56,9 +56,9 @@
}
/**
- * @typedef module:vanadium.rpc~Server~ServeOptions
* ServeOptions is a set of options that are passed to the
* [serve]{@link module:vanadium.rpc~Server#serve}.
+ * @typedef module:vanadium.rpc~Server~ServeOptions
* @property {module:vanadium.security.Authorize} authorizer An Authorizer
* that will handle the authorization for the method call. If null, then the
* default strict authorizer will be used.
@@ -76,20 +76,21 @@
* });
* </pre>
* <p>If name is an empty string, no attempt will made to publish that
- * name to a mount table. It is an error to call {@link Server#serve|serve}
- * if either {@link Server#serveDispatcher|serveDispatcher} or
- * {@link Server.serve|serve} has already been called.
+ * name to a mount table. It is an error to call
+ * {@link module:vanadium.rpc~Server#serve|serve}
+ * if either {@link module:vanadium.rpc~Server#serveDispatcher|serveDispatcher}
+ * or {@link module:vanadium.rpc~Server.serve|serve} has already been called.
* To serve the same object under multiple names,
- * {@link Server#addName|addName} can be used.</p>
+ * {@link module:vanadium.rpc~Server#addName|addName} can be used.</p>
*
* @public
- * @param {string} name Name to serve under
+ * @param {string} name Name to serve under.
* @param {object} serviceObject The service object that has a set of
- * exported methods
- * @param {module:vanadium.rpc~Server~ServeOptions} options Options config
+ * exported methods.
+ * @param {module:vanadium.rpc~Server~ServeOptions} options Options config.
* @param {module:vanadium~voidCb} [cb] If provided, the function
* will be called on completion.
- * @return {Promise} Promise to be called when serve completes or fails.
+ * @return {Promise<void>} Promise to be called when serve completes or fails.
*/
Server.prototype.serve = function(name, serviceObject, options, cb) {
if (typeof options === 'function') {
@@ -109,32 +110,33 @@
};
/**
- * @typedef DispatcherResponse
- * @type {Object}
+ * @typedef module:vanadium.rpc~Server~DispatcherResponse
+ * @type {object}
* @property {object} service The Invoker that will handle
* method call.
- * @property {module:vanadium.security~Authorize} authorizer An Authorizer that
+ * @property {module:vanadium.security.Authorize} authorizer An Authorizer that
* will handle the authorization for the method call. If null, then the default
- * strict authorizer will be used.
+ * authorizer will be used.
*/
/**
* A function that returns the service object for a suffix/method pair.
- * @callback module:vanadium.rpc~Dispatcher
- * @param {string} suffix The suffix for the call
- * @param {string} method The method for the call
- * @param {Dispatcher-callback} cb The callback to call when the dispatch is
- * complete
- * @return {DispatcherResponse|Promise} Either the DispatcherResponse object to
+ * @callback module:vanadium.rpc~Server~Dispatcher
+ * @param {string} suffix The suffix for the call.
+ * @param {string} method The method for the call.
+ * @param {module:vanadium.rpc~Server~Dispatcher-callback} cb
+ * The callback to call when the dispatch is complete.
+ * @return {module:vanadium.rpc~Server~DispatcherResponse | Promise}
+ * Either the DispatcherResponse object to
* handle the method call or a Promise that will be resolved the service
* callback.
*/
/**
- * Callback passed into Dispatcher
- * @callback module:vanadium.rpc~Dispatcher-callback
- * @param {Error} err An error if one occurred
- * @param {object} object The object that will handle the method call
+ * Callback passed into Dispatcher.
+ * @callback module:vanadium.rpc~Server~Dispatcher-callback
+ * @param {Error} err An error if one occurred.
+ * @param {object} object The object that will handle the method call.
*/
/**
@@ -153,20 +155,22 @@
* <p>If name is an empty string, no attempt will made to publish that
* name to a mount table. </p>
*
- * <p>It is an error to call {@link Server#serveDispatcher|serveDispatcher}
- * if {@link Server#serve|serve} has already been called. It is also an error
+ * <p>It is an error to call
+ * {@link module:vanadium.rpc~Server#serveDispatcher|serveDispatcher}
+ * if {@link module:vanadium.rpc~Server#serve|serve} has already been called.
+ * It is also an error
* to call serveDispatcher multiple times.</p>
* To serve the same dispatcher under multiple names,
- * {@link Server#addName|addName} can be used. </p>
+ * {@link module:vanadium.rpc~Server#addName|addName} can be used. </p>
*
* @public
- * @param {string} name Name to serve under
- * @param {module:vanadium.rpc~Dispatcher} dispatcher A function that will
- * take in the suffix and the method to be called and return the service
+ * @param {string} name Name to serve under.
+ * @param {module:vanadium.rpc~Server~Dispatcher} dispatcher A function that
+ * will take in the suffix and the method to be called and return the service
* object for that suffix.
* @param {module:vanadium~voidCb} [cb] If provided, the function
* will be called on completion.
- * @return {Promise} Promise to be called when serve completes or fails.
+ * @return {Promise<void>} Promise to be called when serve completes or fails.
*/
Server.prototype.serveDispatcher = function(name, dispatcher, cb) {
this.dispatcher = dispatcher;
@@ -179,7 +183,8 @@
* All published named are unmounted.
* @param {module:vanadium~voidCb} [cb] If provided, the function
* will be called on completion.
- * @return {Promise} Promise to be called when stop service completes or fails
+ * @return {Promise<void>} Promise to be called when stop service completes or
+ * fails
*/
Server.prototype.stop = function(cb) {
return this._router.stopServer(this, cb);
@@ -193,10 +198,11 @@
* [serveDispatcher]{@link module:vanadium.rpc~Server#serveDispatcher}
* or [addName]{@link module:vanadium.rpc~Server#addName}.
* @public
- * @param {string} name Name to publish
+ * @param {string} name Name to publish.
* @param {module:vanadium~voidCb} [cb] If provided, the function
* will be called on completion.
- * @return {Promise} Promise to be called when operation completes or fails
+ * @return {Promise<void>} Promise to be called when operation completes or
+ * fails
*/
Server.prototype.addName = function(name, cb) {
return this._router.addName(name, this, cb);
@@ -209,10 +215,11 @@
* [serveDispatcher]{@link module:vanadium.rpc~Server#serveDispatcher}
* or [addName]{@link module:vanadium.rpc~Server#addName}.
* @public
- * @param {string} name Name to remove
+ * @param {string} name Name to remove.
* @param {function} [cb] If provided, the function will be called on
* completion. The only argument is an error if there was one.
- * @return {Promise} Promise to be called when operation completes or fails
+ * @return {Promise<void>} Promise to be called when operation completes or
+ * fails.
*/
Server.prototype.removeName = function(name, cb) {
return this._router.removeName(name, this, cb);
@@ -220,7 +227,7 @@
/**
* @private
- * @param {Number} handle The handle for the service
+ * @param {Number} handle The handle for the service.
* @return {Object} The invoker corresponding to the provided error.
*/
Server.prototype.getInvokerForHandle = function(handle) {
@@ -233,11 +240,11 @@
/**
* Handles the authorization for an RPC.
* @private
- * @param {Number} handle The handle for the authorizer
+ * @param {Number} handle The handle for the authorizer.
* @param {module:vanadium.context.Context} ctx The ctx of the
* call.
* @param {module:vanadium.security~SecurityCall} call The security call.
- * @return {Promise} a promise that will be fulfilled with the result.
+ * @return {Promise} A promise that will be fulfilled with the result.
*/
Server.prototype.handleAuthorization = function(handle, ctx, call) {
var handler = this.serviceObjectHandles[handle];
diff --git a/src/vanadium.js b/src/vanadium.js
index 865f8f9..63923b1 100644
--- a/src/vanadium.js
+++ b/src/vanadium.js
@@ -15,7 +15,7 @@
var vlog = require('./lib/vlog');
var defaults = {
- appName: 'untitled webapp',
+ appName: require('is-browser') ? window.location.host : 'untitled js app',
authenticate: isBrowser,
logLevel: vlog.levels.WARN,
wspr: process.env.WSPR || (isBrowser ? null : 'http://localhost:8124')
diff --git a/src/vom/decoder.js b/src/vom/decoder.js
index 4689d24..ae51b8e 100644
--- a/src/vom/decoder.js
+++ b/src/vom/decoder.js
@@ -38,11 +38,13 @@
this._deepWrap = deepWrap || false;
}
-/**
- * Decodes the next object off of the message reader.
+/*
* TODO(bprosnitz) We will want to be able to decode when we get callbacks.
* Revisit this API.
- * @return The next object or null if no more objects are available.
+ */
+/**
+ * Decodes the next object off of the message reader.
+ * @return {object} The next object or null if no more objects are available.
*/
Decoder.prototype.decode = function() {
var type = this._messageReader.nextMessageType(this._typeDecoder);
