Skip to content

AIFACTORY-FEAT-085: TemplateCatalogHost: 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 Template & Library (PF-15) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 83 of 185 (Factory code)

TemplateCatalogHost is the platform API gateway of bounded context BC-14 (Template Catalog). The API gateway of the Template & Library 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.TemplateCatalogHost.

Delivers TemplateCatalogHost (complete)
Stubs —
Realizes adrs: ADR-0012, ADR-0014, ADR-0021
Requirements FR-02, FR-03, FR-06, FUX-01, FUX-03, NFR-11, NFR-13, XL-03, XL-07
Depends on —
Sources model/services/template-library/TemplateCatalogHost.yaml

Scenarios to trace (5, catalog): SCN-TemplateCatalogHost-001 ✓, SCN-TemplateCatalogHost-002 ✓, SCN-TemplateCatalogHost-003 ✓, SCN-TemplateCatalogHost-004 ✓, SCN-TemplateCatalogHost-005 ✓

AIFACTORY-US-085: TemplateCatalogHost routes the calls of its platform under a trusted scope

enabling · persona asset-maintainer As an asset maintainer, I want one gateway in front of BlueprintService, GenerationRecipeService and TemplateRegistryService that validates tokens and scopes, so that no service of the platform is reachable except through its gateway and every call arrives with a scope the service can trust.

This is the integration PBI of the gateway of the Template and Library platform. ADR-0028 re-scopes the former composition host as the API gateway of its platform: TemplateCatalogHost routes public REST and internal gRPC calls to the three services the model lists under deployment.fronts, BlueprintService, GenerationRecipeService and TemplateRegistryService, validates tokens and scopes and owns no business state, no relational store and no secret (gateway role GW-03). The repository ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost is created and scaffolded in I0 by AIFACTORY-TASK-509 of feature repository-and-pipeline-conventions (D140), and this feature starts from that scaffold: 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 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); the gateway copies neither the accessor nor the token contract. 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-709), token, tenant and scope on every read and sandbox route (AIFACTORY-US-710), the pass-through of a shared-write call with its idempotency key (AIFACTORY-US-711), the publication routes whose gate stays behind the gateway (AIFACTORY-US-712), and health, feed metadata, limits and telemetry with the three failure modes of this gateway (AIFACTORY-US-713). 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. Five operations of the platform are scoped by a project in their service files: ListBlueprints and CreateBlueprintVersion of BlueprintService and ListRecipes, DraftRecipe and ListGeneratedOutputs of GenerationRecipeService. ListGeneratedOutputs names the project in its path, ListBlueprints and ListRecipes name it in the required query parameter projectId, and CreateBlueprintVersion and DraftRecipe in the required body member projectId (D123). The gateway reads the project there. It answers 400 itself for a call that names none and 403 itself for a project the roles of the token do not grant, that is a token without a role claim for that project and without the tenant-wide Platform admin role, calls no fronted service in either case, and forwards every other call (AIFACTORY-US-710, AIFACTORY-US-711). Every other route addresses a blueprint, a recipe or a template version by its identifier or lists the catalog of the tenant, which has no project, so the gateway forwards 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 delivered in I1, in the increment of the three services it fronts and like the other gateways (D123): on a deployed instance every route has its service behind it, a caller outside the cluster, the command-line client among them, calls the gateway, and no service host is reached directly. The refusals and the failure branches are still proven against fakes generated from the fronts file. StudioBff and AgentRuntimeWorker, the two callers the model names, arrive in I3 and call the gateway in their own PBIs. The gateway invents no response.

Acceptance criteria

AC1 Given the repository ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost created and scaffolded in I0 by AIFACTORY-TASK-509 of feature repository-and-pipeline-conventions, whose first commit is the unchanged output of dotnet new connectsoft-apigateway -n ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost --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/template-library/TemplateCatalogHost.yaml).
AC2 Given a valid token for a route of each of the three fronted services, 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 token grants where the operation is scoped by one, the correlation id and the trace context, the fronted service answers and the response returns unchanged, as AIFACTORY-US-710 to AIFACTORY-US-712 prove per route class (ADR-0015, FUX-01).
AC3 Given the generated gateway, when its architecture test runs, then the test fails on a persistence model, an aggregate, a migration or a message consumer, the gateway binds no relational store, no outbox and no inbox, its configuration holds no secret, and no event of the model lists TemplateCatalogHost as a consumer (ADR-0012, ADR-0028, model/services/template-library/TemplateCatalogHost.yaml).
AC4 Given the gateway deployed with two replicas, when TemplateCatalogHost/TemplatesHealth is probed and one replica is stopped, then health reports the identity platform and the three fronted services, a replica stays in rotation while it can validate tokens, the other replica keeps serving and nothing is replayed, because the gateway holds no state (ADR-0017, model/services/template-library/TemplateCatalogHost.yaml).
Traces: services TemplateCatalogHost, BlueprintService, GenerationRecipeService, TemplateRegistryService
Traces: apis TemplateCatalogHost/TemplatesHealth
Traces: adrs ADR-0012, ADR-0015, ADR-0017, ADR-0028
Traces: requirements FUX-01, NFR-13
Depends on AIFACTORY-US-709, AIFACTORY-US-710, AIFACTORY-US-711, AIFACTORY-US-712, AIFACTORY-US-713, feature:repository-and-pipeline-conventions, feature:component-api-gateway-template, feature:component-extensions-ai, feature:blueprint-service, feature:generation-recipe-service, feature:template-registry-service
Sources model/services/template-library/TemplateCatalogHost.yaml, model/gateways.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/solution-packs/software-factory/templates/services/template-catalog-host/index.md#purpose-and-responsibilities

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2854 Deployment values of the gateway: replica range, ports, probes and the address of each fronted service operations The deployment manifest of the gateway states the replica range 2 to 4, the ports https 8160 and grpc 8162, the liveness and readiness probes on the health operation and one base address per fronted service from configuration, as model/services/template-library/TemplateCatalogHost.yaml records them; it leaves Templates:Host:FrontedServices at its default, the three service identifiers of deployment.fronts, sets ConnectSoftIdentityPlatform:Authority to the authority of the profile, and holds no secret; the same image runs in the saas-default, hybrid and on-prem topologies (ADR-0017). ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost
AIFACTORY-TASK-788 Verify template-catalog-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-085, 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 TemplateCatalogHost/TemplatesHealth on both, stops one instance and asserts that the other keeps serving and that no call is replayed. ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost

