Fixes #151 - Make Eager Connection Optional

Author: jwulf

CHANGELOG.md

@@ -20,6 +20,7 @@ _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.

README.md

@@ -210,6 +210,12 @@ Retry is provided by [promise-retry](https://www.npmjs.com/package/promise-retry
 
 Additionally, the gRPC Client will continually reconnect when in a failed state, such as when the gateway goes away due to pod rescheduling on Kubernetes.
 
+<a name = "eager-connection"></a>
+
+### Eager Connection
+
+The ZBClient eagerly connects to the broker by issuing a topology command in the constructor. 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`.
+
 <a name = "on-ready"></a>
 
 ### onReady(), onConnectionError(), and connected

src/lib/ConfigurationHydrator.ts

@@ -18,6 +18,7 @@ export class ConfigurationHydrator {
 			...ConfigurationHydrator.decodeConnectionString(gatewayAddress),
 			...ConfigurationHydrator.getCamundaCloudConfig(options),
 			...ConfigurationHydrator.readTLSFromEnvironment(options),
+			...ConfigurationHydrator.getEagerStatus(options),
 		}
 		return configuration
 	}
@@ -195,4 +196,15 @@ export class ConfigurationHydrator {
 			? maybeClusterId.split('.zeebe.camunda.io')[0]
 			: undefined
 	}
+
+	private static getEagerStatus(options: ZBClientOptions | undefined) {
+		return {
+			eagerConnection: !(
+				(
+					process.env.ZEEBE_NODE_EAGER_CONNECT || 'trueByDefault'
+				).toLocaleLowerCase() === 'false' ||
+				options?.eagerConnection === false
+			),
+		}
+	}
 }

src/lib/interfaces-published-contract.ts

@@ -24,6 +24,7 @@ export interface ZBCustomLogger {
 
 export interface ZBClientOptions {
 	connectionTolerance?: MaybeTimeDuration
+	eagerConnection?: boolean
 	loglevel?: Loglevel
 	stdout?: ZBCustomLogger
 	retry?: boolean

src/zb/ZBClient.ts

@@ -190,19 +190,21 @@ export class ZBClient extends EventEmitter {
 		// Send command to broker to eagerly fail / prove connection.
 		// This is useful for, for example: the Node-Red client, which wants to
 		// display the connection status.
-		this.topology()
-			.then(res => {
-				this.logger.logDirect(
-					chalk.blueBright('Zeebe cluster topology:')
-				)
-				this.logger.logDirect(res.brokers)
-			})
-			.catch(e => {
-				// Swallow exception to avoid throwing if retries are off
-				if (e.thisWillNeverHappenYo) {
-					this.emit('never')
-				}
-			})
+		if (!!this.options.eagerConnection) {
+			this.topology()
+				.then(res => {
+					this.logger.logDirect(
+						chalk.blueBright('Zeebe cluster topology:')
+					)
+					this.logger.logDirect(res.brokers)
+				})
+				.catch(e => {
+					// Swallow exception to avoid throwing if retries are off
+					if (e.thisWillNeverHappenYo) {
+						this.emit('never')
+					}
+				})
+		}
 	}
 
 	public activateJobs<