Namespace Virtufin.Worker.DevKit

Namespaces

Virtufin.Worker.DevKit.Codecs

Classes

ApiCommandWorker<T>

A CommandWorker<T> base class that provides a pre-configured Virtufin.Api.Client.ApiClient. Subclasses get Api for free (either fixed via ctor or lazily via EnsureClientFromCommand(JsonNode)).

ApiWorker

Base class for JSON workers that need a pre-configured Virtufin.Api.Client.ApiClient. The base class (WorkerBase<TInput, TOutput>) handles codec decode and envelope construction; this class wires the Api client and passes it to the subclass.

CloudEventExtensions

Fluent extensions for CloudEvent applied automatically by WorkerBase<TInput, TOutput>.BuildResponse.

CommandWorker<T>

JSON convenience overload of CommandWorker<TInput, TOutput, TCommand>. Wires the JsonCloudEventCodec automatically and adds the JSON-specific Response(command, success, id, message) convenience that today's workers expect.

CommandWorker<TInput, TOutput, TCommand>

Generic command-dispatching worker. Builds on WorkerBase<TInput, TOutput>: the base class handles codec decode/encode and envelope construction; this class adds strongly-typed command-string extraction and enum dispatch.

Format-agnostic: this class makes no assumption about payload format. The 2-type-param convenience CommandWorker<T> pre-bakes the JsonCloudEventCodec; workers using non-JSON payloads extend the 3-type-param form directly and supply their own codec.

ConfigResolution

Resolves per-instance worker config from CloudEvent extension attributes -- never from the payload. WorkManager stamps a worker's creation-time config onto every triggering event as extension attributes, so config always arrives this way; same-named payload fields belong to the event's own domain schema and are ignored.

Envelope

The common envelope of a derived event (openspec pubsub-topics, Common Envelope Extensions, "Envelope on a derived event").

EnvelopeAttributes

Attribute names of the pubsub-topics spec's Common Envelope Extensions (CloudEvents extension names: lowercase alphanumerics, no separators).

JsonCloudEventCodec

Default JSON codec for WorkerBase<TInput, TOutput>. Decodes Data into a JsonNode and encodes a JsonObject response payload back into JSON bytes with application/json content type.

AOT/trim-safety: every decode branch works on input that is already JSON -- string passes through, JsonElement and JsonDocument yield their raw text, and a JsonNode writes itself. None of them reach the reflection-based serializer, so this type is clean under PublishAot=true. An unsupported runtime type throws NotSupportedException instead of falling back to reflection: a DefaultJsonTypeInfoResolver fallback is itself flagged IL2026/IL3050 and would fail inside a NativeAOT worker, so failing loudly at the boundary beats failing obscurely at runtime.

JsonWorkerExtensions

Convenience extension on the JSON specialization of WorkerBase<TInput, TOutput>. Extracts a string value from a JsonNode by key.

Outgoing

One output of a step, ready to become a CloudEvent: its payload, its stable ce-type, the topic it is published to (the publishtopic extension) and optionally its subject and extra extensions. Extensions set here win over those carried from the input.

PublishGate

Decides whether a symbol's changed event is due, given its publishintervalms. One instance per worker; the fold runs regardless, and the announcement that does go out carries the newest value.

Wire

Readers for the JSON wire payloads every devkit decodes by hand (candles, trades, positions, order submissions): one copy of the required-field checks, the wire precision and the timestamp parsing, so a malformed payload fails the same way, with the field named, whichever devkit reads it.

WorkerApiEndpoint

How a worker reaches the API Gateway, and with which credential. A worker runs inside its host process (WorkManager / WorkManager Runtime), whose environment names the cluster's gateway (HostEnvVar, PortEnvVar) and carries the host's own gateway key (ApiKeyEnvVar, from the api-auth secret). The gateway rejects every non-health call without a valid key once any key is configured, so a client built without one cannot save state or publish.

The key is only attached when the target IS that configured gateway: an api_host arriving in a command event or worker config could otherwise steer the host's credential to an arbitrary endpoint. Any other target gets no key.

TLS: in-cluster gateways are plaintext, but a worker run outside the cluster (a notebook, a local test) reaches the gateway through its TLS ingress. TlsEnvVar marks the host's gateway as TLS, and an explicit endpoint of the form https://host[:port] (default port 443) asks for TLS (ResolveEndpoint(string?, Func<string, string?>?)). A TLS gateway's key is never sent in plaintext, nor a plaintext gateway's over TLS.

WorkerBase<TInput, TOutput>

Generic base class for Virtufin workers. The worker's typed input and output representations (TInput / TOutput) are bridged to the CloudEvent's Data payload via an ICloudEventCodec<TInput, TOutput> supplied to the constructor.

Subclasses override ProcessAsync(CloudEvent, TInput); the base class decodes the input CloudEvent's Data via the codec, calls the override, encodes the result back into a response CloudEvent (Id, Type, Source, correlationid, timestamp are applied automatically), and either returns it or null if the override returned null.

Format-agnostic: the base class itself makes no assumption about payload format. Format-specific subclasses (CommandWorker<TInput, TOutput, TCommand>, CommandWorker<T>) handle the format-specific bits on top of this base.

WorkerTypeNames

The names of one worker type, from the naming library's virtufin.core/worker entity bound to the type (openspec pubsub-topics, Name Derivation): wrk.<type>.response, wrk.<type>.error, wrk.<type>.command.{worker_id}, com.virtufin.<type>.<event> and urn:com.virtufin:worker:<type>. Plain strings only, so no naming type crosses the Runtime's host-shared boundary.

Structs

Decoded<T>

The result of decoding an input CloudEvent: a value for the process, or Skip when the event is not one the process consumes. A skipped event changes no state and produces no output.

Interfaces

ICloudEventCodec<TInput, TOutput>

Pluggable codec for decoding a CloudEvent's Data payload into a worker-typed input and encoding a worker-typed output back into data + content-type for the response CloudEvent. Concrete implementations: JsonCloudEventCodec (default), and (future) Protobuf/flat-buffer/binary codecs.