Merge pull request #147 from jwulf/grpc-js

Grpc js
v0.23.0-alpha.3 release

.npmignore

@@ -0,0 +1,6 @@
+.github
+.circleci
+guide
+src
+design
+docs

CHANGELOG.md

@@ -1,4 +1,4 @@
-# Version 0.23.0-alpha.2
+# Version 0.23.0-alpha.3
 
 ## Breaking Changes
 
@@ -11,20 +11,24 @@ _Changes in APIs or behaviour that may affect existing applications that use zee
 
 _New shiny stuff._
 
+-   The underlying gRPC implementation has been switched to the pure JS @grpc/grpc-js. This means no more dependency on node-gyp or binary rebuilds for Docker containers / Electron; and a slim-down in the installed package size from 50MB to 27MB.
 -   Timeouts can now be expressed with units using the [typed-duration](https://www.npmjs.com/package/typed-duration) package, which is included in and re-exported by the library. See the README section "A note on representing timeout durations".
 -   There is a new `ZBBatchWorker`. This allows you to batch jobs that are unrelated in a BPMN model, but are related with respect to some (for example: rate-limited) external system. See the README for details. Thanks to Jimmy Beaudoin ([@jbeaudoin11](https://github.com/jbeaudoin11)) for the suggestion, and helping with the design. Ref: [#134](https://github.com/creditsenseau/zeebe-client-node-js/issues/134).
 -   `ZBClient.createWorker` has two new, additional, method signature. The first is a single object parameter signature. This is the preferred signature if you are passing in configuration options. The second signature is a version of the original that elides the `id` for the worker. With this, you can create a worker with just a task type and a job handler. A UUID is assigned as the worker id. This is the equivalent of passing in `null` as the first parameter to the original signature. The previous method signature still works, allowing you to specify an id if you want. See [this article for details](https://www.joshwulf.com/blog/2020/02/refining-method-signature/).
 -   There is now a `ZBLogMessage` interface to help you implement a custom logger [#127](https://github.com/creditsenseau/zeebe-client-node-js/issues/127). For an example of a custom logger, see the [Zeebe GitHub Action implementation](https://github.com/jwulf/zeebe-action/blob/master/src/log/logger.ts).
 -   There is new custom logger implementation `ZBSimpleLogger` that produces flat string output. If you are not interested in structured logs for analysis, this log is easier for humans to read.
 -   `ZBClient` now contains an `activateJobs` method. This effectively exposes the entire Zeebe GRPC API, and allows you to write applications in the completely unmanaged style of the Java and Go libraries, if you have some radically different idea about application patterns.
--   The Grpc layer has been refactored to implement the idea of "connection characteristics". When connecting to Camunda Cloud, which uses TLS and OAuth, the library would emit errors every time. The refactor allows these connection errors to be correctly interpreted as expected behaviour of the "connection characteristics". See [this article](https://www.joshwulf.com/blog/2020/03/camunda-cloud-connection-2/) and [#133](https://github.com/creditsenseau/zeebe-client-node-js/issues/133) for more details.
+-   The Grpc layer has been refactored to implement the idea of "connection characteristics". When connecting to Camunda Cloud, which uses TLS and OAuth, the library would emit errors every time. The refactor allows these connection errors to be correctly interpreted as expected behaviour of the "connection characteristics". You can also set an explicit initial connection tolerance in milliseconds for any broker connection with the environment variable `ZEEBE_INITIAL_CONNECTION_TOLERANCE`. See [this article](https://www.joshwulf.com/blog/2020/03/camunda-cloud-connection-2/), issue [#133](https://github.com/creditsenseau/zeebe-client-node-js/issues/133), and the README section "Initial Connection Tolerance" for more details.
+-   The connection tolerance for transient drop-outs before reporting a connection error is now configurable via the environment variable `ZEEBE_CONNECTION_TOLERANCE`, as well as the previous constructor argument `connectionTolerance`.
+-   The integration tests have been refactored to allow them to run against Camunda Cloud. This required dealing with a Zeebe broker in an unknown state, so all tests now template unique process ids, unique task types, and unique message names to avoid previous test run state in the cluster interfering with subsequent test runs.
 -   I've started documenting the internal operation of the client in BPMN diagrams. These can be found in the `design` directory.
 -   The README now contains a section "Writing Strongly-typed Job Workers", on writing typed workers in TypeScript.
 -   The README also has a shiny TOC. It has grown in size such that one is needed.
 
 ## Fixes
 
--   An unmaintained package in the dependency tree of kafka-node (and probably a bug in NPM's de-duping algorithm) caused zeebe-node to break by installing the wrong version of the `long` dependency, unless the two packages were installed in a specific order. We've explicitly added `long` to the dependencies of zeebe-node to address this, and [reported it to kafka-node](https://github.com/SOHU-Co/kafka-node/issues/1332). Thanks to [@need4eat](https://github.com/need4eat) for discovering this and helping to track down the cause. See [#124](https://github.com/creditsenseau/zeebe-client-node-js/issues/124).
+-   An unmaintained package in the dependency tree of kafka-node (and arguably a bug in NPM's de-duping algorithm) caused zeebe-node to break by installing the wrong version of the `long` dependency, unless the two packages were installed in a specific order. We've explicitly added `long` to the dependencies of zeebe-node to address this, and [reported it to kafka-node](https://github.com/SOHU-Co/kafka-node/issues/1332). Thanks to [@need4eat](https://github.com/need4eat) for discovering this and helping to track down the cause. See [#124](https://github.com/creditsenseau/zeebe-client-node-js/issues/124).
+-   Prior to 0.23.0-alpha.2 of the zeebe-node client, workers would not reconnect if the broker was restarted, throwing gRPC channel errors until they were restarted. The workers will now automatically reconnect when the broker is available, if it goes away and comes back. See [#145](https://github.com/creditsenseau/zeebe-client-node-js/issues/145)
 
 # Version 0.22.1
 

README.md

@@ -30,6 +30,7 @@ Get a hosted instance of Zeebe on [Camunda Cloud](https://camunda.io).
 
 -   [ Client-side gRPC retry in ZBClient ](#client-side-retry)
 -   [ onReady(), onConnectionError(), and connected ](#on-ready)
+-   [ Initial Connection Tolerance ](#initial-connection-tolerance)
 
 **Connecting to a Broker**
 
@@ -235,15 +236,19 @@ const zbWorker = zbc.createWorker({
 
 These handlers are called whenever the gRPC channel is established or lost. As the grpc channel will often "jitter" when it is lost (rapidly emitting READY and ERROR events at the transport layer), there is a `connectionTolerance` property that determines how long the connection must be in a connected or failed state before the handler is called. By default this is 3000ms.
 
-You can specify another value like this:
+You can specify another value either in the constructor or via an environment variable.
+
+To specify it via an environment variable, set `ZEEBE_CONNECTION_TOLERANCE` to a number of milliseconds.
+
+To set it via the constructor, specify a value for `connectionTolerance` like this:
 
 ```TypeScript
 const { ZBClient, Duration } = require('zeebe-node')
 
 const zbc = new ZBClient({
 	onReady: () => console.log(`Connected!`),
 	onConnectionError: () => console.log(`Disconnected!`),
-	connectionTolerance: 5000
+	connectionTolerance: 5000 // milliseconds
 })
 
 const zbWorker = zbc.createWorker({
@@ -272,6 +277,20 @@ zbWorker.on('ready', () => console.log(`Worker connected!`))
 zbWorker.on('connectionError', () => console.log(`Worker disconnected!`))
 ```
 
+<a href = "initial-connection-tolerance" >
+
+### Initial Connection Tolerance
+
+Some broker connections can initially emit error messages - for example: when connecting to Camunda Cloud, during TLS negotiation and OAuth authentication, the eager commands used to detect connection status will fail, and the library will report connection errors.
+
+Since this is expected behaviour - a _characteristic of that particular connection_ - the library has a configurable "_initial connection tolerance_". This is a number of milliseconds representing the expected window in which these errors will occur on initial connection.
+
+If the library detects that you are connecting to Camunda Cloud, it sets this window to five seconds (5000 milliseconds). In some environments and under some conditions this may not be sufficient (like connecting to Camunda Cloud from your apartment Wi-fi in South Brisbane, Australia on a rainy day while the microwave link to the next suburb's ADSL exchange is degraded).
+
+You can set an explicit value for this using the environment variable `ZEEBE_INITIAL_CONNECTION_TOLERANCE`, set to a number of milliseconds.
+
+The effect of this setting is to suppress connection errors during this window, and only report them if the connection did not succeed by the end of the window.
+
 ## Connecting to a Broker
 
 <a name = "tls"></a>