Table of Contents

Namespace Virtufin.Api.Services

Classes

AggregatedReflectionResolver

Resolves gRPC server reflection requests against two descriptor sources: the gateway's own compiled-in protos (Gateway/Config/State/Pubsub) and the backend descriptor caches maintained by GrpcReflectionService. This is what lets clients reflect on backend services (virtufin.WorkManager, ...) through the gateway, which does not compile their protos in. Besides fully-qualified symbols, the registered service name from services.json (e.g. "workmanager") is accepted as a FileContainingSymbol alias for the backend's whole descriptor set.

AggregatedReflectionService

grpc.reflection.v1alpha.ServerReflection endpoint backed by AggregatedReflectionResolver. The Python client and the TUI speak this version.

AggregatedReflectionV1Service

grpc.reflection.v1.ServerReflection endpoint backed by AggregatedReflectionResolver. Modern tooling (grpcurl) and the gateway's own backend-facing client speak this version.

ApiNames

The gateway's own names, from its virtufin.service.api naming fragment (embedded; naming/virtufin.service.api.yaml). The gateway names only what it publishes itself: it never parses or validates callers' topics or keys.

AppMetrics

Application-level metrics for the API gateway.

CloudEventAttributeException

A CloudEvent attribute that cannot be converted (e.g. a time string that is not RFC3339). Callers map it to an invalid-argument error naming Attribute -- it is bad input, not a server fault.

CloudEventExtensions
ConfigService

Implementation of the gRPC Config service. Provides service configuration discovery and management capabilities.

DaprAppCallbackService
DaprPublicationCapabilityGate

Requires the publication state store to report the Dapr ETAG and TRANSACTIONAL capabilities (the same ones an actor state store needs). Reads the sidecar's metadata once it is reachable and caches the verdict.

DaprPublicationStateStore

IPublicationStateStore over the Dapr state API.

DaprPublish

How the gateway puts a CloudEvent on a Dapr topic: as a raw payload, so the stream holds the CloudEvent bytes exactly as given (JSON, or protobuf for binary data) and subscriptions read them back verbatim.

DaprStableAppCallbackMethodProvider

Serves the parts of Dapr's stable AppCallback service that the runtime actually calls: OnJobEvent (scheduled job delivery) and ListTopicSubscriptions (declarative-subscription discovery).

Why this exists: the Dapr runtime (confirmed on 1.18.1) delivers scheduled jobs to AppCallback/OnJobEvent — the stable service, per dapr/dapr's own appcallback.proto. The .NET SDK lags it: the generated code in Dapr.Protos 1.18.2 contains OnJobEventAlpha1 on AppCallbackAlpha and no OnJobEvent anywhere, so DaprAppCallbackService could only ever bind the alpha route. Nothing served the route Dapr actually calls, the request matched no endpoint, and it was rejected 401 by ApiKeyHttpMiddleware (which exempts only requests whose matched endpoint carries GrpcMethodMetadata). Net effect: **no scheduled trigger ever fired**, while Dapr retried roughly once a second forever.

Registering the method here rather than regenerating appcallback.proto into this repo is deliberate: the request and response types already exist in Dapr.Protos and are reused as-is, so there is no second copy of the Dapr message types to collide with the SDK's (the CS0433 duplicate-type trap this codebase has hit before). Only the service/method *name* differs.

Because the endpoint is produced through the normal gRPC service-model pipeline it carries GrpcMethodMetadata, so ApiKeyHttpMiddleware lets it through to ApiKeyInterceptor, which exempts the /dapr.proto.runtime.v1.AppCallback/ prefix — the sidecar cannot present an API key.

Both routes stay live: the alpha one for older runtimes, this one for current ones. They share a single handler, so behaviour cannot drift. Once the SDK generates the stable method, this provider can be replaced by a plain override OnJobEvent on DaprAppCallbackService.

DescriptorSymbols

The fully-qualified symbols a proto file defines, as gRPC server reflection's file_containing_symbol resolves them (any symbol protobuf's descriptor pool finds by name, which is what grpcurl describe sends): services, methods, messages (nested ones too), fields, oneofs, extensions, enums and enum values.

