AIFACTORY-FEAT-034: IntegrationHost: 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 Integration Platform (PF-06) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 72 of 185 (Factory code)
IntegrationHost is the platform API gateway of bounded context BC-16 (Connections). The API gateway of the Integration platform (ADR-0028): routes public REST and internal gRPC calls to the 2 services it fronts, validates tokens and scopes, and owns no business state. Its own repository is ConnectSoft.AI.SoftwareFactory.IntegrationHost.
| Delivers | IntegrationHost (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0012, ADR-0015, ADR-0016, ADR-0017, ADR-0022 |
| Requirements | FR-05, FR-11, FUX-02, NFR-02, NFR-13, NFR-18, XL-10, XL-13 |
| Depends on | — |
| Sources | model/services/integration/IntegrationHost.yaml |
Scenarios to trace (7, catalog): SCN-IntegrationHost-001 ✓, SCN-IntegrationHost-002 ✓, SCN-IntegrationHost-003 ✓, SCN-IntegrationHost-004 ✓, SCN-IntegrationHost-005 ✓, SCN-IntegrationHost-006 ✓, SCN-IntegrationHost-007 ✓
AIFACTORY-US-082: IntegrationHost 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 ConnectorRegistryService and IntegrationService that validates tokens and scopes, so that no service of the Integration 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 Integration platform. ADR-0028 re-scopes the former composition host as the API gateway of its platform: IntegrationHost routes public REST and internal gRPC calls to the two services the model lists under deployment.fronts, ConnectorRegistryService and IntegrationService, validates tokens and scopes and owns no business state, no relational store and no secret. It loads no connector adapter: the adapters are loaded by ConnectorRegistryService, and the webhook ingress is the separate conditional WebhookGatewayService. The repository ConnectSoft.AI.SoftwareFactory.IntegrationHost is created and scaffolded in I0 by AIFACTORY-TASK-463 of feature repository-and-pipeline-conventions (D140), by the steps of its repository checklist, and this feature starts from that scaffold; it was 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 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 (feature component-extensions-ai). A user token has one audience, this gateway, and the gateway forwards it to the fronted service unchanged and exchanges no token, because the fronted service accepts the audience of its own gateway (ADR-0015 amendment D117). A workload token carries service scopes and no tenant claim and is admitted only on an internal gRPC route whose operation names a service scope the token holds (ADR-0015 amendment D114). The feature is delivered by five further PBIs: the fronts file and the routes generated from it (AIFACTORY-US-1009), token, tenant and scope on every read route (AIFACTORY-US-1010), the shared-write and sandbox routes with their idempotency key and their project (AIFACTORY-US-1011), the external and production routes whose gate stays in the fronted service (AIFACTORY-US-1012), and health, adapters, limits and telemetry with the three failure modes of a gateway (AIFACTORY-US-1013). 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. A project-scoped route names its project in the path, in a query parameter or in a body member and never in a header the caller types; the gateway admits the project only for a token that holds a role claim for it or the tenant-wide Platform admin role, answers 403 itself otherwise, and sets the project header from the admitted project; a project header a caller sends is dropped on every REST route and for every user token. On an internal gRPC route the tenant and project metadata of a workload token that holds the service scope of the route are forwarded unchanged, because the fronted service reads a forwarded tenant and project only under that scope (ADR-0015 amendment D114). Every other route is forwarded under the tenant of the token and the scope of the operation, the fronted service answers 403 for a missing right and 404 for a resource of another tenant (ADR-0015 amendment D113), and the gateway returns that answer unchanged. The gateway is of increment I1, like the other gateways (D127, D129), and every dependency of this feature is of I0 or I1, the two fronted services included; the REST operations of the two thin services are reached through this gateway from the first delivery, and this feature adds no direct public route to either service. Both services are delivered thin in I1 and complete in I5: a route whose operation a thin delivery does not host returns the answer of that service unchanged until I5, and the refusals and failure branches of every route class are proven against fakes generated from the fronts file. In I1 a Workspace admin or Platform admin provisions the connection of a project and a Platform admin of the platform tenant certifies the Azure DevOps connector through the public routes of this gateway, by the runbooks AIFACTORY-TASK-4070 of feature integration-service-thin and AIFACTORY-TASK-4069 of feature connector-registry-service-thin (D129). StudioBff, delivered in I3, is the caller the model names for the public routes, for the administration of connections and connectors in its own PBIs (D129). A gateway calls no other gateway and consumes no event: ToolAdapterService and KnowledgeIngestionService call IntegrationService and ConnectorRegistryService directly, and the verified deliveries reach ConnectorRegistryService directly. The typed client of this gateway is published by feature typed-gateway-clients from the OpenAPI document of AIFACTORY-US-1009, and this feature builds no client package. The gateway invents no response.
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.IntegrationHost created and scaffolded in I0 by AIFACTORY-TASK-463 of feature repository-and-pipeline-conventions, whose first commit is the unchanged output of dotnet new connectsoft-apigateway -n ConnectSoft.AI.SoftwareFactory.IntegrationHost --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/integration/IntegrationHost.yaml). |
| AC2 | Given a valid token for a route of each fronted service, 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 the token unchanged, the tenant, the project the gateway admitted where the route names one, the correlation id and the trace context, the fronted service answers and the response returns unchanged, as AIFACTORY-US-1010 to AIFACTORY-US-1012 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, a message consumer or a connector adapter, the gateway binds no relational store, no outbox and no inbox, its configuration holds no secret, and no event of the model lists IntegrationHost as a consumer (ADR-0028, ADR-0012, model/services/integration/IntegrationHost.yaml). |
| AC4 | Given the gateway deployed with two replicas, when IntegrationHost/IntegrationHealth is probed and one replica is stopped, then health reports the identity platform and the two 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, NFR-18). |
| Traces: services | IntegrationHost, ConnectorRegistryService, IntegrationService |
| Traces: apis | IntegrationHost/IntegrationHealth |
| Traces: adrs | ADR-0012, ADR-0015, ADR-0016, ADR-0017, ADR-0022, ADR-0028 |
| Traces: requirements | FR-01, FR-05, NFR-18 |
| Depends on | AIFACTORY-US-1009, AIFACTORY-US-1010, AIFACTORY-US-1011, AIFACTORY-US-1012, AIFACTORY-US-1013, feature:repository-and-pipeline-conventions, feature:component-api-gateway-template, feature:component-extensions-ai, feature:connector-registry-service-thin, feature:integration-service-thin |
| Sources | model/services/integration/IntegrationHost.yaml, model/gateways.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0016-architecture-meta-model.md, docs/planes/capability-tools/connectors/services/integration-host/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4055 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 8, the ports https 7900 and grpc 7902, the liveness and readiness probes on the health operation and one base address per fronted service from configuration, as model/services/integration/IntegrationHost.yaml records them; it leaves Integration:Host:FrontedServices at its default, the two service identifiers of deployment.fronts, 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 and on-prem topologies (ADR-0017). | ConnectSoft.AI.SoftwareFactory.IntegrationHost |
AIFACTORY-TASK-758 Verify integration-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-082, that is the repository 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 IntegrationHost/IntegrationHealth on both, stops one instance and asserts that the other keeps serving and that no call is replayed. |
ConnectSoft.AI.SoftwareFactory.IntegrationHost |
AIFACTORY-US-1009: Integration fronts file: named clients and REST and gRPC routes of the two fronted services, generated at build¶
enabling · persona platform-admin
As a platform admin, I want the route table of the integration gateway generated from the list of services it fronts, so that every operation of the platform has exactly one route with its scope, its class and its project rule 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 Integration platform. It lists the two services of deployment.fronts in model/services/integration/IntegrationHost.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 ConnectorRegistryService these are the five REST operations ListConnectors, CertifyConnector, CreateSubscription, ListDeliveries and ReplayDelivery and the gRPC methods Connectors.Deliver and Connectors.ResolveCapability. For IntegrationService these are the six REST operations RegisterConnection, ListConnections, VerifyConnection, SetGrant, RotateCredential and RevokeConnection and the gRPC method Connections.Resolve. That is eleven REST routes and three unary gRPC routes. The file holds the whole surface of the model, also for the operations the thin deliveries of I1 do not host: the route exists, and until the complete deliveries of I5 it returns the answer of the service unchanged. Each route carries the scope and the side-effect class of its operation, which is what the route class PBIs of this feature enforce; an internal gRPC route names the service scope a workload token must hold. Each REST entry also states how its operation addresses a project, and the four markings cover all eleven. SetGrant names its project in the path parameter subjectId when subjectKind is Project and addresses a connection only for the other kinds. CertifyConnector names its project in the body member projectId, as the thin contract of ConnectorRegistryService fixes it, and so does CreateSubscription, as stated below. ReplayDelivery, VerifyConnection, RotateCredential and RevokeConnection address a delivery or a connection by identifier only. ListConnectors, ListDeliveries, RegisterConnection and ListConnections act on the tenant of the token by design, because a connector descriptor, a delivery and a connection carry no project. CreateSubscription names its project in the required body member projectId, a call without it is answered 400 by the service, and the gateway admits that project against the roles of the token and answers 403 for a project the token does not grant (D129). A test lists the emitted route table against the file and against the two 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 IntegrationHealth and IntegrationAdapters, transforms no payload and composes no response from two services. The option Integration:Host:FrontedServices is bound at startup and compared with the service names of 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, and its default in the model names the two service identifiers of deployment.fronts, so the deployment manifest does not set it. The pipeline publishes the OpenAPI document of the eleven public REST operations as a build output, checked against the fronts file and the two service files; feature typed-gateway-clients generates the typed client of this gateway from it, and this feature builds no client package.
Acceptance criteria
| AC1 | Given the fronts file of the Integration 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, eleven REST routes and three gRPC routes, each with the scope, side-effect class, idempotency and project marking of the operation, and the route table test passes against model/services/integration/IntegrationHost.yaml, model/services/integration/ConnectorRegistryService.yaml and model/services/integration/IntegrationService.yaml (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 Integration:Host:FrontedServices at its default, when the gateway starts, then startup succeeds; given a value that names no service of the fronts file or omits one, 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 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 carrying the token of the caller unchanged, the tenant, the correlation id and the trace context, a project header sent by the caller on the REST route has been dropped, the tenant and project metadata of the workload token on the gRPC route have been forwarded unchanged, and the response of the fake returns unchanged (ADR-0015, FR-01). |
| AC4 | Given the built gateway, when its pipeline publishes the OpenAPI document of the public REST routes, then the document holds exactly the eleven 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 two service files under model/services/integration (docs/architecture/api-governance.md). |
| Traces: services | IntegrationHost, ConnectorRegistryService, IntegrationService |
| Traces: adrs | ADR-0015, ADR-0016, ADR-0028 |
| Traces: requirements | FR-01 |
| Depends on | feature:component-api-gateway-template, feature:connector-registry-service-thin, feature:integration-service-thin |
| Sources | model/services/integration/IntegrationHost.yaml, model/services/integration/ConnectorRegistryService.yaml, model/services/integration/IntegrationService.yaml, model/gateways.yaml, docs/architecture/catalogs/gateways.md, docs/architecture/api-governance.md, docs/planes/capability-tools/connectors/services/integration-host/index.md#context-and-boundaries |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-464 Fronts file with the REST and gRPC operations of ConnectorRegistryService and IntegrationService |
implementation | The fronts file lists the two 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, and for each REST operation one of four project markings that together cover all eleven: the path parameter subjectId for SetGrant when subjectKind is Project, the body member projectId for CertifyConnector and CreateSubscription, the second admitted against the roles of the token (D129), a resource identifier only for ReplayDelivery, VerifyConnection, RotateCredential and RevokeConnection, and the tenant of the token by design for ListConnectors, ListDeliveries, RegisterConnection and ListConnections; a test fails when a REST operation carries none or more than one marking; the build emits the named clients, the eleven REST routes, the three gRPC routes and the route table; Integration:Host:FrontedServices is compared with the fronts file at startup; a project header of a caller is dropped on every REST route and for every user token, and on an internal gRPC route the tenant and project metadata of a workload token that holds the service scope of the route are forwarded unchanged (ADR-0015 amendment D114). | ConnectSoft.AI.SoftwareFactory.IntegrationHost |
AIFACTORY-TASK-4056 Fakes of the two 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 and metadata it received, answers a configured status and a switch that makes it 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 a gRPC route. | ConnectSoft.AI.SoftwareFactory.IntegrationHost |
AIFACTORY-TASK-4057 OpenAPI document of the public REST routes of the gateway as a published build output |
contract | The pipeline publishes one OpenAPI document with the eleven 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 it with the two service files under model/services/integration and fails the build on a missing operation, an operation of another service or a differing method, path, scope or response code, so feature typed-gateway-clients can generate the client of this gateway from it; no client package is built here. | ConnectSoft.AI.SoftwareFactory.IntegrationHost |
AIFACTORY-TASK-4058 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-1009: one route per operation of the two service files under model/services/integration with its project marking, the failing builds, the start with the option at its default, the failing startup on a differing value, the 404 of an unknown path, one forwarded call per service and protocol with the dropped project header of the caller on the REST route and the forwarded metadata of the workload on the gRPC route, and the contract check of the published OpenAPI document. |
ConnectSoft.AI.SoftwareFactory.IntegrationHost |
AIFACTORY-US-1010: A read route of the integration gateway forwards a call only under a validated token, the tenant of the token and the scope of its operation¶
behavior · persona workspace-admin
As a workspace admin, I want my reads of connectors, deliveries and connections to reach the services only with the tenant and the scope my token grants, so that I see the connections and connectors of my tenant and nobody reads across a tenant through the gateway.
A caller reaches a read operation of the Integration platform through the gateway: a Workspace admin, an Operator or an Observer lists the connector descriptors, the deliveries and the connections, as the Studio screens of connectors and connections do through StudioBff; a workload that the model routes through this gateway resolves a capability or a connection over gRPC, while ToolAdapterService and ConnectorRegistryService call IntegrationService directly inside the cluster. 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.connections.read, the scope of ListConnectors, ListDeliveries and ListConnections. It takes the tenant from the tid claim and overwrites any tenant header of the caller. The three read operations act on the tenant of the token by design, because a descriptor, a delivery and a connection carry no project: the gateway forwards them under the tenant of the token and the scope of the operation, the fronted service applies its tenant row filter, and its answer returns unchanged. A project header a caller sends is dropped and establishes nothing. Every public REST operation names a factory. scope and none names a service scope, 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 in X-Tenant-Id, the correlation id and the trace context; the gateway exchanges no token (ADR-0015 amendment D117). The internal gRPC surface has two read methods, Connectors.ResolveCapability and Connections.Resolve. A workload presents a token with service scopes, no audience of a user API and no tenant claim, and each gRPC route names the service scope the token must hold; for a token that holds it the gateway forwards the tenant-id and project metadata of the caller unchanged, because the fronted service reads a forwarded tenant and project only under that scope; for a token without it, and for a user token, the answer is PERMISSION_DENIED and no fronted service is called. The NOT_FOUND, PERMISSION_DENIED and FAILED_PRECONDITION answers of the fronted service, with their reasons, return unchanged. 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 and records connectsoft.factory.integration.host.requests and connectsoft.factory.integration.host.request_duration for the route. 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 service keep serving. ListDeliveries is not hosted by the thin ConnectorRegistryService before I5, so its answer is the answer of that service, returned unchanged.
Acceptance criteria
| AC1 | Given a user token whose audience is this gateway, with factory.connections.read, when the read route of ListConnections is called, then the gateway forwards the call with the user token unchanged, without a token exchange, the tenant of the tid claim, the correlation id and the trace context, IntegrationService answers, the response returns unchanged with the correlation id and nothing is written by the gateway (SCN-IntegrationHost-005, ADR-0015). |
| AC2 | Given the token matrix of the acceptance suite, when the read routes of the two fronted services 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; each refusal is counted for its route and logged with the correlation id and without the token (SCN-IntegrationHost-005, ADR-0015). |
| AC3 | Given a valid user token, a tenant header of the caller that names another tenant and a project header of the caller, when the routes of ListConnectors, ListDeliveries and ListConnections are called, then the tenant header is overwritten with the tid claim, the project header is dropped, the calls are forwarded under the tenant of the token and the answers of the fakes return unchanged, as model/services/integration/IntegrationHost.yaml and the two service files name no project for these operations (SCN-IntegrationHost-005). |
| AC4 | Given a workload token that holds the service scope the route names, when the gRPC routes of Connectors.ResolveCapability and Connections.Resolve are called with tenant-id and project metadata, then the gateway forwards each call with that metadata unchanged and returns the reply, and the NOT_FOUND, PERMISSION_DENIED and FAILED_PRECONDITION answers of the fakes with their reasons unchanged; given a workload token without the scope, or a user token, then the answer is PERMISSION_DENIED and no fronted service is called (SCN-IntegrationHost-005, ADR-0015). |
| AC5 | Given a fronted service that does not answer, when its read routes are called, then the gateway answers 503, over gRPC UNAVAILABLE, with a problem response that carries a retry hint and names the service and never its address, no response is invented, and the read routes of the other service keep serving (SCN-IntegrationHost-005, model/services/integration/IntegrationHost.yaml). |
| Traces: services | IntegrationHost, ConnectorRegistryService, IntegrationService |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-01, FUX-01 |
| Traces: scenarios | SCN-IntegrationHost-005 |
| Relates: screens | connections, connectors |
| Depends on | AIFACTORY-US-1009, feature:component-api-gateway-template, feature:component-extensions-ai |
| Sources | model/services/integration/IntegrationHost.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/capability-tools/connectors/services/integration-host/index.md#security |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4059 Issuer, audience, scope and tenant 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 the scope of its operation; the tenant header is overwritten with the tid claim; a project header of a caller is dropped; ListConnectors, ListDeliveries and ListConnections are forwarded under the tenant of the token; a workload token is refused with 403 on a REST route; the two gRPC read routes name the service scope a workload token must hold and forward the tenant-id and project metadata unchanged with it; 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.IntegrationHost |
AIFACTORY-TASK-4060 Verify the read routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-IntegrationHost-005"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-1010 over the token matrix: the token received by the fake equal to the user token of the caller, the overwritten tenant header and the dropped project header, a workload token refused on a REST route, the two gRPC read routes with and without the service scope and the status answers of the fakes returned with their reasons, and a fake that stops answering. |
ConnectSoft.AI.SoftwareFactory.IntegrationHost |
AIFACTORY-US-1011: A shared-write or sandbox route of the integration gateway admits the project it names, passes the idempotency key through and keeps nothing between calls¶
behavior · persona workspace-admin
As a workspace admin, I want a registration, a grant, a replay or a certification I repeat after a failure to be applied once, and a project I name to be checked against my roles, so that a lost answer or a restarted gateway never registers a second connection or runs a second certification, and nobody grants a connection to a project they hold no role in.
A shared-write operation changes state that others read. The Integration platform has three on its public surface: RegisterConnection and SetGrant of IntegrationService under factory.connections.admin and ReplayDelivery of ConnectorRegistryService under factory.connections.operate. Its one sandbox operation is CertifyConnector of ConnectorRegistryService under factory.connections.admin, whose conformance suite runs against a sandbox connection, so its effect stays in the sandbox system. The caller sends each through the gateway under the token, tenant and scope rules of AIFACTORY-US-1010. Two of them name a project. SetGrant names it in the path parameter subjectId when subjectKind is Project, and CertifyConnector in the body member projectId: the gateway admits the project only for a token that holds a role claim for it or the tenant-wide Platform admin role, sets the project header from it, and answers 403 itself for a project the token does not grant, calling no service. Whether the role suffices to grant is decided by IntegrationService through the policy decision of PolicyEngineService, not by the gateway. ReplayDelivery addresses a delivery by identifier and RegisterConnection writes under the tenant of the token; the gateway forwards them under the tenant of the token and the scope of the operation, and the 403 of the fronted service for a missing right and its 404 for a resource of another tenant (ADR-0015 amendment D113) return unchanged. RegisterConnection and CertifyConnector declare idempotency key-header and are 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, and its answer for a key reused with a different body, 409 for RegisterConnection, returns unchanged. SetGrant and ReplayDelivery are naturally idempotent and need no key. 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 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 one application. The gateway reads no credential and no body member but the project it admits; a body that carries a credential value is refused with 400 by IntegrationService, and that answer returns unchanged. 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. ReplayDelivery is not hosted by the thin ConnectorRegistryService before I5, so its route is proven against the fake and returns the answer of the thin service on a deployed instance. 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.connections.admin and the route of RegisterConnection, whose operation declares idempotency key-header, when the call arrives with an Idempotency-Key, then the gateway forwards the request with the header and the body unchanged, the fake of IntegrationService applies it once and the response returns unchanged with the correlation id; the same call repeated returns the result of the first application, and the 409 of the fake for the same key with a different body returns unchanged; the gateway has stored neither the key nor a result in the shared cache or anywhere else (SCN-IntegrationHost-007, ADR-0028). |
| AC2 | Given the route of SetGrant with subjectKind Project and a project in subjectId, when the token holds a role claim for that project or the tenant-wide Platform admin role, then the call is forwarded with the project in the project header the gateway sets and the answer of the fake, 200 or the 403 of a denied policy decision, returns unchanged; when the token holds neither, then the gateway answers 403 itself and no fronted service is called (SCN-IntegrationHost-007, ADR-0015). |
| AC3 | Given the sandbox route of CertifyConnector with a projectId body member and an Idempotency-Key, when the token holds a role claim for that project, then the call is forwarded with the key and the body unchanged and the 202 of the fake returns unchanged, and when the token holds none, then the gateway answers 403 itself and no fronted service is called; given the fake answering 404 for a descriptor of another tenant (ADR-0015 amendment D113), then that answer returns unchanged (SCN-IntegrationHost-006, ADR-0015). |
| AC4 | Given a call of RegisterConnection with an Idempotency-Key in progress, when the gateway replica that holds it is stopped and the caller retries with the same key through another replica, then the second replica forwards the repeated call, the fake applied the request once and returns the result of that application, and the gateway replayed nothing; given a call without a token, a token without the scope or a fronted service that does not answer, then the answer is 401, 403 or 503 with a retry hint that names the service, and a call the gateway refuses reaches no fronted service (SCN-IntegrationHost-007, model/services/integration/IntegrationHost.yaml). |
| Traces: services | IntegrationHost, ConnectorRegistryService, IntegrationService |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-01, FUX-01 |
| Traces: scenarios | SCN-IntegrationHost-006, SCN-IntegrationHost-007 |
| Relates: screens | connections, connectors |
| Depends on | AIFACTORY-US-1009, AIFACTORY-US-1010, feature:component-api-gateway-template |
| Sources | model/services/integration/IntegrationHost.yaml, model/services/integration/IntegrationService.yaml, model/services/integration/ConnectorRegistryService.yaml, docs/planes/capability-tools/connectors/services/integration-host/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4061 Project admission of SetGrant and CertifyConnector and a stateless write path |
implementation | The route of SetGrant admits the subjectId of its path when subjectKind is Project, and the route of CertifyConnector the projectId body member, only for a token with a role claim for that project or the tenant-wide Platform admin role, sets the project header from it and answers 403 itself otherwise; every shared-write and sandbox 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.IntegrationHost |
AIFACTORY-TASK-4062 Verify the shared-write and sandbox routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-IntegrationHost-006\|Scenario=SCN-IntegrationHost-007)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1011 with a fake that applies a key once and answers 409 for the same key with a different body, the routes of SetGrant and CertifyConnector with a granted and a refused project, the 404 of the fake returned unchanged, a replica stopped during a call and the retry through the second replica, a fake that stops answering and an inspection of the shared cache that finds no key and no body. |
ConnectSoft.AI.SoftwareFactory.IntegrationHost |
AIFACTORY-US-1012: An external or production route of the integration gateway 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 verification, a subscription, an outbound delivery, a rotation or a revocation 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 is never decided twice or by a component that holds no state, and no external call leaves the Factory from the gateway.
Two side-effect classes of the Integration platform reach beyond the Factory. The external routes are VerifyConnection of IntegrationService, a read-only probe of the credential through the Secret Broker, CreateSubscription of ConnectorRegistryService, which subscribes to provider events through a connection and creates the ingress identity of the webhook gateway, and the internal gRPC method Connectors.Deliver, the outbound delivery of an external-class tool with its policy decision and approval. The production routes are RotateCredential and RevokeConnection of IntegrationService, which affect every dependent system. 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, requires factory.connections.admin on the four REST routes and, on Connectors.Deliver, a workload token that holds the service scope of the route, and forwards the call with the established scope. The four REST routes address a connection by identifier or, for CreateSubscription, name the project in the body member projectId, which the gateway admits against the roles of the token and answers 403 for a project the token does not grant (D129, AIFACTORY-US-1009), so the gateway forwards them under the tenant of the token and the scope of the operation, and the 403 of the fronted service for a missing right and its 404 for a resource of another tenant (ADR-0015 amendment D113) return unchanged. The Idempotency-Key of VerifyConnection, CreateSubscription and RotateCredential passes through unchanged. The gate itself is decided where the state is. Whether an action needs an approval is decided by the policy decision of PolicyEngineService alone, never by the gateway; a tool call reaches ConnectorRegistryService through ToolAdapterService, which carries that decision and the approval in tool-invocation-v1, and the gateway passes the message through unchanged. The gateway evaluates no policy and no approval, holds no approval reference, calls no connector, resolves no connection, reads no credential, writes no receipt and no audit evidence; the service that owns a command writes its event and its audit evidence AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted to its own outbox in the transaction of the command. The answer of the fronted service, including 200, 201, 202, 409 and the gRPC status of a delivery, 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. VerifyConnection is hosted by the thin IntegrationService of I1. CreateSubscription, Connectors.Deliver, RotateCredential and RevokeConnection are not hosted before the complete deliveries of I5, so their routes are proven against fakes generated from the fronts entries and return the answer of the thin service on a deployed instance.
Acceptance criteria
| AC1 | Given a token with factory.connections.admin, when the external route of VerifyConnection is called with an Idempotency-Key, then the gateway forwards the call with the key unchanged under the tenant of the token, IntegrationService answers 200 with the outcome and that answer returns unchanged with the correlation id; the gateway called no connector, read no credential and wrote no receipt and no evidence (SCN-IntegrationHost-003, ADR-0028). |
| AC2 | Given a workload token with the service scope of the route and a tool-invocation-v1 message that carries a policy decision and an approval, when the gRPC route of Connectors.Deliver is called against the fake of ConnectorRegistryService, then the message and the forwarded metadata reach the fake unchanged and its reply or status returns unchanged; given a user token or a workload token without the scope, then the answer is PERMISSION_DENIED and no fronted service is called; given the route of CreateSubscription against the fake answering 201 or 409, then each answer returns unchanged (SCN-IntegrationHost-003, ADR-0022). |
| AC3 | Given a token with factory.connections.admin, when the production routes of RotateCredential and RevokeConnection are called against the fake of IntegrationService answering 200, 403, 404 or 409, then the gateway forwards each call under the tenant of the token and the scope of the operation, with the Idempotency-Key of the rotation unchanged, and returns each answer unchanged; the gateway evaluated no approval and holds none (SCN-IntegrationHost-004, 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 an external or production route is called, then the gateway answers 401 or 403 and no fronted service is called; given a route that names only a connectionId, when the fronted service answers 403 for a missing right or 404 for a connection of another tenant (ADR-0015 amendment D113), then the gateway returns that answer unchanged (SCN-IntegrationHost-003, SCN-IntegrationHost-004, ADR-0015). |
| AC5 | Given the route class register of the gateway, when the register test lists every route of class external and production from the route table, then each has a scope, and the test fails when the gateway holds a handler, a cache entry or a store for an approval, a credential, a connection, a receipt or an evidence record (SCN-IntegrationHost-004, model/services/integration/IntegrationHost.yaml). |
| Traces: services | IntegrationHost, ConnectorRegistryService, IntegrationService |
| Traces: descriptors | tool-invocation-v1 |
| Traces: adrs | ADR-0015, ADR-0019, ADR-0022, ADR-0028 |
| Traces: requirements | FR-05, NFR-02, XL-10 |
| Traces: scenarios | SCN-IntegrationHost-003, SCN-IntegrationHost-004 |
| Relates: screens | connections, connectors |
| Depends on | AIFACTORY-US-1009, AIFACTORY-US-1010, feature:component-api-gateway-template |
| Sources | model/services/integration/IntegrationHost.yaml, model/services/integration/IntegrationService.yaml, model/services/integration/ConnectorRegistryService.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0022-mcp-as-tool-protocol.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4063 Route class register of the external and production routes of the gateway |
implementation | A register test lists every route of class external and production from the route table, VerifyConnection, CreateSubscription, Connectors.Deliver, RotateCredential and RevokeConnection, and fails when such a route has no scope, when the gRPC route of Connectors.Deliver admits a token without its service scope, or when the gateway holds a handler, a cache entry or a store for an approval, a credential, a connection, a receipt or an evidence record; the Idempotency-Key of the three key-header operations is forwarded unchanged. | ConnectSoft.AI.SoftwareFactory.IntegrationHost |
AIFACTORY-TASK-4064 Fakes of the external and production operations for the acceptance suite |
fixture | The acceptance suite holds a fake of VerifyConnection that answers 200, 403 and 404, a fake of CreateSubscription that answers 201 and 409, a fake of Connectors.Deliver that records the tool-invocation-v1 message and answers a reply or a status, and fakes of RotateCredential and RevokeConnection that answer 200, 403, 404 and 409, each generated from its fronts entry. | ConnectSoft.AI.SoftwareFactory.IntegrationHost |
AIFACTORY-TASK-4065 Verify the external and production routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-IntegrationHost-003\|Scenario=SCN-IntegrationHost-004)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-1012: the verification forwarded with its key, the delivery message passed through unchanged and refused without the service scope, the answers 200, 201, 403, 404 and 409 of the fakes returned unchanged, the refusals of the gateway without a call to a fronted service and the register of external and production routes. |
ConnectSoft.AI.SoftwareFactory.IntegrationHost |
AIFACTORY-US-1013: Health, adapters, limits and telemetry of the integration gateway while the identity platform, a fronted service or a replica fails¶
behavior · persona operator
As an operator, I want to see whether the integration gateway, the identity platform and each fronted service answer, and which connector adapters the platform runs, 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. IntegrationHost/IntegrationHealth reports liveness and readiness of the gateway with the aggregated health of the two 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. 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 IntegrationHealth 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, IntegrationHealth answers 503 with a problem response that names the identity platform, and calls are refused, so the gateway fails closed. Liveness keeps answering 200 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 service keep serving. IntegrationHost/IntegrationAdapters returns to a caller whose scope carries factory.meta.read the connector adapters of the services behind the gateway, first-party clients and the generic HTTP, OpenAPI and MCP adapters, with their versions and capability interfaces. The gateway loads no adapter and holds no state: the adapters are loaded by ConnectorRegistryService, and the model gives that service no operation that returns its loaded adapters under factory.meta.read, since ListConnectors requires factory.connections.read. The source of the reply is therefore 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 two fronted services and their repositories, as deployment.fronts lists them, and states the adapters as not reported, and invents no value; the reply with the adapters filled is proven against a fake metadata source of the acceptance suite. The operation calls no fronted service, so it has no dependency to fail on. A call that exceeds the rate limit configured for its route is refused with 429, over gRPC RESOURCE_EXHAUSTED, through the pinned rate-limiting library, from the configuration of the gateway, and calls no fronted service; no limit value is fixed in code. The gateway emits connectsoft.factory.integration.host.requests with the dimensions service and status and connectsoft.factory.integration.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 the route names one, on the instrument by default (ADR-0019); the gateway carries the trace context to the service. The gateway belongs to the class pilot-interactive of model/nfr-targets.yaml; the duration series is what it is measured against once the system is deployed, and no value is claimed here. Logs, activities and metrics never contain a token, a credential reference, a credential or a payload. A replica that crashes is detected by the readiness probe and restarts; because the gateway holds no state, nothing is replayed and callers retry with their idempotency key. The roles of the gateway are Observer, Operator and Platform admin.
Acceptance criteria
| AC1 | Given the gateway with the identity platform and the fronted services reachable, when IntegrationHost/IntegrationHealth 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 two 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-IntegrationHost-001, NFR-18). |
| AC2 | Given the identity platform is unreachable and a cached signing key still validates tokens, when calls arrive and IntegrationHost/IntegrationHealth is probed, then already issued tokens pass, readiness stays ready and health answers 200 with the health degraded and a detail that names the identity platform, while liveness answers 200; given no valid key remains, then calls are refused, readiness is unready, IntegrationHost/IntegrationHealth answers 503 with a problem response that names the identity platform and no state changes (SCN-IntegrationHost-001, ADR-0017). |
| AC3 | Given one fronted service does not answer, when IntegrationHost/IntegrationHealth and the routes are called, then health answers 200 and reports the service as unavailable in its detail, its routes answer 503 with a retry hint that names the service, over gRPC UNAVAILABLE, the routes of the other service keep serving and the gateway invents no response (SCN-IntegrationHost-001, ADR-0028). |
| AC4 | Given a caller with factory.meta.read, when IntegrationHost/IntegrationAdapters is called on an instance whose metadata port has no source, then the response is 200 with the two fronted services and their repositories as model/services/integration/IntegrationHost.yaml lists them under deployment.fronts and the adapters stated as not reported; given the fake metadata source bound to the port, then the reply names the adapters with their versions and capability interfaces; a call without a token is answered 401 and a token without the scope 403, no fronted service is called and nothing is written (SCN-IntegrationHost-002). |
| AC5 | Given routed calls and a call above the rate limit of its route, when the metrics and logs are read, then connectsoft.factory.integration.host.requests counts every call by service and status, the call above the limit was refused with 429 and called no fronted service, connectsoft.factory.integration.host.request_duration holds the latency by service and route, both carry the tenant of the call and the project where the route names one, and no log record, activity or metric holds a token, a credential reference or a payload (ADR-0018, ADR-0019, NFR-13, model/services/integration/IntegrationHost.yaml). |
| Traces: services | IntegrationHost, ConnectorRegistryService |
| Traces: apis | IntegrationHost/IntegrationHealth, IntegrationHost/IntegrationAdapters |
| Traces: adrs | ADR-0015, ADR-0017, ADR-0018, ADR-0019, ADR-0028 |
| Traces: requirements | NFR-13, NFR-18 |
| Traces: scenarios | SCN-IntegrationHost-001, SCN-IntegrationHost-002 |
| Relates: nfrs | NFR-10 |
| Depends on | AIFACTORY-US-1009, feature:component-api-gateway-template, feature:component-observability-factory-conventions |
| Sources | model/services/integration/IntegrationHost.yaml, model/nfr-targets.yaml, docs/planes/capability-tools/connectors/services/integration-host/index.md#metrics-and-observability, docs/planes/capability-tools/connectors/services/integration-host/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-465 Health, adapters 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 two 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; when no valid key remains, readiness turns unready and the operation answers 503 with a problem response that names the identity platform; the adapters operation serves, under factory.meta.read, the two fronted services with their repositories and the adapters its metadata port returns, states the adapters as not reported when the port has no source, and calls no fronted service; the port has no production binding; every routed call records connectsoft.factory.integration.host.requests and connectsoft.factory.integration.host.request_duration with their modelled dimensions and, through the helper of the pinned observability library, the tenant and the project where the route names one, and carries the trace context to the service. | ConnectSoft.AI.SoftwareFactory.IntegrationHost |
AIFACTORY-TASK-4066 Rate limits per route from the configuration of the gateway |
implementation | Each route takes its rate limit from the configuration of the gateway through the pinned rate-limiting library 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.integration.host.requests; the limit values are configuration of the deployment and none is fixed in code. | ConnectSoft.AI.SoftwareFactory.IntegrationHost |
AIFACTORY-TASK-4067 Runbook of the three failure modes of the gateway |
documentation | The repository documentation holds one runbook entry per failure mode of model/services/integration/IntegrationHost.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 retry with their idempotency key (NFR-18). | ConnectSoft.AI.SoftwareFactory.IntegrationHost |
AIFACTORY-TASK-4068 Verify health, adapters, limits and telemetry through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-IntegrationHost-001\|Scenario=SCN-IntegrationHost-002)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-1013 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 adapters operation without a metadata source, with the fake metadata source and without its scope, a call above its limit, the two series with their dimensions, the tenant and the project, and a scan of the captured logs and activities for token, credential and payload content. |
ConnectSoft.AI.SoftwareFactory.IntegrationHost |