AIFACTORY-US-709: Template catalog fronts file: named clients and REST and gRPC routes of BlueprintService, GenerationRecipeService and TemplateRegistryService, generated at build

enabling · persona platform-admin As a platform admin, I want the route table of the template catalog gateway generated from the list of services it fronts, so that every operation of the platform has exactly one route with its scope and class and no forwarding code is written by hand.

The API gateway template is a custom gateway with controllers, use cases and named clients and is no reverse proxy, so a route exists only when it is declared. Under UseFactoryProfile the generated solution holds a build-time source generator that reads a fronts file on every build and emits one named HTTP client and one gRPC client per fronted service, the REST and gRPC routes that forward to them and the route table (feature component-api-gateway-template). This PBI writes the fronts file of the Template and Library platform. It lists the three services of deployment.fronts in model/services/template-library/TemplateCatalogHost.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 BlueprintService these are the five REST operations ListBlueprints, GetBlueprintVersion, CreateBlueprintVersion, ValidateBlueprint and SubmitBlueprint and the three internal gRPC methods of Blueprints: SubmitDraftVersion, Validate and GetDerivedModel. For GenerationRecipeService these are the six REST operations ListRecipes, GetRecipe, DraftRecipe, ValidateRecipe, ApproveRecipe and ListGeneratedOutputs and the two gRPC methods Recipes.GetApprovedRecipe and Recipes.RecordOutput. For TemplateRegistryService these are the six REST operations ListTemplates, GetTemplateVersion, ListLibraries, QueryCompatibility, DiscoverTemplates and PublishTemplateVersion and the gRPC method Catalog.ResolveManifest. That is seventeen REST routes and six gRPC routes, all unary. The REST operations are the public surface that StudioBff and a typed client call; the gRPC methods are the internal surface that the agent hosts call through AgentRuntimeWorker during a generation run. 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: the path parameter projectId for ListGeneratedOutputs, the required query parameter projectId for ListBlueprints and ListRecipes, the required body member projectId for CreateBlueprintVersion and DraftRecipe (D123), and a resource identifier only for every other operation, which is what AIFACTORY-US-710 and AIFACTORY-US-711 enforce. 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 TemplatesHealth and TemplatesFeeds, transforms no payload and composes no response from two services. The option Templates: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. The fronts file names its services by their identifiers, BlueprintService, GenerationRecipeService and TemplateRegistryService, as deployment.fronts lists them. The default of the option is those three identifiers, as model/services/template-library/TemplateCatalogHost.yaml states it (D123): the default of a fronted-services option equals the service set of deployment.fronts, as for the Control Plane gateway (D117) and for the model and tool gateways (D121). The gateway therefore starts with the option at its default, and the deployment manifest does not set it. The gateway clients of feature typed-gateway-clients are generated from a contract-first OpenAPI document of the client repository until a gateway publishes its own (decision D117): the pipeline of this repository publishes the OpenAPI document of the seventeen public REST operations as a build output, checked against the fronts file and against the three service files of the model. This feature builds and publishes no client package. The typed client of this gateway is generated and published by feature typed-gateway-clients in the same increment, beside the clients of the control plane, model and tool gateways (AIFACTORY-US-381 and AIFACTORY-US-383 of that feature).

Acceptance criteria

