@openziti/ziti-sdk-nodejs 0.13.1 → 0.13.3

package/.github/workflows/mattermost-ziti-webhook.yml

@@ -13,7 +13,7 @@ on:
 
 jobs:
   mattermost-ziti-webhook:
-    runs-on: macos-latest
+    runs-on: ubuntu-latest
     name: POST Webhook
     env:
       ZITI_LOG: 99

package/API_REFERENCE.hbs

@@ -0,0 +1,10 @@
+
+# API Reference
+{{#module name="@openziti/ziti-sdk-nodejs"}}
+{{>body~}}
+{{>member-index~}}
+{{>separator~}}
+{{>members~}}
+{{/module}}
+
+* * *

package/API_REFERENCE.md

@@ -0,0 +1,268 @@
+
+# API Reference
+OpenZiti SDK for Node.js
+
+
+* [@openziti/ziti-sdk-nodejs](#module_@openziti/ziti-sdk-nodejs)
+    * [~close(conn)](#module_@openziti/ziti-sdk-nodejs..close) ⇒ <code>void</code>
+    * [~dial(serviceName, isWebSocket, onConnect, onData)](#module_@openziti/ziti-sdk-nodejs..dial) ⇒ <code>void</code>
+    * [~express(express, serviceName)](#module_@openziti/ziti-sdk-nodejs..express) ⇒ <code>\*</code>
+    * [~httpRequest(serviceName, schemeHostPort, method, path, headers, onRequest, onResponse, onResponseData)](#module_@openziti/ziti-sdk-nodejs..httpRequest) ⇒ <code>void</code>
+    * [~httpRequestData(req, data, onRequestData)](#module_@openziti/ziti-sdk-nodejs..httpRequestData) ⇒ <code>void</code>
+    * [~httpRequestEnd(req)](#module_@openziti/ziti-sdk-nodejs..httpRequestEnd) ⇒ <code>void</code>
+    * [~init(identityPath)](#module_@openziti/ziti-sdk-nodejs..init) ⇒ <code>number</code>
+    * [~setLogLevel(level)](#module_@openziti/ziti-sdk-nodejs..setLogLevel) ⇒ <code>void</code>
+    * [~serviceAvailable(serviceName, onServiceAvailable)](#module_@openziti/ziti-sdk-nodejs..serviceAvailable) ⇒ <code>void</code>
+    * [~write(conn, data, onWrite)](#module_@openziti/ziti-sdk-nodejs..write) ⇒ <code>void</code>
+    * [~onDataCallback](#module_@openziti/ziti-sdk-nodejs..onDataCallback) : <code>function</code>
+    * [~onConnectCallback](#module_@openziti/ziti-sdk-nodejs..onConnectCallback) ⇒ <code>void</code>
+    * [~onRequestCallback](#module_@openziti/ziti-sdk-nodejs..onRequestCallback) ⇒ <code>void</code>
+    * [~onResonseCallback](#module_@openziti/ziti-sdk-nodejs..onResonseCallback) ⇒ <code>void</code>
+    * [~onResonseDataCallback](#module_@openziti/ziti-sdk-nodejs..onResonseDataCallback) ⇒ <code>void</code>
+    * [~onRequestDataCallback](#module_@openziti/ziti-sdk-nodejs..onRequestDataCallback) ⇒ <code>void</code>
+    * [~onServiceAvailableCallback](#module_@openziti/ziti-sdk-nodejs..onServiceAvailableCallback) ⇒ <code>void</code>
+    * [~onWriteCallback](#module_@openziti/ziti-sdk-nodejs..onWriteCallback) ⇒ <code>void</code>
+
+<a name="module_@openziti/ziti-sdk-nodejs..close"></a>
+
+### @openziti/ziti-sdk-nodejs~close(conn) ⇒ <code>void</code>
+Close a Ziti connection.
+
+**Kind**: inner method of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| conn | <code>number</code> | A Ziti connection handle. |
+
+<a name="module_@openziti/ziti-sdk-nodejs..dial"></a>
+
+### @openziti/ziti-sdk-nodejs~dial(serviceName, isWebSocket, onConnect, onData) ⇒ <code>void</code>
+Create a connection to Ziti Service.
+
+**Kind**: inner method of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| serviceName | <code>string</code> | The name of the Ziti Service to connect to |
+| isWebSocket | <code>boolean</code> | True or False indicator concerning whether this connection if bi-directional. |
+| onConnect | <code>onConnectCallback</code> | The callback that receives the connection handle. |
+| onData | <code>onDataCallback</code> | The callback that receives incoming data from the connection. |
+
+<a name="module_@openziti/ziti-sdk-nodejs..express"></a>
+
+### @openziti/ziti-sdk-nodejs~express(express, serviceName) ⇒ <code>\*</code>
+Wrap ExpressJS to facilitate hosting (listening) on a Ziti Service instead of a TCP port.
+
+**Kind**: inner method of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>\*</code> - The wrapped express() object.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| express | <code>\*</code> | The express() object. |
+| serviceName | <code>string</code> | The name of the Ziti Service being served (hosted). |
+
+<a name="module_@openziti/ziti-sdk-nodejs..httpRequest"></a>
+
+### @openziti/ziti-sdk-nodejs~httpRequest(serviceName, schemeHostPort, method, path, headers, onRequest, onResponse, onResponseData) ⇒ <code>void</code>
+Initiate an HTTP request to a Ziti Service.
+
+**Kind**: inner method of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| serviceName | <code>string</code> | The name of the Ziti Service to send the request. (mutually exclusive with url) |
+| schemeHostPort | <code>string</code> | The scheme/host/port (e.g. http://myserver.ziti:8080) of a Ziti service-config/intercept to send the request. (mutually exclusive with serviceName) |
+| method | <code>string</code> | The REST verb to use (e.g. `GET`, `POST`). |
+| path | <code>string</code> | The URL PATH to use on the request (can include HTTP query parms). |
+| headers | <code>Array.&lt;string&gt;</code> | The HTTP Headers to use on the request. |
+| onRequest | <code>onRequestCallback</code> | The callback that receives the request handle. |
+| onResponse | <code>onResonseCallback</code> | The callback that receives the HTTP Response. |
+| onResponseData | <code>onResonseDataCallback</code> | The callback that receives the HTTP Response data. |
+
+<a name="module_@openziti/ziti-sdk-nodejs..httpRequestData"></a>
+
+### @openziti/ziti-sdk-nodejs~httpRequestData(req, data, onRequestData) ⇒ <code>void</code>
+Send payload data for HTTP POST request to a Ziti Service.
+
+**Kind**: inner method of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| req | <code>number</code> | A Ziti HttpRequest handle. |
+| data | <code>Buffer</code> | The HTTP payload data to send. |
+| onRequestData | <code>onRequestDataCallback</code> | The callback that acknowleges the send. |
+
+<a name="module_@openziti/ziti-sdk-nodejs..httpRequestEnd"></a>
+
+### @openziti/ziti-sdk-nodejs~httpRequestEnd(req) ⇒ <code>void</code>
+Terminate payload data transmission for HTTP POST request to a Ziti Service.
+
+**Kind**: inner method of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| req | <code>number</code> | A Ziti HttpRequest handle. |
+
+<a name="module_@openziti/ziti-sdk-nodejs..init"></a>
+
+### @openziti/ziti-sdk-nodejs~init(identityPath) ⇒ <code>number</code>
+Initialize the Ziti session and authenticate with control plane.
+
+**Kind**: inner method of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>number</code> - A status value ranging from 0 to 255.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| identityPath | <code>string</code> | File system path to the identity file. |
+
+<a name="module_@openziti/ziti-sdk-nodejs..setLogLevel"></a>
+
+### @openziti/ziti-sdk-nodejs~setLogLevel(level) ⇒ <code>void</code>
+Set the logging level.
+
+**Kind**: inner method of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| level | <code>number</code> | 0=NONE, 1=ERROR, 2=WARN, 3=INFO, 4=DEBUG, 5=TRACE |
+
+<a name="module_@openziti/ziti-sdk-nodejs..serviceAvailable"></a>
+
+### @openziti/ziti-sdk-nodejs~serviceAvailable(serviceName, onServiceAvailable) ⇒ <code>void</code>
+Set the logging level.
+
+**Kind**: inner method of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| serviceName | <code>string</code> | The name of the Ziti Service being queried. |
+| onServiceAvailable | <code>onServiceAvailableCallback</code> | The callback that returns results of the query. |
+
+<a name="module_@openziti/ziti-sdk-nodejs..write"></a>
+
+### @openziti/ziti-sdk-nodejs~write(conn, data, onWrite) ⇒ <code>void</code>
+write data to a Ziti connection.
+
+**Kind**: inner method of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| conn | <code>number</code> | A Ziti connection handle. |
+| data | <code>Buffer</code> | The data to send. |
+| onWrite | <code>onWriteCallback</code> | The callback that returns status of the write. |
+
+<a name="module_@openziti/ziti-sdk-nodejs..onDataCallback"></a>
+
+### @openziti/ziti-sdk-nodejs~onDataCallback : <code>function</code>
+This callback is part of the `dial` API.
+
+**Kind**: inner typedef of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| conn | <code>number</code> | A Ziti connection handle. |
+
+<a name="module_@openziti/ziti-sdk-nodejs..onConnectCallback"></a>
+
+### @openziti/ziti-sdk-nodejs~onConnectCallback ⇒ <code>void</code>
+This callback is part of the `dial` API.
+
+**Kind**: inner typedef of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| data | <code>Buffer</code> | Incoming data from the Ziti connection. |
+
+<a name="module_@openziti/ziti-sdk-nodejs..onRequestCallback"></a>
+
+### @openziti/ziti-sdk-nodejs~onRequestCallback ⇒ <code>void</code>
+This callback is part of the `httpRequest` API.
+
+**Kind**: inner typedef of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| req | <code>number</code> | A Ziti HttpRequest handle. |
+
+<a name="module_@openziti/ziti-sdk-nodejs..onResonseCallback"></a>
+
+### @openziti/ziti-sdk-nodejs~onResonseCallback ⇒ <code>void</code>
+This callback is part of the `httpRequest` API.
+
+**Kind**: inner typedef of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Description |
+| --- | --- |
+| resp | Incoming response from the HTTP request. |
+| resp.req | The request handle. |
+| resp.code | The HTTP status code. |
+| resp.headers | The HTTP Headers on the response. |
+
+<a name="module_@openziti/ziti-sdk-nodejs..onResonseDataCallback"></a>
+
+### @openziti/ziti-sdk-nodejs~onResonseDataCallback ⇒ <code>void</code>
+This callback is part of the `httpRequest` API.
+
+**Kind**: inner typedef of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Description |
+| --- | --- |
+| respData | Incoming response data from the HTTP request. |
+| respData.req | The request handle. |
+| respData.len | The length of the response body. |
+| respData.body | The response body. |
+
+<a name="module_@openziti/ziti-sdk-nodejs..onRequestDataCallback"></a>
+
+### @openziti/ziti-sdk-nodejs~onRequestDataCallback ⇒ <code>void</code>
+This callback is part of the `httpRequestData` API.
+
+**Kind**: inner typedef of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Description |
+| --- | --- |
+| reqData | Incoming status data from the HTTP request. |
+| respData.req | The request handle. |
+| respData.status | positive value indicates successful transmit. |
+
+<a name="module_@openziti/ziti-sdk-nodejs..onServiceAvailableCallback"></a>
+
+### @openziti/ziti-sdk-nodejs~onServiceAvailableCallback ⇒ <code>void</code>
+This callback is part of the `serviceAvailable` API.
+
+**Kind**: inner typedef of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Description |
+| --- | --- |
+| availability | results of the query. |
+| availability.status | 0 means `available and OK`, <0 means `unavailable` |
+| availability.permissions | 1 means the identity can dial, 2 means the identity can bind |
+
+<a name="module_@openziti/ziti-sdk-nodejs..onWriteCallback"></a>
+
+### @openziti/ziti-sdk-nodejs~onWriteCallback ⇒ <code>void</code>
+This callback is part of the `write` API.
+
+**Kind**: inner typedef of [<code>@openziti/ziti-sdk-nodejs</code>](#module_@openziti/ziti-sdk-nodejs)  
+**Returns**: <code>void</code> - No return value.  
+
+| Param | Description |
+| --- | --- |
+| status | 0 means success, <0 means failure. |
+
+
+* * *

package/README.hbs

@@ -0,0 +1,227 @@
+<p align="center" width="100%">
+OpenZiti is a free and open source project focused on bringing zero trust to any application.
+     <br>
+The project provides all the pieces required to implement or integrate zero trust into your solutions.
+<br/>
+<br/>
+Please star us.
+<br/>
+<a href="https://github.com/openziti/ziti/stargazers"><img src="https://img.shields.io/github/stars/openziti/ziti?style=flat" ></a>
+<br/>
+     <br>
+</p>
+
+<p align="center" width="100%">
+<a href="https://openziti.io"><img src="ziti.png" width="100"></a>
+</p>
+
+<p align="center">
+    <b>
+    <a>@openziti/ziti-sdk-nodejs</a>
+    <br>
+    <br>
+    <b>
+    This repo hosts the OpenZiti SDK for NodeJS, and is designed to help you deliver secure applications over a <a href="https://openziti.io">OpenZiti Network</a>
+    <br>
+    <br>
+    <b>Part of the <a href="https://openziti.io/about">OpenZiti</a> ecosystem</b>
+</p>
+
+<p align="center">
+    <br>
+    <b>Are you interested in knowing how to easily embed programmable, high performance, zero trust networking into your NodeJS app, on any internet connection, without VPNs?
+    <br>
+    Learn more about our <a href="https://openziti.io/about">OpenZiti</a> project.</b>
+    <br>
+    </p>
+
+---
+[![Build Status](https://github.com/openziti/ziti-sdk-nodejs/workflows/Build/badge.svg?branch=main)]()
+[![Issues](https://img.shields.io/github/issues-raw/openziti/ziti-sdk-nodejs)]()
+[![npm version](https://badge.fury.io/js/@openziti%2Fziti-sdk-nodejs.svg)](https://badge.fury.io/js/@openziti%2Fziti-sdk-nodejs.svg)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![LOC](https://img.shields.io/tokei/lines/github/openziti/ziti-sdk-nodejs)]()
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=rounded)](CONTRIBUTING.md)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)
+
+---
+
+# Associated Article(s)
+For more context on this SDK, you may be interested in this
+[article concerning how to secure NodeJS applications](https://openziti.io/securing-nodejs-applications)
+
+
+
+# Supported platforms
+
+The `@openziti/ziti-sdk-nodejs` module works with the following Node.js versions:
+- v12.x
+- v13.x
+- v14.x
+- v15.x
+- v16.x
+- v17.x
+- v18.x
+
+Binaries for most Node versions and platforms are provided by default via [@mapbox/node-pre-gyp](https://github.com/mapbox/node-pre-gyp).
+
+# Installing
+
+NPM
+``` js
+npm i @openziti/ziti-sdk-nodejs
+```
+or Yarn
+``` js
+yarn add @openziti/ziti-sdk-nodejs
+```
+
+Special note on previous package:
+
+On June 7, 2020 @openziti/ziti-sdk-nodejs@0.6.0 was released. Older, unscoped versions that are not part of the @openziti org are deprecated and only @openziti/ziti-sdk-nodejs will see updates going forward. To upgrade to the new package do:
+
+``` js
+npm uninstall ziti-sdk-nodejs --save
+npm install @openziti/ziti-sdk-nodejs --save
+```
+
+# Usage
+
+**Note:** the module must be [installed](#installing) before use.
+
+ESM example (client-side)
+``` js
+import ziti from '@openziti/ziti-sdk-nodejs';
+
+// Somehow provide path to identity file, e.g. via env var
+const zitiIdentityFile  = process.env.ZITI_IDENTITY_FILE;
+// Authenticate ourselves onto the Ziti network
+await ziti.init( zitiIdentityFile ).catch(( err ) => { /* probably exit */ });
+
+const on_resp_data = ( obj ) => {
+    console.log(`response is: ${obj.body.toString('utf8')}`);
+};
+
+// Perform an HTTP GET request to a dark OpenZiti web service
+ziti.httpRequest(
+  'myDarkWebService',            // OpenZiti Service name or HTTP origin part of the URL
+  'GET',
+  '/',                           // path part of the URL including query params
+  ['Accept: application/json' ], // headers
+  undefined,                     // optional on_req cb 
+  undefined,                     // optional on_req_data cb
+  on_resp_data                   // optional on_resp_data cb
+);
+
+```
+
+ESM example (server-side ExpressJS)
+``` js
+import ziti from '@openziti/ziti-sdk-nodejs';
+import express from 'express';
+let app = ziti.express( express, zitiServiceName );
+app.listen(ignored, function() { ... }
+
+/**
+
+That's right.
+
+With only a single-line code change (the ziti.express call), your web server is now capable
+of being invisible to malicious attackers on the internet, and only accessible to your 
+trusted remote users.
+
+Nothing else in your existing ExpressJS web server code needs to change!
+
+Existing routing, middleware, etc., all operates the same as it always did... 
+but now you enjoy the comfort of knowing that if a connection comes in, it is from 
+a trusted identity on the client side.
+
+No malicious actors can see your dark web server, and thus, no malicious actors can attack it.
+
+*/
+```
+
+CJS example (client-side)
+``` js
+var ziti = require('@openziti/ziti-sdk-nodejs');
+
+const ziti_init = async (identity) => {
+    return new Promise((resolve) => {
+        ziti.ziti_init(identity, () => {
+            resolve();
+        });
+    });
+};
+
+const ziti_service_available = (service) => {
+    return new Promise((resolve) => {
+        ziti.ziti_service_available(service, (status) => {
+            resolve(status);
+        });
+    });
+};
+
+function ziti_dial(service) {
+    return new Promise((resolve, reject) => {
+        ziti.ziti_dial(
+            service,
+            (conn) => {
+                resolve(conn);
+            },
+            (data) => {
+                // Do something with data...
+            },
+        );
+    });
+}
+
+const ziti_write = (conn, data) => {
+    return new Promise((resolve) => {
+        ziti.ziti_write(conn, data, () => {
+            resolve();
+        });
+    });
+};
+
+(async () => {
+
+    await ziti_init(LOCATION_OF_IDENTITY_FILE);
+
+    let status = await ziti_service_available(YOUR_SERVICE_NAME);
+
+    if (status === 0) {
+
+        const conn = await ziti_dial(YOUR_SERVICE_NAME);
+
+        let data = SOME_KIND_OF_DATA;
+
+        let buffer = Buffer.from(data);
+
+        await ziti_write(conn, buffer);
+
+        ...etc
+    }
+
+})();
+```
+
+# API Reference
+{{#module name="@openziti/ziti-sdk-nodejs"}}
+{{>body~}}
+{{>member-index~}}
+{{>separator~}}
+{{>members~}}
+{{/module}}
+
+* * *
+
+Getting Help
+------------
+Please use these community resources for getting help. We use GitHub [issues](https://github.com/openziti/ziti-sdk-nodejs/issues) 
+for tracking bugs and feature requests and have limited bandwidth to address them.
+
+- Read the [docs](https://openziti.github.io/ziti/overview.html)
+- Participate in discussion on [Discourse](https://openziti.discourse.group/)
+
+
+Copyright&copy;  NetFoundry, Inc.

package/README.md

@@ -104,13 +104,13 @@ const on_resp_data = ( obj ) => {
 
 // Perform an HTTP GET request to a dark OpenZiti web service
 ziti.httpRequest(
-  'myDarkWebService', 
-  'GET', 
-  '/',              // path
+  'myDarkWebService',            // OpenZiti Service name or HTTP origin part of the URL
+  'GET',
+  '/',                           // path part of the URL including query params
   ['Accept: application/json' ], // headers
-  undefined,        // optional on_req cb 
-  undefined,        // optional on_req_data cb
-  on_resp_data      // optional on_resp_data cb
+  undefined,                     // optional on_req cb 
+  undefined,                     // optional on_req_data cb
+  on_resp_data                   // optional on_resp_data cb
 );
 
 ```
@@ -205,33 +205,9 @@ const ziti_write = (conn, data) => {
 })();
 ```
 
-
-# Ziti NodeJS SDK - Setup for Development
-
-NOTE: You don't need to compile this SDK in order to use it (we publish pre-built binaries for your OS, NodeJS version, and CPU architecture).
-The following information applies only if you are doing development on the SDK itself.
-
-The following steps should get your NodeJS SDK for Ziti building. The Ziti NodeJS SDK is a native addon for Node JS,
-and is written in C. C development is specific to your operating system and tool chain used. These steps should work 
-properly for you but if your OS has variations you may need to adapt these steps accordingly.
-
-
-## Prerequisites
-
-### Build
-
-* [Cmake (3.12+)](https://cmake.org/install/)
-
-
-## Build
-
-### Linux/MacOS
-
-Building the NodeJS SDK on linux/mac can be accomplished with:
-
-```bash
-$ npm run build
-```
+# API Reference
+For doc concerning API's contained in this SDK, you may be interested in this
+[SDK API Reference](API_REFERENCE.md)
 
 
 Getting Help

package/jsdoc.json

@@ -0,0 +1,24 @@
+{
+    "tags": {
+        "allowUnknownTags": false
+    },
+    "source": {
+        "include": "./lib",
+        "includePattern": "\\.js$",
+        "excludePattern": "(node_modules/|docs)"
+    },
+    "plugins": [
+        "plugins/markdown"
+    ],
+    "opts": {
+        "template": "node_modules/docdash",
+        "encoding": "utf8",
+        "destination": "docs/",
+        "recurse": true,
+        "verbose": true
+    },
+    "templates": {
+        "cleverLinks": false,
+        "monospaceLinks": false
+    }
+}

package/lib/close.js

@@ -20,7 +20,7 @@ limitations under the License.
  * 
  * @param {*} conn 
  */
-const close = ( conn,  ) => {
+const close = ( conn ) => {
 
   ziti.ziti_close( conn );
 

package/lib/express-listener.js

@@ -85,7 +85,6 @@ Server.prototype.on_listen = ( status ) => {
 /**
  * 
  * @param {*} args 
- * @returns 
  */
 function normalizeArgs(args) {
     let arr;

package/lib/httpRequest.js

@@ -46,9 +46,7 @@ const on_resp_data = ( obj ) => {
 
 };
 
-const httpRequest = ( url, method, path, headers, on_req_cb, on_resp_cb, on_resp_data_cb ) => {
-
-    console.log('httpRequest entered: ', url, method, headers);
+const httpRequest = ( serviceName, schemeHostPort, method, path, headers, on_req_cb, on_resp_cb, on_resp_data_cb ) => {   
 
     let _on_req_cb;
     let _on_resp_cb;
@@ -72,7 +70,7 @@ const httpRequest = ( url, method, path, headers, on_req_cb, on_resp_cb, on_resp
         _on_resp_data_cb = on_resp_data_cb;
     }
 
-    ziti.Ziti_http_request( url, method, path, headers, _on_req_cb, _on_resp_cb, _on_resp_data_cb );
+    ziti.Ziti_http_request( serviceName, schemeHostPort, method, path, headers, _on_req_cb, _on_resp_cb, _on_resp_data_cb );
 
 };
 

package/lib/httpRequestEnd.js

@@ -0,0 +1,23 @@
+/*
+Copyright Netfoundry, Inc.
+
+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
+
+https://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.
+*/
+
+
+const httpRequestEnd = ( req ) => {
+    ziti.Ziti_http_request_end( req );
+};
+
+exports.httpRequestEnd = httpRequestEnd;
+

package/lib/init.js

@@ -15,23 +15,14 @@ limitations under the License.
 */
 
 
-/**
- * init()   
- * 
- * @param {*} identityPath 
- * @returns 
- */
-const init = ( identityPath ) => {
+ const init = ( identityPath ) => {
 
   return new Promise((resolve, reject) => {
 
       let rc = ziti.ziti_init( identityPath, ( result ) => {
 
-        setTimeout( () => {
-
           return resolve( result );
         
-        }, 1000);
       });
 
       if (rc < 0) {

package/lib/listen.js

@@ -19,7 +19,6 @@ limitations under the License.
  * listen()   
  * 
  * @param {*} identityPath 
- * @returns 
  */
 const listen = ( serviceName, js_arb_data, on_listen, on_listen_client, on_client_connect, on_client_data ) => {
 

package/lib/ziti.js

@@ -14,6 +14,13 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+/**
+ * OpenZiti SDK for Node.js
+ * 
+ * @module @openziti/ziti-sdk-nodejs
+ * 
+ */
+
 var binding;
 
 function importAll (r) {
@@ -43,13 +50,160 @@ ziti = module.exports = exports = binding;
 /**
  *  Attach the external, app-facing, API to the 'ziti' object
  */
+
+/**
+ * Close a Ziti connection.
+ * @function close
+ * @param {number} conn - A Ziti connection handle.
+ * @returns {void} No return value.
+ */
 exports.close             = require('./close').close;
+
+/**
+ * Create a connection to Ziti Service.
+ * @async
+ * @function dial
+ * @param {string} serviceName - The name of the Ziti Service to connect to
+ * @param {boolean} isWebSocket - True or False indicator concerning whether this connection if bi-directional.
+ * @param {onConnectCallback} onConnect - The callback that receives the connection handle.
+ * @param {onDataCallback} onData - The callback that receives incoming data from the connection.
+ * @returns {void} No return value.
+ */
+/**
+ * This callback is part of the `dial` API.
+ * @callback onDataCallback - The callback that receives the connection handle.
+ * @param {number} conn - A Ziti connection handle.
+ */
+/**
+ * This callback is part of the `dial` API.
+ * @callback onConnectCallback - The callback that receives incoming data from the connection.
+ * @param {Buffer} data - Incoming data from the Ziti connection.
+ * @returns {void} No return value.
+ */
 exports.dial              = require('./dial').dial;
+
+/**
+ * Wrap ExpressJS to facilitate hosting (listening) on a Ziti Service instead of a TCP port.
+ * @function express
+ * @param {*} express - The express() object.
+ * @param {string} serviceName - The name of the Ziti Service being served (hosted).
+ * @returns {*} The wrapped express() object.
+ */
 exports.express           = require('./express').express;
+
+/**
+ * Initiate an HTTP request to a Ziti Service.
+ * @function httpRequest
+ * @param {string} serviceName - The name of the Ziti Service to send the request. (mutually exclusive with url)
+ * @param {string} schemeHostPort - The scheme/host/port (e.g. http://myserver.ziti:8080) of a Ziti service-config/intercept to send the request. (mutually exclusive with serviceName)
+ * @param {string} method - The REST verb to use (e.g. `GET`, `POST`).
+ * @param {string} path - The URL PATH to use on the request (can include HTTP query parms).
+ * @param {string[]} headers - The HTTP Headers to use on the request.
+ * @param {onRequestCallback} onRequest - The callback that receives the request handle.
+ * @param {onResonseCallback} onResponse - The callback that receives the HTTP Response.
+ * @param {onResonseDataCallback} onResponseData - The callback that receives the HTTP Response data.
+ * @returns {void} No return value.
+ */
+/**
+ * This callback is part of the `httpRequest` API.
+ * @callback onRequestCallback - The callback that receives the request handle.
+ * @param {number} req - A Ziti HttpRequest handle.
+ * @returns {void} No return value.
+ */
+/**
+ * This callback is part of the `httpRequest` API.
+ * @callback onResonseCallback - The callback that receives response from the request.
+ * @param resp - Incoming response from the HTTP request.
+ * @param resp.req - The request handle.
+ * @param resp.code - The HTTP status code.
+ * @param resp.headers - The HTTP Headers on the response.
+ * @returns {void} No return value.
+ */
+/**
+ * This callback is part of the `httpRequest` API.
+ * @callback onResonseDataCallback - The callback that receives incoming data from the request.
+ * @param respData - Incoming response data from the HTTP request.
+ * @param respData.req - The request handle.
+ * @param respData.len - The length of the response body.
+ * @param respData.body - The response body.
+ * @returns {void} No return value.
+ */
 exports.httpRequest       = require('./httpRequest').httpRequest;
-exports.httpRequestData   = require('./httpRequestData').httpRequestData;
+
+/**
+ * Send payload data for HTTP POST request to a Ziti Service.
+ * @function httpRequestData
+ * @param {number} req - A Ziti HttpRequest handle.
+ * @param {Buffer} data - The HTTP payload data to send.
+ * @param {onRequestDataCallback} onRequestData - The callback that acknowleges the send.
+ * @returns {void} No return value.
+ */
+/**
+ * This callback is part of the `httpRequestData` API.
+ * @callback onRequestDataCallback - The callback that acknowleges the send.
+ * @param reqData - Incoming status data from the HTTP request.
+ * @param respData.req - The request handle.
+ * @param respData.status - positive value indicates successful transmit.
+ * @returns {void} No return value.
+*/
+ exports.httpRequestData   = require('./httpRequestData').httpRequestData;
+
+/**
+ * Terminate payload data transmission for HTTP POST request to a Ziti Service.
+ * @function httpRequestEnd
+ * @param {number} req - A Ziti HttpRequest handle.
+ * @returns {void} No return value.
+ */
+ exports.httpRequestEnd   = require('./httpRequestEnd').httpRequestEnd;
+
+/**
+ * Initialize the Ziti session and authenticate with control plane.
+ * @function init
+ * @param {string} identityPath - File system path to the identity file.
+ * @returns {number} A status value ranging from 0 to 255.
+ */
 exports.init              = require('./init').init;
+
+// Internal use only
 exports.listen            = require('./listen').listen;
+
+/**
+ * Set the logging level.
+ * @function setLogLevel
+ * @param {number} level - 0=NONE, 1=ERROR, 2=WARN, 3=INFO, 4=DEBUG, 5=TRACE
+ * @returns {void} No return value.
+ */
 exports.setLogLevel       = require('./setLogLevel').setLogLevel;
+
+/**
+ * Set the logging level.
+ * @function serviceAvailable
+ * @param {string} serviceName - The name of the Ziti Service being queried.
+ * @param {onServiceAvailableCallback} onServiceAvailable - The callback that returns results of the query.
+ * @returns {void} No return value.
+ */
+/**
+ * This callback is part of the `serviceAvailable` API.
+ * @callback onServiceAvailableCallback - The callback that returns results of the query.
+ * @param availability - results of the query.
+ * @param availability.status - 0 means `available and OK`, <0 means `unavailable`
+ * @param availability.permissions - 1 means the identity can dial, 2 means the identity can bind
+ * @returns {void} No return value.
+ */
 exports.serviceAvailable  = require('./serviceAvailable').serviceAvailable;
-exports.write             = require('./write').write;
+
+/**
+ * write data to a Ziti connection.
+ * @function write
+ * @param {number} conn - A Ziti connection handle.
+ * @param {Buffer} data - The data to send.
+ * @param {onWriteCallback} onWrite - The callback that returns status of the write.
+ * @returns {void} No return value.
+ */
+/**
+ * This callback is part of the `write` API.
+ * @callback onWriteCallback - The callback that returns results of the v.
+ * @param status - 0 means success, <0 means failure.
+ * @returns {void} No return value.
+ */
+ exports.write             = require('./write').write;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openziti/ziti-sdk-nodejs",
   "description": "A NodeJS-based SDK for delivering secure applications over a Ziti Network",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "main": "./lib/ziti",
   "scripts": {
     "build": "npm run build:init; npm run build:c-sdk; npm install --build-from-source --clang=1",
@@ -16,7 +16,8 @@
     "start": "node main.js ./config/identity.json chapel-hill",
     "install": "node-pre-gyp install --fallback-to-build",
     "install-dbg": "npm install --build-from-source --clang=1 --debug",
-    "publish": "node-pre-gyp package publish"
+    "publish": "node-pre-gyp package publish",
+    "docs": "jsdoc2md -t API_REFERENCE.hbs lib/*.js > API_REFERENCE.md"
   },
   "repository": {
     "type": "git",
@@ -48,7 +49,10 @@
     "url": "http://netfoundry.io"
   },
   "devDependencies": {
-    "aws-sdk": "^2.823.0"
+    "aws-sdk": "^2.823.0",
+    "docdash": "^1.2.0",
+    "jsdoc": "^3.6.11",
+    "jsdoc-to-markdown": "^7.1.1"
   },
   "dependencies": {
     "@mapbox/node-pre-gyp": "^1.0.8"

package/src/Ziti_https_request.c

@@ -726,9 +726,9 @@ void on_client(uv_work_t* req, int status) {
 /**
  * Initiate an HTTPS request
  * 
- * @param {string}   [0] serviceName | URL
+ * @param {string}   [0] serviceName | url         Ziti service name or HTTP origin
  * @param {string}   [1] method
- * @param {string}   [2] path
+ * @param {string}   [2] path                      path part of the URL including query params
  * @param {string[]} [3] headers;                  Array of strings of the form "name:value"
  * @param {func}     [4] JS on_req  callback;      This is invoked from 'on_client' function above
  * @param {func}     [5] JS on_resp callback;      This is invoked from 'on_resp' function above
@@ -750,15 +750,15 @@ napi_value _Ziti_http_request(napi_env env, const napi_callback_info info) {
     HttpsClientListMap = newListMap();
   }
 
-  size_t argc = 7;
-  napi_value args[7];
+  size_t argc = 8;
+  napi_value args[8];
   status = napi_get_cb_info(env, info, &argc, args, NULL, NULL);
   if (status != napi_ok) {
     napi_throw_error(env, NULL, "Failed to parse arguments");
     return NULL;
   }
 
-  if (argc < 7) {
+  if (argc < 8) {
     napi_throw_error(env, "EINVAL", "Too few arguments");
     return NULL;
   }
@@ -767,39 +767,86 @@ napi_value _Ziti_http_request(napi_env env, const napi_callback_info info) {
   ZITI_NODEJS_LOG(DEBUG, "allocated addon_data : %p", addon_data);
   addon_data->env = env;
 
-  // Obtain serviceName length
-  size_t serviceName_len;
-  status = napi_get_value_string_utf8(env, args[0], NULL, 0, &serviceName_len);
-  if (status != napi_ok) {
-    napi_throw_error(env, "EINVAL", "serviceName is not a string");
-    return NULL;
+  bool serviceNameSpecified = false;
+
+  // Determine if the serviceName arg was specified
+  napi_valuetype valuetype;
+  status = napi_typeof(env, args[0], &valuetype);
+  if (valuetype != napi_undefined) {
+    ZITI_NODEJS_LOG(DEBUG, "serviceName is specified");
+    serviceNameSpecified = true;
   }
 
-  // Obtain serviceName
-  char* serviceName = calloc(1, serviceName_len+2);
-  status = napi_get_value_string_utf8(env, args[0], serviceName, serviceName_len+1, &result);
-  if (status != napi_ok) {
-    napi_throw_error(env, "EINVAL", "Failed to obtain serviceName");
+  bool schemeHostPortSpecified = false;
+
+  // Determine if the schemeHostPort arg was specified
+  status = napi_typeof(env, args[1], &valuetype);
+  if (valuetype != napi_undefined) {
+    ZITI_NODEJS_LOG(DEBUG, "schemeHostPort is specified");
+    schemeHostPortSpecified = true;
+  }
+
+  if (serviceNameSpecified && schemeHostPortSpecified) {
+    napi_throw_error(env, "EINVAL", "both serviceName and schemeHostPort were specified; they are mutually exclusive");
+    return NULL;
+  }
+  if (!serviceNameSpecified && !schemeHostPortSpecified) {
+    napi_throw_error(env, "EINVAL", "both serviceName and schemeHostPort were unspecified; must specify one");
     return NULL;
   }
 
-  bool haveURL = false;
-  struct http_parser_url url_parse = {0};
-  rc = http_parser_parse_url(serviceName, strlen(serviceName), false, &url_parse);
-  if (rc == 0) {
-    haveURL = true;
-    ZITI_NODEJS_LOG(DEBUG, "serviceName IS a URL");
-  } else {
-    ZITI_NODEJS_LOG(DEBUG, "serviceName is NOT a URL");
+  char* serviceName;
+
+  if (serviceNameSpecified) {
+    // Obtain serviceName length
+    size_t serviceName_len;
+    status = napi_get_value_string_utf8(env, args[0], NULL, 0, &serviceName_len);
+    if (status != napi_ok) {
+      napi_throw_error(env, "EINVAL", "serviceName is not a string");
+      return NULL;
+    }
+
+    // Obtain serviceName
+    serviceName = calloc(1, serviceName_len+2);
+    status = napi_get_value_string_utf8(env, args[0], serviceName, serviceName_len+1, &result);
+    if (status != napi_ok) {
+      napi_throw_error(env, "EINVAL", "Failed to obtain serviceName");
+      return NULL;
+    }
   }
 
-  struct hostname_port* hostname_port = NULL;
+  char* schemeHostPort;
 
-  if (haveURL) {
+  if (schemeHostPortSpecified) {
+    // Obtain schemeHostPort length
+    size_t schemeHostPort_len;
+    status = napi_get_value_string_utf8(env, args[1], NULL, 0, &schemeHostPort_len);
+    if (status != napi_ok) {
+      napi_throw_error(env, "EINVAL", "schemeHostPort is not a string");
+      return NULL;
+    }
 
-    addon_data->scheme_host_port = strdup(serviceName);
+    // Obtain schemeHostPort
+    schemeHostPort = calloc(1, schemeHostPort_len+2);
+    status = napi_get_value_string_utf8(env, args[1], schemeHostPort, schemeHostPort_len+1, &result);
+    if (status != napi_ok) {
+      napi_throw_error(env, "EINVAL", "Failed to obtain schemeHostPort");
+      return NULL;
+    }
+  
+    struct http_parser_url url_parse = {0};
+    rc = http_parser_parse_url(schemeHostPort, strlen(schemeHostPort), false, &url_parse);
+    if (rc != 0) {
+      napi_throw_error(env, "EINVAL", "schemeHostPort is not a valid URL");
+      return NULL;
+    }
 
-  } else {
+    addon_data->scheme_host_port = strdup(schemeHostPort);
+    addon_data->haveURL = true;
+
+  } else if (serviceNameSpecified) {
+
+    struct hostname_port* hostname_port = NULL;
 
     hostname_port = getHostnamePortForService(serviceName);
     if (NULL == hostname_port) {
@@ -825,20 +872,18 @@ napi_value _Ziti_http_request(napi_env env, const napi_callback_info info) {
     }
   }
 
-  addon_data->haveURL = haveURL;
-
-  ZITI_NODEJS_LOG(DEBUG, "scheme_host_port: %s, haveURL: %d", addon_data->scheme_host_port, haveURL);
+  ZITI_NODEJS_LOG(DEBUG, "scheme_host_port: %s, haveURL: %d", addon_data->scheme_host_port, addon_data->haveURL);
 
   // Obtain method length
   size_t method_len;
-  status = napi_get_value_string_utf8(env, args[1], NULL, 0, &method_len);
+  status = napi_get_value_string_utf8(env, args[2], NULL, 0, &method_len);
   if (status != napi_ok) {
     napi_throw_error(env, "EINVAL", "method is not a string");
     return NULL;
   }
   // Obtain method
   addon_data->method = calloc(1, method_len+2);
-  status = napi_get_value_string_utf8(env, args[1], addon_data->method, method_len+1, &result);
+  status = napi_get_value_string_utf8(env, args[2], addon_data->method, method_len+1, &result);
   if (status != napi_ok) {
     napi_throw_error(env, "EINVAL", "Failed to obtain method");
     return NULL;
@@ -848,14 +893,14 @@ napi_value _Ziti_http_request(napi_env env, const napi_callback_info info) {
 
   // Obtain path length
   size_t path_len;
-  status = napi_get_value_string_utf8(env, args[2], NULL, 0, &path_len);
+  status = napi_get_value_string_utf8(env, args[3], NULL, 0, &path_len);
   if (status != napi_ok) {
     napi_throw_error(env, "EINVAL", "path is not a string");
     return NULL;
   }
   // Obtain path
   addon_data->path = calloc(1, path_len+2);
-  status = napi_get_value_string_utf8(env, args[2], addon_data->path, path_len+1, &result);
+  status = napi_get_value_string_utf8(env, args[3], addon_data->path, path_len+1, &result);
   if (status != napi_ok) {
     napi_throw_error(env, "EINVAL", "Failed to obtain path");
     return NULL;
@@ -864,7 +909,7 @@ napi_value _Ziti_http_request(napi_env env, const napi_callback_info info) {
   ZITI_NODEJS_LOG(DEBUG, "path: %s", addon_data->path);
 
   // Obtain ptr to JS on_req callback function
-  napi_value js_cb = args[4];
+  napi_value js_cb = args[5];
   napi_value work_name;
 
 
@@ -901,7 +946,7 @@ napi_value _Ziti_http_request(napi_env env, const napi_callback_info info) {
   ZITI_NODEJS_LOG(DEBUG, "napi_create_threadsafe_function addon_data->tsfn_on_req() : %p", addon_data->tsfn_on_req);
 
   // Obtain ptr to JS on_resp callback function
-  napi_value js_cb2 = args[5];
+  napi_value js_cb2 = args[6];
 
   // Create a string to describe this asynchronous operation.
   rc = napi_create_string_utf8(env, "on_resp", NAPI_AUTO_LENGTH, &work_name);
@@ -933,7 +978,7 @@ napi_value _Ziti_http_request(napi_env env, const napi_callback_info info) {
 
 
   // Obtain ptr to JS on_resp_data callback function
-  napi_value js_cb3 = args[6];
+  napi_value js_cb3 = args[7];
 
   // Create a string to describe this asynchronous operation.
   rc = napi_create_string_utf8(env, "on_resp_data", NAPI_AUTO_LENGTH, &work_name);
@@ -967,7 +1012,7 @@ napi_value _Ziti_http_request(napi_env env, const napi_callback_info info) {
   // Capture headers
   //
   uint32_t i;
-  status = napi_get_array_length(env, args[3], &addon_data->headers_array_length);
+  status = napi_get_array_length(env, args[4], &addon_data->headers_array_length);
   if (status != napi_ok) {
     napi_throw_error(env, "EINVAL", "Failed to obtain headers array");
     return NULL;
@@ -976,7 +1021,7 @@ napi_value _Ziti_http_request(napi_env env, const napi_callback_info info) {
   for (i = 0; i < addon_data->headers_array_length; i++) {
 
     napi_value headers_array_element;
-    status = napi_get_element(env, args[3], i, &headers_array_element);
+    status = napi_get_element(env, args[4], i, &headers_array_element);
     if (status != napi_ok) {
       napi_throw_error(env, "EINVAL", "Failed to obtain headers element");
       return NULL;

package/src/ziti_init.c

@@ -21,6 +21,8 @@ ziti_context ztx = NULL;
 typedef struct {
   napi_async_work work;
   napi_threadsafe_function tsfn;
+  int zitiContextEventStatus;
+  bool on_init_cb_invoked;
 } AddonData;
 
 
@@ -129,16 +131,8 @@ static void on_ziti_event(ziti_context _ztx, const ziti_event_t *event) {
           ZITI_NODEJS_LOG(ERROR, "Failed to connect to controller: %s", event->event.ctx.err);
       }
 
-      // Initiate the call into the JavaScript callback. 
-      // The call into JavaScript will not have happened 
-      // when this function returns, but it will be queued.
-      nstatus = napi_call_threadsafe_function(
-          addon_data->tsfn,
-          (void*) (long) event->event.ctx.ctrl_status,
-          napi_tsfn_blocking);
-      if (nstatus != napi_ok) {
-        ZITI_NODEJS_LOG(ERROR, "Unable to napi_call_threadsafe_function");
-      }
+      addon_data->zitiContextEventStatus = event->event.ctx.ctrl_status;
+
       break;
 
     case ZitiServiceEvent:
@@ -223,6 +217,15 @@ static void on_ziti_event(ziti_context _ztx, const ziti_event_t *event) {
         free(intercept);
       }
 
+      // Initiate the call into the JavaScript 'on_init' callback, now that we know about all the services
+      ZITI_NODEJS_LOG(DEBUG, "addon_data->on_init_cb_invoked %o", addon_data->on_init_cb_invoked);
+      if (!addon_data->on_init_cb_invoked) {
+        nstatus = napi_call_threadsafe_function(
+            addon_data->tsfn,
+            (void*) (long) addon_data->zitiContextEventStatus,
+            napi_tsfn_blocking);
+        addon_data->on_init_cb_invoked = true;
+      }
 
       break;
 
@@ -293,7 +296,7 @@ napi_value _ziti_init(napi_env env, const napi_callback_info info) {
   // Obtain ptr to JS callback function
   napi_value js_cb = args[1];
   napi_value work_name;
-  AddonData* addon_data = malloc(sizeof(AddonData));
+  AddonData* addon_data = calloc(1, sizeof(AddonData));
 
   // Create a string to describe this asynchronous operation.
   status = napi_create_string_utf8(