Services Documentation
Detailed documentation for each service component in the Virtufin API.
Table of Contents
- GatewayService
- GrpcReflectionService
- GrpcChannelPool
- PubsubService
- TopicDaprSubscriptionRegistry
- StateService
- ConfigService
- TriggerService
GatewayService
File: Services/GatewayService.cs
The central gRPC service providing gateway functionality including service discovery, method invocation, and event streaming.
gRPC Service Definition
service Gateway {
rpc Invoke (InvokeRequest) returns (InvokeResponse);
rpc InvokeJson (InvokeJsonRequest) returns (InvokeJsonResponse);
rpc ListServices (ListServicesRequest) returns (ListServicesResponse);
rpc ListMethods (ListMethodsRequest) returns (ListMethodsResponse);
rpc GetMethodSchema (GetMethodSchemaRequest) returns (GetMethodSchemaResponse);
}
Methods
Invoke
Invokes a method on a registered backend service.
public override async Task<InvokeResponse> Invoke(
InvokeRequest request,
ServerCallContext context)
Request:
- service - Target service name (e.g., "workmanager")
- method - Method name to invoke
- requestData - JSON payload for the request
Response:
- success - Boolean indicating success
- status - gRPC status code string
- message - Error message if failed
- responseData - JSON response payload
InvokeJson
Invokes a method on a registered backend service using JSON request/response data. The recommended method for most use cases.
public override async Task<InvokeJsonResponse> InvokeJson(
InvokeJsonRequest request,
ServerCallContext context)
Request:
- service - Target service name (e.g., "workmanager")
- method - Method name to invoke
- requestData - JSON payload for the request (as a string)
Response:
- success - Boolean indicating success
- status - gRPC status code string
- message - Error message if failed
- responseData - JSON response payload (as a string)
ListServices
Lists all services registered in the gateway configuration.
public override async Task<ListServicesResponse> ListServices(
ListServicesRequest request,
ServerCallContext context)
Response:
- services - List of service name strings
ListMethods
Lists all methods available on a specific service.
public override async Task<ListMethodsResponse> ListMethods(
ListMethodsRequest request,
ServerCallContext context)
Request:
- service - Service name to query
Response:
- methods - List of MethodInfo objects with name, input/output types, streaming flags
Special Handling:
For virtufin.Gateway or Gateway, returns the built-in gateway methods directly.
GetMethodSchema
Returns the schema for a specific method including input/output types and field definitions.
public override async Task<GetMethodSchemaResponse> GetMethodSchema(
GetMethodSchemaRequest request,
ServerCallContext context)
Request:
- service - Service name
- method - Method name
- type - Schema type to return (typically "input" or "output")
Response:
- schema - MethodSchema object with input_type_name, output_type_name, schema_type, and fields (list of FieldSchema with name, type, type_name, is_repeated, is_optional, oneof_group, oneof_cases)
Used by clients to introspect a service's wire format before calling it.
Note:
Gatewayhas noSubscribeRPC. Event streaming lives on thePubsubservice (Pubsub.Subscribe, topic-filtered only) — see PubsubService and events.md. TheWatchSystemEventsRPC was also removed; per-service lifecycle events are delivered throughPubsub.Subscribeon the appropriate per-service topic (e.g.sys.workmanager.worker.lifecycle, which also carries a WebSocketFeed worker's connection status).
GrpcReflectionService
File: Services/GrpcReflectionService.cs
Provides dynamic gRPC service discovery and invocation using the gRPC Reflection protocol.
Key Classes
| Class | Purpose |
|---|---|
GrpcReflectionService |
Public API, manages per-service caches |
ServiceDescriptorCache |
Per-service descriptor caching and loading |
ServiceMethodInfo |
Method metadata storage |
MethodSchema |
Request/response schema |
FieldSchema |
Field definition |
GrpcCallResult |
Invocation result wrapper |
Public API
GetMethodsAsync
public async Task<List<ServiceMethodInfo>> GetMethodsAsync(
string serviceName,
CancellationToken cancellationToken = default)
Returns all methods for a service discovered via reflection.
GetMethodSchemaAsync
public async Task<MethodSchema?> GetMethodSchemaAsync(
string serviceName,
string methodName,
string? type = null,
CancellationToken cancellationToken = default)
Returns the schema for a method's input or output type.
Parameters:
- serviceName - Service to query
- methodName - Method name
- type - "input" or "output" (default: input)
ExecuteCallAsync
public async Task<GrpcCallResult> ExecuteCallAsync(
string serviceName,
string methodName,
string requestJson,
Dictionary<string, string>? metadata = null,
CancellationToken cancellationToken = default)
Executes a gRPC call by name using reflection data.
Returns: GrpcCallResult with:
- Success - Boolean
- StatusCode - gRPC status
- Message - Error detail
- Data - Response JSON
GetFileDescriptorProtosAsync
public async Task<List<ByteString>> GetFileDescriptorProtosAsync(
string serviceName,
CancellationToken cancellationToken = default)
Returns raw protocol buffer descriptors for the service.
Internal Processing
ServiceDescriptorCache
Manages the cached state for a single service:
- Lazy Loading: Descriptors loaded on first access
- Thread-Safe: Uses locking for initialization
- Descriptor Building: Parses FileDescriptorProtos and builds indexes
- Cache staleness: The cache has no TTL and no invalidation mechanism. If a backend service redeploys with a changed proto schema, the gateway will serve stale descriptors until it restarts. This is a known limitation (tracked as P2-1). In production, restart the gateway after any backend service redeploy that changes proto schemas. A configurable TTL (
REFLECTION_CACHE_TTL_SECONDS) and an invalidation endpoint are planned.
JSON↔Protobuf Conversion
The service handles conversion between JSON and protobuf:
Request (JSON → Protobuf):
1. Try JsonParser.Default.Parse() (preferred)
2. Fall back to field-by-field parsing
Response (Protobuf → JSON):
1. Try msgDesc.Parser.ParseFrom()
2. Fall back to field-by-field binary reading
Well-Known Descriptors
Includes google/protobuf/descriptor.proto, which backend reflection servers
don't return; it is the dependency of any proto declaring custom options.
GrpcChannelPool
File: Services/GrpcChannelPool.cs
Thread-safe pool of gRPC channels organized by service name.
Public API
public GrpcChannel GetChannel(string serviceName)
Gets or creates a gRPC channel for the specified service.
Parameters:
- serviceName - Service name from configuration
Returns: GrpcChannel for the service
Throws: ArgumentException if service not found in configuration
Channel Management
- Lazy Creation: Channels created on first access
- Reuse: Same channel returned for repeated calls to same service
- Lifecycle: All channels disposed on
Dispose()
Configuration Integration
Channels are created using service configuration:
services:
- name: workmanager
protocol: grpc
grpc:
host: localhost
port: 5002
pubsub:
pubsubName: pubsub
state:
storeName: statestore
jobs:
crons: []
Hard requirement: Every service in the configuration must implement gRPC reflection. When a gRPC channel is created for a service, the API Gateway probes for reflection support. If reflection is not available, an
InvalidOperationExceptionis thrown — the channel is not created and the service cannot be proxied. Ensure all backend services register gRPC reflection viaGrpc.AspNetCore.Server.Reflection.
Channel address: http://{host}:{port}
PubsubService
File: Services/PubSubService.cs
Provides pub/sub messaging operations using Dapr pub/sub. Implements the Pubsub gRPC service defined in Protos/pubsub.proto.
gRPC Service Definition
service Pubsub {
rpc PublishEvent (PublishRequest) returns (PublishResponse);
rpc PublishEvents (PublishEventsRequest) returns (PublishEventsResponse);
rpc Subscribe (SubscribeRequest) returns (stream SubscribeResponse);
rpc ListTopics (ListTopicsRequest) returns (ListTopicsResponse);
}
Methods
PublishEvent
Publishes an event to a Dapr topic.
public override async Task<PublishResponse> PublishEvent(
PublishRequest request,
ServerCallContext context)
Request:
- topic - The topic name to publish to
- cloudevent - The CloudEvent message (CloudNative.CloudEvents.V1.CloudEvent proto)
Response:
- success - Boolean indicating success
- status - Status string ("OK" or "ERROR")
- message - Success/error message
PublishEvents
Publishes up to 1000 events in one call, saving a round trip per event.
- Each topic's events are published in the given order, one after another; different topics in parallel.
- Every event is validated first; an invalid one rejects the whole call
(
InvalidArgument, namingevents[i]) before anything is published. - A failed event is listed in
failed_indexesand doesn't stop later events of its topic;publishedcounts the rest.status.successis true only if all were published.
This is not Dapr's bulk publish: on Redis Streams that publishes a batch's events in parallel, with no ordering guarantee.
How events are stored
A CloudEvent with binary data is stored in the stream as a protobuf CloudEvent
(application/cloudevents+protobuf): the attributes plus the bytes as they
are, so binary payloads such as the FlatBuffers order book image are never
base64-encoded. Every other event is stored as a JSON CloudEvent. Subscriptions
read entries as stored (rawPayload) and decode both forms, so a subscriber
gets binary_data or text_data exactly as published.
Subscribe
Subscribes to a topic and streams events as they arrive. Topics are created dynamically (no configuration needed).
public override async Task Subscribe(
PubsubSubscribeRequest request,
IServerStreamWriter<PubsubSubscribeResponse> responseStream,
ServerCallContext context)
Request:
- topic - The topic name to subscribe to
Response: Server-streaming of PubsubSubscribeResponse messages containing:
- topic - The topic name
- cloudevent - The CloudEvent message (CloudNative.CloudEvents.V1.CloudEvent proto)
- message_id - Unique message identifier
- timestamp - ISO 8601 timestamp
ListTopics
Lists the topics seen at the gateway, sorted by name.
Dapr's pubsub API cannot list topics, and asking the broker would tie the
gateway to one pubsub component. Every publish and subscribe passes through the
gateway, so it records the names itself (TopicCatalog): PublishEvent,
PublishEvents, state change events and trigger firings count as published,
Subscribe as subscribed. The record is one state-store key,
sys.api.topic.catalog, written with the same ETag-guarded operations as the
publication fence, so any Dapr state store with ETags and transactions works.
- Each replica notes a topic at most once a minute per use, in memory, and merges what it noted into the record every 5 seconds; times are precise to about a minute.
- A topic drops out after 7 days unseen.
- Per-run reply topics (
rpc.<caller>.reply.<run_id>) are not recorded. - A topic appears only once traffic has passed through the gateway; a component publishing to Dapr directly is invisible.
- Topics new to the record are announced on
sys.api.topic.catalog.added(com.virtufin.api.topic.catalog.added, data{topics: [...]}), one event per merge that added any, by the replica whose write added them (api#56). A client keeps its list current from these instead of asking again; like the state-change events they are best effort, so it lists again after it resubscribes.
Response: topics, each a TopicInfo with topic, last_published and
last_subscribed (timestamps, unset if never seen that way).
TopicDaprSubscriptionRegistry
File: Services/TopicDaprSubscriptionRegistry.cs
The in-process fan-out broker. Dapr pub/sub is competing-consumer, so the gateway holds one Dapr subscription per topic per process and writes each message to every subscriber itself.
AcquireAsync(topic, writer, onActive, ct)adds a Subscribe call's channel as a subscriber, opening the topic's Dapr subscription for the first one;onActivefires once it is open. Disposing the returned handle removes the subscriber; the last one leaving closes the Dapr subscription.- The Dapr subscription runs on its own token: the subscriber that opened it may leave first without ending it for the others.
- If the Dapr subscription ends on its own, every subscriber's channel completes with
Unavailable; the next Subscribe opens a fresh one. SubscriptionHealthSweeperHostedServiceevicts subscribers whose channel stays full or closed.
ConfigService
File: Services/ConfigService.cs
Exposes the service registry configuration — which services are registered, their gRPC
endpoints, and their pubsub / state component names — to admin and observability clients.
Implements the Config gRPC service defined in Protos/config.proto.
One caveat on what this reports.
dapr_app_idwas removed fromConfigService: routing is a direct gRPC dial togrpc.host/grpc.port, never Dapr service invocation.pubsub.pubsub_nameis honoured, but as a gateway-wide setting rather than a per-service one — see events.md.
gRPC Service Definition
service Config {
rpc ListServices (ListConfigServicesRequest) returns (ListConfigServicesResponse);
rpc GetService (GetConfigServiceRequest) returns (GetConfigServiceResponse);
}
Methods
ListServices
Returns all services registered in services.json, each with its Dapr app-id, gRPC host/port, pubsub component name, state store name, and scheduled cron jobs.
Response: ListConfigServicesResponse.services — list of ConfigService protos with name, grpc.{host,port}, pubsub.pubsub_name, state.store_name, jobs.crons[].
GetService
Returns a single service by name, or an empty Service field if not found.
Request: GetConfigServiceRequest.name — service name to look up.
Response: GetConfigServiceResponse.service — ConfigService proto, or unset if the service is not registered.
StateService
File: Services/StateService.cs
Provides state management using the Dapr state store. Implements the State gRPC service
defined in Protos/state.proto.
gRPC Service Definition
service State {
rpc SaveState (SaveStateRequest) returns (SaveStateResponse);
rpc GetState (GetStateRequest) returns (GetStateResponse);
rpc DeleteState (DeleteStateRequest) returns (DeleteStateResponse);
rpc QueryState (QueryStateRequest) returns (QueryStateResponse);
rpc GetBulkState (GetBulkStateRequest) returns (GetBulkStateResponse);
rpc DeleteBulkState (DeleteBulkStateRequest) returns (DeleteBulkStateResponse);
}
message SaveStateRequest {
string service = 1;
string key = 2;
string value = 3; // MUST be valid JSON
string etag = 4;
bool publish_change = 5; // publish a state change event after the write
bool include_value = 6; // include the value in that event
int32 ttl_seconds = 7;
bool create_only = 8; // succeed only if the key does not already exist
}
See proto/state.proto for the full message set.
What service means
service selects the Dapr state store to use, via a lookup in the gateway's
services.json. It must be non-empty and must name a registered service; the match is
exact and case-sensitive, so WorkManager is rejected where workmanager is accepted.
service is not an isolation boundary. The API does not check that key begins with
service, QueryState filters are not scoped to the caller's prefix, and all registered
services currently share one store. Keys follow the {service}.{entity}.{id} convention by
caller-side discipline — see AGENTS.md
for the full convention and its limits.
ETag and Optimistic Concurrency
| Scenario | Behavior |
|---|---|
| No ETag provided | Last-write-wins. The write always succeeds. |
| Matching ETag | Write succeeds. State is updated. |
| Mismatched ETag | Fails with StatusCode.Aborted. Re-read and retry. |
create_only: true, empty ETag |
Succeeds only if the key does not exist; otherwise Aborted, on every store. |
ETag the store cannot parse ("abc" on Redis, whose ETags are numbers) |
Fails with InvalidArgument, naming the bad value. Pass an ETag GetState returned. |
An ETag of "0" is rejected with InvalidArgument — it is the Redis component's
force-write sentinel and would silently defeat the compare-and-swap.
var current = await client.GetStateAsync("workmanager", "sys.workmanager.worker.abc123");
await client.SaveStateAsync("workmanager", "sys.workmanager.worker.abc123", newValue,
etag: current.Etag);
// Throws RpcException with StatusCode.Aborted if the ETag doesn't match.
QueryState
QueryState takes Dapr's query-state JSON DSL and passes it to the store. The store keeps
each value as text (so its numbers and key order survive, see Value fidelity),
so a filter cannot match fields inside a value: query everything and filter by key.
{"filter": {}}
{"filter": {}, "page": {"limit": 50}}
It requires a store whose Dapr component implements the Query API. For Redis/Valkey that
means the RediSearch module must be loaded and the component must declare
queryIndexes metadata; without both, every query fails — including Dapr's "{}"
match-everything query. Use GetBulkState against known keys as the fallback.
limit goes to the store as the query's page.limit, so the store returns at most that many
rows.
The answer holds state documents only, that is, values saved through this service. A store's
query can return other rows: state.postgresql returns every row of its table, among them
the gateway's own records (the topic catalog, the publication fences) and other apps' rows.
The gateway leaves those out. They still count towards the store's page.limit, so on such a
store an answer can hold fewer items than limit while more documents exist. On
state.redis the query index holds state documents only. state.postgresql also returns a
key whose time to live has passed until Dapr deletes its row (the component's
cleanupInterval, one hour by default); GetState answers NotFound for it at once.
Value fidelity
A value comes back byte for byte as it was saved: the same digits and the same key order.
The gateway stores it as a JSON string inside the document, {"virtufin.json": "<value>"},
because daprd's Redis JSON path re-marshals anything else with at most 6 decimals and in
random key order (api#52). A document without it (the value itself, as gateways before
0.15.10 stored it) is an internal error for GetState and GetBulkState, and logged: none
are left since api#54. QueryState leaves such a row out.
State Change Broadcasting
SaveState, DeleteState and DeleteBulkState publish a change event only when the
request sets publish_change: true. Events go to the global topics sys.api.state.saved and sys.api.state.deleted,
not to a per-service topic; the payload carries service, key (or keys), and
action ("save" or "delete").
Setting include_value: true adds the value to that payload — and therefore broadcasts it
to every subscriber of those topics, platform-wide. See events.md.
Error reporting
StateService splits its error channel, which is worth knowing when writing a client:
| RPC | Failure surfaces as |
|---|---|
GetState, GetBulkState, QueryState |
thrown RpcException |
SaveState, DeleteState, DeleteBulkState |
gRPC status OK, status.success == false |
Check status.success on writes; a client that only catches RpcException will read a
failed save as a success. A lost compare-and-swap (a stale ETag, or create_only on a key
that exists) is the exception: it is a thrown RpcException with Aborted.
TriggerService
File: Services/TriggerService.cs
Wraps Dapr's Scheduler API to schedule recurring cron triggers. When a trigger fires,
DaprAppCallbackService publishes an empty CloudEvent to the trigger's target_topic
via Dapr pub/sub.
gRPC Service Definition
service Trigger {
rpc ScheduleTrigger (ScheduleTriggerRequest) returns (ScheduleTriggerResponse);
rpc GetTrigger (GetTriggerRequest) returns (GetTriggerResponse);
rpc DeleteTrigger (DeleteTriggerRequest) returns (DeleteTriggerResponse);
rpc ListTriggers (ListTriggersRequest) returns (ListTriggersResponse);
}
Key Behavior
scheduleis a 6-field cron expression or an@everyduration.- A name is scheduled once. Scheduling it again with the same definition (schedule,
due time, repeats, TTL, target topic, owner) succeeds, so a retried call is safe; a
different definition fails with
ALREADY_EXISTS(delete the trigger first to change it). - Errors are returned in-band as
StatusResponse { success: false }with a gRPC status ofOK— checkstatus.success, not the gRPC status code.ListTriggersis the exception: its response has no status, so a failure fails the call with a gRPC status (an empty list means there are no triggers). - Trigger delivery arrives on Dapr's
AppCallback/OnJobEventroute, implemented byDaprAppCallbackServiceand bound to the stable route byDaprStableAppCallbackMethodProvider.