AC1 Given the fronts file of the Template and Library 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, seventeen REST routes and six gRPC routes, each with the scope, side-effect class, idempotency and streaming mode of the operation, and the route table test passes against model/services/template-library/TemplateCatalogHost.yaml, model/services/template-library/BlueprintService.yaml, model/services/template-library/GenerationRecipeService.yaml and model/services/template-library/TemplateRegistryService.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 Templates:Host:FrontedServices at its default, the three service identifiers of deployment.fronts in model/services/template-library/TemplateCatalogHost.yaml, when the gateway starts, then startup succeeds; given a value of the option that names no service of the fronts file or omits one, when the gateway starts, then startup fails with the differing name; given a path no route matches, when it is called, then the answer is 404 and no fronted service is called (ADR-0028, docs/architecture/catalogs/gateways.md).
AC3 Given a fake of each fronted service, when one REST route and one gRPC route per service are called with a valid token, then each call reaches the fake of its service with the authorization header, which carries the token of the caller unchanged because the gateway exchanges no token, the tenant, the correlation id and the trace context, and the response of the fake returns unchanged (ADR-0015, FUX-01).
AC4 Given the built gateway, when its pipeline publishes the OpenAPI document of the public REST routes, then the document holds exactly the seventeen 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/template-library (docs/architecture/api-governance.md).
Traces: services TemplateCatalogHost, BlueprintService, GenerationRecipeService, TemplateRegistryService
Traces: adrs ADR-0015, ADR-0028
Traces: requirements FUX-01
Depends on feature:component-api-gateway-template, feature:blueprint-service, feature:generation-recipe-service, feature:template-registry-service
Sources model/services/template-library/TemplateCatalogHost.yaml, model/services/template-library/BlueprintService.yaml, model/services/template-library/GenerationRecipeService.yaml, model/services/template-library/TemplateRegistryService.yaml, model/gateways.yaml, docs/architecture/catalogs/gateways.md, docs/architecture/api-governance.md, docs/solution-packs/software-factory/templates/services/template-catalog-host/index.md#context-and-boundaries

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-510 Fronts file with the REST and gRPC operations of BlueprintService, GenerationRecipeService and TemplateRegistryService 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, and for each REST operation how it addresses a project, by the path parameter projectId, by the required query parameter projectId, by the required body member projectId or by a resource identifier only; the build emits the named clients, the seventeen REST routes, the six gRPC routes and the route table; at startup the option Templates:Host:FrontedServices, whose default is the three service identifiers of deployment.fronts, is compared with the service names of the fronts file, the gateway starts with the option at its default, and a difference in either direction fails startup with the name; a call without a valid token or scope is refused at the gateway by the generated policies. ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost
AIFACTORY-TASK-2855 Fakes of the three fronted services and the token matrix of the acceptance suite fixture The acceptance suite of the gateway holds one fake per fronted service that records the headers and metadata it received and answers a configured status, a switch that makes a fake stop answering, and tokens for the matrix of role, tenant and project, including an expired token, an identity token, a user token of another audience, 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.TemplateCatalogHost
AIFACTORY-TASK-2856 OpenAPI document of the public REST routes of the gateway as a published build output contract The pipeline publishes one OpenAPI document with the seventeen 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 model/services/template-library/BlueprintService.yaml, model/services/template-library/GenerationRecipeService.yaml and model/services/template-library/TemplateRegistryService.yaml and fails the build on a missing operation, an operation of another service or a differing method, path, scope or response code, so the document can be the input from which feature typed-gateway-clients generates the client of this gateway (decision D117); no client package is built here. ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost
AIFACTORY-TASK-2857 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-709: one route per operation of the three service files under model/services/template-library, the failing builds, the start with the option at its default, the failing startup on a value that names no service of the fronts file or omits one, the 404 of an unknown path, one forwarded call per service and protocol and the contract check of the published OpenAPI document. ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost

AIFACTORY-US-710: A read or sandbox route of the template catalog gateway forwards a call only under a validated token, the tenant of the token, a granted project and the scope of its operation

behavior · persona requester As a requester, I want my read calls to reach the blueprint, recipe and catalog services only with the tenant, project and scope my token grants, so that I see the blueprints, recipes and template versions I am entitled to and nobody reads across a tenant or a project through the gateway.

A caller reaches a read operation of the Template and Library platform through the gateway: a requester lists the blueprints and recipes of a project and reads one version of each, reads the provenance of the generated outputs of a project, lists template and library versions, reads one pinned manifest and queries the compatibility matrix, and an Observer reads the same. A user presents an access token of the authorization server whose one audience is this gateway (ADR-0015 amendment D114); a client that also calls the Control Plane gateway requests a second token for it. The gateway validates issuer, signature, lifetime and audience through the pinned resource-server library and requires the scope the operation names: factory.blueprints.read for ListBlueprints and GetBlueprintVersion, factory.recipes.read for ListRecipes, GetRecipe and ListGeneratedOutputs, and factory.catalog.read for ListTemplates, GetTemplateVersion, ListLibraries and QueryCompatibility. It takes the tenant from the tid claim and overwrites any tenant header of the caller. Five operations of BlueprintService and GenerationRecipeService are scoped by a project in their service files: ListBlueprints returns the blueprints of a project, ListRecipes the recipes of a project and ListGeneratedOutputs the generated outputs of a project, and the two writes CreateBlueprintVersion and DraftRecipe store under the project they name (AIFACTORY-US-711). Each names its project where its operation declares it (D123): ListGeneratedOutputs in its path as projectId, ListBlueprints and ListRecipes in the required query parameter projectId, and the two writes in the required body member projectId. The gateway reads the project there and checks it against the roles of the token: it admits the project only when the token holds a role claim for it or the tenant-wide Platform admin role, and for a project the roles of the token do not grant it answers 403 itself. A call to ListBlueprints or ListRecipes without the parameter is answered 400 by the gateway. In both cases no fronted service is called. A granted call is forwarded with its path and its query unchanged, and the fronted service reads the project from the same place. A project header of the caller names the project of no project-scoped operation: on those five routes the gateway sets the project header of the forwarded scope from the project it admitted. On a route addressed by a resource identifier the header stays optional, a granted one is forwarded and one the token does not grant is refused with 403, so no project header of a caller is forwarded unchecked on any route. Every public REST operation of the three services names a factory. scope and none names a service scope, so no REST route admits a workload token; a workload token on such a 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 project the gateway admitted in the project header of the abstractions package, the correlation id and the trace context. The gateway exchanges no token; the fronted service validates the forwarded token again, accepts the audience of its own gateway, which is this one, and applies its own tenant filter and role policies (ADR-0015 amendment D117). The other read routes, GetBlueprintVersion, GetRecipe and the four reads of the catalog, name a blueprint, a recipe or a template version by identifier or list the catalog of the tenant, which has no project, and a gateway without business state cannot know the tenant or the project of such a resource. It forwards the call under the tenant of the token and the scope of the operation; the fronted service answers 403 for a missing role and 404 for a blueprint, a recipe or a template version of another tenant (ADR-0015 amendment D113), and the gateway returns that answer unchanged. The internal gRPC surface has three read methods and one sandbox method. Blueprints.GetDerivedModel, Recipes.GetApprovedRecipe and Catalog.ResolveManifest are read by workloads during a generation run, and Blueprints.Validate is the sandbox route of this platform: it validates one blueprint version against the schema and the rule set of its kind and returns a receipt. A workload presents a token that carries 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 workload token that holds it, the gateway forwards the tenant-id and the project metadata of the caller unchanged, because the fronted service reads a forwarded tenant and project only under that scope (ADR-0015 amendment D114); for a workload token without it, and for a user token, which holds no service scope, the answer is PERMISSION_DENIED and no fronted service is called. The gateway adds no gate of its own to the sandbox class and returns the receipt of the service unchanged. For every one of these routes the response is served by the fronted service, the gateway returns it unchanged with the correlation id and keeps nothing of the call. A call without a token, with an expired token, with an identity token or with a user token issued for another gateway is answered 401 and a token without the scope of the operation 403; in these cases no fronted service is called, and the refusal is counted for the route and logged with the correlation id and without the token. When a fronted service does not answer, its routes answer 503 with a retry hint, over gRPC UNAVAILABLE, and the routes of the other two services keep serving.