FenceRecord

A connection's fence: which activation may publish, and until when it must renew.

FencedPublicationKeys

The per-connection keys of the publication fence. Default comes from the naming registry; tests use an isolated ForPrefix(string).

FencedPublicationStore

The publication fence on any Dapr state store with ETags (and the TRANSACTIONAL capability the guarded writes use). Every change is one ETag-guarded write of a single key, the one thing all such stores make atomic.

Heartbeat fencing: publishers do not pass the fence per frame. The holder renews its lease every second or so; a superseded holder learns it from a rejected renewal and stops, so a stale owner publishes for at most one renewal interval after its successor claims. Times are this replica's UTC clock, as for WorkManager's recovery lease.

FencedPublicationSweeper

Removes abandoned publication fences (inactive or expired for two leases), walking the fence index; nothing here depends on the state store's provider.

FieldSchema

Describes a single field within a message schema.

ForwardedHeaders

The allow-list of request headers the gateway propagates to a backend on a proxied call, and the filters that apply it.

GatewayService

Implementation of the gRPC Gateway service: service discovery and method invocation. Subscribing is Pubsub.Subscribe (see PubsubService).

GrpcCallResult

Represents the result of a gRPC call invocation.

GrpcCallStatusCodes

The status vocabulary Gateway.Invoke / InvokeJson report in InvokeResponse.status.

Every status the gateway emits MUST come from here, so one condition yields one string whether the gateway or the backend detected it. Translate a downstream RpcException with GrpcStatusCodeMap.ToGatewayStatus.

GrpcChannelPool
GrpcReflectionService

Provides gRPC reflection functionality including service discovery, method schema retrieval, and dynamic gRPC invocation based on reflection data.

GrpcStatusCodeMap

Translates StatusCode into the gateway's own GrpcCallStatusCodes vocabulary, so one condition yields one string regardless of whether the gateway or the backend produced it.

MethodSchema

Describes the schema of a gRPC method's input or output type.

NoopConsumerGroupPositioner

No-op positioner: for pub/sub backends without one, or a Redis backend without access configured (local dev).

OneofCaseSchema

Represents a case within a oneof field group.

ProtoJson

The protobuf JSON mapping over runtime descriptors: InvokeJson's converter. Google.Protobuf's C# JsonParser/JsonFormatter need generated message classes, which a descriptor built from gRPC reflection does not have (C# has no DynamicMessage), so the mapping is implemented here on the wire format and checked against those reference implementations on compiled test messages (tests/Virtufin.Api.Tests/ProtoJsonConformanceTests.cs).

Encoding accepts a field by its proto name (code_source) or JSON name (codeSource) and refuses any other key. Decoding writes proto field names and default values (JsonFormatter with PreserveProtoFieldNames and FormatDefaultValues): 64-bit integers as strings, enums by name, bytes as base64, the well-known types in their JSON forms.

ProtoJsonException

A request JSON that is not the message it should be, with the JSON path of the problem.

ProviderSelectingConsumerGroupPositioner

Picks the positioner for the pub/sub backend actually loaded, by the Dapr component's type, the first time it is needed (the sidecar is up by then). Only pubsub.redis has one; other backends start subscriptions as their component configures (e.g. Kafka initialOffset: newest).

PubSubTopics
PubsubReplayOptions

Bounds of a replay_since Subscribe (configuration PubsubReplayMaxEntries, PubsubReplayMaxBytes): a replay of more retained entries, or more payload bytes, is refused with OUT_OF_RANGE before anything is sent. The entries are held in memory while they are sent, so the byte bound protects the gateway from a replay of large events (an order-book image is ~127 KB).

PubsubService

Implements the Pubsub gRPC service for publish/subscribe messaging via Dapr. Publish receives a CloudEvent proto; Subscribe streams reconstructed CloudEvents.

PubsubSubscriptionOptions

