AIFACTORY-FEAT-055: DataEventFoundations: gateway delivery¶
Generated from the architecture model
This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
A design artefact, not a tracker
This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).
Epic Data & Event Platform (PF-11) · Increment I4 Trust and accountability · State elaborated · Route backend-developer · Build order 125 of 185 (Factory code)
DataEventFoundations is the platform API gateway of bounded context BC-42 (Data & Event Foundations). The API gateway of the Data & Event platform (ADR-0028): routes public REST and internal gRPC calls to the 3 services it fronts, validates tokens and scopes, and owns no business state. Its own repository is ConnectSoft.AI.SoftwareFactory.DataEventFoundations.
| Delivers | DataEventFoundations (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0006, ADR-0012, ADR-0013, ADR-0014, ADR-0019 |
| Requirements | FR-10, FR-12, FUX-11, NFR-05, NFR-14, NFR-16, XL-02, XL-09 |
| Depends on | — |
| Sources | model/services/data-event/DataEventFoundations.yaml |
Scenarios to trace (5, catalog): SCN-DataEventFoundations-001 ✓, SCN-DataEventFoundations-002 ✓, SCN-DataEventFoundations-003 ✓, SCN-DataEventFoundations-004 ✓, SCN-DataEventFoundations-005 ✓
AIFACTORY-US-086: DataEventFoundations routes its platform's calls under a trusted scope¶
enabling · persona platform-admin
As a platform admin, I want one gateway in front of EnvelopeRegistryService, RetentionResidencyService and StoreProfileService that validates tokens and scopes, so that no service of the platform is reachable except through its gateway and every call arrives with a scope it can trust.
This is the integration PBI of the Data & Event gateway. ADR-0028 makes DataEventFoundations the API gateway of its platform: it routes public REST and internal gRPC calls to the three services the model lists under deployment.fronts (EnvelopeRegistryService, RetentionResidencyService and StoreProfileService), validates tokens and scopes and owns no business state. The repository ConnectSoft.AI.SoftwareFactory.DataEventFoundations is created by the repository checklist of feature repository-and-pipeline-conventions and scaffolded from the pinned API gateway template package with UseFactoryProfile and the gateway role Platform, which fixes persistence, messaging and the actor model to none: the gateway has no relational store, no outbox and no inbox and consumes no event (ADR-0028 amendment on gateways and events). The scope of a call is established once from the validated token with the scope accessor of the pinned ConnectSoft.Extensions.AI.Factory.Abstractions package, never copied. The gateway forwards the user token to the fronted service unchanged and exchanges no token, and the fronted service accepts the audience of its own gateway (ADR-0015 amendment D117). The feature is delivered by five PBIs: the fronts file and the routes generated from it (AIFACTORY-US-1441), token, tenant and scope on every read route and on the internal gRPC routes (AIFACTORY-US-1442), the pass-through of a shared-write call (AIFACTORY-US-1443), the production routes whose gate stays in the fronted service (AIFACTORY-US-1444), and health, profiles, limits and telemetry with the three failure modes of a gateway (AIFACTORY-US-1445). None of the routes of this platform names a project in its path; the tenant comes from the token, and a route that names a resource id (a topic, a store, an order) is forwarded under the tenant of the token, the fronted service answering 404 for a resource of another tenant (ADR-0015 amendment D113). The three fronted services are delivered in the same increment, so every route reaches its real service. The gateway invents no response.
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.DataEventFoundations, whose first commit is the unchanged output of dotnet new connectsoft-apigateway -n ConnectSoft.AI.SoftwareFactory.DataEventFoundations --UseFactoryProfile true --GatewayRole Platform from the pinned template package, when its pipeline runs with the work of this feature, then no second scaffold was run, the solution builds, the tests pass and a container image is published (ADR-0028, model/services/data-event/DataEventFoundations.yaml). |
| AC2 | Given a valid token for a route of each of EnvelopeRegistryService, RetentionResidencyService and StoreProfileService, when the call passes the gateway, then the scope is established once from the token, the call is forwarded with the user token unchanged, the tenant and the correlation id, the fronted service answers and the response returns unchanged, as AIFACTORY-US-1442 to AIFACTORY-US-1444 prove per route class (ADR-0015, model/scenarios/DataEventFoundations.yaml). |
| AC3 | Given the generated gateway, when its architecture test runs, then the test fails on a persistence model, an aggregate, a migration or a message consumer, the gateway binds no relational store, no outbox and no inbox, and no event of the model lists DataEventFoundations as a consumer (ADR-0028, model/services/data-event/DataEventFoundations.yaml). |
| AC4 | Given the gateway deployed with two replicas, when DataEventFoundations/DataEventHealth is probed and one replica is stopped, then health reports the identity platform and the three fronted services, the other replica keeps serving and nothing is replayed, because the gateway holds no state (ADR-0017, model/services/data-event/DataEventFoundations.yaml). |
| Traces: services | DataEventFoundations, EnvelopeRegistryService, RetentionResidencyService, StoreProfileService |
| Traces: apis | DataEventFoundations/DataEventHealth |
| Traces: adrs | ADR-0006, ADR-0012, ADR-0013, ADR-0015, ADR-0017, ADR-0018, ADR-0028 |
| Traces: requirements | FR-10, FR-12 |
| Depends on | AIFACTORY-US-1441, AIFACTORY-US-1442, AIFACTORY-US-1443, AIFACTORY-US-1444, AIFACTORY-US-1445, feature:repository-and-pipeline-conventions, feature:component-api-gateway-template, feature:component-extensions-ai |
| Sources | model/services/data-event/DataEventFoundations.yaml, model/gateways.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/data-event/services/data-event-foundations/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-371 Create the repository ConnectSoft.AI.SoftwareFactory.DataEventFoundations and scaffold it from the ConnectSoft.ApiGatewayTemplate template with the Factory profile and the Platform role |
implementation | The repository exists by the repository checklist of feature repository-and-pipeline-conventions, the output of dotnet new connectsoft-apigateway -n ConnectSoft.AI.SoftwareFactory.DataEventFoundations --UseFactoryProfile true --GatewayRole Platform from the pinned template package is committed unchanged, the repository records the template version, the solution builds and the template tests, the architecture test of the Platform role included, pass in the repository pipeline, which publishes the container image. |
ConnectSoft.AI.SoftwareFactory.DataEventFoundations |
AIFACTORY-TASK-5861 Deployment values of the gateway: replica range, ports, probes and the address of each fronted service |
operations | The deployment manifest of the gateway states the replica range 2 to 4, the ports https 8110 and grpc 8112, the liveness and readiness probes on the health operation and one base address per fronted service from configuration, as model/services/data-event/DataEventFoundations.yaml records them, and leaves DataEvent:Host:FrontedServices at its modelled default; the same image runs in the saas-default, hybrid, on-prem and hybrid-compute topologies with the identity authority of the profile (ADR-0017). | ConnectSoft.AI.SoftwareFactory.DataEventFoundations |
AIFACTORY-TASK-703 Verify data-event-foundations-routes-its-platform by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build in the pipeline of the repository, then dotnet test -c Release --filter "Category=Acceptance&Feature=TwoReplicas"; a run that discovers no test counts as a failure; the runs pass and prove AC1 to AC4 of AIFACTORY-US-086: the scaffold of the Platform role, the scope established once and forwarded, the architecture test, and two gateway instances behind one test balancer with the fakes of the fronted services, one of them stopped while the other keeps serving and no call is replayed. |
ConnectSoft.AI.SoftwareFactory.DataEventFoundations |
AIFACTORY-US-1441: Data & Event fronts file: named clients and REST and gRPC routes of the three fronted services, generated at build¶
enabling · persona platform-admin
As a platform admin, I want the route table of the Data & Event gateway generated from the list of services it fronts, so that every operation of the platform has exactly one route with its scope and class and no forwarding code is written by hand.
The API gateway template is a custom gateway with controllers, use cases and named clients, so a route exists only when it is declared. Under UseFactoryProfile the generated solution holds a build-time source generator that reads a fronts file on every build and emits one named HTTP client and one gRPC client per fronted service, the REST and gRPC routes that forward to them and the route table (feature component-api-gateway-template). This PBI writes the fronts file of the Data & Event platform. It lists the three services of deployment.fronts in model/services/data-event/DataEventFoundations.yaml, each with its base addresses from configuration and its operations in the shape of the apis section of its service file: the five REST operations and two gRPC methods of EnvelopeRegistryService, the seven REST operations and one gRPC method of RetentionResidencyService and the three REST operations and one gRPC method of StoreProfileService, each with name, method and path or gRPC method, scope, side-effect class and idempotency. A test lists the emitted route table against the file and against the three service files of the model, so an operation of the model without a route, a route without an operation, a service named twice or a route named twice fails the build with the entry named. A path that no route matches is answered 404 and reaches no service. The gateway adds no operation of its own beyond DataEventHealth and DataEventProfiles and transforms no payload. The option DataEvent:Host:FrontedServices is bound at startup and compared with the fronts file through the short name each service carries in the file, as the modelled default lists them: envelopes for EnvelopeRegistryService, stores for StoreProfileService and retention for RetentionResidencyService. A value that names no service of the file, or a service of the file that the value omits, fails startup with the name, so the option can neither add nor remove a route; it is not reloadable. The typed client of this gateway belongs to this feature (D140): one library in the repository ConnectSoft.AI.SoftwareFactory.Clients, generated with dotnet new connectsoft-api-library, the generation switch and UseFactoryProfile in the user-token layout by the rules of feature typed-gateway-clients (AIFACTORY-US-381 to AIFACTORY-US-383), which it applies and does not repeat. This gateway publishes no OpenAPI document of its own, so the input of the library is a document written contract-first in the client repository from the intake of the model, as that feature does for a gateway that publishes none. The library holds the fourteen public REST operations of the three services: of EnvelopeRegistryService ListTopics, GetTopic, RegisterTopic, PublishSchemaVersion and ListEnvelopeProfiles; of RetentionResidencyService ListRetentionRules, SetRetentionRule, GetResidency, SetResidency, IssueGovernanceOrder and GetGovernanceOrder; of StoreProfileService ListStoreBindings, ListStoreProfiles and SetStoreBinding. The internal REST route AcknowledgeOrderTask and the four gRPC methods are not in it. It is checked against the model by the contract check of that feature, takes the shared types from the pinned contracts package, attaches the token issued for this gateway only to requests to the base address of this gateway, is versioned with the contracts package, published to the ConnectSoft feed and recorded on the Runbook page with the consumer that pins it. The caller of the package is StudioBff, which holds a user token and reads this gateway through a static stub in I3 (AIFACTORY-TASK-5485) until this package exists; no caller writes a client of this gateway by hand. In this feature StudioBff replaces that static stub with the pinned client package, so a screen whose source is a service fronted by this gateway shows its data and freshness instead of Unknown (AIFACTORY-TASK-6641, D141).
Acceptance criteria
| AC1 | Given the fronts file of the Data & Event platform, when the gateway builds, then one named HTTP client and one gRPC client exist per service of deployment.fronts and one route per REST operation and gRPC method of the three services, each with the scope, side-effect class and idempotency of the operation, and the route table test passes against model/services/data-event/DataEventFoundations.yaml and the service files it fronts (ADR-0028). |
| AC2 | Given an operation removed from the file, a route named twice or a service named twice, when the gateway builds, then the build fails with the entry named; given DataEvent:Host:FrontedServices at its default [envelopes, stores, retention], when the gateway starts, then startup succeeds; given a value that differs from the short names of the fronts file, when the gateway starts, then startup fails with the differing name; given a path no route matches, when it is called, then the answer is 404 and no fronted service is called (model/services/data-event/DataEventFoundations.yaml, docs/architecture/catalogs/gateways.md). |
| AC3 | Given a fake of each fronted service, when one REST route and one gRPC route per service are called with a valid token, then each call reaches the fake of its service with the authorization header, which carries the token of the caller unchanged, the tenant, the correlation id and the trace context, and the response of the fake returns unchanged (ADR-0015, FR-10). |
| AC4 | Given the contract-first OpenAPI document of this gateway and the pinned API library template, when the client of this gateway is generated, built and published in the repository ConnectSoft.AI.SoftwareFactory.Clients, then it holds the fourteen public REST operations in the user-token layout, without AcknowledgeOrderTask and without a gRPC method, the contract check against the three service files under model/services/data-event passes, the token issued for DataEventFoundations is attached only to requests to its base address, and the package is on the ConnectSoft feed with a version tied to the contracts package and recorded on the Runbook page with StudioBff as its consumer (model/backlog/pbis/engineering-readiness/typed-gateway-clients.yaml, ADR-0015). |
| AC5 | Given the client package of DataEventFoundations published by AIFACTORY-TASK-6604, when StudioBff is built with that package pinned, then the static stub of DataEventFoundations of AIFACTORY-TASK-5485 is removed, StudioBff reads the gateway through the package with the user token issued for DataEventFoundations, attached only to requests to its base address, and a screen whose source is EnvelopeRegistryService, RetentionResidencyService or StoreProfileService shows the data and freshness of that source instead of Unknown (D141, model/backlog/pbis/factory-studio/studio-bff.yaml). |
| Traces: services | DataEventFoundations, EnvelopeRegistryService, RetentionResidencyService, StoreProfileService, StudioBff |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-10 |
| Depends on | feature:component-api-gateway-template, feature:envelope-registry-service, feature:retention-residency-service, feature:store-profile-service, feature:typed-gateway-clients, feature:component-api-library-template-factory-clients, feature:studio-bff |
| Sources | model/services/data-event/DataEventFoundations.yaml, model/backlog/pbis/engineering-readiness/typed-gateway-clients.yaml, model/services/data-event/EnvelopeRegistryService.yaml, model/services/data-event/RetentionResidencyService.yaml, model/services/data-event/StoreProfileService.yaml, docs/architecture/catalogs/gateways.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-372 Fronts file with the REST and gRPC operations of EnvelopeRegistryService, RetentionResidencyService and StoreProfileService |
implementation | The fronts file lists the three services of deployment.fronts with their short names envelopes, retention and stores, their base addresses from configuration and every REST operation and gRPC method of their service files with name, path or method, scope, side-effect class and idempotency; the build emits the named clients, the routes and the route table; at startup the option DataEvent:Host:FrontedServices is compared with the short names of the fronts file and a difference in either direction fails startup with the name; a call without a valid token or scope is refused at the gateway by the generated policies. | ConnectSoft.AI.SoftwareFactory.DataEventFoundations |
AIFACTORY-TASK-5851 Fakes of the three fronted services and the token matrix of the acceptance suite |
fixture | The acceptance suite of the gateway holds one fake per fronted service, generated from its fronts entry, that records the headers it received and answers a configured status, a switch that makes a fake stop answering, and tokens for the matrix of role and tenant, including an expired token, an identity token, a user token of another audience and a workload token with and without the scope of each internal route, the four gRPC methods and the internal REST route of RetentionResidencyService/AcknowledgeOrderTask, and of the production routes that admit a workload caller. | ConnectSoft.AI.SoftwareFactory.DataEventFoundations |
AIFACTORY-TASK-5852 Verify the route table against the fronts file and the model |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Feature=RouteTable"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1441: one route per operation of model/services/data-event/EnvelopeRegistryService.yaml, model/services/data-event/RetentionResidencyService.yaml and model/services/data-event/StoreProfileService.yaml, the failing builds, the start with the option at its default, the failing startup on a differing value, the 404 of an unknown path and one forwarded call per service and protocol; AC4 is proven in the pipeline of ConnectSoft.AI.SoftwareFactory.Clients by the build, the tests and the probe stage of AIFACTORY-TASK-6604. |
ConnectSoft.AI.SoftwareFactory.DataEventFoundations |
AIFACTORY-TASK-6604 Typed client of DataEventFoundations in the user-token layout from a contract-first document, published to the ConnectSoft feed |
implementation | The client repository ConnectSoft.AI.SoftwareFactory.Clients holds one OpenAPI document of DataEventFoundations with its content hash, written contract-first from the intake of the model like the documents of AIFACTORY-TASK-1556 and covered by its contract check; one client library generated from it with dotnet new connectsoft-api-library, the generation switch and UseFactoryProfile in the JWT bearer layout of the template holds the fourteen public REST operations of EnvelopeRegistryService, RetentionResidencyService and StoreProfileService, without AcknowledgeOrderTask and without a gRPC method, takes the shared types from the pinned contracts package and declares no handler, header name or claim name of its own; a stub of the gateway in the fixture of the client solution answers 401, 403, 404 and a redirect to a second host, and the token issued for DataEventFoundations is attached only to requests to its base address; the package is versioned with the contracts package, published to the ConnectSoft feed by the generated pipeline after its tests pass and restored by the probe consumer from the feed alone; the Runbook page records its version with StudioBff as the consumer that pins it. |
ConnectSoft.AI.SoftwareFactory.Clients |
AIFACTORY-TASK-6641 Replace the I3 static stub of DataEventFoundations in StudioBff with the pinned client package |
implementation | StudioBff pins the client package of DataEventFoundations that AIFACTORY-TASK-6604 published to the ConnectSoft feed, registers it with the base address of the gateway and the user token issued for DataEventFoundations as its one audience, and removes the static stub of DataEventFoundations of AIFACTORY-TASK-5485, so the read models of EnvelopeRegistryService, RetentionResidencyService and StoreProfileService that a screen names are read through the gateway and show their data and freshness instead of Unknown; the static stub of FleetOperationsHost stays until I7; no client of the gateway is written by hand; the tests of the StudioBff solution prove AC5 of AIFACTORY-US-1441 (D141). | ConnectSoft.AI.SoftwareFactory.StudioBff |
AIFACTORY-US-1442: A read route of the Data & Event platform forwards a call only under a validated token, the tenant of the token and the scope of its operation¶
behavior · persona observer
As an observer or a workload of another platform, I want my reads of topics, stores, rules and orders to reach the service only with the tenant and scope my token grants, so that nobody reads the data governance of another tenant through the gateway.
A caller reaches a read operation of the Data & Event platform through the gateway: an observer lists topics, store bindings, retention rules or reads an order, StudioBff serves the views topic-registry, stores, retention-residency and governance-orders, and the hosts of every platform call the internal gRPC methods Envelopes.ResolveTopic, Envelopes.ValidateEnvelope, Stores.ResolveBinding and Retention.EvaluateResidency, all of side-effect class read. A user presents an access token whose one audience is this gateway (ADR-0015 amendment D114); a workload presents a workload token, which carries service scopes, no audience of a user API and no tenant claim, and is admitted on the internal routes, meaning the four gRPC methods above and the internal REST route of RetentionResidencyService/AcknowledgeOrderTask (AIFACTORY-US-1443), when it holds the scope that the route names, and on the production routes whose model names a workload caller, the release pipeline on RegisterTopic and PublishSchemaVersion and provisioning on SetStoreBinding, under the same rule (AIFACTORY-US-1444). The gateway validates issuer, signature, lifetime and audience through the pinned resource-server library and requires the scope the operation names (factory.data.read on the REST reads). For a user token it takes the tenant from the tid claim and overwrites any tenant header of the caller; for a workload token that holds the service scope it forwards the tenant-id metadata of the caller unchanged, because the fronted service reads a forwarded tenant only under that scope (D114), and without the scope the answer is PERMISSION_DENIED and no service is called. The user token is forwarded unchanged and no token is exchanged (D117). The fronted service serves the read with no side effect; the gateway returns the response unchanged with the correlation id and keeps nothing. A call without a token, with an expired token, with an identity token or with a user token of another gateway is answered 401 and a token without the scope 403, and no fronted service is called. No route of this platform names a project or a tenant in its path, so the gateway refuses no project itself: a route addressed by a topic, a store or an order id is forwarded under the tenant of the token, and the 404 the fronted service gives for a resource of another tenant, the same answer as for an id that does not exist (ADR-0015 amendment D113), returns unchanged. When the fronted service does not answer, its routes answer 503 with a retry hint and the routes of the other services keep serving.
Acceptance criteria
| AC1 | Given a user token whose audience is this gateway with factory.data.read, when a read route of each fronted service is called, then the gateway forwards the call with the user token unchanged, the tenant of the tid claim, the correlation id and the trace context, the fronted service answers and the response returns unchanged, and nothing is written by the gateway (SCN-DataEventFoundations-004, ADR-0015). |
| AC2 | Given the token matrix of the acceptance suite, when the read routes are called, then a call without a token, with an expired token, with an identity token or with a user token issued for another gateway is answered 401 and a token without factory.data.read 403, and no fronted service is called; given a route addressed by a topic, a store id or an order id of another tenant, when it is called, then the gateway forwards it under the tenant of the token and the 404 of the fronted service returns unchanged (SCN-DataEventFoundations-004, ADR-0015). |
| AC3 | Given a user token and a tenant header of the caller that names another tenant, when a read route is called, then the header is overwritten with the tid claim; given a workload token on the gRPC route of EnvelopeRegistryService/Envelopes.ResolveTopic, EnvelopeRegistryService/Envelopes.ValidateEnvelope, StoreProfileService/Stores.ResolveBinding or RetentionResidencyService/Retention.EvaluateResidency, when the token holds the service scope of the method, then the tenant-id metadata is forwarded unchanged, and when it lacks the scope the answer is PERMISSION_DENIED and no fronted service is called (SCN-DataEventFoundations-004, ADR-0015). |
| AC4 | Given a fronted service that does not answer, when one of its read routes is called, then the gateway answers 503 with a problem response that carries a retry hint and names the service and never its address, invents no response, and the read routes of the other two services keep serving (SCN-DataEventFoundations-004, model/services/data-event/DataEventFoundations.yaml). |
| Traces: services | DataEventFoundations, EnvelopeRegistryService, RetentionResidencyService, StoreProfileService |
| Traces: apis | EnvelopeRegistryService/Envelopes.ResolveTopic, EnvelopeRegistryService/Envelopes.ValidateEnvelope, StoreProfileService/Stores.ResolveBinding, RetentionResidencyService/Retention.EvaluateResidency |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-10, NFR-14 |
| Traces: scenarios | SCN-DataEventFoundations-004 |
| Relates: screens | topic-registry, stores, retention-residency, governance-orders |
| Depends on | AIFACTORY-US-1441, feature:component-api-gateway-template, feature:component-extensions-ai, feature:envelope-registry-service, feature:retention-residency-service, feature:store-profile-service |
| Sources | model/services/data-event/DataEventFoundations.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5853 Issuer, audience, tenant and workload scope configuration of the read routes |
implementation | The gateway is configured with the authority of ConnectSoftIdentityPlatform:Authority and its own resource as the one audience of a user token; every REST read route requires factory.data.read; a workload token is admitted on the internal routes, the four gRPC methods and the internal REST route of AcknowledgeOrderTask, and on the production routes of RegisterTopic, PublishSchemaVersion and SetStoreBinding, only when it holds the scope that the route names, and on no other route; for a user token the tenant header is overwritten with the tid claim, for a workload token that holds the service scope the tenant-id metadata of the caller is forwarded unchanged, and a workload token without the scope is answered PERMISSION_DENIED before any call; routes addressed by a resource id are forwarded under the tenant of the token; refusals are counted per route and logged with the correlation id and without the token. | ConnectSoft.AI.SoftwareFactory.DataEventFoundations |
AIFACTORY-TASK-5854 Verify the read routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-DataEventFoundations-004"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1442 over the token matrix, the token received by the fake equal to the user token of the caller, the 404 of a fake for a resource of another tenant returned unchanged, the overwritten tenant header, a workload token with and without the service scope on the four gRPC read routes, and a fake that stops answering. |
ConnectSoft.AI.SoftwareFactory.DataEventFoundations |
AIFACTORY-US-1443: A shared-write route of the Data & Event platform is forwarded unchanged and the gateway keeps nothing between calls¶
behavior · persona workspace-admin
As a workspace admin, or an owning service acknowledging an order, I want a rule change or an acknowledgement I repeat after a failure to be applied once, so that a lost answer or a restarted gateway never changes a retention rule or an order task twice.
Two operations of the platform are of class shared-write, both fronted on RetentionResidencyService: SetRetentionRule, which a Workspace admin calls with factory.data.admin to shorten a retention of the tenant and a Platform admin calls to set a platform default, and AcknowledgeOrderTask, which an owning service calls with its workload token and factory.data.acknowledge to acknowledge its task of a governance order with a receipt. Both declare idempotency natural: the same PUT of a rule and the same acknowledgement repeated change nothing the second time, and no Idempotency-Key is needed; a key the caller sends anyway is forwarded unchanged. The gateway validates the token under the rules of AIFACTORY-US-1442, takes the tenant from the tid claim of a user token or forwards the tenant of a workload token that holds factory.data.acknowledge (ADR-0015 amendment D114), and forwards body and headers unchanged. It is no party to idempotency: it stores neither a request nor a result, keeps no session and no pending call, has no outbox and writes no event, so a replica that crashes during a call loses nothing; the replica restarts, nothing is replayed, and the caller repeats the call and receives the answer of the one application. When RetentionResidencyService does not answer, the route answers 503 with a retry hint that names the service. A refusal by the gateway (401, 403) reaches no fronted service, so it applies nothing; a 422 of a rule that would lengthen a platform ceiling and a 404 for an order of another tenant are answers of the fronted service and return unchanged with the correlation id (ADR-0015 amendment D113).
Acceptance criteria
| AC1 | Given a user token with factory.data.admin, when the route of RetentionResidencyService/SetRetentionRule is called and then repeated with the same body, then the gateway forwards both unchanged, the fronted service applies the rule once and both answers return unchanged with the correlation id; the gateway stored nothing (SCN-DataEventFoundations-005, ADR-0028). |
| AC2 | Given a workload token with factory.data.acknowledge, when the route of RetentionResidencyService/AcknowledgeOrderTask is called with the tenant of the order, then the tenant is forwarded unchanged and the answer of the fronted service returns unchanged; given the same token without the scope, then the answer is 403 and no fronted service is called (SCN-DataEventFoundations-005, ADR-0015). |
| AC3 | Given a gateway replica stopped while a shared-write call is in flight, when the caller repeats the call through another replica, then the fronted service returns the result of the one application, nothing is replayed by the gateway and no second state change exists (SCN-DataEventFoundations-005, model/services/data-event/DataEventFoundations.yaml). |
| AC4 | Given a call without a token, a token without the scope, or a fronted service that does not answer, when a shared-write route is called, then the answer is 401, 403 or 503 respectively, a call the gateway refuses reaches no fronted service, and the 422 and the 404 of the fronted service return unchanged (SCN-DataEventFoundations-005, ADR-0015). |
| Traces: services | DataEventFoundations, RetentionResidencyService |
| Traces: apis | RetentionResidencyService/SetRetentionRule, RetentionResidencyService/AcknowledgeOrderTask |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-12 |
| Traces: scenarios | SCN-DataEventFoundations-005 |
| Relates: screens | retention-residency |
| Depends on | AIFACTORY-US-1441, AIFACTORY-US-1442, feature:component-api-gateway-template, feature:retention-residency-service |
| Sources | model/services/data-event/DataEventFoundations.yaml, model/services/data-event/RetentionResidencyService.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5855 Forwarded headers of a shared-write route and a stateless call path |
implementation | The routes of SetRetentionRule and AcknowledgeOrderTask forward the body, an Idempotency-Key header when the caller sends one and the established scope unchanged and return the status and the body of RetentionResidencyService unchanged; no request, body or result is written to a cache or a store; request count and latency are recorded for the route with the returned status. | ConnectSoft.AI.SoftwareFactory.DataEventFoundations |
AIFACTORY-TASK-5856 Verify the shared-write routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-DataEventFoundations-005"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1443 with a fake of RetentionResidencyService that applies a request once, a workload token with and without factory.data.acknowledge, a replica stopped during a call and a fake that stops answering. |
ConnectSoft.AI.SoftwareFactory.DataEventFoundations |
AIFACTORY-US-1444: A production route of the Data & Event platform is forwarded under its scope and the gate of the action stays in the fronted service¶
behavior · persona platform-admin
As a platform admin or a workspace admin, I want a topic registration, a schema publication, a residency selection, a governance order or a store binding to be decided by the service that owns its state, so that an approval or a refusal is never decided twice or by a component that holds no state.
Five operations of the platform are of class production: RegisterTopic and PublishSchemaVersion of EnvelopeRegistryService, SetResidency and IssueGovernanceOrder of RetentionResidencyService and SetStoreBinding of StoreProfileService, each under factory.data.admin. The model names a workload caller for three of them, the release pipeline for RegisterTopic and PublishSchemaVersion and provisioning for SetStoreBinding; the gateway admits a workload token on these three routes when it holds factory.data.admin as a service scope, forwards the tenant-id of the caller unchanged under that scope (D114), and leaves to the fronted service the user role a user caller needs. ADR-0028 leaves a platform gateway routing and the validation of tokens and scopes and no business state, so the gateway treats these routes as it treats every route: it validates the token, takes the tenant from it, requires the scope and forwards the call with the established scope, the body and an Idempotency-Key unchanged; PublishSchemaVersion and IssueGovernanceOrder declare idempotency key-header, and the key is applied by the fronted service. The gate of each action is decided where the state is. EnvelopeRegistryService refuses a Forward or Breaking schema version that a registered consumer has not acknowledged; RetentionResidencyService decides the role of the caller (Workspace admin for the tenant, Platform admin for defaults), refuses a tenant deletion without its approval with 412 and records the evidence of an order through AuditService; StoreProfileService refuses a binding that violates the residency of the tenant with 422 and the rule id. The gateway evaluates no approval, holds no approval reference, writes no audit evidence and refuses nothing on behalf of a missing approval: the derived default of the scenario, which had the gateway refuse a production call without an approval, is replaced by this rule. The answers of the fronted service, 201, 202, 409, 412 and 422 included, return unchanged with the correlation id. A call without a token is answered 401 and a token without the scope 403, and no fronted service is called. Every production route of this platform names at most a topic, a store id or nothing in its path, so the gateway forwards it under the tenant of the token and the fronted service answers 404 for a resource of another tenant (ADR-0015 amendment D113).
Acceptance criteria
| AC1 | Given a token with factory.data.admin, when the routes of EnvelopeRegistryService/RegisterTopic, EnvelopeRegistryService/PublishSchemaVersion, RetentionResidencyService/SetResidency, RetentionResidencyService/IssueGovernanceOrder and StoreProfileService/SetStoreBinding are called, then each call is forwarded under the tenant of the token with the body and the Idempotency-Key unchanged and the answer of the fronted service returns unchanged with the correlation id; the gateway evaluates no approval and writes nothing (SCN-DataEventFoundations-003, ADR-0028). |
| AC2 | Given fakes that answer 409, 412 and 422 on these routes, when the routes are called, then each answer returns unchanged, and the gateway holds no approval reference, no cache entry and no store for an approval, which a register test of the route classes checks over the route table (SCN-DataEventFoundations-003, model/services/data-event/DataEventFoundations.yaml). |
| AC3 | Given a call without a token or with an expired token, or a token that lacks factory.data.admin, when a production route is called, then the gateway answers 401 or 403 and no fronted service is called; given a workload token that holds the service scope factory.data.admin, when the route of EnvelopeRegistryService/RegisterTopic, EnvelopeRegistryService/PublishSchemaVersion or StoreProfileService/SetStoreBinding is called, then it is forwarded, and on RetentionResidencyService/SetResidency or RetentionResidencyService/IssueGovernanceOrder it is refused with 403; given a topic or a store id of another tenant, when its route is called, then the call is forwarded and the 404 of the fronted service returns unchanged (SCN-DataEventFoundations-003, ADR-0015). |
| Traces: services | DataEventFoundations, EnvelopeRegistryService, RetentionResidencyService, StoreProfileService |
| Traces: apis | EnvelopeRegistryService/RegisterTopic, EnvelopeRegistryService/PublishSchemaVersion, RetentionResidencyService/SetResidency, RetentionResidencyService/IssueGovernanceOrder, StoreProfileService/SetStoreBinding |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-10, FR-12 |
| Traces: scenarios | SCN-DataEventFoundations-003 |
| Relates: screens | governance-orders, retention-residency |
| Depends on | AIFACTORY-US-1441, AIFACTORY-US-1442, feature:component-api-gateway-template, feature:envelope-registry-service, feature:retention-residency-service, feature:store-profile-service |
| Sources | model/services/data-event/DataEventFoundations.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5857 Register of the production routes and fakes that answer the gate refusals |
fixture | The acceptance suite holds fakes of the five production operations that answer 201, 202, 409, 412 and 422 as configured; a register test lists every route of class production from the route table and fails when such a route has no scope or when the gateway holds a handler, a cache entry or a store for an approval or an evidence record. | ConnectSoft.AI.SoftwareFactory.DataEventFoundations |
AIFACTORY-TASK-5858 Verify the production routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-DataEventFoundations-003"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1444: the five routes forwarded under their scope with the Idempotency-Key unchanged, the refusals of the fakes returned unchanged, the refusals of the gateway without a call to a fronted service, a workload token with factory.data.admin forwarded on RegisterTopic, PublishSchemaVersion and SetStoreBinding and refused on SetResidency and IssueGovernanceOrder, the 404 of a fake for a resource of another tenant, and the register of production routes. |
ConnectSoft.AI.SoftwareFactory.DataEventFoundations |
AIFACTORY-US-1445: Health, installation profiles, limits and telemetry of the Data & Event gateway while the identity platform, a fronted service or a replica fails¶
behavior · persona operator
As an operator, I want to see whether the gateway, the identity platform and each fronted service answer, and which messaging and store profiles the installation runs, so that I can tell a failing service from a failing gateway and know which adapters the installation uses.
An operator, the Studio about page and the probes of the cluster read the state of the gateway through its two own operations. DataEventFoundations/DataEventHealth reports liveness and readiness of the gateway with the aggregated health of the three services it fronts and of the identity platform; liveness needs no token and the detail is served under factory.health.read. The identity platform is the one required dependency, and the gateway follows the two phases the ADR-0015 amendment D117 sets for every gateway: while a cached signing key still validates tokens, readiness stays ready, already issued tokens keep passing and health answers 200 degraded with a detail that names the identity platform as unreachable; when no valid key remains, readiness turns unready, health answers 503 with a problem response that names the identity platform and calls are refused, so the gateway fails closed. A fronted service is an optional dependency: when it does not answer, health reports it unavailable, its routes answer 503 with a retry hint and the other routes keep serving. DataEventFoundations/DataEventProfiles answers a caller with factory.meta.read with the messaging profile and the store profiles the installation runs and their adapter versions (ADR-0012, ADR-0013): the gateway composes them from the active envelope profile that EnvelopeRegistryService/ListEnvelopeProfiles returns and from the store profiles of the topology of the installation that StoreProfileService/ListStoreProfiles returns, keeping nothing; where this answer comes from for a gateway without state is reported to the owner, and the operation answers 503 with the service named when one of the two does not answer. A call above the rate limit of its route is refused with 429 (ADR-0018). The gateway emits connectsoft.factory.data_event.host.requests with the dimensions service, route and status and connectsoft.factory.data_event.host.request_duration with service and route, the latency including the fronted service, carries the trace context, and never logs a token or a payload. A replica that crashes is detected by the readiness probe and restarts; nothing is replayed.
Acceptance criteria
| AC1 | Given the identity platform and the three fronted services reachable, when DataEventFoundations/DataEventHealth is called, then liveness answers 200 without a token and a caller with factory.health.read receives 200 with the state of each fronted service and of the identity platform; given one fronted service down, then health reports it unavailable, its routes answer 503 with a retry hint and the other routes keep serving (SCN-DataEventFoundations-001, ADR-0028). |
| AC2 | Given the identity platform unreachable and a cached signing key that still validates tokens, when calls arrive and health is probed, then issued tokens pass, readiness stays ready and health answers 200 degraded naming the identity platform; given no valid key remains, then calls are refused, readiness is unready and DataEventFoundations/DataEventHealth answers 503 with a problem response that names the identity platform, while liveness keeps answering 200 (SCN-DataEventFoundations-001, ADR-0015). |
| AC3 | Given a caller with factory.meta.read, when DataEventFoundations/DataEventProfiles is called, then the response is 200 with the messaging profile of the installation and its envelope schema version from EnvelopeRegistryService/ListEnvelopeProfiles and the store profiles of the topology with engine and adapter library from StoreProfileService/ListStoreProfiles; a call without a token is 401, without the scope 403, and an unanswering source service is named in a 503; nothing is written (SCN-DataEventFoundations-002, ADR-0012, ADR-0013). |
| AC4 | Given routed calls and a call above the rate limit of its route, when metrics and logs are read, then connectsoft.factory.data_event.host.requests counts every call by service, route and status, the call above the limit was refused with 429, connectsoft.factory.data_event.host.request_duration holds the latency by service and route, and no log record holds a token or a payload (ADR-0018, model/services/data-event/DataEventFoundations.yaml). |
| Traces: services | DataEventFoundations, EnvelopeRegistryService, StoreProfileService |
| Traces: apis | DataEventFoundations/DataEventHealth, DataEventFoundations/DataEventProfiles, EnvelopeRegistryService/ListEnvelopeProfiles, StoreProfileService/ListStoreProfiles |
| Traces: adrs | ADR-0012, ADR-0013, ADR-0015, ADR-0018, ADR-0028 |
| Traces: requirements | NFR-05, NFR-16 |
| Traces: scenarios | SCN-DataEventFoundations-001, SCN-DataEventFoundations-002 |
| Depends on | AIFACTORY-US-1441, feature:component-api-gateway-template, feature:component-observability-factory-conventions, feature:envelope-registry-service, feature:store-profile-service |
| Sources | model/services/data-event/DataEventFoundations.yaml, docs/planes/data-event/services/data-event-foundations/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-373 Health, installation profiles and telemetry of the gateway |
implementation | DataEventHealth serves liveness without a token and the detail under factory.health.read with the aggregated state of the three fronted services and of the identity platform, degraded and in rotation while a cached signing key validates tokens and 503 and out of rotation when none remains (D117); DataEventProfiles answers under factory.meta.read with the active envelope profile and the store profiles of the topology read from the two fronted services, keeping nothing; every route takes its rate limit from configuration through the pinned rate-limiting library and answers 429 above it; every routed call records connectsoft.factory.data_event.host.requests and connectsoft.factory.data_event.host.request_duration with their modelled dimensions and carries the trace context. | ConnectSoft.AI.SoftwareFactory.DataEventFoundations |
AIFACTORY-TASK-5859 Runbook of the three failure modes of the gateway |
documentation | The repository documentation holds one runbook entry per failure mode of model/services/data-event/DataEventFoundations.yaml (identity platform unreachable, fronted service unavailable, gateway replica crash) with its detection signal, the expected answers of the gateway and the recovery step, the identity platform entry stating its two phases (D117). | ConnectSoft.AI.SoftwareFactory.DataEventFoundations |
AIFACTORY-TASK-5860 Verify health, profiles, limits and telemetry through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-DataEventFoundations-001\|Scenario=SCN-DataEventFoundations-002)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1445 with the identity platform stopped while a cached key validates tokens and after it expired, one fake stopped, the profiles composed from the fakes of EnvelopeRegistryService and StoreProfileService and a call above its limit. |
ConnectSoft.AI.SoftwareFactory.DataEventFoundations |