Skip to content

Services Documentation

Detailed documentation for each service component in the Virtufin API.

Table of Contents


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: Gateway has no Subscribe RPC. Event streaming lives on the Pubsub service (Pubsub.Subscribe, topic-filtered only) — see PubsubService and events.md. The WatchSystemEvents RPC was also removed; per-service lifecycle events are delivered through Pubsub.Subscribe on 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 InvalidOperationException is thrown — the channel is not created and the service cannot be proxied. Ensure all backend services register gRPC reflection via Grpc.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, naming events[i]) before anything is published.
  • A failed event is listed in failed_indexes and doesn't stop later events of its topic; published counts the rest. status.success is 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; onActive fires 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.
  • SubscriptionHealthSweeperHostedService evicts 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_id was removed from ConfigService: routing is a direct gRPC dial to grpc.host/grpc.port, never Dapr service invocation. pubsub.pubsub_name is 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

  • schedule is a 6-field cron expression or an @every duration.
  • 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 of OK — check status.success, not the gRPC status code. ListTriggers is 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 / OnJobEvent route, implemented by DaprAppCallbackService and bound to the stable route by DaprStableAppCallbackMethodProvider.