How long a topic's Dapr subscription stays open after its last subscriber left (configuration PubsubSubscriptionLingerSeconds, default DefaultLingerSeconds, 0 closes at once). A subscriber that joins meanwhile reuses it, so a quick resubscribe never closes and reopens a Dapr subscription: a closed one leaves daprd's reader behind to take the topic's next message (common#28). Messages published while nobody is subscribed are acked and dropped, as with no subscription at all (no catch-up).

RedisConsumerGroupPositioner

IConsumerGroupPositioner over a direct Redis connection to the pub/sub component's Redis. Safe only because the group is this pod's alone ({podName}) and the registry calls it while this process holds no Dapr subscription for the topic.

ReflectionAnswer

Protocol-neutral result of a reflection lookup; adapted into the v1alpha/v1 response messages by the two service endpoints below. Exactly one of ServiceNames, FileDescriptorProtos, or ErrorMessage is set.

RetainedEntry

One retained stream entry: its stream id and the payload as stored (what a raw-payload Dapr subscription delivers).

ServiceMethodInfo

Represents a gRPC method with its metadata.

SidecarReaderSweeper

Debounced UnblockSidecarReadersAsync(CancellationToken) after Dapr subscriptions close, so a closed subscription's parked reader exits before it takes a message (see the positioner's remarks).

StateActionConstants
StateChangeEvents

CloudEvent attributes for the Tier 0 state-change topics (sys.api.state.saved, sys.api.state.deleted).

StateService
StatusStrings
StoredItem

One state entry as read: raw JSON (null when absent) and its ETag.

StoredWrite

One write in a transaction: an upsert (Json set) or a delete, guarded by ETag when set.

StreamIds

Redis stream ids (ms-seq), ordered as the stream orders them.

SubscriptionHealthSweeperHostedService

Periodically probes every subscriber with a heartbeat write and evicts the ones whose channel stays full or closed: their clients are gone or stuck.

TimeoutConstants
TopicCatalog

The topics seen at the gateway, for Pubsub.ListTopics.

Dapr's pubsub API cannot list topics, and asking the broker would tie this to one component (Redis stream keys, Kafka metadata, ...). Every publish and subscribe in Virtufin passes through the gateway, so the gateway records the names itself, in one state-store record (TopicCatalogKey) written with the ETag-guarded operations of IPublicationStateStore.

Note(string, TopicUse) is on the publish path, so it only touches memory: each replica notes a topic at most once per RecordInterval per use, and TopicCatalogWriter merges what is pending into the record in one write. Entries unseen for Retention are dropped then. Per-run reply topics (rpc.<caller>.reply.<run_id>) are never recorded: each is used once, and they would bury the real topics.

TopicCatalogEvents

Announces topics new to the catalog on sys.api.topic.catalog.added (api#56), data {topics: [...]}. Best effort, as the state-change events: a failed publish is logged; a client that missed it reads the catalog again (Pubsub.ListTopics) when it resubscribes.

TopicCatalogWriter

Flushes TopicCatalog every few seconds.

TopicDaprSubscriptionRegistry

The gateway's in-process fan-out broker: one Dapr subscription per topic per API process, shared by every Pubsub.Subscribe call on that topic, each message written to every subscriber's channel.

TopicDaprSubscriptionRegistry.SubscriptionHandle

Per-caller handle. Disposing removes the caller's subscriber.

TopicSighting

When a topic was last published or subscribed through the gateway; 0 = never.

TriggerService

Interfaces

IConsumerGroupPositioner

Moves this gateway pod's Redis consumer group for a topic to the stream's tail right before the gateway opens its Dapr subscription for that topic, so a new subscription only receives messages published after it opened.

IPublicationCapabilityGate

Whether fenced publication can run on the configured state store.

IPublicationStateStore

The state operations fenced publication needs, and nothing provider specific: bulk read with ETags, create-if-absent, and an all-or-nothing transaction whose writes may be ETag-guarded. Any Dapr state store with the ETAG and TRANSACTIONAL capabilities provides them.

Enums

TopicUse

How the gateway saw a topic.