AIFACTORY-FEAT-042: DeliveryHost: 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 DevOps / GitOps (PF-08) · Increment I2 Deliver it · State elaborated · Route backend-developer · Build order 94 of 185 (Factory code)
DeliveryHost is the platform API gateway of bounded context BC-23 (Source & Pipelines). The API gateway of the DevOps / GitOps 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.DeliveryHost.
| Delivers | DeliveryHost (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0004, ADR-0012, ADR-0014, ADR-0015 |
| Requirements | FR-07, FR-08, FUX-05, FUX-06, NFR-08, NFR-12, XL-04, XL-10 |
| Depends on | — |
| Sources | model/services/devops-gitops/DeliveryHost.yaml |
Scenarios to trace (5, catalog): SCN-DeliveryHost-001 ✓, SCN-DeliveryHost-002 ✓, SCN-DeliveryHost-003 ✓, SCN-DeliveryHost-004 ✓, SCN-DeliveryHost-005 ✓
AIFACTORY-US-075: DeliveryHost routes the calls of the DevOps and GitOps platform under a trusted scope¶
enabling · persona operator
As an operator, I want one gateway in front of EnvironmentPromotionService, PipelineExecutionService and ReleaseService that validates tokens and scopes, so that no service of the platform is reachable from outside the cluster except through its gateway and every call arrives with a scope the service can trust.
This is the integration PBI of the gateway of the DevOps and GitOps platform. ADR-0028 makes DeliveryHost the API gateway of its platform: it routes public REST and internal gRPC calls to the three services the model lists under deployment.fronts, EnvironmentPromotionService, PipelineExecutionService and ReleaseService, validates tokens and scopes and owns no business state, no relational store and no secret (gateway role GW-03). The repository ConnectSoft.AI.SoftwareFactory.DeliveryHost is created by the first task of this feature by the steps of the repository checklist of feature repository-and-pipeline-conventions: it is scaffolded once from the pinned API gateway template package with UseFactoryProfile and the gateway role Platform (feature component-api-gateway-template), which fixes persistence, messaging and the actor model to none. The gateway therefore has no outbox and no inbox, consumes and publishes no event (D129) 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 (feature component-extensions-ai); the gateway copies neither the accessor nor the token contract. A user token has one audience, this gateway, and the gateway forwards it unchanged to the fronted service, which accepts the audience of its own gateway, and exchanges no token (ADR-0015 amendments D114 and D117). A workload token carries service scopes and is admitted only on an internal gRPC route whose fronts entry names a service scope the token holds; each of the three gRPC methods takes the service scope of its service (D114, D135): factory.delivery.promote for Promotions.Request, factory.delivery.propose for Pipelines.RecordProposal and factory.delivery.read for Releases.GetRelease (AIFACTORY-US-1317). The feature is delivered by five further PBIs: the fronts file and the routes generated from it (AIFACTORY-US-1317), token, tenant, project and scope on every read route (AIFACTORY-US-1318), the pass-through of a shared-write call (AIFACTORY-US-1319), the production routes whose one approval stays in EnvironmentPromotionService (AIFACTORY-US-1320), and health, systems, limits and telemetry with the three failure modes of a gateway (AIFACTORY-US-1321). A call without a token, with an expired token or with a user token issued for another gateway is answered 401, a missing scope or a project the token does not grant 403, and no fronted service is called. A resource of another tenant is answered 404 by the fronted service (ADR-0015 amendment D113) and the gateway returns that answer unchanged. All three fronted services are delivered complete in this increment, PipelineExecutionService by feature pipeline-execution-service-complete after its thin delivery of I1, so every route serves from the start. The inbound list of model/services/devops-gitops/DeliveryHost.yaml names StudioBff and ToolExecutorHost: ToolExecutorHost, delivered in I1, calls the services for the deploy-environment and propose-change-set tools, and StudioBff in I3; each calls the gateway in its own PBIs, and this feature waits for none of them. The gateway invents no response.
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.DeliveryHost created by the steps of the repository checklist, whose first commit is the unchanged output of dotnet new connectsoft-apigateway -n ConnectSoft.AI.SoftwareFactory.DeliveryHost --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/devops-gitops/DeliveryHost.yaml). |
| AC2 | Given the pipeline of the repository with the acceptance suites of AIFACTORY-US-1317 to AIFACTORY-US-1321, when it runs, then every suite passes: the scope established once through the scope accessor of the pinned abstractions package and the forwarding of the token, the tenant, the correlation id and the trace context are proven by AC3 of AIFACTORY-US-1317, and the stateless replica crash by AC2 of AIFACTORY-US-1319, so this PBI proves neither again (ADR-0015, FR-08). |
| 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, its configuration holds no secret, and no event of the model lists DeliveryHost as a consumer or a publisher (ADR-0028, model/services/devops-gitops/DeliveryHost.yaml). |
| AC4 | Given the gateway deployed with two replicas, when DeliveryHost/DeliveryHealth is probed on each replica, then each reports the identity platform and the three fronted services with the same aggregated state, because the state is read from the fronted services and the gateway holds none (ADR-0017, model/services/devops-gitops/DeliveryHost.yaml). |
| Traces: services | DeliveryHost, EnvironmentPromotionService, PipelineExecutionService, ReleaseService |
| Traces: apis | DeliveryHost/DeliveryHealth |
| Traces: adrs | ADR-0004, ADR-0012, ADR-0014, ADR-0015, ADR-0017, ADR-0028 |
| Traces: requirements | FR-07, FR-08 |
| Depends on | AIFACTORY-US-1317, AIFACTORY-US-1318, AIFACTORY-US-1319, AIFACTORY-US-1320, AIFACTORY-US-1321, feature:repository-and-pipeline-conventions, feature:component-api-gateway-template, feature:component-extensions-ai, feature:environment-promotion-service, feature:pipeline-execution-service-thin, feature:pipeline-execution-service-complete, feature:release-service |
| Sources | model/services/devops-gitops/DeliveryHost.yaml, model/gateways.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/execution/delivery-engine/services/delivery-host/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-245 Create the repository ConnectSoft.AI.SoftwareFactory.DeliveryHost and scaffold it from the API gateway template with the Factory profile and the Platform gateway role |
implementation | The repository exists, created by the steps of the repository checklist of feature repository-and-pipeline-conventions; its first commit is the unchanged output of dotnet new connectsoft-apigateway -n ConnectSoft.AI.SoftwareFactory.DeliveryHost --UseFactoryProfile true --GatewayRole Platform from the pinned template package, whose version the repository records; 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; a deviation is corrected in the repository before the fronts file of AIFACTORY-TASK-246 is written. |
ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-TASK-5275 Deployment values of the gateway that the environment stack reads: replica range, ports, probes and the address of each fronted service |
operations | The repository holds the deployment values of the gateway, from which the environment stack of ADR-0028 (D105) writes the workload manifest of the service; the values state the replica range of 2 to 6, the https port 8120 and the grpc port 8122, the liveness and readiness probes on the health operation and one base address per fronted service from configuration, as model/services/devops-gitops/DeliveryHost.yaml records them; it sets Delivery:Host:FrontedServices to the three service identifiers of deployment.fronts, because the default of the model names the short names pipelines, releases and promotions, sets ConnectSoftIdentityPlatform:Authority to the authority of the profile, holds no secret and binds the shared cache as its only store; the same image runs in the saas-default, hybrid, on-prem and hybrid-compute topologies (ADR-0017). | ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-TASK-707 Verify delivery-host-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-075, that is the repository with its scaffold of the Platform role, the acceptance suites of AIFACTORY-US-1317 to AIFACTORY-US-1321 passing in the same run, 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 with the fakes of the fronted services and probes DeliveryHost/DeliveryHealth on each; the replica crash is proven by AIFACTORY-TASK-5282, not here. |
ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-US-1317: Delivery 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 delivery 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 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 DevOps and GitOps platform. It lists the three services of deployment.fronts in model/services/devops-gitops/DeliveryHost.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 with its streaming mode, scope, side-effect class and idempotency. For EnvironmentPromotionService these are the five REST operations ListPromotions, GetPromotion, RequestPromotion, RollbackPromotion and GetCurrentRelease and the gRPC method Promotions.Request. For PipelineExecutionService these are the six REST operations ListChangeProposals, GetChangeProposal, OpenChangeProposal, ListPipelineRuns, GetPipelineRun and ReconcilePipelineRun and the gRPC method Pipelines.RecordProposal. For ReleaseService these are the four REST operations ListProductReleases, GetProductRelease, CreateProductRelease and WithdrawProductRelease and the gRPC method Releases.GetRelease. That is fifteen REST routes and three unary gRPC routes. By side-effect class nine REST routes and Releases.GetRelease are read, four REST routes and Pipelines.RecordProposal are shared-write, and RequestPromotion, RollbackPromotion and Promotions.Request are production. Each REST entry also states how its operation addresses a project. ListChangeProposals and ListPipelineRuns filter by project, so their project filter is marked as checked against the roles of the token. The operations that address a promotion, a proposal, a pipeline run, a release or an environment by identifier, and RequestPromotion, OpenChangeProposal and CreateProductRelease, whose body names a release, a change set or a pipeline run, are marked as addressed by a resource identifier. ListPromotions and ListProductReleases are marked as scoped by the tenant of the token. Each gRPC entry names the service scope of its method, because a workload token carries service scopes (ADR-0015 amendment D114), and its route admits a workload token only when the token holds that scope; any other caller, a user token among them, is answered PERMISSION_DENIED. Each of the three methods takes the service scope of its service (D135): Promotions.Request names factory.delivery.promote, Pipelines.RecordProposal names factory.delivery.propose and Releases.GetRelease names factory.delivery.read, the scopes the three service files give them. 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. The gateway adds no operation of its own beyond DeliveryHealth and DeliverySystems, transforms no payload and composes no response from two services. The option Delivery:Host:FrontedServices is bound at startup and compared with the service identifiers of the fronts file, and a value that names no service of the file or omits one fails startup with the name; its default in the model names the short names pipelines, releases and promotions instead of the service identifiers, which is reported as a correction like the defaults corrected for other gateways, and until then the deployment sets it (AIFACTORY-TASK-5275). The pipeline publishes the OpenAPI document of the fifteen public REST operations as a build output, checked against the fronts file and the three service files. 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 from that published document, by the rules of feature typed-gateway-clients (AIFACTORY-US-381 to AIFACTORY-US-383), which it applies and does not repeat. It holds the fifteen public REST operations and no internal gRPC method, 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 consumers that pin it. No workload layout is generated, because no public REST operation of this gateway admits a workload token. Its callers hold a user token: the promotions waiting command of the command-line client (AIFACTORY-US-1313) and StudioBff (AIFACTORY-US-1363, AIFACTORY-US-1364) pin the package in their own repositories, and no caller writes a client of this gateway by hand.
Acceptance criteria
| AC1 | Given the fronts file of the DevOps and GitOps 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 those services, fifteen REST routes and three gRPC routes, each with the scope, side-effect class, idempotency and streaming mode of the operation, each gRPC route admitting only a workload token that holds the service scope its entry names, factory.delivery.promote for Promotions.Request, factory.delivery.propose for Pipelines.RecordProposal and factory.delivery.read for Releases.GetRelease (D135), and the route table test passes against model/services/devops-gitops/DeliveryHost.yaml and the three service files under model/services/devops-gitops (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 Delivery:Host:FrontedServices set to the three service identifiers, when the gateway starts, then startup succeeds; given a value that names no service of the fronts file or omits one, the default of the model among them, then startup fails with the differing name; given a path no route matches, 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 per service is called with a valid user token and one gRPC route per service with a workload token that holds the service scope its fronts entry names, then each call reaches the fake of its service with the authorization header carrying the token of the caller unchanged, the tenant of a user token or the tenant metadata a workload forwards, the correlation id and the trace context, and the response of the fake returns unchanged (ADR-0015, FR-08). |
| AC4 | Given the built gateway, when its pipeline publishes the OpenAPI document of the public REST routes, then the document holds exactly the fifteen REST operations of the fronts file with their methods, paths, scopes and response codes and no internal gRPC method, and a contract check fails the build when it differs from the three service files under model/services/devops-gitops (docs/architecture/api-governance.md). |
| AC5 | Given the published OpenAPI document 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 fifteen public REST operations in the user-token layout and no internal gRPC method, the contract check against the three service files under model/services/devops-gitops passes, the token issued for DeliveryHost 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 the command-line client and StudioBff as its consumers (model/backlog/pbis/engineering-readiness/typed-gateway-clients.yaml, ADR-0015). |
| Traces: services | DeliveryHost, EnvironmentPromotionService, PipelineExecutionService, ReleaseService |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-07, FR-08 |
| Depends on | feature:component-api-gateway-template, feature:environment-promotion-service, feature:pipeline-execution-service-complete, feature:release-service, feature:typed-gateway-clients, feature:component-api-library-template-factory-clients |
| Sources | model/services/devops-gitops/DeliveryHost.yaml, model/backlog/pbis/engineering-readiness/typed-gateway-clients.yaml, model/services/devops-gitops/EnvironmentPromotionService.yaml, model/services/devops-gitops/PipelineExecutionService.yaml, model/services/devops-gitops/ReleaseService.yaml, model/gateways.yaml, docs/architecture/catalogs/gateways.md, docs/architecture/api-governance.md, docs/planes/execution/delivery-engine/services/delivery-host/index.md#context-and-boundaries |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-246 Fronts file with the REST and gRPC operations of EnvironmentPromotionService, PipelineExecutionService and ReleaseService |
implementation | The fronts file lists the three 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, streaming mode, scope, side-effect class and idempotency; each REST operation carries one of three markings, a project filter checked against the roles of the token for ListChangeProposals and ListPipelineRuns, addressed by a resource identifier, or scoped by the tenant of the token, and a test fails when an operation carries none or two; each gRPC entry names the service scope a workload token must hold, factory.delivery.promote for Promotions.Request, factory.delivery.propose for Pipelines.RecordProposal and factory.delivery.read for Releases.GetRelease, and a test fails on a gRPC entry without a scope; a user token on a gRPC route is answered PERMISSION_DENIED; the build emits the named clients, the fifteen REST routes, the three gRPC routes and the route table; Delivery:Host:FrontedServices is compared with the fronts file at startup; a call without a valid token or scope is refused at the gateway by the generated policies. | ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-TASK-5276 Fakes of the three fronted services and the token matrix of the acceptance suite |
fixture | The acceptance suite holds one fake per fronted service, generated from its fronts entry, that records the headers, metadata and body it received, answers a configured status and can 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, a token with a role in one project and none in another, a token with the tenant-wide Platform admin role, and a workload token with and without the service scope of each gRPC route, factory.delivery.promote, factory.delivery.propose and factory.delivery.read (D135). | ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-TASK-5277 OpenAPI document of the public REST routes of the gateway as a published build output |
contract | The pipeline publishes one OpenAPI document with the fifteen public REST operations of the fronts file, their methods, paths, scopes, idempotency headers and response codes, and no internal gRPC method; a contract check compares the document with the three service files under model/services/devops-gitops and fails the build on a missing operation, an operation of another service or a differing method, path, scope or response code; the document is the input of the client of AIFACTORY-TASK-6601, and no client package is built in this repository. | ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-TASK-6601 Typed client of DeliveryHost in the user-token layout, generated from the published document and published to the ConnectSoft feed |
implementation | One client library in the repository ConnectSoft.AI.SoftwareFactory.Clients, generated with dotnet new connectsoft-api-library, the generation switch and UseFactoryProfile in the JWT bearer layout of the template from the OpenAPI document of AIFACTORY-TASK-5277, holds the fifteen public REST operations of EnvironmentPromotionService, PipelineExecutionService and ReleaseService and no internal gRPC method, takes the shared types from the pinned contracts package and declares no handler, header name or claim name of its own; the contract check of AIFACTORY-TASK-1556 covers its document; 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 DeliveryHost 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 the command-line client and StudioBff as the consumers that pin it. |
ConnectSoft.AI.SoftwareFactory.Clients |
AIFACTORY-TASK-5278 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 AC4 of AIFACTORY-US-1317: one route per operation of the three service files under model/services/devops-gitops, the failing builds, the start with the three service identifiers and the failing startup on a differing value, the 404 of an unknown path, one forwarded call per service and protocol, each gRPC route admitting only a workload token with its service scope, and the contract check of the published OpenAPI document; a check of the deployment values of AIFACTORY-TASK-5275 fails when Delivery:Host:FrontedServices differs from the three service identifiers of deployment.fronts; AC5 is proven in the pipeline of ConnectSoft.AI.SoftwareFactory.Clients by the build, the tests and the probe stage of AIFACTORY-TASK-6601. |
ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-US-1318: A read route of the delivery gateway forwards a call only under a validated token, the tenant and project of the token and the scope of its operation¶
behavior · persona observer
As an observer of the project, I want my reads of proposals, pipeline runs, releases and promotions to reach the services only with the tenant, the projects and the scope my token grants, so that nobody reads across a tenant or a project through the gateway and every read is served by the service that owns the state.
A caller reaches a read operation of the DevOps and GitOps platform through the gateway: an Operator, a Reviewer, a Workspace admin, a Platform admin or an Observer reads change proposals, pipeline runs, product releases, promotions and the current release of an environment. A user presents an access token of the authorization server whose one audience is this gateway (ADR-0015 amendment D114). The gateway validates issuer, signature, lifetime and audience through the pinned resource-server library and requires factory.delivery.read, the scope all nine read operations name. It takes the tenant from the tid claim and overwrites any tenant header of the caller. ListChangeProposals and ListPipelineRuns filter by project: the gateway checks a project the filter names against the roles of the token, the Platform admin holding every project of its tenant, and answers 403 for a project the token does not grant without calling the fronted service. The other read operations address a promotion, a proposal, a pipeline run, a release or an environment by identifier, or read under the tenant of the token; a gateway without business state cannot know the tenant or the project of such a resource, 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 role and 404 for a resource of another tenant (ADR-0015 amendment D113), and the gateway returns that answer unchanged. A project header a caller sends is dropped and establishes nothing. Every public REST operation names a factory. scope a user holds, so a workload token on a REST route is answered 403. The scope is established once with the scope accessor of the pinned abstractions package and forwarded: the authorization header with the user token itself, the tenant, the correlation id and the trace context; the gateway exchanges no token. The internal read method Releases.GetRelease admits a workload token only when it holds factory.delivery.read, the service scope its fronts entry names (D135, AIFACTORY-US-1317), and forwards the tenant-id and the project metadata of the caller unchanged; a workload token without that scope, or a user token, is answered PERMISSION_DENIED. OpenChangeProposal is the route of a person, and the propose-change-set tool records its proposal through Pipelines.RecordProposal (D135); the summary of RequestPromotion still names the deploy-environment tool as a caller, yet a tool calls with a workload token, which reaches EnvironmentPromotionService only through Promotions.Request; this is reported as an open point. For every read route the response is served by the fronted service with no side effect and returns unchanged with the correlation id; the gateway 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 403; in each case no fronted service is called and the refusal is counted for the route and logged with the correlation id and without the token. When the fronted service does not answer, the route answers 503, over gRPC UNAVAILABLE, with a retry hint that names the service and never its address, and the routes of the other services keep serving.
Acceptance criteria
| AC1 | Given a user token whose audience is this gateway, with factory.delivery.read, when the read routes of EnvironmentPromotionService/GetPromotion, PipelineExecutionService/GetPipelineRun and ReleaseService/GetProductRelease are called, then the gateway forwards each call with the user token unchanged in the authorization header, the tenant of the tid claim, the correlation id and the trace context, the fronted service answers, the response returns unchanged with the correlation id and nothing is written by the gateway (SCN-DeliveryHost-004, ADR-0015). |
| AC2 | Given a token with a role in one project and none in another, when PipelineExecutionService/ListChangeProposals and PipelineExecutionService/ListPipelineRuns are called with a project filter, then the call for the granted project is forwarded and the call for the other project is answered 403 without a call to the fronted service; given a Platform admin token, then every project of its tenant is forwarded; given a project header of the caller, then it is dropped (SCN-DeliveryHost-004, ADR-0015). |
| AC3 | Given the token matrix of the acceptance suite, when the nine 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, a token without the scope and a workload token on a REST route are answered 403, and in none of these cases a fronted service is called; given a tenant header that names another tenant, then it is overwritten with the tid claim, and the 403 of a fake for a missing role and its 404 for a resource of another tenant return unchanged (SCN-DeliveryHost-004, model/services/devops-gitops/DeliveryHost.yaml). |
| AC4 | Given a workload token that holds factory.delivery.read, the service scope the fronts entry of ReleaseService/Releases.GetRelease names (D135), when the gRPC route is called with tenant-id and project metadata, then it is forwarded with that metadata unchanged and the reply, a NOT_FOUND for a release outside the forwarded tenant included, returns unchanged; given a workload token without that scope or a user token, then the answer is PERMISSION_DENIED and no fronted service is called; given the fake of ReleaseService stops answering, then its routes answer 503, over gRPC UNAVAILABLE, with a retry hint naming the service while the routes of the other services keep serving (SCN-DeliveryHost-004, ADR-0015). |
| Traces: services | DeliveryHost, EnvironmentPromotionService, PipelineExecutionService, ReleaseService |
| Traces: apis | EnvironmentPromotionService/GetPromotion, PipelineExecutionService/GetPipelineRun, PipelineExecutionService/ListChangeProposals, PipelineExecutionService/ListPipelineRuns, ReleaseService/GetProductRelease, ReleaseService/Releases.GetRelease |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-07, FR-08 |
| Traces: scenarios | SCN-DeliveryHost-004 |
| Relates: screens | promotions, pipeline-runs, proposals, product-releases |
| Depends on | AIFACTORY-US-1317, feature:component-api-gateway-template, feature:component-extensions-ai, feature:environment-promotion-service, feature:pipeline-execution-service-complete, feature:release-service |
| Sources | model/services/devops-gitops/DeliveryHost.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/execution/delivery-engine/services/delivery-host/index.md#security |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5279 Issuer, audience, scope, tenant and project 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; each read route requires factory.delivery.read; the tenant header is overwritten with the tid claim; a project header of a caller is dropped on every route; the project filter of ListChangeProposals and ListPipelineRuns is checked against the roles of the token and a project the token does not grant is answered 403; a route addressed by a resource identifier or scoped by the tenant of the token is forwarded under the tenant of the token; a workload token is refused with 403 on a REST route; the gRPC route of Releases.GetRelease admits a workload token only with factory.delivery.read, the service scope its fronts entry names, answers PERMISSION_DENIED to every other caller, and forwards the tenant-id and project metadata unchanged; the user token is forwarded unchanged and no token is exchanged; refusals are counted per route and logged with the correlation id and without the token. | ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-TASK-5280 Verify the read routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-DeliveryHost-004"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1318 over the token matrix: the token received by the fake equal to the user token of the caller, the project filter granted and refused, the overwritten tenant header and the dropped project header, the 403 and 404 of the fakes returned unchanged, a workload token refused on a REST route, the gRPC read route with and without the scope, and a fake that stops answering. |
ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-US-1319: A shared-write route of the delivery gateway passes the call and its idempotency key through and the gateway keeps nothing between calls¶
behavior · persona operator
As an operator, I want a change proposal, a release, a withdrawal or a reconciliation I repeat after a failure to be applied once, so that a lost answer or a restarted gateway never opens a second pull request or assembles a second release.
A shared-write operation changes state that others read. The DevOps and GitOps platform has four on its public surface and one on its internal gRPC surface. OpenChangeProposal of PipelineExecutionService pushes a change set as a branch and opens a pull request, under factory.delivery.propose, and is idempotent by key header. ReconcilePipelineRun re-reads a pipeline run from the system of record, under factory.delivery.operate, and is naturally idempotent. CreateProductRelease of ReleaseService assembles a release from a succeeded pipeline run, under factory.delivery.release, and is idempotent by key header. WithdrawProductRelease withdraws a release with a reason under the same scope and is naturally idempotent. Pipelines.RecordProposal records a proposal whose pull request the propose-change-set tool opened through the connection, and its route admits a workload token only when it holds factory.delivery.propose, the service scope its fronts entry names (D135, AIFACTORY-US-1317). The caller sends each through the gateway under the token, tenant and scope rules of AIFACTORY-US-1318. Each names a change set, a pipeline run or a release by identifier, so the gateway forwards it under the tenant of the token and the scope of the operation, and the 403 of the fronted service for a missing role and its 404 for a resource of another tenant (ADR-0015 amendment D113) return unchanged. The Idempotency-Key of OpenChangeProposal and CreateProductRelease passes through unchanged, and the fronted service applies a repeated request once; a request without the key, or with a reused key and another body, is refused by the fronted service and its answer returns unchanged. The gateway is no party to idempotency. It stores neither a key nor a 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 repeats the call with its idempotency key and receives from the service the result of the one application (failure mode of a gateway replica crash in the model). When the fronted service does not answer, the route answers 503, over gRPC UNAVAILABLE, with a problem response that names the service and carries a retry hint, the other routes keep serving, and the caller repeats the call. A refusal by the gateway, 401 or 403, reaches no fronted service, so it applies nothing. Every domain refusal, the 409 and 412 of OpenChangeProposal, the 409 and 422 of CreateProductRelease and the 409 of WithdrawProductRelease among them, is an answer of the fronted service and returns 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 with factory.delivery.release, when the route of ReleaseService/CreateProductRelease is called with an Idempotency-Key and repeated with the same key after the first answer was lost, then the gateway forwards both with the key, the body and the established scope unchanged, the fake of ReleaseService answers the second from its record of the first, and both responses return unchanged with the correlation id (SCN-DeliveryHost-005, ADR-0015). |
| AC2 | Given a workload token that holds factory.delivery.propose, the service scope the fronts entry of PipelineExecutionService/Pipelines.RecordProposal names (D135), when a gateway replica is stopped while a call of PipelineExecutionService/Pipelines.RecordProposal is in flight and the caller repeats it through another replica, then the second replica forwards the repeated call unchanged, the gateway replayed nothing, and an inspection of the shared cache finds no key and no result; that PipelineExecutionService records the proposal once is the rule of that service and is proven by its own suite (SCN-DeliveryHost-005, model/services/devops-gitops/DeliveryHost.yaml). |
| AC3 | Given the fakes answer 409 and 412 for PipelineExecutionService/OpenChangeProposal, 409 and 422 for ReleaseService/CreateProductRelease, 409 for ReleaseService/WithdrawProductRelease, 202 for PipelineExecutionService/ReconcilePipelineRun, 403 for a missing role and 404 for a resource of another tenant, when the calls pass the gateway, then each answer returns unchanged with its body and the correlation id (SCN-DeliveryHost-005, ADR-0015). |
| AC4 | Given a call without a token, a token that lacks the scope, a user token or a workload token without factory.delivery.propose on the gRPC route, and a fronted service that does not answer, when a shared-write route is called, then the answer is 401, 403, PERMISSION_DENIED or 503 respectively, a call the gateway refuses reaches no fronted service and applies nothing, and the 503 names the service and carries a retry hint while the other routes keep serving (SCN-DeliveryHost-005, model/services/devops-gitops/DeliveryHost.yaml). |
| Traces: services | DeliveryHost, PipelineExecutionService, ReleaseService |
| Traces: apis | PipelineExecutionService/OpenChangeProposal, PipelineExecutionService/ReconcilePipelineRun, PipelineExecutionService/Pipelines.RecordProposal, ReleaseService/CreateProductRelease, ReleaseService/WithdrawProductRelease |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-07, FR-08 |
| Traces: scenarios | SCN-DeliveryHost-005 |
| Relates: screens | proposals, pipeline-runs, product-releases |
| Depends on | AIFACTORY-US-1317, AIFACTORY-US-1318, feature:component-api-gateway-template, feature:pipeline-execution-service-complete, feature:release-service |
| Sources | model/services/devops-gitops/DeliveryHost.yaml, model/services/devops-gitops/PipelineExecutionService.yaml, model/services/devops-gitops/ReleaseService.yaml, docs/planes/execution/delivery-engine/services/delivery-host/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5281 Forwarded body, idempotency key, headers and metadata of a shared-write route and a stateless call path |
implementation | A shared-write route forwards the body, the Idempotency-Key header and the established scope unchanged and returns the status and the body of the fronted service unchanged; the route of Pipelines.RecordProposal admits a workload token only with factory.delivery.propose, the service scope its fronts entry names, answers PERMISSION_DENIED otherwise, and forwards the tenant-id and project metadata 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.DeliveryHost |
AIFACTORY-TASK-5282 Verify the shared-write routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-DeliveryHost-005"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1319 with a release creation repeated under its key, a replica stopped during a RecordProposal call and the repeat through the second replica, the 409, 412, 422, 403 and 404 of the fakes returned unchanged, the refusals of the gateway without a call to a fronted service, a fake that stops answering and an inspection of the shared cache that finds no key or result. |
ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-US-1320: A production route of the delivery gateway is forwarded under its scope and the one production approval stays in EnvironmentPromotionService¶
behavior · persona operator
As an operator, I want a promotion request or a rollback to be gated by the service that owns the promotion, with the gateway only checking who I am and what I may call, so that a production approval is asked once, bound to the release and the environment, and never decided by a component that holds no state.
Three operations of the DevOps and GitOps platform are of side-effect class production, all of EnvironmentPromotionService: RequestPromotion, which promotes a ready release into an environment under factory.delivery.promote with an Idempotency-Key, RollbackPromotion, which rolls a completed promotion back to the previous release under factory.delivery.operate, and the internal method Promotions.Request, through which the deploy-environment tool requests a promotion with the run and the receipt, whose route admits a workload token only when it holds factory.delivery.promote, the service scope its fronts entry names (D135, AIFACTORY-US-1317). ADR-0028 leaves a platform gateway routing and the validation of tokens and scopes and no business state. The gateway therefore treats these routes as it treats every route: it validates the token, takes the tenant from it, requires the scope the operation names and forwards the call with the established scope. RequestPromotion names a release and an environment and RollbackPromotion a promotion by identifier, so the gateway forwards them under the tenant of the token and the scope of the operation; Promotions.Request is forwarded with its call metadata unchanged, the tenant and the project the workload forwards and the requester of the run as delegatedUserId, and with its request, which carries the runId and the stepRunId of the requesting step, so that the Policy gate of EnvironmentPromotionService names the requester of the run as the delegated user and the completion events echo the run correlation (D141); the 403 of the fronted service for a missing role and its 404 for a resource of another tenant (ADR-0015 amendment D113) return unchanged. The gate itself is decided where the state is. A person gives one production approval, and it is the gate of EnvironmentPromotionService, bound to the release id and the environment; the workflow steps approve-production of delivery-run and release wait on that approval and the deploy-environment tool presents its id (D133, D135). EnvironmentPromotionService requests that approval from RunControlService with the subject kind promotion and applies the decision it publishes; an Operator holds the approval of a rollback by role, and the rollback promotion skips the approval gate (D135). The gateway evaluates no policy and no approval, holds no approval reference, refuses nothing for a missing approval, writes no evidence and audits nothing itself: AuditService records the evidence of a promotion from the events EnvironmentPromotionService publishes. The Idempotency-Key of RequestPromotion passes through unchanged. The answer of the fronted service, the 202 of an accepted request or rollback, the 409 of a reused key or of a promotion that is not Completed, the 412 of a release that is not ready and the 422 of an invalid request among them, 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.
Acceptance criteria
| AC1 | Given a token with factory.delivery.promote, when the production route of EnvironmentPromotionService/RequestPromotion is called with an Idempotency-Key against the fake of EnvironmentPromotionService that answers 202, 409, 412, 422, 403 and 404, then the gateway forwards the call with the key and the body unchanged under the tenant of the token and returns each answer unchanged with the correlation id; the gateway evaluated no policy, held no approval and wrote nothing (SCN-DeliveryHost-003, ADR-0028). |
| AC2 | Given a token with factory.delivery.operate, when the route of EnvironmentPromotionService/RollbackPromotion is called against the fake that answers 202, 409, 403 and 404, and a workload token that holds factory.delivery.promote, the service scope the fronts entry of EnvironmentPromotionService/Promotions.Request names (D135), calls its route with the requester of the run as delegatedUserId in the call metadata and the runId and stepRunId of the requesting step in the request against the fake that replies with an acknowledgement and with FAILED_PRECONDITION, then the fake received the metadata and the request unchanged (D141), every answer returns unchanged and no route was refused by the gateway for a missing approval (SCN-DeliveryHost-003, model/services/devops-gitops/DeliveryHost.yaml). |
| AC3 | Given a call without a token or with an expired token, a token that lacks the scope of the operation, or a user token or a workload token without factory.delivery.promote on the gRPC route, when a production route is called, then the gateway answers 401, 403 or PERMISSION_DENIED, no fronted service is called and the refusal is counted for the route (SCN-DeliveryHost-003, ADR-0015). |
| AC4 | Given the route table, when the register test lists every route of class production, then it finds exactly the routes of EnvironmentPromotionService/RequestPromotion, EnvironmentPromotionService/RollbackPromotion and EnvironmentPromotionService/Promotions.Request, each with its scope, and fails when the gateway holds a handler, a cache entry or a store for a policy decision, an approval, a receipt or an evidence record (SCN-DeliveryHost-003, ADR-0028). |
| Traces: services | DeliveryHost, EnvironmentPromotionService |
| Traces: apis | EnvironmentPromotionService/RequestPromotion, EnvironmentPromotionService/RollbackPromotion, EnvironmentPromotionService/Promotions.Request |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-08, FUX-05, XL-04 |
| Traces: scenarios | SCN-DeliveryHost-003 |
| Relates: screens | promotions |
| Depends on | AIFACTORY-US-1317, AIFACTORY-US-1318, feature:component-api-gateway-template, feature:environment-promotion-service |
| Sources | model/services/devops-gitops/DeliveryHost.yaml, model/services/devops-gitops/EnvironmentPromotionService.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5283 Production routes forwarded under their scope and the register of production routes |
implementation | The routes of RequestPromotion, RollbackPromotion and Promotions.Request require factory.delivery.promote, factory.delivery.operate and, of a workload token, factory.delivery.promote, the service scope the fronts entry of Promotions.Request names, PERMISSION_DENIED being the answer to any other caller, forward the body, the Idempotency-Key of RequestPromotion, the established scope and, for Promotions.Request, the call metadata with the delegatedUserId and the request with the runId and stepRunId unchanged (D141), and return the answer of the fronted service unchanged; 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 a policy decision, an approval, a receipt or an evidence record. | ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-TASK-5284 Fakes of the three production operations for the acceptance suite |
fixture | The acceptance suite holds a fake of RequestPromotion that answers 202, 409, 412, 422, 403 and 404, a fake of RollbackPromotion that answers 202, 409, 403 and 404 and a fake of Promotions.Request that replies with an acknowledgement and with FAILED_PRECONDITION, each generated from its fronts entry and recording the headers, metadata and body it received. | ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-TASK-5285 Verify the production routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-DeliveryHost-003"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1320: the request forwarded with its key, the answers of the three fakes returned unchanged, the refusals of the gateway without a call to a fronted service and the register of production routes; the one production approval is proven by the suite of EnvironmentPromotionService. |
ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-US-1321: Health, systems of record, limits and telemetry of the delivery gateway while the identity platform, a fronted service or a replica fails¶
behavior · persona operator
As an operator, I want to see whether the delivery gateway, the identity platform and each fronted service answer, and which systems of record the platform works with, so that I can tell a failing service from a failing gateway and act on the right one.
An operator and the probes of the cluster read the state of the gateway through its two own operations. DeliveryHost/DeliveryHealth 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; 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. 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 the health operation answers 200 with the health degraded and a detail that names the identity platform as unreachable (ADR-0015 amendment D117). The gateway leaves rotation only when no valid key remains, because none was cached or the cached keys expired: readiness turns unready, the health operation 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 that degrades: when it does not answer, health reports it as unavailable in the detail and the answer stays 200, its routes answer 503 with a retry hint, and the routes of the other services keep serving. DeliveryHost/DeliverySystems returns to a caller whose scope carries factory.meta.read the source-control and CI systems of record configured per tenant through connectors, Azure DevOps and GitHub. The gateway holds no state and the model gives it no dependency that knows the connections of a tenant, so the source of the reply is an open point reported to the owner. Until it is decided the reply is read through one metadata port of the gateway that has no production binding: a deployed instance answers 200 with the systems of record stated as not reported, inventing no value, and adds nothing else, the list of fronted services belonging to the modules endpoint of the template and not to this operation. That stub is provisional and owed to the owner; the reply with the systems filled is proven against a fake metadata source of the acceptance suite. The model lists only 200 for that operation; the 401 for a call without a token and the 403 for a token without the scope are given by the host and are reported as codes the model omits, and when no valid signing key remains the call is refused with the 503 of the failing-closed gateway. ADR-0028 decision 7 gives a platform gateway the rate-limiting library, and the model lists connectsoft-extensions-rate-limiting for DeliveryHost: a call that exceeds the rate limit configured for its route is refused with 429, over gRPC RESOURCE_EXHAUSTED, through that pinned library, from the configuration of the deployment, and calls no fronted service. The model states no limit value and no class of limits, so the values are reported as unmodelled and set by the deployment. The gateway emits connectsoft.factory.delivery.host.requests with the dimensions service, route and status and connectsoft.factory.delivery.host.request_duration with service and route, the latency including the fronted service, each recorded through the helper of the pinned observability library, which puts the tenant, and the project where a call carries one, on the instrument by default (ADR-0019); the gateway carries the trace context to the service. Logs, activities and metrics never contain a token, a change set, a release manifest or any other payload. A replica that crashes is detected by the readiness probe and restarts; because the gateway holds no state, nothing is replayed and callers repeat their call with their idempotency key.
Acceptance criteria
| AC1 | Given the gateway with the identity platform and the fronted services reachable, when DeliveryHost/DeliveryHealth 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 three fronted services and of the identity platform; a call for the detail without a token is answered 401 and a token without the scope 403 (SCN-DeliveryHost-001). |
| AC2 | Given the identity platform is unreachable and a cached signing key still validates tokens, when calls arrive and DeliveryHost/DeliveryHealth is probed, then already issued tokens pass, readiness stays ready and health answers 200 degraded with a detail that names the identity platform; given no valid key remains, then calls are refused, readiness is unready, DeliveryHost/DeliveryHealth answers 503 with a problem response that names the identity platform and liveness keeps answering 200; given one fronted service does not answer, then health answers 200 and reports it unavailable, its routes answer 503 with a retry hint and the other routes keep serving (SCN-DeliveryHost-001, model/services/devops-gitops/DeliveryHost.yaml). |
| AC3 | Given a caller with factory.meta.read, when DeliveryHost/DeliverySystems is called on an instance whose metadata port has no source, then the response is 200 with the systems of record stated as not reported and nothing else, a provisional stub owed to the owner until the source of the systems of record of model/services/devops-gitops/DeliveryHost.yaml is decided; given the fake metadata source bound to the port, then the reply names the Azure DevOps and GitHub systems of the tenant; given no token, a token without the scope or no valid signing key, then the answer is 401, 403 or 503, no fronted service is called and nothing is written (SCN-DeliveryHost-002). |
| AC4 | Given routed calls and a call above the rate limit the deployment configures for its route through the pinned connectsoft-extensions-rate-limiting library (ADR-0028), when the metrics and logs are read, then connectsoft.factory.delivery.host.requests counts every call by service, route and status, the call above the limit was refused with 429 and called no fronted service, connectsoft.factory.delivery.host.request_duration holds the latency by service and route, both carry the tenant of the call from the helper of the pinned observability library, and no log record, activity or metric holds a token or a payload (ADR-0019, model/services/devops-gitops/DeliveryHost.yaml). |
| Traces: services | DeliveryHost, EnvironmentPromotionService, PipelineExecutionService, ReleaseService |
| Traces: apis | DeliveryHost/DeliveryHealth, DeliveryHost/DeliverySystems |
| Traces: adrs | ADR-0015, ADR-0017, ADR-0019, ADR-0028 |
| Traces: requirements | NFR-08, NFR-12, FUX-06 |
| Traces: scenarios | SCN-DeliveryHost-001, SCN-DeliveryHost-002 |
| Depends on | AIFACTORY-US-1317, feature:component-api-gateway-template, feature:component-observability-factory-conventions |
| Sources | model/services/devops-gitops/DeliveryHost.yaml, docs/architecture/adr/0017-deployment-profiles.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/execution/delivery-engine/services/delivery-host/index.md#metrics-and-observability, docs/planes/execution/delivery-engine/services/delivery-host/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-247 Health, systems of record 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 three 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 degraded naming the identity platform; when no valid key remains, readiness turns unready and the operation answers 503 naming the identity platform (D117); the systems operation serves, under factory.meta.read, only the systems of record from one metadata port that has no production binding, stated as not reported in a provisional stub owed to the owner until its source is decided; every routed call records connectsoft.factory.delivery.host.requests and request_duration with their modelled dimensions and the tenant of the call, and carries the trace context to the service. | ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-TASK-5286 Rate limits per route from the configuration of the gateway |
implementation | Each route takes its rate limit from the configuration of the deployment through the pinned connectsoft-extensions-rate-limiting library that ADR-0028 decision 7 gives a platform gateway, and answers 429 above it, over gRPC RESOURCE_EXHAUSTED; a refusal by the limit calls no fronted service and is counted under its status in connectsoft.factory.delivery.host.requests; no limit value is fixed in code. | ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-TASK-5287 Runbook of the three failure modes of the gateway |
documentation | The repository documentation holds one runbook entry per failure mode of model/services/devops-gitops/DeliveryHost.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; the entry of the replica crash states that nothing is replayed and that callers repeat their call with their idempotency key. | ConnectSoft.AI.SoftwareFactory.DeliveryHost |
AIFACTORY-TASK-5288 Verify health, systems of record, limits and telemetry through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-DeliveryHost-001\|Scenario=SCN-DeliveryHost-002)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1321 with the identity platform stopped while a cached key validates tokens, without a cached key and after the cached key expired, one fake stopped, the systems operation without a metadata source, with the fake source and without its scope, a call above its limit, the two series with service, route, status and tenant, and a scan of the captured logs and activities for token and payload content. |
ConnectSoft.AI.SoftwareFactory.DeliveryHost |