C# Client Library
Virtufin.WorkManager.Client is the worker-management contract and its
cluster implementation: one IWorkManagerClient interface that a notebook,
a test or a service drives the same way whether the worker runs on the
cluster (through the api gateway) or in the calling process
(LocalWorkManager in Worker.DevKit, with the loaders from
Virtufin.WorkManager.Engines.Local).
Installation
Add the Virtufin package source with a personal access token (scope:
read:packages):
dotnet nuget add source https://nuget.haenerconsulting.com/api/packages/virtufin/nuget/index.json \
--name Virtufin --username <your-gitea-username> --password <your-gitea-token>
dotnet add package Virtufin.WorkManager.Client
The package carries the generated gRPC stubs (Virtufin.WorkManager.Protos,
packed inside) and depends on Virtufin.Worker.Host (the worker contract) and
Virtufin.Api.Client (the gateway client). It is NativeAOT-compatible.
Quick start
using Virtufin.Api.Client;
using Virtufin.WorkManager.Client;
// The gateway client is the only connection: WorkManager is reached through Gateway.Invoke.
await using var api = new ApiClient(host: "api.virtufin.com", port: 443, apiKey: key, useTls: true);
await using IWorkManagerClient workers = new GatewayWorkManagerClient(api);
var spec = new WorkerSpec(
Code: CodeSource.Url(new Uri("https://nuget.haenerconsulting.com/api/packages/virtufin/nuget/package/my.worker/1.2.3/my.worker.1.2.3.nupkg"),
SourceCredential.Virtufin),
MimeType: WorkerMimeTypes.DotNetDll,
Topics: ["wrk.my-worker.command"],
Tags: new Dictionary<string, string> { ["name"] = "my-worker" });
// Create + Start + wait until Running; Stop + Delete if the load fails.
var id = await workers.DeployAsync(spec, timeout: TimeSpan.FromSeconds(90));
foreach (var w in await workers.ListWorkersAsync(new Dictionary<string, string> { ["name"] = "my-worker" }))
Console.WriteLine($"{w.Id} {w.State} {w.MimeType} {string.Join(",", w.Topics)}");
await workers.StopWorkerAsync(id);
await workers.DeleteWorkerAsync(id);
Several identical copies can split a topic instead of each processing every
event (a shard): assign each copy a distinct ShardIndex under the same
Shard and ShardSize. An event then goes to the member whose slot is
hash(subject or id) % ShardSize; omit all three for a dedicated (broadcast)
worker. The fields are immutable.
for (var i = 0u; i < 3; i++)
{
var sharded = spec with { Shard = "orders", ShardSize = 3, ShardIndex = i };
await workers.DeployAsync(sharded);
}
See Delivery and Scaling.
The same program against a local host:
await using var local = new LocalWorkManager(new LocalWorkManagerOptions
{
Loaders = EngineWorkerLoaders.Default(), // nupkg + C# source, in-process
});
IWorkManagerClient workers = local;
var id = await workers.DeployAsync(spec); // identical spec, no cluster
The contract
public interface IWorkManagerClient : IAsyncDisposable
{
Task<string> CreateWorkerAsync(WorkerSpec spec, CancellationToken ct = default);
Task LoadCodeAsync(string id, CodeSource code, CancellationToken ct = default);
Task StartWorkerAsync(string id, CancellationToken ct = default);
Task StopWorkerAsync(string id, CancellationToken ct = default);
Task DeleteWorkerAsync(string id, CancellationToken ct = default);
Task<IReadOnlyList<WorkerDescriptor>> ListWorkersAsync(IReadOnlyDictionary<string, string>? tagFilters = null, CancellationToken ct = default);
Task<IReadOnlyDictionary<string, string>> GetTagsAsync(string id, CancellationToken ct = default);
Task SetTagsAsync(string id, IReadOnlyDictionary<string, string> tags, CancellationToken ct = default);
}
| Member | Semantics (identical on both hosts) |
|---|---|
CreateWorkerAsync |
Registers the worker and returns its id while the code is still Loading. A CodeSource.Instance is already Stopped on return (local hosts only). |
StartWorkerAsync |
Subscribes the worker's topics. While Loading the start is deferred until the load finishes; a LoadFailed worker throws WorkerLoadFailedException. Starting a Running worker is a no-op. |
StopWorkerAsync |
Unsubscribes; the loaded worker is kept. |
DeleteWorkerAsync |
Stops, disposes the worker and deletes the triggers it owns. |
LoadCodeAsync |
Replaces the code (hot reload); the worker goes through Loading again. |
ListWorkersAsync |
Creation order; tagFilters are ANDed. |
GetTagsAsync / SetTagsAsync |
Resource metadata; tags never reach the worker. |
Extension methods (WorkManagerClientExtensions): GetWorkerAsync(id) (via
List; WorkerNotFoundException), WaitUntilRunningAsync(id, timeout), and
DeployAsync(spec, timeout) = Create + Start + wait, with Stop + Delete on
failure.
WorkerSpec and CodeSource
public sealed record WorkerSpec(
CodeSource Code, string MimeType, IReadOnlyList<string> Topics,
IReadOnlyDictionary<string, string>? Config = null,
IReadOnlyDictionary<string, string>? Tags = null,
IReadOnlyDictionary<string, string>? Secrets = null); // references, never values
public abstract record CodeSource
{
public sealed record Url(Uri Location, SourceCredential? Credential = null) : CodeSource;
public sealed record Content(ReadOnlyMemory<byte> Bytes) : CodeSource { public static Content Text(string source); }
public sealed record Instance(IWorker Worker) : CodeSource; // in-process hosts only
}
CodeSource.Urlis fetched by the host: on the cluster by the Runtime (the credential travels in the request:SourceCredential.Virtufinnames the registry credential the Runtime holds;Basic/Bearerare per-request), locally by the loader (the named credential readsVIRTUFIN_REGISTRY_USER/VIRTUFIN_REGISTRY_TOKEN;file://is allowed).CodeSource.Contentsends the bytes: a nupkg, C# source text (Content.Text), Python source or a wheel.CodeSource.Instancehands an already constructedIWorkerto a local host.GatewayWorkManagerClientrejects it withNotSupportedExceptionbefore any RPC.
WorkerMimeTypes holds the mime types: CSharpSource (text/x-csharp),
DotNetDll (application/x-dotnet-dll), PythonSource, PythonWheel,
NativeDll, and InProcessInstance for an Instance (never accepted by the
cluster).
WorkerDescriptor and WorkerState
public enum WorkerState { Unspecified, Stopped, Running, Loading, LoadFailed }
public sealed record WorkerDescriptor(
string Id, string MimeType, string Language, IReadOnlyList<string> Topics, DateTimeOffset? CreatedAt,
WorkerState State, IReadOnlyDictionary<string, string> Config, IReadOnlyDictionary<string, string> Tags,
IReadOnlyDictionary<string, string> Secrets, string? CodeUrl);
WorkerState maps 1:1 onto the proto WorkerStatus; CodeUrl is the code
URL without credentials or query (null for inline content).
GatewayWorkManagerClient
public sealed class GatewayWorkManagerClient(IGatewayApi api, GatewayWorkManagerClientOptions? options = null)
Every call is one typed Gateway.Invoke (IGatewayApi.InvokeAsync) with
the workmanager service; the api key, TLS and retries of the connection
belong to the ApiClient. The options cover what the gateway path adds:
| Option | Default | Meaning |
|---|---|---|
ServiceName |
workmanager |
The gateway service name. |
CreateTimeout |
90 s | Deadline for CreateWorker (a cold create fetches and loads code). |
DefaultTimeout |
30 s | Deadline for every other call. |
TransientRetries |
3 | Retries on DEADLINE_EXCEEDED/UNAVAILABLE (GatewayInvokeException.IsTransient, RpcException DeadlineExceeded/Unavailable). |
RetryDelay |
2 s | Pause between retries. |
Errors: NOT_FOUND → WorkerNotFoundException; StartWorker on a worker whose
load failed (FAILED_PRECONDITION) → WorkerLoadFailedException; anything else
surfaces as the GatewayInvokeException (Service, Method, Status,
Detail). Cluster-only members stay on the class: GetWorkerHistoryAsync,
RecoverWorkersAsync.
IWorkerLoader
public interface IWorkerLoader
{
bool CanLoad(WorkerSpec spec);
Task<IWorker> LoadAsync(WorkerSpec spec, CancellationToken ct = default); // may return an IAsyncDisposable
}
A local host picks the first loader whose CanLoad accepts the spec.
InstanceWorkerLoader.Instance handles CodeSource.Instance;
Virtufin.WorkManager.Engines.Local adds the nupkg and
C# source loaders that mirror the Runtime's engines.
Python and TypeScript
The Python (virtufin-workmanager) and TypeScript (@virtufin/workmanager)
clients still speak to the WorkManager gRPC service directly; see
Python SDK and TypeScript SDK. A
Python LocalWorkManager.create_worker(code_source, …) mirror follows when a
Python local loader exists.