Add documentation for TLS

Author: jakewins

esdoc.json

@@ -2,7 +2,7 @@
   "source": "./src",
   "destination": "./docs/build",
   "includes": ["\\.js$"],
-  "excludes": ["external"],
+  "excludes": ["external", "internal"],
   "package": "./package.json",
   "title": "Neo4j Bolt  Driver for Javascript",
   "unexportIdentifier": true,

package.json

@@ -21,6 +21,7 @@
     "babelify": "^6.3.0",
     "browserify": "^11.0.0",
     "esdoc": "^0.4.0",
+    "esdoc-importpath-plugin": "0.0.1",
     "glob": "^5.0.14",
     "gulp": "^3.9.0",
     "gulp-babel": "^5.2.1",

src/v1/driver.js

@@ -21,18 +21,27 @@ import Session from './session';
 import {Pool} from './internal/pool';
 import {connect} from "./internal/connector";
 import StreamObserver from './internal/stream-observer';
+import {VERSION} from '../../version';
 
 /**
-  * A Driver instance is used for mananging {@link Session}s.
-  * @access public
-  */
+ * A driver maintains one or more {@link Session sessions} with a remote
+ * Neo4j instance. Through the {@link Session sessions} you can send statements
+ * and retrieve results from the database.
+ *
+ * Drivers are reasonably expensive to create - you should strive to keep one
+ * driver instance around per Neo4j Instance you connect to.
+ *
+ * @access public
+ */
 class Driver {
   /**
+   * You should not be calling this directly, instead use {@link driver}.
    * @constructor
    * @param {string} url
    * @param {string} userAgent
    * @param {Object} token
    * @param {Object} config
+   * @access private
    */
   constructor(url, userAgent = 'neo4j-javascript/0.0', token = {}, config = {}) {
     this._url = url;
@@ -85,7 +94,16 @@ class Driver {
   }
 
   /**
-   * Create and return new session
+   * Acquire a session to communicate with the database. The driver maintains
+   * a pool of sessions, so calling this method is normally cheap because you
+   * will be pulling a session out of the common pool.
+   *
+   * This comes with some responsibility - make sure you always call
+   * {@link Session#close()} when you are done using a session, and likewise,
+   * make sure you don't close your session before you are done using it. Once
+   * it is returned to the pool, the session will be reset to a clean state and
+   * made available for others to use.
+   *
    * @return {Session} new session.
    */
   session() {
@@ -113,8 +131,9 @@ class Driver {
   }
 
   /**
-   * Close sessions connections
-   * @return
+   * Close all open sessions and other associated resources. You should
+   * make sure to use this when you are done with this driver instance.
+   * @return undefined
    */
   close() {
     for (let sessionId in this._openSessions) {
@@ -143,4 +162,63 @@ class _ConnectionStreamObserver extends StreamObserver {
   }
 }
 
-export default Driver
+let USER_AGENT = "neo4j-javascript/" + VERSION;
+
+/**
+ * Construct a new Neo4j Driver. This is your main entry point for this
+ * library.
+ *
+ * ## Configuration
+ *
+ * This function optionally takes a configuration argument. Available configuration
+ * options are as follows:
+ *
+ *     {
+ *       // Enable TLS encryption. This is on by default in modern NodeJS installs,
+ *       // but off by default in the Web Bundle and old (<=1.0.0) NodeJS installs
+ *       // due to technical limitations on those platforms.
+ *       encrypted: true|false,
+ *
+ *       // Trust strategy to use if encryption is enabled. There is no mode to disable
+ *       // trust other than disabling encryption altogether. The reason for
+ *       // this is that if you don't know who you are talking to, it is easy for an
+ *       // attacker to hijack your encrypted connection, rendering encryption pointless.
+ *       //
+ *       // TRUST_ON_FIRST_USE is the default for modern NodeJS deployments, and works
+ *       // similarly to how `ssl` works - the first time we connect to a new host,
+ *       // we remember the certificate they use. If the certificate ever changes, we
+ *       // assume it is an attempt to hijack the connection and require manual intervention.
+ *       // This means that by default, connections "just work" while still giving you
+ *       // good encrypted protection.
+ *       //
+ *       // TRUST_SIGNED_CERTIFICATES is the classic approach to trust verification -
+ *       // whenever we establish an encrypted connection, we ensure the host is using
+ *       // an encryption certificate that is in, or is signed by, a certificate listed
+ *       // as trusted. In the web bundle, this list of trusted certificates is maintained
+ *       // by the web browser. In NodeJS, you configure the list with the next config option.
+ *       trust: "TRUST_ON_FIRST_USE" | "TRUST_SIGNED_CERTIFICATES",
+ *
+ *       // List of one or more paths to trusted encryption certificates. This only
+ *       // works in the NodeJS bundle, and only matters if you use "TRUST_SIGNED_CERTIFICATES".
+ *       // The certificate files should be in regular X.509 PEM format.
+ *       // For instance, ['./trusted.pem']
+ *       trustedCertificates: [],
+ *
+ *       // Path to a file where the driver saves hosts it has seen in the past, this is
+ *       // very similar to the ssl tool's known_hosts file. Each time we connect to a
+ *       // new host, a hash of their certificate is stored along with the domain name and
+ *       // port, and this is then used to verify the host certificate does not change.
+ *       // This setting has no effect unless TRUST_ON_FIRST_USE is enabled.
+ *       knownHosts:"~/.neo4j/known_hosts",
+ *     }
+ *
+ * @param {string} url The URL for the Neo4j database, for instance "bolt://localhost"
+ * @param {Map<String,String>} authToken Authentication credentials. See {@link auth} for helpers.
+ * @param {Object} config Configuration object. See the configuration section above for details.
+ * @returns {Driver}
+ */
+function driver(url, authToken, config={}) {
+  return new Driver(url, USER_AGENT, authToken, config);
+}
+
+export {Driver, driver}

src/v1/index.js

@@ -18,14 +18,11 @@
  */
 
 import {int, isInt} from './integer';
-import Driver from './driver';
-import {VERSION} from '../version';
+import {driver} from './driver';
 import {Node, Relationship, UnboundRelationship, PathSegment, Path} from './graph-types'
 
-let USER_AGENT = "neo4j-javascript/" + VERSION;
-
 export default {
-  driver: (url, token, config={}) => new Driver(url, USER_AGENT, token, config),
+  driver,
   int,
   isInt,
   auth: {