AIFACTORY-FEAT-002: ControlPlaneApi: 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 Control Plane (PF-01) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 52 of 185 (Factory code)
ControlPlaneApi is the platform API gateway of bounded context BC-01 (Project & Environment). The API gateway of the Control Plane platform (ADR-0028): routes public REST and internal gRPC calls to the 7 services it fronts, validates tokens and scopes, and owns no business state. Its own repository is ConnectSoft.AI.SoftwareFactory.ControlPlaneApi.
| Delivers | ControlPlaneApi (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0001, ADR-0009, ADR-0012, ADR-0015, ADR-0016, ADR-0017 |
| Requirements | FR-01, FR-03, FUX-01, NFR-01, NFR-07, NFR-17, XL-01 |
| Depends on | — |
| Sources | model/services/control-plane/ControlPlaneApi.yaml |
Scenarios to trace (8, catalog): SCN-ControlPlaneApi-001 ✓, SCN-ControlPlaneApi-002 ✓, SCN-ControlPlaneApi-003 ✓, SCN-ControlPlaneApi-004 ✓, SCN-ControlPlaneApi-005 ✓, SCN-ControlPlaneApi-006 ✓, SCN-ControlPlaneApi-007 ✓, SCN-ControlPlaneApi-008 ✓
AIFACTORY-US-054: ControlPlaneApi routes the calls of its platform under a trusted scope¶
enabling · persona platform-admin
As a platform admin, I want one gateway in front of the seven services of the Control Plane 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 the service can trust.
This is the integration PBI of the Control Plane gateway. ADR-0028 re-scopes the former composition host as the API gateway of its platform: ControlPlaneApi routes public REST and internal gRPC calls to the seven services the model lists under deployment.fronts (ProjectService, EnvironmentService, AgentRegistryService, AgentCardService, RunControlService, CostUsageService and FactoryCommercialService), validates tokens and scopes and owns no business state. The repository ConnectSoft.AI.SoftwareFactory.ControlPlaneApi is not created by this feature: the repository checklist of feature repository-and-pipeline-conventions created it in I0 (AIFACTORY-TASK-1514, after AIFACTORY-TASK-190 proved the checklist on the first repository), and this feature takes it as it stands. It is 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, consumes no event (ADR-0028 amendment on gateways and events) and its only store is the shared cache. 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; the gateway copies neither the accessor nor the token contract. 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-404), token, tenant, project and scope on every read and sandbox route (AIFACTORY-US-405), the pass-through of a shared-write call with its idempotency key (AIFACTORY-US-406), the production, publication and spend routes whose gate stays in the fronted service (AIFACTORY-US-407), and health, modules, limits and telemetry with the three failure modes of a gateway (AIFACTORY-US-408). A call without a token, with an expired token or with a user token issued for another gateway is answered 401 and a missing scope 403, and no fronted service is called. Where the path or a message field of a route names the project or the tenant, the gateway answers 403 for a project the token does not grant and 404 for another tenant itself and calls no service; where a route names only a resource id, the gateway forwards under the tenant of the token and the scope of the operation, the fronted service answers 403 for a missing project role and 404 for a resource of another tenant (ADR-0015 amendment D113), and the gateway returns that answer unchanged. Five of the seven services are delivered in the same increment. AgentCardService and FactoryCommercialService arrive in later increments, and so do the REST operations of AgentRegistryService: until then a route whose service is not deployed answers 503 with a problem response that names the service, and a route whose operation a thin delivery does not host returns the answer of that service unchanged. The gateway invents no response.
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.ControlPlaneApi as the repository checklist of feature repository-and-pipeline-conventions created it in I0, whose first commit is the unchanged output of dotnet new connectsoft-apigateway -n ConnectSoft.AI.SoftwareFactory.ControlPlaneApi --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 with complete reports and a container image is published (ADR-0028, model/services/control-plane/ControlPlaneApi.yaml). |
| AC2 | Given a valid token for a route of each fronted service delivered in the increment, when the call passes the gateway, then the scope is established once from the token through the scope accessor of the pinned abstractions package, the call is forwarded with tenant, project and correlation id, the fronted service answers and the response returns unchanged, as AIFACTORY-US-405 to AIFACTORY-US-407 prove per route class (ADR-0015, FR-01). |
| 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 ControlPlaneApi as a consumer (ADR-0028, model/services/control-plane/ControlPlaneApi.yaml). |
| AC4 | Given the gateway deployed with two replicas, when ControlPlaneApi/Health is probed and one replica is stopped, then health reports the identity platform and the fronted services, a replica stays in rotation while it can validate tokens, the other replica keeps serving and nothing is replayed, because the gateway holds no state (ADR-0017, model/services/control-plane/ControlPlaneApi.yaml). |
| Traces: services | ControlPlaneApi, ProjectService, EnvironmentService, AgentRegistryService, RunControlService, CostUsageService |
| Traces: apis | ControlPlaneApi/Health |
| Traces: adrs | ADR-0001, ADR-0015, ADR-0017, ADR-0028 |
| Traces: requirements | FR-01 |
| Depends on | AIFACTORY-US-404, AIFACTORY-US-405, AIFACTORY-US-406, AIFACTORY-US-407, AIFACTORY-US-408, feature:repository-and-pipeline-conventions, feature:component-api-gateway-template, feature:component-extensions-ai |
| Sources | model/services/control-plane/ControlPlaneApi.yaml, model/gateways.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/control/services/control-plane-api/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-004 Take the repository ConnectSoft.AI.SoftwareFactory.ControlPlaneApi as the repository checklist created it and confirm its scaffold of the Platform gateway role |
implementation | The repository is not created here and no second scaffold is run: the repository checklist of feature repository-and-pipeline-conventions created it in I0 (AIFACTORY-TASK-1514, after AIFACTORY-TASK-190 proved the checklist on the first repository), with the unchanged output of dotnet new connectsoft-apigateway -n ConnectSoft.AI.SoftwareFactory.ControlPlaneApi --UseFactoryProfile true --GatewayRole Platform from the pinned template package as its first commit. This task takes the repository as it stands: it confirms that the pinned template package and the gateway role Platform of that commit are the ones this feature builds on, that the solution builds and that the template tests, the architecture test of the Platform role included, pass in the repository pipeline, which publishes the container image; a deviation is corrected in the repository before the fronts file of AIFACTORY-TASK-005 is written. |
ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |
AIFACTORY-TASK-1658 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 6, the ports https 7400 and grpc 7402, the liveness and readiness probes on the health operation and one base address per fronted service from configuration, as model/services/control-plane/ControlPlaneApi.yaml records them, and leaves ControlPlane:Host:FrontedServices at its modelled default, the seven service names of deployment.fronts (D117); the same image runs in the saas-default, hybrid and on-prem topologies with the identity authority of the profile (ADR-0017). | ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |
AIFACTORY-TASK-698 Verify control-plane-api-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; a run that discovers no test counts as a failure; the runs pass and prove AC1 to AC4 of AIFACTORY-US-054, that is the repository taken as the checklist created it with its scaffold of the Platform role, the scope established once and forwarded, the architecture test of the Platform role and, for AC4, the acceptance test of feature TwoReplicas (dotnet test -c Release --filter "Category=Acceptance&Feature=TwoReplicas"), which hosts two instances of the gateway behind one test balancer with the fakes of the fronted services, probes ControlPlaneApi/Health on both, stops one instance and asserts that the other keeps serving and that no call is replayed. |
ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |
AIFACTORY-US-404: Control Plane fronts file: named clients and REST and gRPC routes of the seven fronted services, generated at build¶
enabling · persona platform-admin
As a platform admin, I want the route table of the Control Plane 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 and is no reverse proxy, 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 Control Plane. It lists the seven services of deployment.fronts in model/services/control-plane/ControlPlaneApi.yaml, each with its base addresses from configuration and its operations in the shape of the apis section of its service file: name, method and path or gRPC method, scope, side-effect class and idempotency. The REST operations are the public surface that StudioBff and the clients call; the gRPC methods are the internal surface the Agent Mesh calls through AgentRuntimeWorker for leases, outcomes, approval requests and release loading. Each route carries the scope and the side-effect class of its operation, which is what the route class PBIs of this feature enforce. A test lists the emitted route table against the file and against the 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. The gateway adds no operation of its own beyond Health and ListModules, transforms no payload and composes no response from two services: the response of a fronted service returns unchanged. The fronts file alone decides which routes are hosted, because the routes are generated from it at build. The option ControlPlane:Host:FrontedServices of the model is bound at startup and compared with the fronts file: 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, so a change of the list is a new build and a new deployment. The modelled default of the option equals the service set of deployment.fronts, the seven service names (D117), so a gateway deployed without a value for the option starts with exactly the routes of the fronts file.
Acceptance criteria
| AC1 | Given the fronts file of the Control Plane, 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 those services, each with the scope, side-effect class and idempotency of the operation, and the route table test passes against model/services/control-plane/ControlPlaneApi.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 ControlPlane:Host:FrontedServices at its default, which model/services/control-plane/ControlPlaneApi.yaml states as the seven services of deployment.fronts, when the gateway starts, then startup succeeds; given a value of the option that differs from the services 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 (ADR-0028, 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 because the gateway exchanges no token, the tenant, the project, the correlation id and the trace context, and the response of the fake returns unchanged (ADR-0015, FR-01). |
| Traces: services | ControlPlaneApi, ProjectService, EnvironmentService, AgentRegistryService, RunControlService, CostUsageService |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-01 |
| Depends on | feature:component-api-gateway-template |
| Sources | model/services/control-plane/ControlPlaneApi.yaml, model/gateways.yaml, docs/architecture/catalogs/gateways.md, docs/planes/control/services/control-plane-api/index.md#context-and-boundaries |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-005 Fronts file with the REST and gRPC operations of ProjectService, EnvironmentService, AgentRegistryService, AgentCardService, RunControlService, CostUsageService and FactoryCommercialService |
implementation | The fronts file lists the seven services of deployment.fronts with 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 ControlPlane:Host:FrontedServices, whose default is the seven service names of deployment.fronts (D117), is compared with the services 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.ControlPlaneApi |
AIFACTORY-TASK-1659 Fakes of the seven fronted services and the token matrix of the acceptance suite |
fixture | The acceptance suite of the gateway holds one fake per fronted service 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, tenant and project, including an expired token, an identity token, a user token of another audience and a workload token with and without a service scope. | ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |
AIFACTORY-TASK-1660 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-404: one route per operation of model/services/control-plane/ControlPlaneApi.yaml and the service files it fronts, the failing builds, the start with the option at its default, the failing startup on an option value that differs from the fronts file, the 404 of an unknown path and one forwarded call per service and protocol. |
ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |
AIFACTORY-US-405: A read or sandbox route forwards a call only under a validated token, the tenant of the token, a granted project and the scope of its operation¶
behavior · persona requester
As a requester, I want my read calls to reach the service only with the tenant, project and scope my token grants, so that I see what I am entitled to and nobody reads across a tenant or a project through the gateway.
A caller reaches a read or sandbox operation of the Control Plane through the gateway: a requester reads a run or the environments of a project, an observer lists usage, an asset maintainer validates a release candidate, and a worker of the Agent Mesh streams a release over gRPC. A user presents an access token of the authorization server whose one audience is this gateway (ADR-0015 amendment on the audience of a user token); a client that calls two gateways requests two tokens. A workload presents a workload token, which carries service scopes, no audience of a user API and no tenant claim, and is admitted only on a route whose operation names a service scope the token holds. The gateway validates issuer, signature, lifetime and audience through the pinned resource-server library and requires the scope the operation names. For a user token it takes the tenant from the tid claim and overwrites any tenant header of the caller, and it admits the project a route names in its path or in a message field only when the token holds a role claim for that project or the tenant-wide Platform admin role. A workload token carries no tenant claim, so the overwrite does not apply to it: for a workload token that holds the service scope the operation names, the gateway forwards the tenant-id and the project metadata of the caller unchanged, because the fronted service reads a forwarded tenant and project only under that scope (ADR-0015 amendment D114); for a workload token without the scope the answer is PERMISSION_DENIED and no fronted service is called. The scope is established once with the scope accessor of the pinned ConnectSoft.Extensions.AI.Factory.Abstractions package and forwarded: the authorization header, the tenant in X-Tenant-Id on REST and tenant-id in gRPC metadata, the project header of the abstractions package, the correlation id and the trace context. The authorization header carries the user token itself: the gateway exchanges no token, and the fronted service validates the forwarded token again, accepts the audience of its own gateway, which is this one, and applies its own tenant filter (ADR-0015 amendment D117). For a read route the response is served by the fronted service with no side effect; for a sandbox route, which in this platform is ValidateRelease of AgentRegistryService, the service reports and changes no shared state. In this increment the sandbox route is proven against the fake of AgentRegistryService generated from the fronts entry, because ValidateRelease arrives with feature agent-registry-service-publication in I2 (D140). The gateway returns the response unchanged with the correlation id and keeps nothing of the call. 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 the scope of the operation 403. Where the path or a message field of the route names the project or the tenant, the gateway answers 403 for a token without a role in that project and 404, over gRPC NOT_FOUND, for another tenant itself. In each of these cases no fronted service is called, and the refusal is counted for the route and logged with the correlation id and without the token. Where the route names only a resource id, such as a run, a release or an environment, a gateway without business state cannot know the project or the tenant of the resource: it forwards the call under the tenant of the token and the scope of the operation, the fronted service answers 403 for a missing project role and 404 for a resource of another tenant (ADR-0015 amendment D113), and the gateway returns that answer unchanged. When the fronted service does not answer, the route answers 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 the scope of a read operation and a role in the addressed project, when the read route is called, then the gateway forwards the call with the user token unchanged in the authorization header, without a token exchange, the tenant of the tid claim, the project header, the correlation id and the trace context, the fronted service, which accepts the audience of its own gateway, answers, the response returns unchanged with the correlation id and nothing is written by the gateway (SCN-ControlPlaneApi-005, ADR-0015, FR-01). |
| AC2 | Given the matrix of role, tenant and project of the acceptance suite, when read routes of ProjectService, EnvironmentService, RunControlService and CostUsageService 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 the scope 403; where the path or a message field of the route names the project or the tenant, a token without a role in that project is answered 403 and another tenant 404 by the gateway itself, and in none of these cases a fronted service is called; where the route names only a resource id, the gateway forwards the call under the tenant of the token and the scope of the operation, the fronted service answers 403 for a missing project role and 404 for a resource of another tenant (ADR-0015 amendment D113) and the gateway returns that answer unchanged (SCN-ControlPlaneApi-005, ADR-0015). |
| AC3 | Given a valid 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 before the call is forwarded; given a workload token, which carries no tenant claim, on an internal gRPC route, when the token holds the service scope the operation names, then the gateway forwards the tenant-id and the project metadata of the caller unchanged, because the fronted service reads a forwarded tenant and project only under that scope (ADR-0015 amendment D114), and when the token lacks that scope the answer is PERMISSION_DENIED and no fronted service is called; a resource outside the forwarded tenant is answered NOT_FOUND by the fronted service and that answer returns unchanged (SCN-ControlPlaneApi-005, ADR-0015). |
| AC4 | Given a token with factory.assets.write, when the sandbox route of AgentRegistryService is called, then the call is forwarded under the same token, tenant and scope rules, the gateway adds no gate of its own to the class and the answer of the service returns unchanged; the refusals apply as on a read route and no fronted service is called when the gateway refuses; in this increment the sandbox route is proven against the fake of AgentRegistryService generated from the fronts entry, because ValidateRelease arrives with feature agent-registry-service-publication in I2 (D140, SCN-ControlPlaneApi-006, model/services/control-plane/AgentRegistryService.yaml). |
| AC5 | 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 services keep serving (SCN-ControlPlaneApi-005, model/services/control-plane/ControlPlaneApi.yaml). |
| Traces: services | ControlPlaneApi, ProjectService, EnvironmentService, AgentRegistryService, RunControlService, CostUsageService |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-01, FUX-01, NFR-01 |
| Traces: scenarios | SCN-ControlPlaneApi-005, SCN-ControlPlaneApi-006 |
| Depends on | AIFACTORY-US-404, feature:component-api-gateway-template, feature:component-extensions-ai |
| Sources | model/services/control-plane/ControlPlaneApi.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/control/services/control-plane-api/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1661 Issuer, audience, project parameter and workload scope configuration of the read and sandbox routes |
implementation | The gateway is configured with the authority of ConnectSoftIdentityPlatform:Authority and its own resource as the one audience of a user token; each read and sandbox route names the path or message field that addresses its project or tenant, or is marked as addressed by a resource id only, in which case the gateway checks token and scope and leaves the project role and the tenant of the resource to the fronted service; on a gRPC route the route names the service scope a workload token must hold; for a user token the tenant header is overwritten with the tid claim, and for a workload token that holds the service scope the tenant-id and project metadata of the caller are forwarded unchanged (ADR-0015 amendment D114), while a workload token without the scope is answered PERMISSION_DENIED before any call; the scope is established through the scope accessor of the pinned abstractions package and forwarded in the canonical tenant header and the project header; the user token is forwarded unchanged in the authorization header and no token is exchanged, since the fronted service accepts the audience of its own gateway (ADR-0015 amendment D117); refusals are counted per route and logged with the correlation id and without the token. | ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |
AIFACTORY-TASK-1662 Verify the read and sandbox routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ControlPlaneApi-005\|Scenario=SCN-ControlPlaneApi-006)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-405 over the matrix of role, tenant and project, the token received by the fake equal to the user token of the caller, a route addressed by a resource id whose 403 and 404 come from the fake and return unchanged, the overwritten tenant header of a user token, a workload token on a gRPC route with the service scope (tenant-id and project metadata forwarded unchanged) and without it (PERMISSION_DENIED and no call to the fake), the sandbox route against the fake of AgentRegistryService generated from the fronts entry and a fake that stops answering. |
ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |
AIFACTORY-US-406: A shared-write route passes the idempotency key through and the gateway keeps nothing between calls¶
behavior · persona requester
As a requester, I want a write I repeat after a failure to be applied once, so that a lost answer or a restarted gateway never creates a second project, environment or run.
A shared-write operation changes state that others read: creating a project or an environment, setting a membership, submitting or cancelling a run, setting a budget. The caller sends it through the gateway under the token, tenant, project and scope rules of AIFACTORY-US-405. An operation whose model entry declares idempotency key-header is called with an Idempotency-Key; the gateway forwards the header unchanged and the fronted service applies the request once under its own rule: the same key with the same body returns the same result, the same key with a different body is a conflict, and that 409 returns to the caller unchanged. The gateway is no party to idempotency. It stores neither the key nor the result, keeps no session and no pending call, has no outbox and writes no event, so a gateway replica that crashes during a call loses nothing: the replica restarts, nothing is replayed, and the caller retries with the same key and receives from the service the result of the first application (failure mode of a gateway replica crash in the model). When the fronted service does not answer, the route answers 503 with a problem response that names the service and carries a retry hint, the other routes keep serving, and the caller retries with its key. A refusal by the gateway (401, 403 or, on a route whose path or message field names the project or the tenant, 404) reaches no fronted service, so it applies nothing. On a route that names only a resource id, such as the cancellation of a run, the gateway forwards under the tenant of the token and the scope of the operation, and the 403 of the fronted service for a missing project role and its 404 for a resource of another tenant (ADR-0015 amendment D113) return unchanged; the service has applied nothing. The answer to a decision a waiting attempt asks for is such a route: the Studio and the command-line client call RunControlService/AnswerDecision through the gateway with the user token of a member whose scope carries factory.runs.operate, the gateway forwards it under that token, and the 404, 409 and 503 of RunControlService return unchanged (D137). A missing key, an invalid body and every domain refusal are answers of the fronted service and return unchanged with the correlation id. The gateway records request count and latency for the route with the status that was returned.
Acceptance criteria
| AC1 | Given a valid token and a shared-write route whose operation declares idempotency key-header, when the call arrives with an Idempotency-Key, then the gateway forwards the request with the header unchanged, the fronted service applies it once and the response returns unchanged with the correlation id (SCN-ControlPlaneApi-007, ADR-0015). |
| AC2 | Given the same call repeated with the same key, and then with the same key and a different body, when both pass the gateway, then the first returns the result of the first application and the second returns the 409 of the fronted service unchanged; the gateway has stored neither the key nor a result (SCN-ControlPlaneApi-007, ADR-0028). |
| AC3 | Given a gateway replica stopped while a shared-write call is in flight, when the caller retries with the same key 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-ControlPlaneApi-007, model/services/control-plane/ControlPlaneApi.yaml). |
| AC4 | Given a call without a token, a token that lacks 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; where the path or a message field of the route names the project or the tenant, a token without a role in that project is answered 403 and another tenant 404 by the gateway itself; a call the gateway refuses reaches no fronted service; where the route names only a resource id, the gateway forwards under the tenant of the token and the scope of the operation, and the 403 of the fronted service for a missing project role and its 404 for a resource of another tenant (ADR-0015 amendment D113) return unchanged; the 503 names the service and carries a retry hint while the other routes keep serving (SCN-ControlPlaneApi-007, ADR-0015). |
| Traces: services | ControlPlaneApi, ProjectService, EnvironmentService, RunControlService, CostUsageService |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-03 |
| Traces: scenarios | SCN-ControlPlaneApi-007 |
| Depends on | AIFACTORY-US-404, AIFACTORY-US-405, feature:component-api-gateway-template |
| Sources | model/services/control-plane/ControlPlaneApi.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1663 Forwarded headers of a write route and a stateless call path |
implementation | A shared-write route forwards the Idempotency-Key header, the body and the established scope unchanged and returns the status and the body of the fronted service unchanged; no key, body or result is written to the shared cache or to any store; request count and latency are recorded for the route with the returned status. | ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |
AIFACTORY-TASK-1664 Verify the shared-write routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ControlPlaneApi-007"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-406 with a fake that applies a key once, a replica stopped during a call, a route addressed by a resource id whose 403 and 404 come from the fake and return unchanged, and a fake that stops answering. |
ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |
AIFACTORY-US-407: A production, publication or spend route is forwarded under its scope and the gate of the action stays in the fronted service¶
behavior · persona workspace-admin
As a workspace admin, I want a gated action to be decided by the service that owns its state, with the gateway only checking who I am and what I may call, so that an approval or a budget is never decided twice or by a component that holds no state.
Three side-effect classes of the model carry a gate beyond the scope: a production action, a publication and a spend. In the Control Plane the production routes are those of EnvironmentService and ProjectService (freezing and unfreezing an environment, closing, suspending and resuming a project), the publication routes are those of AgentRegistryService (submitting, publishing, deprecating and revoking a release, moving an alias) and the spend routes are those of FactoryCommercialService. ADR-0028 leaves a platform gateway routing and the validation of tokens and scopes and no business state, and names a gateway that accumulates logic beyond routing and validation as a reason to revisit the decision. The gateway therefore treats these routes as it treats every route: it validates the token, takes the tenant from it, admits the project a route names only when the token grants it, requires the scope the operation names (factory.projects.admin, factory.assets.write, factory.assets.publish or the scope of the spend operation) and forwards the call with the established scope. The gate itself is decided where the state is. EnvironmentService and ProjectService decide a production action and announce it by their events; AgentRegistryService publishes a release only after its gates and the publication approval and answers 412 when a precondition does not hold; the rules of the commands D117 added, the reason and the Workspace admin or Platform admin of SuspendProject and ResumeProject and the reason and the Platform admin of DeprecateRelease and RevokeRelease, are enforced by ProjectService and AgentRegistryService, and their routes are generated from the fronts file under these classes like every other route; the approval is requested from and decided in RunControlService; budgets and reservations are owned by CostUsageService. The gateway evaluates no approval, holds no approval reference, reads no budget and keeps no reservation, and it writes no audit evidence. Where a command leaves evidence of its own, the service that owns the command writes it in the transaction of the command, as AgentRegistryService does for a publication; where the service writes only its event, as EnvironmentService does with EnvironmentStateChanged for a freeze or an unfreeze, AuditService records the evidence from that event. The answer of the fronted service, including 409 and 412, returns 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. Where the path or a message field of a route names the project or the tenant, the gateway answers 403 for a token without a role in that project and 404 for another tenant itself and calls no service. The production routes this PBI proves, FreezeEnvironment and UnfreezeEnvironment, name only an environmentId, and so does every route addressed by a run, a release or an approval: a gateway without business state cannot resolve the project or the tenant of such an id, so it forwards the call under the tenant of the token and the scope of the operation, the fronted service answers 403 for a missing project role and 404 for a resource of another tenant (ADR-0015 amendment D113), and the gateway returns that answer unchanged. In this increment the production routes are proven against EnvironmentService and ProjectService; the publication and spend routes are proven against a fake fronted service generated from the fronts entry, because the REST operations of AgentRegistryService and the service FactoryCommercialService arrive in later increments with their own features.
Acceptance criteria
| AC1 | Given a token with factory.projects.admin and a role in the project of an environment, when the production route that freezes the environment is called, then the gateway forwards the call under the tenant of the token and the scope of the operation, because the route names only the environmentId; EnvironmentService resolves the project of the environment, decides the action and writes its event, and its answer returns unchanged with the correlation id; the gateway evaluates no approval and writes nothing (SCN-ControlPlaneApi-003, ADR-0028). |
| AC2 | Given a token with factory.assets.publish, when a publication route is called against the fake of AgentRegistryService that answers 200, 409 or 412, then the gateway forwards the call under the established scope and returns each answer unchanged, holding no approval reference of its own (SCN-ControlPlaneApi-004, ADR-0028, model/services/control-plane/AgentRegistryService.yaml). |
| AC3 | Given a token with the scope of a spend operation, when the spend route is called against a fake fronted service generated from the fronts entry, then the gateway forwards the call under the established scope and returns the answer unchanged; it reads no budget and holds no reservation (SCN-ControlPlaneApi-008, ADR-0028). |
| AC4 | Given a call without a token or with an expired token, or a token that lacks the scope of the operation, when a production, publication or spend route is called, then the gateway answers 401 or 403 and no fronted service is called; given a route whose path or message field names the project or the tenant, when the token grants no role in that project or the route addresses another tenant, then the gateway answers 403 or 404 itself and calls no service; given a route that names only a resource id, such as the environmentId of a freeze or the releaseId of a publication, when it is called, then the gateway forwards under the tenant of the token and the scope of the operation, the fronted service answers 403 for a missing project role and 404 for a resource of another tenant (ADR-0015 amendment D113) and the gateway returns that answer unchanged (SCN-ControlPlaneApi-003, SCN-ControlPlaneApi-004, SCN-ControlPlaneApi-008, ADR-0015). |
| Traces: services | ControlPlaneApi, EnvironmentService, ProjectService, AgentRegistryService |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-01, NFR-04 |
| Traces: scenarios | SCN-ControlPlaneApi-003, SCN-ControlPlaneApi-004, SCN-ControlPlaneApi-008 |
| Depends on | AIFACTORY-US-404, AIFACTORY-US-405, feature:component-api-gateway-template |
| Sources | model/services/control-plane/ControlPlaneApi.yaml, model/services/control-plane/EnvironmentService.yaml, model/services/control-plane/AgentRegistryService.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1665 Fakes of the publication and spend routes and the route class register of the gateway |
fixture | The acceptance suite holds a fake of the publication operations of AgentRegistryService that answers 200, 409 and 412 and a fake fronted service generated from the spend entry of the fronts file; a register test lists every route of class production, publication and spend 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 a budget. | ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |
AIFACTORY-TASK-1666 Verify the production, publication and spend routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ControlPlaneApi-003\|Scenario=SCN-ControlPlaneApi-004\|Scenario=SCN-ControlPlaneApi-008)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-407: each class forwarded under its scope, the answers 409 and 412 returned unchanged, the refusals of the gateway without a call to a fronted service, the 403 and the 404 of a fronted service on a route addressed by a resource id returned unchanged, and the register of gated routes. |
ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |
AIFACTORY-US-408: Health, modules, limits and telemetry of the 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 services the gateway fronts, so that I can tell a failing service from a failing gateway and act on the right one.
An operator, the Studio about page and the probes of the cluster read the state of the gateway through its two own operations. ControlPlaneApi/Health reports liveness and readiness of the gateway with the aggregated health of the seven services it fronts and of the identity platform. Liveness needs no token; the detail is served to a caller whose scope carries factory.health.read. The identity platform is the one required dependency of the gateway, and the health check is the detection signal the model names for its failure. What the gateway does when it is unreachable is decided (D117, ADR-0015 amendment). While a cached signing key still validates tokens, the gateway stays in rotation: readiness stays ready, tokens that were already issued keep passing, and from the first failed probe ControlPlaneApi/Health answers 200 with the health degraded and a detail that names the identity platform as unreachable, so the operator sees the failure in health while calls still pass. The gateway leaves rotation only when no valid key remains, because none was cached or the cached keys expired: readiness turns unready, ControlPlaneApi/Health answers 503 with a problem response that names the identity platform, and calls are refused, so the gateway fails closed. Liveness keeps answering 200 without a token in both phases. A fronted service is an optional dependency: when it does not answer, health reports it as unavailable in the detail, its routes answer 503 with a retry hint, and the routes of the other services keep serving. ControlPlaneApi/ListModules returns the services the gateway fronts with their versions and repositories to a caller whose scope carries factory.meta.read. The configuration platform is optional as well: it supplies feature flags and the runtime configuration of routes and rate limits when it is available, and when it is not, the gateway keeps the routes and limits of its own configuration. A call that exceeds the rate limit configured for its route is refused with 429. The gateway emits connectsoft.factory.host.requests with the dimensions service, route and status and connectsoft.factory.host.request_duration with service and route, the latency including the fronted service, and carries the trace context to the service; its logs never contain a token, a prompt, an artifact or a payload. A replica that crashes is detected by the readiness probe and restarts; because the gateway holds no state, nothing is replayed. The roles of the gateway are Observer, Operator and Platform admin.
Acceptance criteria
| AC1 | Given the gateway with the identity platform and all fronted services reachable, when ControlPlaneApi/Health is called, then liveness answers 200 without a token and a caller with factory.health.read receives 200 with the state of each of the seven fronted services and of the identity platform (SCN-ControlPlaneApi-001, NFR-17). |
| AC2 | Given the identity platform is unreachable and a cached signing key still validates tokens, when calls arrive and ControlPlaneApi/Health is probed, then tokens that were already issued are validated with the cached key, readiness stays ready so the replica stays in rotation, and from the first failed probe health answers 200 with the health degraded and a detail that names the identity platform as unreachable, while liveness keeps answering 200; given no valid key remains, because none was cached or the cached keys expired, when calls arrive, then they are refused, readiness is unready so the replica leaves rotation, ControlPlaneApi/Health answers 503 with a problem response that names the identity platform and no state changes (SCN-ControlPlaneApi-001, model/services/control-plane/ControlPlaneApi.yaml). |
| AC3 | Given one fronted service does not answer, when ControlPlaneApi/Health and the routes are called, then health reports that service as unavailable in its detail, its routes answer 503 with a retry hint that names the service and the routes of the other services keep serving (SCN-ControlPlaneApi-001, ADR-0028). |
| AC4 | Given a caller with factory.meta.read, when ControlPlaneApi/ListModules is called, then the response is 200 with the seven fronted services, each with its version and repository, as model/services/control-plane/ControlPlaneApi.yaml lists them under deployment.fronts; a call without a token is answered 401 and a token without the scope 403, and nothing is written (SCN-ControlPlaneApi-002). |
| AC5 | Given routed calls, a call above the rate limit of its route and an unavailable configuration platform, when the metrics and logs are read, then connectsoft.factory.host.requests counts every call by service, route and status, the call above the limit was refused with 429, connectsoft.factory.host.request_duration holds the latency by service and route, the gateway kept the routes and limits of its own configuration, and no log record holds a token or a payload (model/services/control-plane/ControlPlaneApi.yaml). |
| Traces: services | ControlPlaneApi |
| Traces: apis | ControlPlaneApi/Health, ControlPlaneApi/ListModules |
| Traces: adrs | ADR-0015, ADR-0017, ADR-0028 |
| Traces: requirements | NFR-07, NFR-17 |
| Traces: scenarios | SCN-ControlPlaneApi-001, SCN-ControlPlaneApi-002 |
| Depends on | AIFACTORY-US-404, feature:component-api-gateway-template, feature:component-observability-factory-conventions |
| Sources | model/services/control-plane/ControlPlaneApi.yaml, docs/planes/control/services/control-plane-api/index.md#metrics-and-observability, docs/planes/control/services/control-plane-api/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-006 Health, modules and telemetry of the gateway |
implementation | The health operation serves liveness without a token and the detail under factory.health.read with the aggregated state of the seven fronted services and of the identity platform; while the identity platform is unreachable and a cached signing key still validates tokens, readiness stays ready and the operation answers 200 with the health degraded and the identity platform named in the detail from the first failed probe; when no valid key remains, readiness turns unready and the operation answers 503 with a problem response that names the identity platform (D117); liveness stays at 200 in both phases; the modules operation lists the fronted services with version and repository under factory.meta.read; every routed call records connectsoft.factory.host.requests and connectsoft.factory.host.request_duration with their modelled dimensions and carries the trace context to the service. | ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |
AIFACTORY-TASK-1667 Rate limits per route from configuration and the degrade path of the configuration platform |
implementation | Each route takes its rate limit from the configuration of the gateway through the pinned rate-limiting library and answers 429 above it; when the configuration platform is available its route and limit values replace the local ones, and when it is not, the gateway keeps its own configuration and reports the configuration platform as an optional dependency in the health detail. | ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |
AIFACTORY-TASK-1668 Runbook of the three failure modes of the gateway |
documentation | The repository documentation holds one runbook entry per failure mode of model/services/control-plane/ControlPlaneApi.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 entry of the identity platform states its two phases, degraded and in rotation while a cached signing key validates tokens, and out of rotation and failing closed when no valid key remains (D117, NFR-17). | ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |
AIFACTORY-TASK-1669 Verify health, modules, limits and telemetry through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ControlPlaneApi-001\|Scenario=SCN-ControlPlaneApi-002)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-408 with the identity platform stopped while a cached key validates tokens (readiness ready, health 200 and degraded), without a cached key and after the cached key expired (readiness unready, health 503), one fake stopped, a call above its limit and the configuration platform stopped. |
ConnectSoft.AI.SoftwareFactory.ControlPlaneApi |