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
- C# SDK Reference:
Virtufin.WorkManager.Client(the generated client and messages) - Python SDK Reference: the
virtufin-workmanagerpackage - TypeScript SDK Reference: the
@virtufin/workmanagerpackage
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
}