Skip to content

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.* a service namespace SHALL be dialable: false and SHALL NOT be listed, dialled or asked for reflection: statestore, and workmanager-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 ListMethods for 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 InvokeJson request names codeSorce
  • 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.Api under 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 Invoke reaches a service that answers with an in-band failure (DEADLINE_EXCEEDED, UNAVAILABLE, NOT_FOUND, FAILED_PRECONDITION, …)
  • THEN the client SHALL throw GatewayInvokeException carrying that status, with IsTransient true only for DEADLINE_EXCEEDED and UNAVAILABLE

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 PublishEvent with 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) calls PublishEvent
  • THEN it SHALL have already set correlationid and replytopic as 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 a ce_timestamp value
  • THEN the CloudEvent time attribute SHALL be preserved in the published event

Scenario: Default time

  • WHEN a client publishes a CloudEvent without a time attribute
  • 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 correlationid and replytopic as 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 correlationid in 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 correlationid extension of kind StringValue
  • 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 correlationid extension 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/State RPCs
  • 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-key header
  • 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 -- Unauthenticated for 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:Keys configured 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:Keys configured 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 ChangePublicationFence carries a fresh new_token
  • THEN it SHALL succeed only if expected_token is current, the fence is inactive or absent, or the lease expired; otherwise ABORTED

Scenario: Renew and revoke are holder-only

  • WHEN new_token equals expected_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_PRECONDITION naming 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