Skip to content

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.Url is fetched by the host: on the cluster by the Runtime (the credential travels in the request: SourceCredential.Virtufin names the registry credential the Runtime holds; Basic/Bearer are per-request), locally by the loader (the named credential reads VIRTUFIN_REGISTRY_USER/VIRTUFIN_REGISTRY_TOKEN; file:// is allowed).
  • CodeSource.Content sends the bytes: a nupkg, C# source text (Content.Text), Python source or a wheel.
  • CodeSource.Instance hands an already constructed IWorker to a local host. GatewayWorkManagerClient rejects it with NotSupportedException before 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.

SDK Reference