Skip to content

API Reference

The WorkManager is a gRPC service, virtufin.WorkManager, defined in workmanager.proto. It keeps the worker catalog and routes every worker to its WorkManager.Runtime actor; it runs no worker code itself. Clients reach it directly (port 5002) or through the API's gRPC invocation methods. Server reflection is enabled.

Ports

Port Serves
gRPC (5002; 25002 in the local deploy) virtufin.WorkManager, gRPC server reflection, gRPC health
HTTP (5001; 25001 in the local deploy) The Kubernetes probes /health, /healthz, /ready

Every worker operation (create, code loading, start/stop, tags) is a gRPC call.

Exploring the API

Use grpcurl on the command line and grpcui as a browser explorer, against the gRPC port (never the HTTP port):

grpcurl -plaintext localhost:25002 describe virtufin.WorkManager
grpcurl -plaintext -d '{}' localhost:25002 virtufin.WorkManager/ListWorkers
grpcui -plaintext localhost:25002   # or: bash common/scripts/run_grpcui_local.sh localhost:25002

For the cluster, port-forward the service's gRPC port, or go through the API gateway, whose reflection includes virtufin.WorkManager. Keep the grpcui UI loopback-only; reflection and RPCs follow the target's access policy.

Generated API Documentation

RPCs

RPC What it does
CreateWorker Validates the request, registers the worker with its Runtime actor and persists it as LOADING, then returns its id. The code loads in the background; the lifecycle event loaded or load-failed marks the end.
StartWorker Starts a loaded worker (subscribes its topics). On a LOADING worker the start is recorded and happens when the load finishes.
StopWorker Stops a running worker; on a LOADING worker it withdraws a pending start.
LoadCode Replaces the worker's code and appends it to the history.
DeleteWorker Deletes the worker from its Runtime and the catalog, and deletes the triggers it owns.
ListWorkers Every worker in the catalog, optionally filtered by tags (all filters must match).
GetWorkerHistory The worker's code sources, oldest first.
SetTag / SetTags / GetTag / GetTags Catalog metadata; never delivered to the worker.
RecoverWorkers Pokes every running worker's Runtime actor now (a deactivated one reactivates and resubscribes; the WorkManager also does this every 60 s) and returns the catalog size.

Sharded groups

CreateWorkerRequest carries three optional fields that split a topic between several copies of a worker instead of every copy processing every event:

Field Meaning
shard Shard name. Empty (the default) = a dedicated worker that receives every event.
shard_size Number of members, 1..1024; every member uses the same value.
shard_index This member's slot in [0, shard_size); unique among live members sharing a topic. StartWorker claims it atomically and refuses a duplicate or a different size with FAILED_PRECONDITION, also while the worker is still loading.

An event goes to the member whose slot is hash(subject or id) % shard_size, so each event is handled exactly once and a per-entity subject keeps that entity's events on one member. ListWorkers returns the three fields. This is not a broker consumer group and does not steal work; see Delivery and Scaling.

The clients expose the fields as WorkerSpec.Shard/ShardSize/ShardIndex (C#), create_worker(shard=..., shard_size=..., shard_index=...) (Python) and createWorker(..., shard, shardSize, shardIndex) (TypeScript).

Mime types

Mime type Engine Runtime actor type
text/x-csharp C# source (Roslyn, subprocess) CSharpSourceWorker
application/x-dotnet-dll .NET DLL (worker nupkg) DotnetDllWorker
application/x-native-dll Native library (ABI v2) NativeDllWorker
text/x-python Python source PythonWorker
application/x-python Python wheel PythonWorker
text/x-typescript TypeScript (or JavaScript) ES module TypeScriptWorker
application/x-npm npm package (npm pack tarball) TypeScriptWorker

Code sources

CodeSource is either inline content or a url. A URL must be HTTP(S) and passes the SSRF guard: when ALLOWED_CODE_SOURCE_HOSTS is set, its host must be on the list (a listed host may resolve to a private address); otherwise it must not resolve to a private address. See Security.

credential authorizes a URL fetch: basic or bearer carry a secret, which the WorkManager uses for that one fetch and never stores; named: "virtufin" is the org registry credential, resolved server-side and the only credential kept in the catalog (the Runtime re-fetches with it).

Concurrency

Every write to a worker's record (status, tags, history, the load outcome) is an etag compare-and-swap with retry, so any WorkManager replica can serve any RPC for any worker without losing a concurrent update.

Errors

Status When
INVALID_ARGUMENT Malformed worker id, unsupported mime type, missing or empty code source, non-HTTP(S) URL, invalid secret references
NOT_FOUND No worker with that id
FAILED_PRECONDITION StartWorker on a worker whose load failed
INTERNAL A code source rejected by the SSRF guard, a fetch or Runtime failure (the message carries the cause)

WorkerStatus

enum WorkerStatus {
  WORKER_STATUS_UNSPECIFIED = 0;
  WORKER_STATUS_STOPPED = 1;
  WORKER_STATUS_RUNNING = 2;
  WORKER_STATUS_LOADING = 3;      // code still loading in the background
  WORKER_STATUS_LOAD_FAILED = 4;  // see the load-failed lifecycle event
}