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.apinaming 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
timestring that is not RFC3339). Callers map it to an invalid-argument error naming Attribute -- it is bad input, not a server fault.
- ConfigService
Implementation of the gRPC Config service. Provides service configuration discovery and management capabilities.
- 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
AppCallbackservice that the runtime actually calls:OnJobEvent(scheduled job delivery) andListTopicSubscriptions(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 ownappcallback.proto. The .NET SDK lags it: the generated code inDapr.Protos1.18.2 containsOnJobEventAlpha1onAppCallbackAlphaand noOnJobEventanywhere, 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 byApiKeyHttpMiddleware(which exempts only requests whose matched endpoint carriesGrpcMethodMetadata). Net effect: **no scheduled trigger ever fired**, while Dapr retried roughly once a second forever.Registering the method here rather than regenerating
appcallback.protointo this repo is deliberate: the request and response types already exist inDapr.Protosand 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, soApiKeyHttpMiddlewarelets it through toApiKeyInterceptor, 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 OnJobEventon DaprAppCallbackService.
- DescriptorSymbols
The fully-qualified symbols a proto file defines, as gRPC server reflection's
file_containing_symbolresolves them (any symbol protobuf's descriptor pool finds by name, which is whatgrpcurl describesends): 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/InvokeJsonreport inInvokeResponse.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.
- 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/JsonFormatterneed 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 (JsonFormatterwithPreserveProtoFieldNamesandFormatDefaultValues): 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.redishas one; other backends start subscriptions as their component configures (e.g. KafkainitialOffset: newest).
- PubsubReplayOptions
Bounds of a
replay_sinceSubscribe (configurationPubsubReplayMaxEntries,PubsubReplayMaxBytes): a replay of more retained entries, or more payload bytes, is refused withOUT_OF_RANGEbefore 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).
- StateChangeEvents
CloudEvent attributes for the Tier 0 state-change topics (
sys.api.state.saved,sys.api.state.deleted).
- 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.
- 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.Subscribecall 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.
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.