Skip to content

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