Acceptance criteria

AC1 Given a user token whose audience is this gateway, with factory.catalog.read, when the read route of ListTemplates is called, then the gateway forwards the call with the user token unchanged in the authorization header, without a token exchange, the tenant of the tid claim, the correlation id and the trace context, TemplateRegistryService answers, the response returns unchanged with the correlation id and nothing is written by the gateway (SCN-TemplateCatalogHost-004, ADR-0015, FUX-01).
AC2 Given the token matrix of the acceptance suite, when the read routes of the three 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 of the operation 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-TemplateCatalogHost-004, ADR-0015).
AC3 Given a valid user token and a tenant header of the caller that names another tenant, when a read route is called, then the header is overwritten with the tid claim before the call is forwarded; given the routes of ListBlueprints and ListRecipes with the required query parameter projectId and the route of ListGeneratedOutputs with a projectId in its path, when the token holds a role claim for that project or the tenant-wide Platform admin role, then the call is forwarded with its path and its query unchanged, when the roles of the token do not grant the project, then the gateway answers 403 itself, and when a call to ListBlueprints or ListRecipes names no projectId, then the gateway answers 400 itself, and in neither case a fronted service is called; given a route addressed by a blueprintId, a recipeId or a templateId, when the caller sends a project header the token does not grant, then the answer is 403 and nothing is forwarded, and when the fronted service answers 403 for a missing role or 404 for a resource of another tenant (ADR-0015 amendment D113), then the gateway returns that answer unchanged (SCN-TemplateCatalogHost-004, ADR-0015).
AC4 Given a workload token that holds the service scope the route names, when the gRPC read route of Catalog.ResolveManifest and the sandbox route of Blueprints.Validate are called with tenant-id and project metadata, then the gateway forwards each call with that metadata unchanged, adds no gate of its own to the sandbox class and returns the reply of the service unchanged; given a workload token without the scope, or a user token, which holds no service scope, then the answer is PERMISSION_DENIED and no fronted service is called; a NOT_FOUND of the fronted service for a resource outside the forwarded tenant returns unchanged (SCN-TemplateCatalogHost-004, ADR-0015).
AC5 Given a fronted service that does not answer, when one of its read routes is 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, invents no response, and the read routes of the other two services keep serving (SCN-TemplateCatalogHost-004, model/services/template-library/TemplateCatalogHost.yaml).
Traces: services TemplateCatalogHost, BlueprintService, GenerationRecipeService, TemplateRegistryService
Traces: adrs ADR-0015, ADR-0028
Traces: requirements FUX-01, FUX-03
Traces: scenarios SCN-TemplateCatalogHost-004
Relates: screens template-catalog, recipes
Depends on AIFACTORY-US-709, feature:component-api-gateway-template, feature:component-extensions-ai, feature:blueprint-service, feature:generation-recipe-service, feature:template-registry-service
Sources model/services/template-library/TemplateCatalogHost.yaml, model/services/template-library/BlueprintService.yaml, model/services/template-library/GenerationRecipeService.yaml, model/services/template-library/TemplateRegistryService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/solution-packs/software-factory/templates/services/template-catalog-host/index.md#purpose-and-responsibilities

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2858 Issuer, audience, scope and project configuration of the read and sandbox routes implementation The gateway is configured with the authority of ConnectSoftIdentityPlatform:Authority and its own resource as the one audience of a user token; each read route requires the scope of its operation; the routes of the five project-scoped operations are marked with the place that names their project, the path parameter projectId for ListGeneratedOutputs, the required query parameter projectId for ListBlueprints and ListRecipes and the required body member projectId for CreateBlueprintVersion and DraftRecipe (D123); the gateway reads the project there, admits it only for a token with a role claim for it or the tenant-wide Platform admin role, answers 403 itself for a project the roles of the token do not grant and 400 itself for a call that names none, calling no fronted service in either case, and forwards a granted call with its path, its query and its body unchanged; a route addressed by blueprintId, recipeId or templateId is marked as addressed by a resource id only, so the gateway checks token and scope, refuses a project header the token does not grant and leaves the role and the tenant of the resource to the fronted service; no project header of a caller is forwarded unchecked; the tenant header is overwritten with the tid claim; a workload token is refused with 403 on a REST route; a gRPC route names the service scope a workload token must hold and forwards the tenant-id and project metadata unchanged with it (ADR-0015 amendment D114); the user token is forwarded unchanged and no token is exchanged (ADR-0015 amendment D117); refusals are counted per route and logged with the correlation id and without the token. ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost
AIFACTORY-TASK-2859 Verify the read and sandbox routes through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-TemplateCatalogHost-004"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-710 over the token matrix, the token received by the fake equal to the user token of the caller, the routes of ListBlueprints, ListRecipes and ListGeneratedOutputs forwarded unchanged for a granted project and refused with 403 for a project without a role claim, the routes of ListBlueprints and ListRecipes refused with 400 for a call without the query parameter projectId, a tenant-wide Platform admin admitted to a project, a route addressed by a resource id that refuses a project header the token does not grant and whose 403 and 404 come from the fake and return unchanged, the overwritten tenant header, a workload token refused on a REST route, the gRPC routes of Catalog.ResolveManifest and Blueprints.Validate with and without the service scope, and a fake that stops answering. ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost

