Worker Configuration
A Worker is the process that connects to the ORCHER engine, polls a task queue for workflow
and task work, and runs your code.
Creating a Worker
Pass the options to the constructor:
1const worker = new Worker({2 serverUrl: 'http://localhost:50051',3 namespace: 'default',4 taskQueue: 'orders',5 identity: 'orders-worker-1',6 maxConcurrentWorkflows: 100,7 maxConcurrentTasks: 50,8 shutdownGraceTime: Duration.fromSeconds(30),9 versionId: process.env.GIT_SHA,10});1112await worker.run();Or build it fluently. build() is async, because it can import files first (see
auto-discovery):
1const worker = await Worker.builder()2 .serverUrl('http://localhost:50051')3 .namespace('default')4 .taskQueue('orders')5 .maxConcurrentTasks(50)6 .build();78await worker.run();The worker starts polling as soon as it is constructed. run() connects its client, waits
until the pollers are up, and resolves; it does not wait for shutdown, and it rejects if the
worker could not start polling. The worker then runs until shutdown().
Configuration
| Option | Default | Description |
|---|---|---|
serverUrl | (required) | Engine gRPC address. https:// turns TLS on. |
namespace | (required) | Namespace to work in |
taskQueue | (required) | Queue this worker polls |
identity | hostname, process id and start time | Name the worker reports itself under |
maxConcurrentWorkflows | 100 | Workflow activations running at once |
maxConcurrentTasks | 100 | Tasks running at once |
workflowPollerCount | 4 | Parallel workflow pollers (at least 1) |
taskPollerCount | 4 | Parallel task pollers (at least 1) |
maxConcurrentActorOperations | 100 | Actor operations running at once |
actorPollerCount | 2 | Parallel actor pollers, started only when actors are registered |
shutdownGraceTime | 30 seconds | How long shutdown() waits for in-flight work; a Duration or milliseconds |
versionId | ORCHER_VERSION_ID | The code release this worker runs, such as a git sha or image tag |
apiKey | none | API key, sent as a bearer token on every request |
tls | on for https:// | caPath, certPath, keyPath; see Client |
organizationId | none | Sent as X-Organization-Id on every request |
logger | console | An object with debug, info, warn and error methods |
The builder has a setter for each option except apiKey, tls, maxConcurrentActorOperations
and actorPollerCount. To use those, pass options to the constructor.
versionId is opaque: it is sent on every poll and never parsed or compared. Set it from your
build (the worker reads ORCHER_VERSION_ID when the option is not given). The engine records
it on an execution the first time a worker claims that execution.
API Keys and TLS
An engine that requires authentication rejects a worker without a valid API key. Pass it as
apiKey; it is sent as authorization: Bearer <key> on every request the worker makes. The SDK
doesn't read ORCHER_API_KEY, so read it yourself:
1// The builder has no apiKey or tls setter; pass them to the constructor.2const worker = new Worker({3 serverUrl: 'https://orcher.example.com', // https:// turns TLS on4 namespace: 'payments',5 taskQueue: 'payments',6 apiKey: process.env.ORCHER_API_KEY,7});8await worker.run();TLS follows the URL scheme. An https:// URL connects over TLS and verifies the engine against
the system trust store, with no other setting. An http:// URL connects in plaintext, so use
https:// whenever the engine expects TLS. The tls option adds certificates: a CA certificate
to trust a private or self-signed authority, and a client certificate and key for mutual TLS.
Setting tls at all turns TLS on:
1const worker = new Worker({2 serverUrl: 'https://orcher.internal:50051',3 namespace: 'payments',4 taskQueue: 'payments',5 tls: {6 caPath: '/etc/orcher/ca.pem', // only for a private certificate authority7 certPath: '/etc/orcher/worker.pem',8 keyPath: '/etc/orcher/worker-key.pem',9 },10});11await worker.run();Registering Workflows and Tasks
workflow(), task(), @Workflow() and @Task() register what they define when their module
is loaded. By default a worker serves every workflow and task registered in its process at the
moment it is constructed, so import those modules before you create the worker:
1import { Worker } from '@orcher/sdk';2// Importing the modules runs their decorators and task()/workflow() calls,3// which register them for the worker.4import './tasks';5import './workflows';67async function main(): Promise<void> {8 const worker = await Worker.builder()9 .serverUrl(process.env.ORCHER_URL ?? 'http://localhost:50051')10 .namespace('default')11 .taskQueue('orders')12 .build();1314 // Resolves once the worker is polling; it keeps polling until shutdown().15 await worker.run();1617 process.once('SIGTERM', () => {18 void worker.shutdown();19 });20}2122main().catch((err) => {23 console.error(err);24 process.exit(1);25});To serve only some of them, pass workflows and tasks: the references workflow() and
task() return, and those from createTaskRefs(). The modules must still be imported.
1// Serve these and nothing else registered in the process.2const worker = new Worker({3 serverUrl: 'http://localhost:50051',4 namespace: 'default',5 taskQueue: 'orders',6 workflows: [processOrder],7 tasks: [chargePayment, orderTasks.reserveInventory, orderTasks.sendConfirmation],8});9await worker.run();A @Workflow() class given in workflows is registered under the name its decorator declares.
Names are global within a process: a second task or workflow registered under a name already in use replaces the first, with a warning in the log.
Auto-Discovery
Worker.builder().autoDiscover() imports matching files for you before it builds the worker:
1const worker = await Worker.builder()2 .serverUrl('http://localhost:50051')3 .namespace('default')4 .taskQueue('orders')5 // Import every file under src/workflows and src/tasks before building.6 .autoDiscover({ patterns: ['./src/workflows/**/*.ts', './src/tasks/**/*.ts'] })7 .build();autoDiscover option | Default | Description |
|---|---|---|
patterns | ./src/**/*.ts, ./src/**/*.js | Globs of files to import |
exclude | tests, specs, .d.ts, node_modules, dist, build, .next, coverage | Globs to skip. Setting it replaces the default list. |
baseDir | process.cwd() | Directory the globs are resolved against |
throwOnError | false | Fail on the first file that cannot be imported, instead of logging it and going on |
The defaults suit a worker run from TypeScript source. A worker run from compiled JavaScript
must point the patterns at its output, and replace the exclude list, which skips dist/ and
build/:
1const worker = await Worker.builder()2 .serverUrl('http://localhost:50051')3 .namespace('default')4 .taskQueue('orders')5 // Running compiled JavaScript: scan dist/, and replace the default6 // exclude list, which skips dist/ and build/.7 .autoDiscover({8 patterns: ['./dist/workflows/**/*.js', './dist/tasks/**/*.js'],9 exclude: ['**/*.test.js', '**/*.d.ts'],10 })11 .build();Auto-discovery is a builder option only. With the constructor, import your modules yourself.
Graceful Shutdown
shutdown() stops polling, gives in-flight work up to shutdownGraceTime to finish, then
stops the worker. Calling it again while it runs returns the same promise.
1const stop = (): void => {2 // Stop polling, give in-flight work up to shutdownGraceTime, then stop.3 worker4 .shutdown()5 .then(() => process.exit(0))6 .catch((err: unknown) => {7 console.error(err);8 process.exit(1);9 });10};11process.once('SIGTERM', stop);12process.once('SIGINT', stop);To override the grace time for one shutdown, or not to wait at all, pass one of:
1await worker.shutdown({ timeout: 60_000 }); // wait up to 60 s instead2await worker.shutdown({ force: true }); // don't wait for in-flight workWork a stopped worker had claimed is released by the engine and handed to another worker. In a container, start Node in exec form so the signal reaches it rather than a shell:
1# Exec form: SIGTERM reaches node2CMD ["node", "dist/worker.js"]34# Not shell form: the signal goes to /bin/sh5# CMD node dist/worker.jsScaling
Run more worker processes on the same task queue to add capacity; each polls independently,
and the engine hands each piece of work to one of them. Within a process,
maxConcurrentWorkflows and maxConcurrentTasks bound how much runs at once. Apart from
ORCHER_VERSION_ID, the SDK reads no environment variables for the worker's settings, so read
your own (as the samples above do with process.env) and pass them in.