AIFACTORY-FEAT-159: API gateway template: the platform gateway profile¶
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 Ecosystem component extensions · Increment I0 Readiness · State elaborated · Route backend-developer · Phase before development · Build order 12 of 185 (Templates and libraries)
Before development
Template or library work: every task of this feature changes a template or a shared library the Factory builds on, and it lands before the Factory's own repositories of I0 are developed. The mark travels with every task (tag phase:before-development).
The fourteen platform gateways and the Studio backend-for-frontend are scaffolded from the API gateway template (ADR-0028, D73): they validate tokens and scopes, route public REST and internal gRPC calls to the services they front, and own no business state. The template is a custom BFF gateway with controllers, use cases and named clients; it has no profile that generates the route table of a platform from the fronts list of the model, no scope validation that refuses a call outside the tenant and project of the token, and no guard against business state. Component: API Gateway template (extend).
| Delivers | — |
| Stubs | — |
| Realizes | components: cmp-api-gateway adrs: ADR-0028 |
| Requirements | — |
| Depends on | — |
| Sources | model/components.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, model/gateways.yaml |
AIFACTORY-US-236: API gateway template: the UseFactoryProfile switch generates named clients and the REST and gRPC routes of a platform from its fronts file¶
enabling · persona asset-maintainer
As an asset maintainer, I want the gateway template to generate the route table of a platform gateway from the list of services it fronts, so that each of the fourteen platform gateways is scaffolded with its routes and clients and without hand-written forwarding code.
ADR-0028 decision 2 re-scopes the fourteen composition hosts as the API gateways of their platforms on the API gateway template: they route public REST and internal gRPC calls to the services they front, and decision 6 puts the list of those services into the model as deployment.fronts of the gateway (for example model/services/control-plane/ControlPlaneApi.yaml). The template is a custom gateway with controllers, use cases and named clients and is not a reverse proxy (Docs/TenantPropagation.md of the template), so a route exists today only when a developer writes it. This PBI adds the platform gateway profile and a fronts file to the template. The switch of the profile is the one the amendment of ADR-0028 (D114) decides for every template that has a Factory shape: the boolean UseFactoryProfile, off by default so that other generations of the gateway template do not change, and passed by the Factory scaffold command. The file names each fronted service with its base addresses and its operations in the shape of the apis section of a service file of the model. A template instantiation cannot read a data file, so the routes are not written when the solution is generated: the generated solution holds a build-time source generator that reads the fronts file on every build, validates it against its schema and emits one named HTTP client and one gRPC client per service, the REST and gRPC routes that forward to them and the route table. A schema violation, a service named twice, a route named twice or an operation without a service fails the build with the entry named, and a test lists the emitted route table against the file. The generated gateway also carries the request count and latency metrics per route that decision 7 leaves with a gateway, a modules endpoint that lists the fronted services, and the health operation every gateway of the model exposes (for example /factory/health of the same service file): liveness and readiness with the aggregated health of the fronted services and of the identity authority, answering 503 when a required dependency is down. A forwarded call carries the authorization header, the tenant in X-Tenant-Id on REST and in tenant-id in gRPC metadata, the project header, the correlation id and the trace context, as the token and header propagation page of the template prescribes. A path that no route matches is answered 404, and a fronted service that does not answer is reported as 503 with a problem response that names the service and never its address.
Acceptance criteria
| AC1 | Given a fronts file that lists two services with REST operations and gRPC methods, when a gateway is generated with UseFactoryProfile and built, then it holds one named HTTP client and one gRPC client per service and one route per operation, a modules endpoint lists the two services, and the health operation answers with the aggregated health of the fronted services and of the identity authority and with 503 when a required dependency is down (ADR-0028 decisions 2 and 6, model/gateways.yaml, model/services/control-plane/ControlPlaneApi.yaml). |
| AC2 | Given a generated platform gateway and a fake fronted service, when a REST call and a gRPC call pass a route, then each is forwarded to the fronted service with the authorization header, the tenant in X-Tenant-Id or tenant-id, the project header, the correlation id and the trace context, and a request count and a latency measurement are recorded for the route (ADR-0028 decision 7, FR-01). |
| AC3 | Given a fronts file that violates its schema or names a service twice, a route twice or an operation without a service, when the generated solution builds, then the source generator fails the build with the entry named; given a path no route matches, when it is called, then the answer is 404; given a fronted service that does not answer, when its route is called, then the answer is 503 with a problem response naming the service (ADR-0028 decision 7 failure mode of an unavailable fronted service, docs/architecture/catalogs/gateways.md). |
| Traces: adrs | ADR-0028 |
| Traces: requirements | FR-01 |
| Sources | model/components.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, model/gateways.yaml, docs/architecture/catalogs/gateways.md, model/template-parameters/connectsoft-apigateway.yaml, model/services/control-plane/ControlPlaneApi.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1103 UseFactoryProfile symbol of the gateway template and the schema of the fronts file |
contract | The template configuration holds the boolean UseFactoryProfile of the ADR-0028 amendment, off by default and named as in the base, worker and library templates; a JSON schema of the fronts file ships with the template and names service, base addresses and operations with method, path or gRPC method and scope; the template page for the platform profile documents both. |
ConnectSoft.ApiGatewayTemplate |
AIFACTORY-TASK-588 Platform gateway switch with routes from the fronts list |
implementation | The UseFactoryProfile switch adds to the generated solution a build-time source generator that reads the fronts file listing the services of the platform, validates it against its schema and emits the named clients, the REST and gRPC routes and the route table; a schema violation or a duplicate entry fails the build with the entry named; a test of the generated solution lists the emitted route table against the file; the generated gateway forwards each route with the tenant and project headers, serves the modules endpoint and the health operation with the aggregated health of the fronted services and of the identity authority; the acceptance suite covers one route per protocol. |
ConnectSoft.ApiGatewayTemplate |
AIFACTORY-TASK-1104 Two fake fronted services for the route tests of the generated gateway |
fixture | The generated acceptance suite starts two fake fronted services, one REST and one gRPC, that record the headers they receive and can report themselves unhealthy, and holds scenarios for a forwarded call per protocol, an unknown path, a fronted service that is down and the health operation with a healthy and with an unhealthy dependency. | ConnectSoft.ApiGatewayTemplate |
AIFACTORY-TASK-1105 Verify the generated routes of a platform gateway |
verification | Generate a gateway with UseFactoryProfile and a fronts file of two services, build it in Release and run the route scenarios; forwarding, 404, 503 and the health operation answer as stated, the route table test matches the file and a duplicated entry fails the build, which proves AC1 to AC3 of AIFACTORY-US-236 (ADR-0028). |
ConnectSoft.ApiGatewayTemplate |
AIFACTORY-US-237: API gateway template: a platform gateway validates the token and its scope, never forwards a tenant the token does not carry, and refuses a project the token does not grant¶
enabling · persona asset-maintainer
As an asset maintainer, I want a generated platform gateway to validate every call against the token before it forwards it, so that no call reaches a Factory service with a scope the caller merely claimed.
ADR-0028 decision 2 makes the platform gateways validate tokens and scopes, and ADR-0015 decision 2 forbids a scope taken from caller-controlled headers. The identity platform page of the template (Docs/Identity-Platform-Integration.md of the template) lists what a gateway does: validate platform access tokens, reject identity tokens as API credentials, enforce route policies before forwarding, keep an explicit anonymous allowlist, resolve the tenant from the validated token and overwrite or reject tenant headers of the public client. ADR-0028 decision 7 names the resource-server library for that, the gateway files of the model list it, and the template already pins ConnectSoft.Extensions.ResourceServer and the SaaS tenancy libraries. The validation of issuer, signature, lifetime and audience and the refusal of an identity token are therefore the registration of the pinned library, and this PBI adds what is specific to a platform gateway under UseFactoryProfile: the route scope, tenant and project rules. A user token has one audience, the gateway that fronts its granted scopes (ADR-0015 amendment of D114), so it must be addressed to the resource of this gateway, a token issued for another gateway is refused, and a client that calls two gateways requests two tokens. A workload token carries service scopes, no audience of a user API and no tenant claim; it is admitted only on a route whose operation names an svc. scope the token holds, and the tenant and project it forwards are read only under that scope. Each route requires the scope its operation names in the fronts file. The tenant comes from the tid claim: a tenant header of the caller is overwritten, and a route that addresses another tenant by identifier is answered 404, over gRPC the status NOT_FOUND, the answer every Factory service gives for a resource outside the tenant of the caller. A route that addresses a project is forwarded only when the token holds a role claim for that project or the tenant-wide Platform admin role; otherwise the answer is 403, as it is for a missing scope. A call without a token, with an expired token or with an identity token is answered 401. When the identity authority cannot be reached and no signing key is cached, the gateway refuses calls and reports the authority in its health. ADR-0015 decision 1 has the Factory inherit the canonical tenant tokens and define none of its own, so the validated tenant travels to the fronted service in X-Tenant-Id on REST and in tenant-id in gRPC metadata, through the SaaS tenancy libraries the template already uses (Docs/TenantPropagation.md of the template). Only the project header is a Factory name. It is taken from the pinned ConnectSoft.Extensions.AI.Factory.Abstractions package, which holds the scope accessor, the claim type names and the parser of the scoped role value, all delivered by AIFACTORY-US-220 of feature component-extensions-ai (AIFACTORY-TASK-186, AIFACTORY-TASK-142, AIFACTORY-TASK-1173); the template copies none of them and waits for no other template. Refusals are counted per route and logged with the correlation id and without the token.
Acceptance criteria
| AC1 | Given a generated platform gateway configured with the issuer and its own audience, when it receives a call, then the registration of the pinned ConnectSoft.Extensions.ResourceServer validates issuer, signature, lifetime and audience; a valid user access token addressed to the resource of this gateway passes; 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 nothing is forwarded; a workload token, which carries no audience of a user API, is admitted only on a route whose operation names an svc. scope it holds (ADR-0028 decisions 2 and 7, ADR-0015 decision 6 and its amendment on the one audience of a user token). |
| AC2 | Given a valid token of one tenant, when the caller sends a tenant header with another value, then the header is overwritten with the tid claim of the token and forwarded in X-Tenant-Id on REST and in tenant-id in gRPC metadata through the SaaS tenancy libraries, and when the route addresses another tenant by identifier, then the answer is 404, over gRPC the status NOT_FOUND, and nothing is forwarded (ADR-0015 decisions 1 and 2 and its amendment on a resource of another tenant, D113; docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md). |
| AC3 | Given a valid token, when the route addresses a project for which the token holds no role claim and the token is not Platform admin, or the token lacks the scope the operation names, then the answer is 403 and nothing is forwarded; when the token grants both, then the call is forwarded with the validated tenant in the canonical tenant header and the project in the project header of the pinned Factory abstractions package (ADR-0015 decisions 3 and 5, FR-01). |
| AC4 | Given the matrix of role, tenant and project of the generated acceptance suite, when it runs, then every combination answers as the three criteria above state, each refusal is counted for its route and logged with the correlation id and without token content, and when the identity authority is unreachable without a cached key the gateway refuses calls and its health reports the authority (ADR-0028 decision 7). |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-01 |
| Depends on | AIFACTORY-US-236, feature:component-extensions-ai |
| Sources | model/components.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, model/gateways.yaml, docs/templates-docs/api-gateway-template.md, docs/reference/schemas/execution-scope.schema.json |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1106 Issuer, audience and route scope options of the platform profile |
contract | The generated options hold the issuer and the audience of the gateway for the registration of the pinned ConnectSoft.Extensions.ResourceServer, validated at startup, and each generated route reads its required scope from the fronts file; the tenant header names are those of the SaaS tenancy libraries the template already pins, the project header name, the claim type names and the parser of the scoped role value are those of the pinned ConnectSoft.Extensions.AI.Factory.Abstractions, and the template holds no copy of any of them. |
ConnectSoft.ApiGatewayTemplate |
AIFACTORY-TASK-589 Token and scope validation at the gateway |
implementation | The generated gateway validates the token of the authorization server through the pinned resource-server library, overwrites a tenant header of the caller with the tid claim, answers 404 for a route that addresses another tenant, refuses a project the token does not grant and a missing scope with 403, admits a workload token only on a route with an svc. scope it holds, and forwards the validated tenant in X-Tenant-Id or tenant-id and the project in the project header to the fronted service; the matrix of role, tenant and project is covered. |
ConnectSoft.ApiGatewayTemplate |
AIFACTORY-TASK-1107 Role, tenant and project matrix with a test token issuer |
fixture | The generated acceptance suite holds a test issuer that signs tokens with the claim type names and the scoped role value of the pinned Factory abstractions package and a matrix feature over role, tenant, project, scope, audience and workload token with the expected answer of each combination. | ConnectSoft.ApiGatewayTemplate |
AIFACTORY-TASK-1108 Verify token and scope validation on a generated platform gateway |
verification | Generate a platform gateway, build it in Release and run the matrix; every combination answers 200, 401, 403 or 404 as stated and the fake fronted service receives only the validated tenant and project headers, which proves AC1 to AC4 of AIFACTORY-US-237 (ADR-0015, ADR-0028). | ConnectSoft.ApiGatewayTemplate |
AIFACTORY-US-238: API gateway template: an architecture test keeps a platform gateway free of state and consumers, and holds the backend-for-frontend to one named list of session and view types¶
enabling · persona asset-maintainer
As an asset maintainer, I want a generated gateway to be kept free of business state by a test that knows the two gateway roles, so that a platform gateway stays a thin route and the Studio backend-for-frontend holds its session state and nothing else.
ADR-0028 decision 2 states that a platform gateway owns no business state, decision 7 leaves it the shared cache as its only store with the tenancy, resource-server, rate-limiting and observability libraries, and the amendment on gateways and events states that a platform gateway consumes no events and is never listed as a consumer. A revisit trigger of the decision is a gateway that accumulates logic beyond routing and validation. The same template scaffolds the Studio backend-for-frontend, and the model shows that it is a different case: model/services/factory-studio/StudioBff.yaml has the role bff, a primary relational store with the tables StudioSessions and SavedViews, the NHibernate persistence library and the messaging model library, two aggregates of session state with their commands and events, and a long list of consumed events whose handlers refresh a view. The amendment of ADR-0028 on consumers names the Studio backend-for-frontend as the consumer that refreshes the view of the aggregate. The template can generate a persistence model, an actor model and a messaging model, because it composes on the base template (PersistenceModelType, ActorModelType and MessagingModelType in model/template-parameters/connectsoft-apigateway.yaml). This PBI therefore defines the two cases explicitly. Under UseFactoryProfile the choice GatewayRole has the values Platform and BackendForFrontend, after the roles platform-gateway and bff of the model. For the Platform role the template fixes PersistenceModelType, MessagingModelType and ActorModelType to None and migrations to off, and an architecture test of the generated solution fails when an aggregate, a persistence mapping, a migration or a message consumer is present, naming the offending type. For the BackendForFrontend role the template admits NHibernate persistence, the migrations of its session and view tables and the message handlers that refresh a view, all behind one named exemption: a single file that lists each admitted type with a reason. The test still fails there on any aggregate, mapping, migration, published event or handler the list does not name, on a listed handler that writes through a repository of a type outside the list, and on a second exemption or an entry without a reason. The exemption is checked by negative controls, in the way the findings page of the authorization server template describes its own narrow exemptions.
Acceptance criteria
| AC1 | Given a gateway generated with UseFactoryProfile and the role Platform, when its architecture tests run, then they pass on the generated solution and fail with the offending type named when an aggregate, a persistence mapping or a migration is planted; a generation of that role with a value other than None for PersistenceModelType, MessagingModelType or ActorModelType is refused with the symbol named (ADR-0028 decisions 2 and 7, model/gateways.yaml). |
| AC2 | Given the same gateway, when a message consumer, an inbox registration or an outbox registration is planted, then the architecture test fails and names it, and the generated solution holds no messaging registration (ADR-0028 amendment on gateways that consume no events, model/template-parameters/connectsoft-apigateway.yaml). |
| AC3 | Given a gateway generated with the role BackendForFrontend and the named exemption that lists its session and view types, when its architecture tests run, then they pass with NHibernate persistence, the migrations of the listed tables and the message handlers that refresh a listed view present; they fail when an aggregate, a mapping, a migration, a published event or a handler outside the list is planted, when a listed handler writes through a repository of a type outside the list, and when a second exemption or an entry without a reason is added (ADR-0028 decision 2 on the Studio backend-for-frontend, model/services/factory-studio/StudioBff.yaml, docs/architecture/catalogs/gateways.md). |
| Traces: adrs | ADR-0028 |
| Depends on | AIFACTORY-US-236 |
| Sources | model/components.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, model/gateways.yaml, docs/architecture/catalogs/gateways.md, model/template-parameters/connectsoft-apigateway.yaml, model/services/factory-studio/StudioBff.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1109 GatewayRole choice with the persistence, messaging and actor choices fixed for the Platform role |
contract | With UseFactoryProfile the template configuration holds the choice GatewayRole with the values Platform, the default, and BackendForFrontend; for Platform it fixes PersistenceModelType, MessagingModelType and ActorModelType to None and migrations to off and rejects a generation that asks for another value with a message naming the symbol; for BackendForFrontend it admits NHibernate persistence, migrations and a messaging model and generates the exemption file with its schema; the template page for the platform profile documents the two roles. |
ConnectSoft.ApiGatewayTemplate |
AIFACTORY-TASK-590 No business state in a gateway |
implementation | An architecture test of the generated gateway fails for the Platform role when a persistence model, an aggregate, a migration or a message consumer is present; the Studio backend-for-frontend keeps its session and view state through an explicit override of the test, one named exemption file that lists each admitted aggregate, mapping, migration, published event and handler with a reason, and the test fails there on any type outside the list, on a listed handler that writes outside the list and on a second exemption. | ConnectSoft.ApiGatewayTemplate |
AIFACTORY-TASK-1110 Planted violations of both roles and the negative controls of the exemption |
fixture | Test fixtures plant, for the Platform role, an aggregate, a mapping, a migration, a consumer and an outbox registration one at a time and assert the named failure; for the BackendForFrontend role they plant an aggregate, a migration, a published event and a handler outside the list, a listed handler that writes through a foreign repository, a second exemption and an entry without a reason, and assert that the test fails on each. | ConnectSoft.ApiGatewayTemplate |
AIFACTORY-TASK-1111 Verify the guard on a platform gateway and on the backend-for-frontend case |
verification | Generate the Platform case and the BackendForFrontend case, run their architecture tests clean and with each planted violation; clean runs pass and planted runs fail with the type named, which proves AC1 to AC3 of AIFACTORY-US-238 (ADR-0028). | ConnectSoft.ApiGatewayTemplate |
AIFACTORY-US-239: API gateway template: the platform gateway and backend-for-frontend cases are packed, installed, generated, built and tested by the shared template pipeline before the package publishes¶
evidence · persona asset-maintainer
As an asset maintainer, I want the platform gateway profile to be a gated case of the template pipeline, so that the fourteen platform gateways and the Studio backend-for-frontend are scaffolded only from a package whose generated gateway builds and passes.
The estate gates its templates with the shared template pipeline of ConnectSoft.AzurePipelines (template-ci/v1), whose rollout ledger lists the gateway template as pending. The gateway template composes on the base template through its base-template submodule and keeps a package snapshot in build/MaterializedDirectory.Packages.props. This PBI is the proof of the feature and moves the template onto that mechanism. The submodule pointer moves to the base template state the findings feature publishes, and the package snapshot is refreshed from it. A build/template-ci.json manifest keeps the default generation of the template gated as today and declares two Factory cases: a platform gateway generated with UseFactoryProfile, the role Platform and a fronts file of two services under the name of a Factory gateway repository, and a backend-for-frontend case generated with UseFactoryProfile, the role BackendForFrontend, NHibernate persistence and its named exemption, with SQL Server as its required service. The amendment of ADR-0028 (D114) admits one additional gating case per declared profile, so the manifest declares the two gateway roles as two profiles and each case is the one additional gating case of its profile. The admission in the shared tooling is AIFACTORY-TASK-1464 of the feature component-base-template-factory-profile, on which this PBI depends. The template pipeline imports the shared installer jobs: the candidate is packed once and installed, each case is generated, restored and built in Release, its route, token and scope and architecture tests run with the discovery and completion checks, and the dependency audit runs on it. The Scripts check of the shared tooling runs in check mode and keeps the root Scripts folder in step with the Scripts folder of the base-template submodule. A case that fails any stage fails the run with the case and the stage named, and publication is not reached. Publication requires the complete reports of both cases bound to the candidate and pushes a version that is not yet on the ConnectSoft feed. The PBI proves decision 2 of ADR-0028 for the template and the release gate of FR-11, and it ends with the template inventory of this repository listing the new symbols.
Acceptance criteria
| AC1 | Given a change of the gateway template, when the template pipeline runs the shared installer jobs with build/template-ci.json, then the candidate is packed once and installed, the default case runs as today, the platform gateway case with a fronts file of two services and the backend-for-frontend case, each the one additional gating case of its declared profile, are generated, restored and built in Release, their tests run with the discovery and completion checks, the dependency audit runs on each, and the Scripts check passes in check mode (ADR-0028 decision 2 and its amendment on the Factory profile switch, FR-11). |
| AC2 | Given a case that fails any stage, when the pipeline evaluates the run, then the run fails with the case and the stage named and publication is not reached; a planted failing route test proves the refusal (FR-11, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md). |
| AC3 | Given complete reports of both cases bound to the candidate hash, when the publication job runs, then the package is pushed with a version that was not on the feed, a fresh install of that version generates a platform gateway that builds unchanged, and model/template-parameters/connectsoft-apigateway.yaml lists UseFactoryProfile and GatewayRole after the next template inventory (ADR-0028, FR-11). |
| Traces: adrs | ADR-0028 |
| Traces: requirements | FR-11 |
| Depends on | AIFACTORY-US-236, AIFACTORY-US-237, AIFACTORY-US-238, feature:component-base-template-findings, feature:component-base-template-factory-profile |
| Sources | model/components.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, model/gateways.yaml, model/template-parameters/connectsoft-apigateway.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1169 Base-template submodule pointer moved and the package snapshot refreshed |
operations | The base-template submodule of the gateway template points at the base template state the feature component-base-template-findings publishes, build/MaterializedDirectory.Packages.props is regenerated from it, and the snapshot check of the shared tooling passes; no file inside the submodule is edited. |
ConnectSoft.ApiGatewayTemplate |
AIFACTORY-TASK-1112 Template pipeline manifest with the platform gateway and backend-for-frontend cases |
operations | build/template-ci.json of the gateway template declares the package, the solutions, the tests, the default case and the two declared profiles with one additional gating case each, the platform gateway case with a fronts file of two services and the backend-for-frontend case with its exemption file and SQL Server as required service, each with its test filter; azure-pipelines-template.yml imports template-ci/v1/installer-jobs.yml of the shared tooling and holds no stage of its own for generation, tests or audit. |
ConnectSoft.ApiGatewayTemplate |
AIFACTORY-TASK-1170 Scripts check of the gateway template in check mode |
operations | The manifest of the gateway template holds the entry of the Scripts check, the root Scripts folder is written from the Scripts folder of the base-template submodule, and the pipeline runs the check in check mode beside the package snapshot check and fails with the missing and the changed files named. | ConnectSoft.ApiGatewayTemplate |
AIFACTORY-TASK-1113 Planted failing route test and publication on complete reports |
fixture | A pipeline fixture plants a failing route test in the platform gateway case and asserts that the run fails with the case named; publication requires the complete reports of both cases bound to the candidate hash and refuses a version that is already on the feed. | ConnectSoft.ApiGatewayTemplate |
AIFACTORY-TASK-1114 Verify the gate of the gateway template on a green and a planted run |
verification | One green run reaches publication and a fresh install of the published version generates a platform gateway that builds unchanged; the planted run fails before publication; both prove AC1 to AC3 of AIFACTORY-US-239 (ADR-0028, FR-11). | ConnectSoft.ApiGatewayTemplate |
AIFACTORY-US-106: API gateway template: the platform gateway profile is delivered and proven on a generated solution¶
enabling · persona asset-maintainer
As an asset maintainer, I want API Gateway to carry the platform gateway profile, so that it serves GW-01 edge ingress, GW-02 Studio BFF, GW-07 product gateways, the 14 platform gateways (ADR-0028) without later rework.
This is the integration PBI of the feature. The fourteen platform gateways and the Studio backend-for-frontend are scaffolded from the API gateway template; they validate tokens and scopes and route public REST and internal gRPC calls to the services they front, a platform gateway owns no business state, and the backend-for-frontend holds its session and view state and nothing else. With the routes generated from the fronts file, the token and scope validation with its 401, 403 and 404 answers, the guard for the two gateway roles and the two gated cases in the shared template pipeline, the asset maintainer runs the pipeline end to end: pack, install, generate both cases, build, test and audit, then publish. A case that fails any stage blocks publication. The migrated implementation tasks sit under the PBIs that deliver them, and the verification task of this PBI is the proof on the published package. The feature is done when a gateway generated from the published package with the platform profile builds and passes unchanged and the template inventory of this repository lists the new symbols.
Acceptance criteria
| AC1 | Given the template repository ConnectSoft.ApiGatewayTemplate with the work of this feature, when the template is packed, installed and instantiated in its pipeline, then the generated solution builds and its tests pass before the package publishes with a verified version (ADR-0028, model/components.yaml). |
| AC2 | Given the work of AIFACTORY-TASK-588 (platform gateway switch with routes from the fronts list) is done, then the UseFactoryProfile switch generates the named clients and the REST and gRPC routes from a fronts file that lists the services of the platform, the generated gateway forwards each route with the tenant and project headers, and the acceptance suite covers one route per protocol (ADR-0028 decision 2, model/gateways.yaml). |
| AC3 | Given the work of AIFACTORY-TASK-589 (token and scope validation at the gateway) is done, then the generated gateway validates the token of the authorization server, answers 404 for a route that addresses another tenant and 403 for a project or a scope the token does not grant, and forwards the validated scope to the fronted service, and the matrix of role, tenant and project is covered (ADR-0015). |
| AC4 | Given the work of AIFACTORY-TASK-590 (no business state in a gateway) is done, then an architecture test of a gateway generated with the Platform role fails when a persistence model, an aggregate, a migration or a message consumer is present, and the Studio backend-for-frontend keeps its session and view state through an explicit override of the test, one named exemption that lists each admitted type, outside which the test still fails (ADR-0028 decision 2, model/services/factory-studio/StudioBff.yaml). |
| Traces: adrs | ADR-0015, ADR-0028 |
| Depends on | AIFACTORY-US-236, AIFACTORY-US-237, AIFACTORY-US-238, AIFACTORY-US-239 |
| Sources | model/components.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, model/gateways.yaml, model/services/factory-studio/StudioBff.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-668 Verify api-gateway-template-delivered by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build on the gateway generated from the published package with the platform profile; they pass and prove AC1 to AC4 of AIFACTORY-US-106. |
ConnectSoft.ApiGatewayTemplate |
AIFACTORY-TASK-1115 Template inventory of this repository records the UseFactoryProfile switch and the GatewayRole choice |
documentation | After python -I tools/docs_model inventory-templates, model/template-parameters/connectsoft-apigateway.yaml lists UseFactoryProfile and GatewayRole with its two values, and the generated row of docs/architecture/catalogs/templates.md still renders. |
ConnectSoft.AI.SoftwareFactory.Documentation |