AIFACTORY-US-711: A shared-write route of the template catalog gateway passes the idempotency key through and the gateway keeps nothing between calls

behavior · persona requester As a requester, I want a write I repeat after a failure to be applied once, so that a lost answer or a restarted gateway never stores a second blueprint version, drafts a second recipe or approves a recipe twice.

A shared-write operation changes state that others read. On this platform these are six public REST operations and two internal gRPC methods. Of BlueprintService: CreateBlueprintVersion and ValidateBlueprint under factory.blueprints.write, and the gRPC method Blueprints.SubmitDraftVersion, by which a run stores a document it produced as a new Draft version. Of GenerationRecipeService: DraftRecipe and ValidateRecipe under factory.recipes.write, ApproveRecipe under factory.recipes.approve, and the gRPC method Recipes.RecordOutput, by which a generation attempt records the provenance of its output. Of TemplateRegistryService: DiscoverTemplates under factory.catalog.admin, which through I4 the service admits only for an administrator of the platform tenant and answers 403 for a caller of another tenant (D123), an answer the gateway returns unchanged. The caller sends a REST call through the gateway under the token, tenant, project and scope rules of AIFACTORY-US-710. Two of the writes are scoped by a project, CreateBlueprintVersion and DraftRecipe: the caller names the project in the required body member projectId (D123). The gateway reads that one member of the body, admits the project only for a token that holds a role claim for it or the tenant-wide Platform admin role, and answers 400 itself for a body that names no project and 403 itself for a project the roles of the token do not grant, calling no fronted service in either case. It forwards a granted call with its body unchanged, and the fronted service stores under the project the body names. The other writes address a blueprint or a recipe by identifier or, for DiscoverTemplates, the catalog of the platform tenant; on them the gateway reads no project, a project header is optional and is refused with 403 when the token does not grant it. Two of the operations declare the idempotency key-header, CreateBlueprintVersion and DraftRecipe: each is called with an Idempotency-Key, the gateway forwards the header unchanged and the fronted service applies the request once under its own rule, and what the service answers for the same key with the same body and for the same key with a different body returns to the caller unchanged. The other four declare the idempotency natural: the gateway demands no key for them, and the service makes a repeat harmless by the natural key of what it writes, a blueprint version, a recipe version or a commit that is already pinned. An internal gRPC route is called by a workload: the token carries service scopes, no audience of a user API and no tenant claim, and the route names the service scope it must hold. For a workload token that holds the scope, the gateway forwards the tenant-id and the project metadata of the caller unchanged, because the fronted service reads a forwarded tenant and project only under that scope (ADR-0015 amendment D114); for a workload token without it, and for a user token, which holds no service scope, the answer is PERMISSION_DENIED and no fronted service is called. Blueprints.SubmitDraftVersion is idempotent on the hash of the document inside BlueprintService, so a repeated call returns the version that was stored first, and Recipes.RecordOutput is idempotent on run, attempt and module inside GenerationRecipeService, so a repeated call records one output. 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 retries with the same key, or with the same document or version, and receives from the service the result of the first application (failure mode of a gateway replica crash in the model). ApproveRecipe is of the shared-write class in the model although it is an approval: who may approve a recipe, a Requester, an Asset maintainer or a Reviewer where the policy of the project requires one, is decided by GenerationRecipeService, and the gateway checks the scope factory.recipes.approve and nothing else. When the fronted service does not answer, the route answers 503, over gRPC UNAVAILABLE, with the service named and a retry hint, the routes of the other two services keep serving, and the caller retries. A refusal by the gateway reaches no fronted service, so it applies nothing. A missing key, an invalid body, the 403 of the service for a missing role, the 404 for a resource of another tenant and every domain refusal, such as the 409 of ApproveRecipe, the 412 of DraftRecipe or the 422 of CreateBlueprintVersion, are answers of the fronted service and return unchanged with the correlation id. The gateway records request count and latency for the route with the status that was returned.

Acceptance criteria

