Skip to content

Commit

Permalink
style(formatting): technical review (#96)
Browse files Browse the repository at this point in the history
  • Loading branch information
@christinaausley
christinaausley authored Apr 1, 2024
1 parent 1c3112a commit b801f5f
Showing 1 changed file with 27 additions and 27 deletions.
54 changes: 27 additions & 27 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[![NPM](https://nodei.co/npm/@camunda8/sdk.png)](https://www.npmjs.com/package/@camunda8/sdk)

This is the official Camunda 8 JavaScript SDK. It is written in TypeScript and runs on NodeJS ([why not in a web browser?](https://github.com/camunda-community-hub/camunda-8-js-sdk/issues/79)).
This is the official Camunda 8 JavaScript SDK. It is written in TypeScript and runs on Node.js. See details on why [this is not in a web browser](https://github.com/camunda-community-hub/camunda-8-js-sdk/issues/79)).

## Using the SDK in your project

Expand All @@ -14,7 +14,7 @@ npm i @camunda8/sdk

## Usage

In this release, the functionality of the Camunda Platform 8 is exposed via dedicated clients for the component APIs.
In this release, the functionality of Camunda 8 is exposed via dedicated clients for the component APIs.

```typescript
import { Camunda8 } from '@camunda8/sdk'
Expand All @@ -34,31 +34,31 @@ The configuration for the SDK can be done by any combination of environment vari

Any configuration passed in to the `Camunda8` constructor is merged over any configuration in the environment.

The configuration object fields and the environment variables have exactly the same names. See the file `src/lib/Configuration.ts` for a complete list of configuration.
The configuration object fields and the environment variables have exactly the same names. See the file `src/lib/Configuration.ts` for a complete configuration outline.

## A note on how int64 is handled in the JavaScript SDK

Entity keys in Camunda 8 are stored and represented as `int64` numbers. The range of `int64` extends to numbers that cannot be represented by the JavaScript `number` type. To deal with this, `int64` keys are serialised by the SDK to the JavaScript `string` type. See [this issue](https://github.com/camunda-community-hub/camunda-8-js-sdk/issues/78) for more details.

Some number values - for example: "_total returned results_ " - may be specified as `int64` in the API specifications. Although these numbers will usually not contain unsafe values, they are always serialised to `string`.

For `int64` values whose type is not known ahead of time, such as job variables, you can pass an annotated Dto object to decode them reliably. If no Dto is specified, the default behaviour of the SDK is to serialise all numbers to JavaScript `number`, and if a number value is detected at runtime that cannot be accurately stored as `number`, to throw an Exception.
For `int64` values whose type is not known ahead of time, such as job variables, you can pass an annotated data transfer object (DTO) to decode them reliably. If no DTO is specified, the default behavior of the SDK is to serialise all numbers to JavaScript `number`, and if a number value is detected at a runtime that cannot be accurately stored as `number`, to throw an exception.

## OAuth

Calls to APIs are authorized using a token that is obtained via a client id/secret pair exchange and then passes as an authorisation header on API calls. The SDK handles this transparently for you.
Calls to APIs are authorized using a token that is obtained via a client id/secret pair exchange, and then passes as an authorization header on API calls. The SDK handles this for you.

If your Camunda 8 Platform is secured using token exchange you will need to provide the client id and secret to the SDK.
If your Camunda 8 platform is secured using token exchange, provide the client id and secret to the SDK.

### Disable OAuth

To disable OAuth, set the environment variable `CAMUNDA_OAUTH_DISABLED`. You can use this when, for example, running against a minimal Zeebe broker in a development environment.
To disable OAuth, set the environment variable `CAMUNDA_OAUTH_DISABLED`. You can use this when running against a minimal Zeebe broker in a development environment, for example.

With this environment variable set, the SDK will inject a `NullAuthProvider` that does nothing.

### Configuring OAuth

To get a token for use with the application APIs you need to provide the following configuration fields at a minimum, either via the `Camunda8` constructor or in environment variables:
To get a token for use with the application APIs, provide the following configuration fields at a minimum, either via the `Camunda8` constructor or in environment variables:

```bash
ZEEBE_ADDRESS
Expand All @@ -67,7 +67,7 @@ ZEEBE_CLIENT_SECRET
CAMUNDA_OAUTH_URL
```

To get a token for the Camunda SaaS Admin Console API or the Camunda SaaS Modeler API you need to set the following:
To get a token for the Camunda SaaS Administration API or the Camunda SaaS Modeler API, set the following:

```bash
CAMUNDA_CONSOLE_CLIENT_ID
Expand All @@ -76,11 +76,11 @@ CAMUNDA_CONSOLE_CLIENT_SECRET

### Token caching

OAuth tokens are cached in-memory and on-disk. The disk cache is useful, for example, to prevent token endpoint saturation when restarting or rolling over workers. They can all hit the cache instead of requesting new tokens.
OAuth tokens are cached in-memory and on-disk. The disk cache is useful to prevent token endpoint saturation when restarting or rolling over workers, for example. They can all hit the cache instead of requesting new tokens.

You can turn off the disk caching by setting `CAMUNDA_TOKEN_DISK_CACHE_DISABLE` to true. This will cache tokens in-memory only.

By default the token cache directory is `$HOME/.camunda`. You can specify a different directory by providing a full file path value for `CAMUNDA_TOKEN_CACHE_DIR`.
By default, the token cache directory is `$HOME/.camunda`. You can specify a different directory by providing a full file path value for `CAMUNDA_TOKEN_CACHE_DIR`.

Here is an example of specifying a different cache directory via the constructor:

Expand All @@ -94,19 +94,19 @@ const c8 = new Camunda8({
})
```

If the cache directory does not exist, the SDK will attempt to create it (recursively). If the SDK is unable to create it, or the directory exists but is not writeable by your application then the SDK will throw an exception.
If the cache directory does not exist, the SDK will attempt to create it (recursively). If the SDK is unable to create it, or the directory exists but is not writeable by your application, the SDK will throw an exception.

### Token refresh

Token refresh timing relative to expiration is controlled by the `CAMUNDA_OAUTH_TOKEN_REFRESH_THRESHOLD_MS` value. By default this is 1000ms. Tokens are renewed this amount of time before they expire.
Token refresh timing relative to expiration is controlled by the `CAMUNDA_OAUTH_TOKEN_REFRESH_THRESHOLD_MS` value. By default, this is 1000ms. Tokens are renewed this amount of time before they expire.

If you experience intermittent `401: Unauthorized` errors, this may not be sufficient time to refresh the token before it expires in your infrastructure. Increase this value to force a token to be refreshed before it expires.

## Connection Configuration Examples
## Connection configuration examples

### Self-Managed

This is the complete environment configuration needed to run against the Dockerised Self-Managed Stack in the `docker` subdirectory:
This is the complete environment configuration needed to run against the Dockerised Self-Managed stack in the `docker` subdirectory:

```bash
# Self-Managed
Expand All @@ -119,7 +119,7 @@ export CAMUNDA_OPERATE_BASE_URL='http://localhost:8081'
export CAMUNDA_OPTIMIZE_BASE_URL='http://localhost:8083'
export CAMUNDA_MODELER_BASE_URL='http://localhost:8070/api'

# Turn off the tenant ID, which may have been set by Multi-tenant tests
# Turn off the tenant ID, which may have been set by multi-tenant tests
# You can set this in a constructor config, or in the environment if running multi-tenant
export CAMUNDA_TENANT_ID=''

Expand Down Expand Up @@ -184,7 +184,7 @@ The SDK uses the [`debug`](https://github.com/debug-js/debug) library. To enable

| Value | Component |
| ---------------------- | -------------------- |
| `camunda:adminconsole` | Admin Console API |
| `camunda:adminconsole` | Administration API |
| `camunda:modeler` | Modeler API |
| `camunda:operate` | Operate API |
| `camunda:optimize` | Optimize API |
Expand All @@ -194,18 +194,18 @@ The SDK uses the [`debug`](https://github.com/debug-js/debug) library. To enable
| `camunda:worker` | Zeebe Worker |
| `camunda:zeebeclient` | Zeebe Client |

## Typing of Zeebe Worker Variables
## Typing of Zeebe worker variables

The variable payload in a Zeebe Worker task handler is available as an object `job.variables`. By default, this is of type `any`.
The variable payload in a Zeebe worker task handler is available as an object `job.variables`. By default, this is of type `any`.

The `ZBClient.createWorker()` method accepts an `inputVariableDto` to control the parsing of number values and provide design-time type information. Passing an `inputVariableDto` class to a Zeebe worker is optional. If a Dto class is passed to the Zeebe Worker, it is used for two purposes:
The `ZBClient.createWorker()` method accepts an `inputVariableDto` to control the parsing of number values and provide design-time type information. Passing an `inputVariableDto` class to a Zeebe worker is optional. If a DTO class is passed to the Zeebe worker, it is used for two purposes:

1. To provide design-time type information on the `job.variables` object.
2. To specify the parsing of JSON number fields. These can potentially represent `int64` values that cannot be represented accurately by the JavaScript `number` type. With a Dto, you can specify that a specific JSON number fields be parsed losslessly to a `string` or `BigInt`.
- To provide design-time type information on the `job.variables` object.
- To specify the parsing of JSON number fields. These can potentially represent `int64` values that cannot be represented accurately by the JavaScript `number` type. With a DTO, you can specify that a specific JSON number fields be parsed losslessly to a `string` or `BigInt`.

With no Dto specified, there is no design-time type safety. At run-time, all JSON numbers are converted to the JavaScript `number` type. If a variable field has a number value that cannot be safely represented using the JavaScript number type (a value greater than 2^53 -1) then an exception is thrown.
With no DTO specified, there is no design-time type safety. At run-time, all JSON numbers are converted to the JavaScript `number` type. If a variable field has a number value that cannot be safely represented using the JavaScript number type (a value greater than 2^53 -1), an exception is thrown.

To provide a Dto, extend the `LosslessDto` class, like so:
To provide a DTO, extend the `LosslessDto` class like so:

```typescript
class MyVariableDto extends LosslessDto {
Expand All @@ -220,7 +220,7 @@ class MyVariableDto extends LosslessDto {

In this case, `veryBigNumber` is an `int64` value. It is transferred as a JSON number on the wire, but the parser will parse it into a `string` so that no loss of precision occurs. Similarly, `veryBigInteger` is a very large integer value. In this case, we direct the parser to parse this variable field as a `bigint`.

You can nest Dtos like this:
You can nest DTOs like this:

```typescript
class MyLargerDto extends LosslessDto {
Expand All @@ -230,8 +230,8 @@ class MyLargerDto extends LosslessDto {
}
```

## Typing of Custom Headers
## Typing of custom headers

The Zeebe worker receives custom headers as `job.customHeaders`. The `ZBClient.createWorker()` method accepts a `customHeadersDto` to control the behaviour of custom header parsing of number values and provide design-time type information.
The Zeebe worker receives custom headers as `job.customHeaders`. The `ZBClient.createWorker()` method accepts a `customHeadersDto` to control the behavior of custom header parsing of number values and provide design-time type information.

This follows the same strategy as the job variables, as previously described.

0 comments on commit b801f5f

Please sign in to comment.