API Gateway
Purpose
Unified API Gateway providing dynamic gRPC service discovery, JSON-to-Protobuf invocation over gRPC, distributed state management, and pub/sub event streaming for all backend Virtufin services.
Requirements
Requirement: Dynamic Service Discovery
The gateway SHALL discover available backend gRPC services and their methods via gRPC reflection, without requiring pre-compiled proto stubs for each backend.
Scenario: List known services
- WHEN a client calls
ListServices - THEN the gateway SHALL return every dialable service defined in its configuration: a backend it can invoke, which SHALL serve gRPC reflection
- AND an entry that only gives
State.*aservicenamespace SHALL bedialable: falseand SHALL NOT be listed, dialled or asked for reflection:statestore, andworkmanager-runtime, which serves no gRPC API (Dapr actors and health checks only) and persists its records under that namespace
Scenario: List methods for a service
- WHEN a client calls
ListMethodsfor a configured service - THEN the gateway SHALL return all gRPC methods discovered via reflection from that backend
Scenario: Schema introspection
- WHEN a client requests a method's input/output schema
- THEN the gateway SHALL return the full Protobuf message descriptor including field names, types, and oneof groups
Scenario: Reflection cache invalidation
- WHEN a backend service is redeployed with new methods
- THEN the gateway SHALL support invalidating its reflection cache for that service
Requirement: Dynamic gRPC Invocation
The gateway SHALL invoke gRPC methods on backend services without pre-compiled client stubs, using the method name and a JSON or protobuf payload provided at runtime. InvokeJson SHALL follow the protobuf JSON mapping over the backend's reflected descriptors: a field by its proto name or its JSON name, an unknown key or two members of one oneof refused with INVALID_ARGUMENT naming them, null as the default, 64-bit integers as strings or numbers, enums by name or number, bytes as standard or URL-safe base64, and the well-known types (Timestamp, Duration, FieldMask, the wrappers, Struct, Value, ListValue, Empty, Any) in their JSON forms. Its answer SHALL use proto field names and include default values. The mapping SHALL be checked in CI against Google.Protobuf's JSON parser and formatter on compiled test messages.
Scenario: JSON-to-Protobuf invocation
- WHEN a client sends a JSON payload with a service name and method name
- THEN the gateway SHALL dynamically marshal the JSON into the method's Protobuf input type, invoke the backend, and return the Protobuf output as JSON
Scenario: Raw bytes invocation
- WHEN a client sends a raw Protobuf-encoded byte payload
- THEN the gateway SHALL forward it directly to the backend method and return the raw response bytes
Scenario: A misspelt field
- WHEN an
InvokeJsonrequest namescodeSorce - THEN the gateway SHALL answer INVALID_ARGUMENT naming the key and the message's fields, and SHALL NOT call the backend
Requirement: gRPC-only Business APIs
API and WorkManager SHALL expose business operations only as gRPC services: native gRPC, and on the API gateway also gRPC-Web for browsers. Their HTTP ports SHALL serve only the health/readiness probes (and, on the gateway, gRPC-Web); required Dapr callbacks SHALL remain available. Service protos SHALL NOT carry google.api.http annotations.
Scenario: Plain HTTP request to a business path
- WHEN a caller sends a plain (non-gRPC) HTTP request for anything other than a probe
- THEN it SHALL NOT execute a business operation
- AND business operations SHALL be reachable through the generated gRPC SDKs or gateway invocation over gRPC
Scenario: Health endpoints served
- WHEN Kubernetes probes an HTTP health or readiness endpoint
- THEN the service SHALL answer the probe
Scenario: gRPC-Web browser access
- WHEN a browser client connects via gRPC-Web
- THEN the gateway SHALL upgrade the request and forward it as native gRPC to the backend
Requirement: Distributed State Management
The gateway SHALL provide CRUD operations on the Dapr state store with optimistic concurrency control via ETags. State changes SHALL emit events when the caller opts in.
Scenario: Save state with ETag
- WHEN a client saves state with an ETag that matches the stored value
- THEN the save SHALL succeed and the new ETag SHALL be returned
Scenario: Save state with stale ETag
- WHEN a client saves state with an ETag that does not match the stored value
- THEN the save SHALL fail with a concurrency conflict error
Scenario: State change events
- WHEN state is saved or deleted and the request enables change notification
- THEN a state change event SHALL be published, on the topic determined by the State Change Events requirement in pubsub-topics
- AND when the request does not enable it, no event SHALL be published — emitting one is opt-in per request, not a property of every state change
Scenario: Bulk state retrieval
- WHEN a client requests multiple keys in one call
- THEN the gateway SHALL return the stored value for each key it holds
- AND the client SHALL supply the keys explicitly: the gateway maintains no registry of a service's keys, so there is no "all state for this service" operation
Scenario: Bulk state deletion with partial failure
- WHEN a bulk delete succeeds for some keys and fails for others
- THEN the response SHALL identify the keys that failed, so the caller can retry those rather than repeating the whole batch
- AND any change event SHALL name only the keys actually deleted
Requirement: API Client Interface
The C# client SHALL expose its operations behind capability interfaces (IStateApi, IPubsubApi, ITriggerApi, IGatewayApi) composed into IVirtufinApi, implemented by the gateway client (ApiClient) and by an in-memory local client (LocalVirtufinApi, Worker.DevKit) that workers see under a local host. IGatewayApi SHALL offer a typed Invoke (request and response as protobuf messages over Gateway.Invoke, no reflection) whose in-band failure surfaces as GatewayInvokeException with the gateway's status. The local client SHALL keep the gateway's observable semantics: etags are versions (etag "0" is invalid; a lost compare-and-swap or create-only write fails as a concurrency conflict; a missing key is not found), a save or delete with change notification publishes the Tier 0 state change event (or the caller's override verbatim), events a worker publishes through the API during a call are delivered before that call's outputs (the gateway publishes at once; a host publishes outputs after the call returns), and @every triggers fire on the host's clock; QueryState SHALL fail as not supported.
Scenario: Same worker, two clients
- WHEN a worker saves and reads state through
context.Apiunder the Runtime and under a local host - THEN the sequence of values and etags it observes SHALL be the same, and a stale etag SHALL fail with a concurrency conflict on both
Scenario: Typed invoke failure
- WHEN a typed
Invokereaches a service that answers with an in-band failure (DEADLINE_EXCEEDED,UNAVAILABLE,NOT_FOUND,FAILED_PRECONDITION, …) - THEN the client SHALL throw
GatewayInvokeExceptioncarrying that status, withIsTransienttrue only forDEADLINE_EXCEEDEDandUNAVAILABLE
Requirement: Pub/Sub and Event Streaming
The gateway SHALL support publishing events to Dapr pub/sub topics and subscribing clients to topic events via server-side streaming. Dead subscriptions SHALL be cleaned up.
Scenario: Publish event
- WHEN a client publishes an event to a topic
- THEN the gateway SHALL forward it to Dapr pub/sub on that topic
Scenario: Subscribe to events
- WHEN a client opens a server-side streaming subscription to a topic
- THEN all events published to that topic SHALL be streamed to the client until the subscription is cancelled
Scenario: Dead subscription cleanup
- WHEN a subscriber's connection drops without explicit unsubscribe
- THEN the gateway SHALL detect the dead subscription and remove it within one minute
Requirement: Service Configuration
The gateway SHALL load per-service configuration from a JSON or YAML file, specifying each backend's gRPC host/port, Dapr app ID, pubsub component, state store, and optional cron jobs.
Scenario: Configuration hot-reload
- WHEN the services configuration file is updated
- THEN the gateway SHOULD reload the configuration without restarting
Requirement: API Documentation
The gateway SHALL document its gRPC services and expose their descriptors through gRPC reflection.
Scenario: gRPC service documentation
- WHEN a developer requests service descriptors through gRPC reflection
- THEN the gateway SHALL return descriptors for its own and discovered backend gRPC services
Requirement: PubSub CloudEvent Propagation
PublishEvent SHALL receive a complete io.cloudevents.v1.CloudEvent proto from the caller and publish it as-is to Dapr — the gateway SHALL NOT add, remove, or modify CloudEvent attributes. The caller is responsible for constructing the CloudEvent with all desired attributes (id, source, type, time, etc.).
Scenario: Pure passthrough
- WHEN a caller invokes
PublishEventwith a CloudEvent - THEN the gateway SHALL publish it to Dapr exactly as received, without adding, removing, or modifying any attribute
Scenario: Request-reply correlation
- WHEN a request-reply client (
PublishWithResult) callsPublishEvent - THEN it SHALL have already set
correlationidandreplytopicas CloudEvent attributes before the call
Requirement: CloudEvent Time Attribute
The CloudEvent time attribute (RFC 3339) SHALL be carried as a standard CloudEvent attribute in the proto's attributes map with type ce_timestamp — the caller sets it directly on the io.cloudevents.v1.CloudEvent proto, with no metadata indirection; it flows from publisher through Dapr to subscriber as part of the standard CloudEvent payload.
Scenario: Caller-supplied time
- WHEN a client publishes a CloudEvent with
attributes["time"]set to ace_timestampvalue - THEN the CloudEvent
timeattribute SHALL be preserved in the published event
Scenario: Default time
- WHEN a client publishes a CloudEvent without a
timeattribute - THEN the gateway SHALL NOT add a default — the caller owns the CloudEvent entirely
Scenario: Publish with correlation ID (request-reply)
- WHEN a client calls PublishWithResult with a CloudEvent
- THEN the client library SHALL set
correlationidandreplytopicas CloudEvent string attributes before passing to PublishEvent - AND the Subscribe handler SHALL extract the correlation ID from
SubscribeResponse.Cloudevent.Attributes["correlationid"]
Scenario: Publish without correlation ID
- WHEN a client publishes an event without
correlationidin metadata - THEN the gateway SHALL publish the event normally without the correlation ID key
Requirement: PubSub Metadata Extraction
The Subscribe handler SHALL extract correlation IDs from Dapr TopicMessage.Extensions using Value.StringValue (not Value.ToString()) to avoid JSON-quoted string artifacts. Extracted metadata SHALL be forwarded to gRPC subscribers via BroadcastToTopicAsync.
Scenario: Extract StringValue metadata
- WHEN a Dapr message arrives with a
correlationidextension of kindStringValue - THEN the handler SHALL extract the raw string value without surrounding JSON quotes and include it in the gRPC subscriber broadcast metadata
Scenario: Non-string metadata kind
- WHEN a Dapr message arrives with a
correlationidextension of a non-StringValue protobuf kind - THEN the handler SHALL skip that extension rather than producing a JSON-encoded string
Requirement: Per-service Pubsub and State
The gateway SHALL expose the regular Pubsub (PublishEvent, PublishEvents, Subscribe (cancel the call to unsubscribe), ListTopics, ChangePublicationFence; deprecated: PublishFenced, Unsubscribe) and State (SaveState, GetState, DeleteState, QueryState, GetBulkState, DeleteBulkState) RPCs for general use by any service.
Scenario: Service uses its own topic and state entry
- WHEN a service calls the
Pubsub/StateRPCs - THEN it SHALL use the topics and keys of its own naming fragment and its own state service entry (matching its service name in
services.json) — not another service's
Requirement: Authentication
The gateway SHALL enforce a shared-secret x-api-key scheme on all
business surfaces: native gRPC and gRPC-Web. Health check paths
SHALL be exempt. Authentication is enabled only when at least one key is
configured; when no keys are configured, the gateway SHALL treat this as
an intentional local-development default in the Development environment,
and SHALL surface it loudly (a critical-level log at startup and a failed
readiness health check) in any other environment, rather than silently
running unauthenticated.
Scenario: Valid key on gRPC
- WHEN a native gRPC or gRPC-Web call presents a configured
x-api-key - THEN the call SHALL proceed, attributed in logs to the matching key's name
Scenario: Valid key on a plain HTTP request
- WHEN a plain (non-gRPC) HTTP request presents a configured
x-api-keyheader - THEN no business operation SHALL execute
Scenario: Missing or invalid key
- WHEN a call or request presents no key, or a key that does not match any configured key
- THEN it SHALL be rejected --
Unauthenticatedfor gRPC, HTTP 401 for HTTP -- while keys are configured
Scenario: Health checks are exempt
- WHEN a request targets
grpc.health.v1.Health/*,/health, or/healthz - THEN it SHALL be served without requiring
x-api-key, regardless of whether authentication is otherwise enabled
Scenario: Endpoint classification is not caller-controlled
- WHEN the HTTP-surface middleware decides whether a request is native gRPC or gRPC-Web (and therefore already covered by the gRPC-side interceptor) versus a plain HTTP route
- THEN that decision SHALL be based on server-resolved routing
information from the matched endpoint, not on any client-supplied
request header -- a caller-controlled signal (e.g.
Content-Type) SHALL NOT be sufficient to bypass authentication on a route that isn't actually gRPC
Scenario: No keys configured in Development
- WHEN the gateway starts with no
ApiAuth:Keysconfigured and the environment is Development - THEN authentication SHALL be disabled and the gateway SHALL start normally -- this is the intended zero-config local-dev default
Scenario: No keys configured outside Development
- WHEN the gateway starts with no
ApiAuth:Keysconfigured and the environment is not Development - THEN authentication SHALL still be disabled (the same zero-config behavior, not a hard failure) -- but the gateway SHALL log a critical-level warning at startup and SHALL fail its readiness health check, so an accidental unauthenticated deployment is loudly visible rather than silent
Requirement: Publication Fence
The API SHALL provide Pubsub.ChangePublicationFence for publishers whose ownership moves between processes: the WorkManager Runtime's worker lease (worker-management, Worker Lease), keyed by the worker id. A fence holds a token, an active flag and a lease (lease_seconds). The API SHALL keep fences in a Dapr state store, SHALL rely only on the store's ETAG and TRANSACTIONAL capabilities (checked against the sidecar's metadata) and never on a provider-specific API, and SHALL assume atomicity only for single-key ETag-guarded writes.
Scenario: Claim requires current token, inactive fence or expired lease
- WHEN
ChangePublicationFencecarries a freshnew_token - THEN it SHALL succeed only if
expected_tokenis current, the fence is inactive or absent, or the lease expired; otherwiseABORTED
Scenario: Renew and revoke are holder-only
- WHEN
new_tokenequalsexpected_token - THEN the API SHALL renew (
active) or revoke (!active) only if that token is current, and SHALL never reactivate an inactive fence this way
Scenario: Superseded holder learns it on renewal
- WHEN a successor has claimed the fence and the previous holder renews with its old token
- THEN the API SHALL answer
ABORTED
Scenario: Concurrent claims
- WHEN several activations claim an absent fence at once
- THEN exactly one SHALL succeed
Scenario: Store without the capabilities
- WHEN the publication state store lacks ETAG or TRANSACTIONAL
- THEN the fence RPCs SHALL fail with
FAILED_PRECONDITIONnaming the missing capability, and other RPCs SHALL be unaffected
Scenario: Abandoned fences are removed
- WHEN a fence has been inactive or expired for two leases
- THEN the API SHALL delete it
Requirement: Pub/Sub Backend Hooks By Component Type
Backend-specific subscription handling (positioning a new subscription at the stream tail, waking parked readers, acking abandoned entries) SHALL be selected by the loaded Dapr pub/sub component's type. Only pubsub.redis SHALL get the Redis implementation; other backends SHALL start subscriptions as their component configures.
Scenario: Non-Redis pub/sub
- WHEN the pub/sub component is not
pubsub.redis - THEN the API SHALL make no direct connection to any backend for subscriptions