AC1 Given a valid user token with factory.blueprints.write and a role claim for the project the body member projectId names, and the shared-write route of CreateBlueprintVersion, when the call arrives with an Idempotency-Key, then the gateway forwards the request with the key header and the body unchanged, the fronted service applies it once and the response returns unchanged with the correlation id (SCN-TemplateCatalogHost-005, ADR-0015, FR-03).
AC2 Given the same call repeated with the same key, and then with the same key and a different body, when both pass the gateway, then the first returns the result of the first application and the second returns the answer of the fronted service for a reused key unchanged; given the route of DraftRecipe called with a key and a granted project for a blueprint version a recipe may not bind, when the fronted service answers 412, then that answer returns unchanged; the gateway has stored neither a key nor a result (SCN-TemplateCatalogHost-005, ADR-0014, ADR-0028).
AC3 Given the routes of ValidateBlueprint, ValidateRecipe, ApproveRecipe and DiscoverTemplates, the four that declare the idempotency natural, when each is called with a valid token of its scope and without a key header, then the gateway forwards the call and returns the answer of the fronted service unchanged, the 422 of the two validations and the 409 of ApproveRecipe among them; given a workload token that holds the service scope the routes of Blueprints.SubmitDraftVersion and Recipes.RecordOutput name, when each method is called twice with the same request and with tenant-id and project metadata, then the gateway forwards every call with that metadata unchanged and returns each reply 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-TemplateCatalogHost-005, ADR-0015).
AC4 Given a gateway replica stopped while a shared-write call is in flight, when the caller retries with the same key through another replica, then the fronted service returns the result of the one application, nothing is replayed by the gateway and no second state change exists (SCN-TemplateCatalogHost-005, model/services/template-library/TemplateCatalogHost.yaml).
AC5 Given a call without a token, a token that lacks the scope, a call to CreateBlueprintVersion or DraftRecipe whose body names no projectId, such a call whose projectId names a project the roles of the token do not grant, or a fronted service that does not answer, when a shared-write route is called, then the answer is 401, 403, 400, 403 or 503 respectively, over gRPC UNAUTHENTICATED, PERMISSION_DENIED and UNAVAILABLE for the first, the second and the last; a call the gateway refuses reaches no fronted service and applies nothing; the 403 of the fronted service for a missing role, the 403 of DiscoverTemplates for a caller of another tenant than the platform tenant among them, and its 404 for a resource of another tenant (ADR-0015 amendment D113) return unchanged; the 503 names the service and carries a retry hint while the routes of the other two services keep serving (SCN-TemplateCatalogHost-005, ADR-0015).
Traces: services TemplateCatalogHost, BlueprintService, GenerationRecipeService, TemplateRegistryService
Traces: adrs ADR-0014, ADR-0015, ADR-0028
Traces: requirements FR-03
Traces: scenarios SCN-TemplateCatalogHost-005
Depends on AIFACTORY-US-709, AIFACTORY-US-710, feature:component-api-gateway-template, feature:blueprint-service, feature:generation-recipe-service, feature:template-registry-service
Sources model/services/template-library/TemplateCatalogHost.yaml, model/services/template-library/BlueprintService.yaml, model/services/template-library/GenerationRecipeService.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2860 Forwarded headers and metadata of a write route and a stateless call path implementation A shared-write REST route forwards the Idempotency-Key header where the operation declares key-header, the body and the established scope unchanged and returns the status and the body of the fronted service unchanged; the routes of CreateBlueprintVersion and DraftRecipe take their project from the required body member projectId (D123), are forwarded with the body unchanged only when the token holds a role claim for that project or the tenant-wide Platform admin role, and are answered by the gateway 403 for a project the roles of the token do not grant and 400 for a body that names none; a route whose operation declares the idempotency natural demands no key; an internal gRPC route names the service scope a workload token must hold, answers PERMISSION_DENIED without it and forwards the tenant-id and project metadata of the caller unchanged with it (ADR-0015 amendment D114); 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.TemplateCatalogHost
AIFACTORY-TASK-2861 Verify the shared-write routes through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-TemplateCatalogHost-005"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-711 with a fake that applies a key once, the routes of CreateBlueprintVersion and DraftRecipe forwarded with the body unchanged for a granted project, refused with 403 for a project without a role claim and with 400 for a body that names none, the 412 of DraftRecipe returned unchanged, the four routes without a key header (ValidateBlueprint, ValidateRecipe, ApproveRecipe and DiscoverTemplates) with their 422 and 409 answers, the gRPC routes of Blueprints.SubmitDraftVersion and Recipes.RecordOutput under a workload token with and without the service scope and under a user token of the token matrix (PERMISSION_DENIED and no call to the fake), a replica stopped during a call, a route addressed by a resource id whose 403 and 404 come from the fake and return unchanged, and a fake that stops answering. ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost

AIFACTORY-US-712: A publication route is forwarded under its scope, and the review and the approval of the release stay in Asset Publication behind the fronted service

behavior · persona asset-maintainer As an asset maintainer, I want a submission for publication to be decided by the services that own the version and the release, with the gateway only checking who calls and what may be called, so that an approval is never decided twice or by a component that holds no state.

Two operations of this platform are of the publication class, the highest side-effect class the model gives this gateway. SubmitBlueprint of BlueprintService submits a Validated blueprint version to Asset Publication as a blueprint release candidate, under factory.blueprints.publish. PublishTemplateVersion of TemplateRegistryService submits a Verified template version to Asset Publication as a template release, under factory.catalog.admin; through I4 the service admits it only for an administrator of the platform tenant and answers 403 for a caller of another tenant (D123). Neither publishes anything by itself: each hands a candidate to AgentRegistryService, the release authority of the Control Plane, and answers 202; the review, the evaluation where a suite exists and the approval by someone other than the subject that submitted the candidate are decided there (ADR-0021), and each service marks its version Published only when the release is published. 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 the scope the operation names and forwards the call with the established scope and the user token unchanged, so the fronted service knows the caller as the submitting subject. The gate itself is decided where the state is. BlueprintService submits only a Validated version and TemplateRegistryService only a Verified one, and each answers 409 otherwise and 404 for a version the tenant of the caller cannot read; the gateway returns those answers unchanged. The gateway evaluates no approval and holds no approval reference: neither operation declares one in the model, so a request is forwarded without one, and no request is refused for lacking one. It resolves no release, reads no release state and never asks AgentRegistryService anything, which belongs to another platform and is no service this gateway fronts. It writes no audit evidence: the fronted service writes its evidence in the transaction of its command. A call without a token, with an expired token, with an identity token or with a user token issued for another gateway is answered 401, and a token without the scope of the operation 403, a token that holds only factory.blueprints.write on the route of SubmitBlueprint among them; in these cases no fronted service is called. Both routes name only a resource id, a blueprintId or a templateId with a version: the fronted service answers 403 for a caller whose role may not submit and 404 for a version of another tenant (ADR-0015 amendment D113), and the gateway returns that answer unchanged. When the fronted service does not answer, the route answers 503 with a retry hint that names the service, and the routes of the other two services keep serving; when AgentRegistryService does not answer the fronted service, the service fails fast, TemplateRegistryService with 503 and a problem response that names AgentRegistryService, and that answer returns unchanged. A register test of the acceptance suite lists the routes of the publication class from the route table and fails when such a route has no scope or when the gateway holds a handler, a cache entry or a store for an approval, a release or a candidate.

