Reference

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:

1
const 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
});
11
12
await worker.run();

Or build it fluently. build() is async, because it can import files first (see auto-discovery):

1
const worker = await Worker.builder()
2
.serverUrl('http://localhost:50051')
3
.namespace('default')
4
.taskQueue('orders')
5
.maxConcurrentTasks(50)
6
.build();
7
8
await 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

OptionDefaultDescription
serverUrl(required)Engine gRPC address. https:// turns TLS on.
namespace(required)Namespace to work in
taskQueue(required)Queue this worker polls
identityhostname, process id and start timeName the worker reports itself under
maxConcurrentWorkflows100Workflow activations running at once
maxConcurrentTasks100Tasks running at once
workflowPollerCount4Parallel workflow pollers (at least 1)
taskPollerCount4Parallel task pollers (at least 1)
maxConcurrentActorOperations100Actor operations running at once
actorPollerCount2Parallel actor pollers, started only when actors are registered
shutdownGraceTime30 secondsHow long shutdown() waits for in-flight work; a Duration or milliseconds
versionIdORCHER_VERSION_IDThe code release this worker runs, such as a git sha or image tag
apiKeynoneAPI key, sent as a bearer token on every request
tlson for https://caPath, certPath, keyPath; see Client
organizationIdnoneSent as X-Organization-Id on every request
loggerconsoleAn 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.
2
const worker = new Worker({
3
serverUrl: 'https://orcher.example.com', // https:// turns TLS on
4
namespace: 'payments',
5
taskQueue: 'payments',
6
apiKey: process.env.ORCHER_API_KEY,
7
});
8
await 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:

1
const 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 authority
7
certPath: '/etc/orcher/worker.pem',
8
keyPath: '/etc/orcher/worker-key.pem',
9
},
10
});
11
await 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:

1
import { Worker } from '@orcher/sdk';
2
// Importing the modules runs their decorators and task()/workflow() calls,
3
// which register them for the worker.
4
import './tasks';
5
import './workflows';
6
7
async 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();
13
14
// Resolves once the worker is polling; it keeps polling until shutdown().
15
await worker.run();
16
17
process.once('SIGTERM', () => {
18
void worker.shutdown();
19
});
20
}
21
22
main().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.
2
const 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
});
9
await 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:

1
const 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 optionDefaultDescription
patterns./src/**/*.ts, ./src/**/*.jsGlobs of files to import
excludetests, specs, .d.ts, node_modules, dist, build, .next, coverageGlobs to skip. Setting it replaces the default list.
baseDirprocess.cwd()Directory the globs are resolved against
throwOnErrorfalseFail 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/:

1
const worker = await Worker.builder()
2
.serverUrl('http://localhost:50051')
3
.namespace('default')
4
.taskQueue('orders')
5
// Running compiled JavaScript: scan dist/, and replace the default
6
// 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.

1
const stop = (): void => {
2
// Stop polling, give in-flight work up to shutdownGraceTime, then stop.
3
worker
4
.shutdown()
5
.then(() => process.exit(0))
6
.catch((err: unknown) => {
7
console.error(err);
8
process.exit(1);
9
});
10
};
11
process.once('SIGTERM', stop);
12
process.once('SIGINT', stop);

To override the grace time for one shutdown, or not to wait at all, pass one of:

1
await worker.shutdown({ timeout: 60_000 }); // wait up to 60 s instead
2
await worker.shutdown({ force: true }); // don't wait for in-flight work

Work 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 node
2
CMD ["node", "dist/worker.js"]
3
4
# Not shell form: the signal goes to /bin/sh
5
# CMD node dist/worker.js

Scaling

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.


Next Steps

  • Workflows: the WorkflowContext API
  • Tasks: task options and injection
  • Workers: running workers in production