Fixes camunda-community-hub#158 Fixes camunda-community-hub#152 Fixes camunda-community-hub#99

Author: jwulf

.circleci/config.yml

@@ -33,7 +33,7 @@ jobs:
   test:
     docker:
       - image: circleci/node:11.10.1
-      - image: camunda/zeebe:0.23.0
+      - image: camunda/zeebe:0.23.1
     working_directory: ~/zeebe-client-node-js
     steps:
       - checkout

CHANGELOG.md

@@ -5,6 +5,7 @@
 _Changes in APIs or behaviour that may affect existing applications that use zeebe-node._
 
 -   The `job.variables` and `job.customHeaders` in the worker job handler are now typed as read-only structures. This will only be a breaking change if your code relies on mutating these data structures. See the section "Working with Workflow Variables and Custom Headers" in the README for an explanation on doing deep key updates on the job variables.
+-   The ZBClient no longer eagerly connects to the broker by default. Previously, it did this by issuing a topology command in the constructor. This allows you an onReady event to be emitted. You can re-enable the eager connection behavior, by either passing `eagerConnection: true` to the client constructor options, or setting the environment variable `ZEEBE_NODE_EAGER_CONNECTION` to `true`. See [#151](https://github.com/creditsenseau/zeebe-client-node-js/issues/151).
 -   The library nows logs with the simplified `ZBSimpleLogger` by default, for friendly human-readable logs. This will only be a breaking change if you currently rely on the structured log output. To get the previous structured log behaviour, pass in `stdout: ZBJsonLogger` to the `ZBClient` constructor options, or set the environment variable `ZEEBE_NODE_LOG_TYPE` to `JSON`. Refer to the "Logging" section in the README.
 
 ## New Features
@@ -20,7 +21,6 @@ _New shiny stuff._
 -   `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". 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 ZBClient eagerly connects to the broker by issuing a topology command. This allows you an onReady event to be emitted. You can disable this (for example, for testing without a broker), by either passing `eagerConnection: false` to the client constructor options, or setting the environment variable `ZEEBE_NODE_EAGER_CONNECTION` to `false`. See [#151](https://github.com/creditsenseau/zeebe-client-node-js/issues/151).
 -   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.

design/grpc-error-handling.md

@@ -0,0 +1,10 @@
+# GRPC Channel Error Handling
+
+There are a few things that can go wrong on the Grpc channel:
+
+-   **No resolvable DNS address**. In this case, the stream emits an error with `code`: `14`, and `details`: `Name resolution failed for target nobroker:26500`.
+-   **Resolvable address, but no broker**
+-   **Broker goes away**. This can be due to a Docker restart, or a K8s pod reschedule (for example, in Camunda Cloud).
+-   **Intermittent Network Error**
+-   **Business Error**. For example:
+-   **Broker backpressure**. This returns error code 8.