Worker.Host
Workers are authored with Worker.DevKit (WorkerBase<TInput, TOutput>,
the codecs, the envelope helpers and the domain DevKits built on it). Its
documentation is at
worker-devkit.docs.virtufin.com.
This repository publishes the contract those workers run against,
Virtufin.Worker.Host, at the WorkManager's LIBRARY_VERSION. It is
host-shared: the Runtime image supplies it to every .NET worker, whatever
version the worker was built against, so release and deploy the WorkManager
before raising a worker's Worker.Host pin. Every release is checked for binary
compatibility against the previous one (EnablePackageValidation).
Contents
| Type | Purpose |
|---|---|
IWorker |
Task<IReadOnlyList<CloudEvent>> ProcessAsync(CloudEvent input, IWorkerContext context): the one entry point a worker implements; zero or more outputs, published in order. |
IWorkerContext |
What the host hands the worker on every call: WorkerId, Api (IVirtufinApi), Logger, Cancellation. |
WorkerContext |
The plain implementation hosts construct (new WorkerContext(id, api, logger, ct)). |
WorkerContexts |
EnvironmentApi: the host's configured gateway (VIRTUFIN_API_HOST/_GRPC_PORT/_KEY/_TLS), one shared ApiClient per process. |
WorkerAttributes |
The routing extension names: publishtopic, replytopic, correlationid. |
WorkerEventRules |
The per-event rules (prepare input, finish outputs, route, dead-letter) every host applies; see conformance vectors. |
CloudEventProtoCodec |
The worker wire protocol: one protobuf CloudEvent in, one CloudEventBatch out (Encode/Decode, EncodeBatch/DecodeBatch, ToProto/FromProto). |
AotNative<W> |
The native C ABI (v2) bridge for a NativeAOT worker library (ProcessStatic, FreeResultStatic); builds the context from the native host handle, with the Runtime's log callback as the Logger. |
InvalidWorkerResponseException |
A native worker's internal failure or malformed response. |
The worker context
A worker that needs the platform reads it from the context, never from the environment:
public sealed class Counter : IWorker
{
public async Task<IReadOnlyList<CloudEvent>> ProcessAsync(CloudEvent input, IWorkerContext context)
{
var (value, etag) = await context.Api.GetStateAsync("counter", context.WorkerId, context.Cancellation);
await context.Api.SaveStateAsync("counter", context.WorkerId, (int.Parse(value) + 1).ToString(), etag,
cancellationToken: context.Cancellation);
context.Logger.LogInformation("counted");
return [];
}
}
Who supplies it: the Runtime (DotNetDllEngine, both bridges, AotNative<W>)
with WorkerContexts.EnvironmentApi, the Runtime's logger and the actor's
cancellation; a LocalWorkManager with its in-memory IVirtufinApi. The
same worker therefore runs in a notebook without a gateway and on the cluster
with one. Worker.DevKit's WorkerBase passes the context to its typed
override (ProcessAsync(input, payload, context)).
Wire protocol
Every hop that carries an event (WorkManager → Runtime actor, Runtime →
engine, engine → worker) uses CloudEvents Protobuf (io.cloudevents.v1): a
request is one CloudEvent, a response one CloudEventBatch (empty = no
output). Binary data travels verbatim; every attribute keeps its type. Errors
are signalled by the transport, never inside a CloudEvent. C workers use the
header-only codec src/Virtufin.Worker.Host/Schemas/virtufin_worker_api_pb.h.
The Runtime publishes each output to its publishtopic extension (stripped
before publishing), else to its ce-type.
See also
- C# client:
IWorkManagerClient, one contract for local and cluster - Local worker loaders: run nupkgs and C# source in-process
- DotNet DLL Workers: packaging, discovery and dependency resolution
- NativeDll Workers: the native ABI and
AotNative<W> - Engines