Acceptance criteria

AC1 Given a user token with factory.blueprints.publish, when the publication route of SubmitBlueprint is called against the fake of BlueprintService that answers 202 or 409, then the gateway forwards the call under the established scope with the user token unchanged and returns each answer unchanged with the correlation id; it evaluates no approval, holds no approval reference and writes nothing (SCN-TemplateCatalogHost-003, ADR-0028, model/services/template-library/BlueprintService.yaml).
AC2 Given a user token with factory.catalog.admin, when the publication route of PublishTemplateVersion is called against the fake of TemplateRegistryService that answers 202, 403 for a caller of another tenant than the platform tenant, 404 or 409, or 503 with a problem response that names AgentRegistryService because the release authority does not answer it, then the gateway returns each answer unchanged; a request that carries no approval reference is forwarded, because neither publication operation declares one, and the gateway called no service other than the one the route fronts (SCN-TemplateCatalogHost-003, ADR-0021, FR-06).
AC3 Given a call without a token or with an expired token, a token that lacks the scope of the operation, a token with factory.blueprints.write only on the route of SubmitBlueprint among them, when a publication route is called, then the gateway answers 401 or 403 and no fronted service is called; given a route that names only a blueprintId or a templateId with a version, when the fronted service answers 403 for a missing role or 404 for a version of another tenant (ADR-0015 amendment D113), then the gateway returns that answer unchanged; given a fronted service that does not answer, then the answer is 503 with a retry hint that names the service (SCN-TemplateCatalogHost-003, ADR-0015).
AC4 Given the route table of the built gateway, when the register test runs, then it lists exactly the two routes of the publication class of model/services/template-library/BlueprintService.yaml and model/services/template-library/TemplateRegistryService.yaml, each with its scope, and it fails when such a route has no scope or when the gateway holds a handler, a cache entry or a store for an approval, a release or a candidate (SCN-TemplateCatalogHost-003, ADR-0028).
Traces: services TemplateCatalogHost, BlueprintService, TemplateRegistryService
Traces: adrs ADR-0015, ADR-0021, ADR-0028
Traces: requirements FR-02, FR-06, NFR-11
Traces: scenarios SCN-TemplateCatalogHost-003
Relates: screens template-catalog
Depends on AIFACTORY-US-709, AIFACTORY-US-710, feature:component-api-gateway-template, feature:blueprint-service, feature:template-registry-service
Sources model/services/template-library/TemplateCatalogHost.yaml, model/services/template-library/BlueprintService.yaml, model/services/template-library/TemplateRegistryService.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0021-quality-gates.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2862 Fakes of the two publication routes and the route class register of the gateway fixture The acceptance suite holds a fake of SubmitBlueprint that answers 202 and 409 and a fake of PublishTemplateVersion that answers 202, 403, 404, 409 and the 503 of the service with a problem response that names AgentRegistryService, each recording the token and the headers it received; a register test lists every route of class publication from the route table and fails when such a route has no scope or when the gateway holds a handler, a cache entry or a store for an approval, a release or a candidate, or a client for a service outside deployment.fronts of model/services/template-library/TemplateCatalogHost.yaml. ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost
AIFACTORY-TASK-2863 Verify the publication routes through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-TemplateCatalogHost-003"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-712: each publication route forwarded under its scope with the user token unchanged, the answers 202, 403, 404, 409 and the 503 of the service that names AgentRegistryService returned unchanged, a request without an approval reference forwarded, the refusals of the gateway without a call to a fronted service, a fake that stops answering, and the register of publication routes. ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost

AIFACTORY-US-713: Health, feed metadata, limits and telemetry of the template catalog gateway while the identity platform, a fronted service or a replica fails

behavior · persona operator As an operator, I want to see whether the template catalog gateway, the identity platform and each fronted service answer, and which package feeds and template sources this installation reads, 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. TemplateCatalogHost/TemplatesHealth 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. What the gateway does when it is unreachable is decided (D117, ADR-0015 amendment). While a cached signing key still validates tokens, the gateway stays in rotation: readiness stays ready, tokens that were already issued keep passing, and from the first failed probe TemplatesHealth answers 200 with the health degraded and a detail that names the identity platform as unreachable, so the operator sees the failure in health while calls still pass. The gateway leaves rotation only when no valid key remains, because none was cached or the cached keys expired: readiness turns unready, TemplatesHealth answers 503 with a problem response that names the identity platform, and calls are refused, so the gateway fails closed. Liveness keeps answering 200 without a token in both phases. A fronted service is an optional dependency: when it does not answer, health reports it as unavailable in the detail and the answer stays 200, its routes answer 503 with a retry hint, and the routes of the other two services keep serving. TemplateCatalogHost/TemplatesFeeds returns to a caller whose scope carries factory.meta.read the package feeds and the template sources configured for this installation, by name and never with a credential. The gateway reads no feed and holds no state: the feeds are named by the option Templates:Feeds:PackageFeeds of TemplateRegistryService, which also reads the template sources through connectors. The model gives TemplateRegistryService no operation that returns that list and names no option for the template sources, so the source of the answer is an open point reported to the owner. Until it is decided, the operation is hosted with its scope, its refusals and its response shape and reads the list through one metadata port of the gateway. The port has no production binding in this delivery. The call path, the token and the scope under which the gateway would read the list wait for the same decision, because the caller holds factory.meta.read while the reads of TemplateRegistryService require factory.catalog.read, and the gateway calls no operation of TemplateRegistryService for this operation until then. The happy path is therefore proven against a fake metadata source of the acceptance suite only. A deployed instance, whose port has no source, answers 503 with a problem response that says so and invents no list. The operation lists the code 200 only, so the 503 is no modelled code of TemplateCatalogHost/TemplatesFeeds; it is reported with the open point. A call that exceeds the rate limit configured for its route is refused with 429 through the pinned rate-limiting library, from the configuration of the gateway. The gateway emits connectsoft.factory.templates.host.requests with the dimensions service, route and status and connectsoft.factory.templates.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 interactive class of the model, whose objective is an acknowledgement within 2 seconds at p95; 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 blueprint document, a recipe 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 retry with their idempotency key, as AIFACTORY-US-711 states. The roles of the gateway are Asset maintainer, Operator, Platform admin and Observer.

