Cross-cutting
Purpose
Shared infrastructure, security, observability, and resilience requirements that apply across all Virtufin services. Every service SHALL conform to these requirements.
Topic and state-key naming conventions live in pubsub-topics/spec.md; scenario registry conventions live in scenarios/spec.md. This spec covers the access patterns (API-mediated access, ownership) and the non-naming cross-cutting concerns.
Requirements
Requirement: API-Mediated Pub/Sub and State
Services MUST NOT call DaprClient.PublishEventAsync, DaprClient.GetStateAsync, DaprClient.SaveStateAsync, DaprClient.DeleteStateAsync, GetBulkStateAsync, or any other Dapr pubsub or state API directly. Services MUST use the virtufin-api's Pubsub and State gRPC services (listed in api-gateway §Per-service Pubsub and State) for all pubsub and state operations.
The virtufin-api is the only service that talks to Dapr pubsub/state on behalf of other services. This gives the API a single place for access control, observability, and state ownership. It does not validate topic names: Pub/Sub Topics spec §No Topic or Scenario-State Validation Anywhere is the one statement of that rule.
The high-volume data plane is no exception: a WebSocketFeed worker publishes every received frame through its host's outbox, which publishes through the API like every worker output (websocket-feed §Frame Publishing).
Scenario registry management (create / pause / archive / delete) uses the same generic State RPCs, not dedicated scenario RPCs -- per scenarios/spec.md, "No new RPCs SHALL be added to virtufin-api for scenario management"; virtufin-api stays pure infrastructure with no domain logic.
Scenario: Service publishes an event
- WHEN a service needs to publish an event
- THEN it SHALL call
Pubsub.PublishEvent(orPubsub.PublishEventsfor a batch) on the virtufin-api (gRPC) - AND it SHALL NOT call
DaprClient.PublishEventAsyncdirectly
Scenario: Service reads or writes state
- WHEN a service needs to read or write persistent state
- THEN it SHALL call the API's
StategRPC service - AND it SHALL NOT call any Dapr state API directly
Scenario: Dapr sidecar usage
- WHEN a service uses Dapr for actors, secrets, service-invocation, mTLS, distributed tracing, or metrics
- THEN the Dapr sidecar is the right path; pubsub and state go through the API
Requirement: Topic Naming (delegated to pubsub-topics spec)
Topic patterns, the naming library and its fragments, the CloudEvents envelope contract, scenario ID conventions and the state-key taxonomy are defined in pubsub-topics/spec.md. This spec does NOT duplicate those rules; services SHALL conform to them.
Scenario: Subscriber consumes another service's events
- WHEN a service needs to consume another service's events
- THEN it SHALL build the topic with the naming library from the publisher's fragment (e.g.
virtufin.service.workmanager) and callPubsub.Subscribewith it, never a hand-copied string
Scenario: Topic name is a public contract
- WHEN a publisher changes a name in its fragment
- THEN it is a breaking change for every subscriber, released under the pubsub-topics Delete-on-Deploy rule
Requirement: Per-service State Service Names
Each service uses its own state service entry (the entry in the API's services.json matching the service's name). Callers use the regular State.* RPCs with the service field set to the per-service name (e.g. workmanager). There are no State.*System* RPC variants.
The service field selects the Dapr state store to use and SHALL name an entry registered in services.json; the match is exact and case-sensitive. Its effect is limited to that resolution. The sys.<service>.<entity>.<id> key convention (pubsub-topics, State Keys) is caller-side discipline — it keeps keys legible and makes prefix queries useful — and is NOT enforced by the API. See the Trust Model requirement.
Scenario: Service reads or writes its own state
- WHEN a service needs to read or write its own persistent state
- THEN it SHALL call the regular
State.*RPCs withservice: "<service-name>" - AND it SHALL NOT call any
State.*System*variant (none exist)
Scenario: Service keeps to its own key namespace
- WHEN a service writes state
- THEN it SHALL prefix its own keys with
sys.<service>., by convention - AND it SHALL NOT rely on the API to reject a key that does not
Scenario: Unregistered or wrong-case service name
- WHEN a caller passes a
servicethat is not registered inservices.json, or differs from a registered name only by case - THEN the API SHALL reject the call as a caller error (
InvalidArgument), not as a server fault
Requirement: Lifecycle Events as CloudEvents v1.0
Services that publish lifecycle events MUST format them as CloudEvents v1.0 envelopes. The CloudEvents attributes (ce-id, ce-source, ce-type, ce-time, ce-specversion, ce-datacontenttype) MUST be carried in the request metadata field, prefixed with ce-. The CloudEvents data field MUST be the request's data field.
Scenario: Connection lifecycle event
- WHEN a WebSocket connection is established, reconnects, or drops (a WebSocketFeed worker reports its own state)
- THEN it SHALL be published as a worker lifecycle event (below) with
state = status,statusanddetail, never on a connection topic of its own
Scenario: Worker lifecycle event
- WHEN a service publishes a worker lifecycle event (registered, online, stopped, failed, loaded, load-failed)
- THEN it SHALL publish to
sys.workmanager.worker.lifecycleand setce-typetocom.virtufin.workmanager.worker.lifecycle - AND
ce-sourcetourn:com.virtufin:workmanager - AND the data payload to a JSON object with
state,worker_id,topic(anderror_type/error_messagefor error events)
Requirement: API Endpoint Configuration
Services that call the virtufin-api MUST accept the API's gRPC endpoint via configuration. The endpoint SHALL be configurable via environment variables (VIRTUFIN_API_HOST, VIRTUFIN_API_GRPC_PORT) with sensible defaults (localhost:5002).
Scenario: Production deployment
- WHEN a service is deployed to a cluster
- THEN
VIRTUFIN_API_HOSTandVIRTUFIN_API_GRPC_PORTSHALL be set to the cluster-internal address of the virtufin-api service
Scenario: Local development
- WHEN a service runs locally
- THEN the default
localhost:5002is used unless overridden
Requirement: Observability
Every service SHALL emit OpenTelemetry traces and metrics. Health checks SHALL gate readiness until the service is fully initialized.
Scenario: Distributed tracing
- WHEN a request is processed across multiple services
- THEN each span SHALL be exported to the configured OpenTelemetry collector with correlation context
Scenario: Liveness and readiness
- WHEN a service starts up and before it recovers its persistent state
- THEN the readiness health check SHALL fail, preventing traffic routing
Scenario: Startup recovery
- WHEN a service restarts after a crash
- THEN it SHALL restore its persisted state before marking itself healthy
Requirement: Resilience
All Dapr operations and external calls SHALL use retry with exponential backoff and circuit breaking.
Scenario: Transient Dapr failure
- WHEN a Dapr API call fails with a transient error
- THEN the operation SHALL be retried up to 3 times with exponential backoff before failing
Scenario: Persistent failure
- WHEN Dapr API calls consistently fail beyond a threshold
- THEN the circuit breaker SHALL open, failing fast for subsequent calls until the break duration elapses
Requirement: Security
All service-to-service communication SHALL be encrypted. User-supplied code execution's isolation level SHALL match its engine class: subprocess-based engines SHALL run code in a sandboxed subprocess with restricted I/O; in-process engines run with the same trust as the host process and SHALL require their code source be fully-trusted rather than sandboxed at execution time. URL-based code fetching SHALL prevent SSRF.
Authentication at the API gateway is a single flat API-key set: a presented key is matched against the configured keys and yields a key name used for log attribution only. There is no binding from key to permitted service, key namespace, or topic. Authorization between first-party services is out of scope by the Trust Model requirement.
Scenario: Service-to-service communication
- WHEN one service communicates with another
- THEN Dapr mTLS SHALL encrypt the connection
Scenario: API key scope
- WHEN a caller presents a valid API key
- THEN it SHALL be authorized for every
service, state key, and topic the gateway exposes - AND operators SHALL treat issuing a key as granting full access to platform state and pub/sub
Scenario: Credential propagation across the proxy
- WHEN the gateway proxies a call to a backend service
- THEN it SHALL NOT forward the caller's API key to that backend
- AND it SHALL forward only an explicit allow-list of headers (tracing and correlation identifiers), since backends authenticate to the gateway with their own credentials
Scenario: Subprocess-isolated code execution
- WHEN a worker runs on a subprocess-based engine (e.g. Python)
- THEN the engine SHALL launch it in a sandboxed subprocess with no ambient access to the host process's own memory or file handles
- AND, for a raw-source Python worker specifically, the subprocess
SHALL additionally enforce a configurable blocked-module/restricted-I/O
list (see
worker-management's Python Sandboxing requirement) -- a Python worker packaged as a wheel relies on publish-time dependency vetting instead, not this list
Scenario: In-process code execution
- WHEN a worker runs on an in-process engine (e.g. compiled C# source, managed DLL, native DLL)
- THEN the worker code SHALL execute with the same privileges as the host process, with no sandboxing at execution time
- AND the service SHALL restrict that engine to fully-trusted code sources only (e.g. a registered, content-addressed package feed) rather than relying on runtime isolation
Scenario: SSRF prevention
- WHEN fetching code from a user-supplied URL
- THEN the service SHALL reject URLs targeting private IP ranges (loopback, RFC1918, link-local) unless the host is in an explicit allowlist
Requirement: Native AOT Compilation
Services targeting AOT-capable runtimes SHALL compile to native code. All JSON serialization SHALL use source-generated contexts.
Scenario: Build and deployment
- WHEN a service is built for production
- THEN it SHALL compile to a self-contained native binary with trimmed dependencies
Requirement: Configuration
Every service SHALL support configuration via command-line arguments, environment variables, and configuration files. Ports SHALL be configurable. Dapr component names SHALL be configurable.
Scenario: Port override
- WHEN the
HttpPortenvironment variable or--http-portargument is set - THEN the service SHALL listen on that port instead of the default
Scenario: Dapr component override
- WHEN
pubsubNameis configured - THEN the service SHALL use the named Dapr pubsub component for all pub/sub operations
Requirement: Containerization
Every service SHALL be containerizable as a minimal Docker image based on the chiseled runtime image.
Scenario: Docker build
- WHEN a service's Dockerfile is built
- THEN the resulting image SHALL contain only the native AOT binary and its runtime dependencies on a
runtime-depsbase
Requirement: Trust Model
The Virtufin service mesh SHALL be treated as a trusted mesh. Every caller holding a valid API key is first-party and mutually trusting. service names, state key prefixes, and topic names are routing and component-resolution identifiers; they are NOT security boundaries, and the platform SHALL NOT be relied upon to isolate one service's data from another's.
Concretely: all registered services resolve to one Dapr state store and one pub/sub component; the API validates that a service is registered but does not check that a state key begins with it; QueryState filters are not scoped to the caller's prefix; and any authenticated caller may publish to or subscribe to any topic. A valid API key therefore grants full access to platform state and pub/sub.
This is a deliberate position, not an unimplemented intention. Isolation enforced at the gateway would stop an honest mistake but not a determined caller, who can reach the same Dapr components through the sidecar; real isolation requires per-service stores and credentials, which also forecloses legitimate cross-service reads.
Scenario: Service reads another service's state
- WHEN a service calls
State.GetStatewith akeyoutside its ownsys.{service}.prefix - THEN the call SHALL succeed
- AND this SHALL NOT be treated as a defect in the API
Scenario: Broad state query
- WHEN a caller issues
QueryStatewith a filter broader than its own prefix, including Dapr's{}match-everything query - THEN the query SHALL return matching entries across every service's keys
- AND callers SHALL treat the store as a shared namespace when reasoning about what a query returns
Scenario: Subscribing to another service's topic
- WHEN an authenticated caller subscribes to a topic it does not own, including
sys.api.state.savedor another service'ssys.<service>.*topics - THEN the subscription SHALL succeed
Scenario: Documentation states the boundary
- WHEN a proto comment, README, or doc page describes state keys, topics, or the
servicefield - THEN it SHALL NOT claim namespace enforcement, isolation, or rejection of out-of-namespace access
- AND where the topic arises it SHALL state that the convention is caller-side discipline
Scenario: Trust set changes
- WHEN a caller that is not first-party is admitted to the mesh — a third party, a customer-supplied integration, or any principal outside the operating team
- THEN this requirement SHALL be revisited before that caller is granted an API key
- AND isolation SHALL be reconsidered as required rather than optional, since the assumption this requirement rests on no longer holds