Add header comments. Use PORT. Assume SHAs and binaries co-exist

Author: cjbj

package/README.md

@@ -44,15 +44,18 @@ Installation is described in [INSTALL](../INSTALL.md).
   [npm](https://www.npmjs.com/package/oracledb).
 
     - `make npmpackage` makes the main node-oracledb package
-      containing the JavaScript files.
+      containing the general node-oracledb JavaScript files and the
+      package.json in this directory.  This is the package that an
+      `npm install oracledb` will initially install.
 
     - `make binarypackage` makes a binary package for the current
-      Node.js/node-oracledb/platform and generates a SHA256 for the
-      binary.
+      Node.js-node / oracledb / platform combination and generates a
+      SHA256 for the binary.
 
-- The `package.json` in this directory invokes an install script that
-  downloads a binary package from GitHub.  This variant of
-  `package.json` is the copy bundled for the npm release..
+- As part of `npm install`, the `package.json` in this directory
+  invokes `oracledbinstall.js` that downloads the appropriate binary
+  package from GitHub.  This variant of `package.json` is the copy
+  bundled for the npm release.
 
   The parent file `../package.json` doesn't have the install target
   meaning that node-gyp will be invoked to compile node-oracledb.  This

package/createpackage.js

@@ -15,6 +15,16 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *
+ * NAME
+ *   createpackage.js
+ *
+ * DESCRIPTION
+ *   Creates a binary package for the current node-oracledb binary.  A
+ *   custom package format is used.  The package uses a custom format
+ *   with three components: length bytes (giving the length of the
+ *   license file), the license file, and then the node-oracledb
+ *   binary.  The package is gzipped.
+ *
  *****************************************************************************/
 
 'use strict';

package/extractpackage.js

@@ -15,6 +15,21 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *
+ * NAME
+ *   extractpackage.js
+ *
+ * DESCRIPTION
+ *   This script is a command-line interface to extract node-oracledb
+ *   binaries from an available binary package, see INSTALL.md.
+ *
+ * USAGE
+ *   Run this script like:
+ *     node extractpackage.js path=oracledb-vX.Y.Z-node-vNN-platform-architecture.gz
+ *   For example:
+ *     node extractpackage.js path=oracledb-v2.0.14-node-v57-darwin-x64.gz
+ *
+ *   The extracted binary can be manually moved to the correct directory.
+ *
  *****************************************************************************/
 
 'use strict';

package/oracledbinstall.js

@@ -15,6 +15,15 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *
+ * NAME
+ *   oracledbinstall.js
+ *
+ * DESCRIPTION
+ *   This script is included in the npm bundle of node-oracledb.  It
+ *   is invoked by package.json during npm install.  It downloads a
+ *   pre-built node-oracleb binary if one is available, or gives a
+ *   message on how to compile from source code.
+ *
  *****************************************************************************/
 
 'use strict';
@@ -52,7 +61,6 @@ try {
 
 const PACKAGE_HOSTNAME = 'github.com';
 const PACKAGE_PATH_REMOTE = '/oracle/node-oracledb/releases/download/' + packageUtil.dynamicProps.GITHUB_TAG + '/' + packageUtil.dynamicProps.PACKAGE_FILE_NAME;
-const SHA_HOSTNAME = PACKAGE_HOSTNAME;
 const SHA_PATH_REMOTE = '/oracle/node-oracledb/releases/download/' + packageUtil.dynamicProps.GITHUB_TAG + '/' + packageUtil.SHA_FILE_NAME;
 const PORT = 443;
 
@@ -130,7 +138,7 @@ function verifyBinary() {
       .then((sha) => {
         binarySha = sha;
 
-        return getRemoteFileReadStream(SHA_HOSTNAME, SHA_PATH_REMOTE);
+        return getRemoteFileReadStream(PACKAGE_HOSTNAME, SHA_PATH_REMOTE);
       })
       .then(readStream => {
         return new Promise((resolve, reject) => {
@@ -191,7 +199,7 @@ function getFileReadStreamByProxy(hostname, path, proxyHostname, proxyPort) {
       host: proxyHostname,
       port: proxyPort,
       method: 'CONNECT',
-      path: hostname + ':443'
+      path: hostname + ':' + PORT
     });
 
     req.on('error', reject);