Acceptance criteria

AC1 Given the gateway with the identity platform and the three fronted services reachable, when TemplateCatalogHost/TemplatesHealth 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-TemplateCatalogHost-001, NFR-18).
AC2 Given the identity platform is unreachable and a cached signing key still validates tokens, when calls arrive and TemplateCatalogHost/TemplatesHealth is probed, then tokens that were already issued are validated with the cached key, readiness stays ready so the replica stays in rotation, and from the first failed probe health answers 200 with the health degraded and a detail that names the identity platform as unreachable, while liveness keeps answering 200; given no valid key remains, because none was cached or the cached keys expired, when calls arrive, then they are refused, readiness is unready so the replica leaves rotation, TemplateCatalogHost/TemplatesHealth answers 503 with a problem response that names the identity platform and no state changes (SCN-TemplateCatalogHost-001, model/services/template-library/TemplateCatalogHost.yaml).
AC3 Given one fronted service does not answer, when TemplateCatalogHost/TemplatesHealth and the routes are called, then health answers 200 and reports that 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 two services keep serving and the gateway invents no response (SCN-TemplateCatalogHost-001, ADR-0028).
AC4 Given a caller with factory.meta.read and the fake metadata source of the acceptance suite bound to the metadata port, when TemplateCatalogHost/TemplatesFeeds is called, then the response is 200 with the package feeds and the template sources as the source reported them, by name and without a credential, which is the only proof of the happy path in this delivery; a call without a token is answered 401 and a token without the scope 403; when no source is bound, as on a deployed instance, or the source does not answer, the answer is 503 with a problem response that names it, a code that model/services/template-library/TemplateCatalogHost.yaml does not list for the operation and that is reported with the open point; the gateway called no operation of TemplateRegistryService, nothing is written and no list is invented (SCN-TemplateCatalogHost-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.templates.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.templates.host.request_duration holds the latency by service and route, both series carry the tenant of the call, and the project where the route names one, as the helper of the pinned observability library adds them, and no log record, activity or metric holds a token or a payload (ADR-0019, model/services/template-library/TemplateCatalogHost.yaml).
Traces: services TemplateCatalogHost
Traces: apis TemplateCatalogHost/TemplatesHealth, TemplateCatalogHost/TemplatesFeeds
Traces: adrs ADR-0015, ADR-0017, ADR-0019, ADR-0028
Traces: requirements NFR-13, NFR-18
Traces: scenarios SCN-TemplateCatalogHost-001, SCN-TemplateCatalogHost-002
Relates: nfrs NFR-07
Depends on AIFACTORY-US-709, feature:component-api-gateway-template, feature:component-observability-factory-conventions, feature:template-registry-service
Sources model/services/template-library/TemplateCatalogHost.yaml, model/services/template-library/TemplateRegistryService.yaml, docs/solution-packs/software-factory/templates/services/template-catalog-host/index.md#metrics-and-observability, docs/solution-packs/software-factory/templates/services/template-catalog-host/index.md#failure-and-recovery

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-511 Health, feed metadata 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 with the health degraded and the identity platform named in the detail from the first failed probe; when no valid key remains, readiness turns unready and the operation answers 503 with a problem response that names the identity platform (D117); liveness stays at 200 in both phases; the feeds operation serves, under factory.meta.read, the list its metadata port returns and answers 503 when the port has no source or the source does not answer; the port has no production binding and calls no operation of TemplateRegistryService; every routed call records connectsoft.factory.templates.host.requests and connectsoft.factory.templates.host.request_duration with their modelled dimensions and, through the helper of the pinned observability library, with the tenant of the call and the project where the route names one (ADR-0019), and carries the trace context to the service. ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost
AIFACTORY-TASK-2864 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.templates.host.requests; the limit values are configuration of the deployment and none is fixed in code. ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost
AIFACTORY-TASK-2865 Runbook of the three failure modes of the gateway documentation The repository documentation holds one runbook entry per failure mode of model/services/template-library/TemplateCatalogHost.yaml (identity platform unreachable, fronted service unavailable, gateway replica crash) with its detection signal, the expected answers of the gateway and the recovery step; the entry of the identity platform states its two phases, degraded and in rotation while a cached signing key validates tokens, and out of rotation and failing closed when no valid key remains (D117); the entry of the replica crash states that nothing is replayed and that callers retry with their idempotency key (NFR-18). ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost
AIFACTORY-TASK-2866 Verify health, feed metadata, limits and telemetry through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-TemplateCatalogHost-001\|Scenario=SCN-TemplateCatalogHost-002)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-713 with the identity platform stopped while a cached key validates tokens (readiness ready, health 200 and degraded), without a cached key and after the cached key expired (readiness unready, health 503), one fake stopped, the feeds operation with the fake metadata source, without a source and without its scope, a call above its limit, the two series connectsoft.factory.templates.host.requests and connectsoft.factory.templates.host.request_duration with service, route and status, the tenant of the call and the project of a project-scoped route, and a scan of the captured logs and activities for token and payload content. ConnectSoft.AI.SoftwareFactory.TemplateCatalogHost