AIFACTORY-FEAT-188: ConnectorRegistryService: inbound deliveries and delivery reads for the second outcome¶
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 I2 Deliver it · State elaborated · Route backend-developer · Build order 93 of 185 (Factory code)
ConnectorRegistryService is the service of bounded context BC-17 (Connectors & Webhooks). In this increment it receives the inbound deliveries of Azure DevOps through the webhook ingress of WebhookGatewayService, records each verified delivery and publishes DeliveryReceived, and serves the reads of pipeline runs, pull requests, package feeds and container registries that PipelineExecutionService and ReleaseService need, so that review states, merges and pipeline runs reach the second outcome (D135). Outbound deliveries and the other providers stay with the complete delivery in I5. Its repositories are ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService and ConnectSoft.AI.SoftwareFactory.WebhookGatewayService.
| Delivers | ConnectorRegistryService (thin): Inbound Azure DevOps deliveries recorded and announced as DeliveryReceived, and the reads of pipeline runs, pull requests, package feeds and container registries for Azure DevOps (D135).WebhookGatewayService (thin): The webhook ingress for the Azure DevOps signature scheme with replay-window and deduplication checks, emitting verified deliveries to ConnectorRegistryService (D135). |
| Stubs | — |
| Realizes | adrs: ADR-0012, ADR-0017, ADR-0022 |
| Requirements | FR-05, FR-11, FUX-02, NFR-02, NFR-05, NFR-09, NFR-13, NFR-18, XL-10, XL-15, XL-16 |
| Depends on | AIFACTORY-FEAT-032 ConnectorRegistryService: thin delivery for the first outcomeAIFACTORY-FEAT-033 IntegrationService: thin delivery for the first outcome |
| Sources | model/services/integration/ConnectorRegistryService.yaml, model/services/integration/WebhookGatewayService.yaml |
Scenarios to trace (22, catalog): SCN-ConnectorRegistryService-001 ✓, SCN-ConnectorRegistryService-002 ✓, SCN-ConnectorRegistryService-003 ✓, SCN-ConnectorRegistryService-004 ✓, SCN-ConnectorRegistryService-005, SCN-ConnectorRegistryService-006, SCN-ConnectorRegistryService-007 ✓, SCN-ConnectorRegistryService-015 ✓, SCN-ConnectorRegistryService-016 ✓, SCN-ConnectorRegistryService-017 ✓, SCN-ConnectorRegistryService-018 ✓, SCN-ConnectorRegistryService-008 ✓, SCN-ConnectorRegistryService-009, SCN-ConnectorRegistryService-010 ✓, SCN-ConnectorRegistryService-011 ✓, SCN-ConnectorRegistryService-012, SCN-ConnectorRegistryService-013, SCN-ConnectorRegistryService-014, SCN-WebhookGatewayService-001 ✓, SCN-WebhookGatewayService-002 ✓, SCN-WebhookGatewayService-003 ✓, SCN-WebhookGatewayService-004 ✓
AIFACTORY-US-1476: ConnectorRegistryService and WebhookGatewayService carry Azure DevOps subscriptions, deliveries and reads to the second outcome¶
behavior · persona platform-admin
As a platform admin, I want the webhook ingress and the connector registry to subscribe a project to its Azure DevOps service hooks, to receive and record those deliveries and to serve the Azure DevOps reads of pipeline runs, pull requests, package feeds and container registries, so that review states, merges and pipeline runs reach PipelineExecutionService and publication evidence reaches ReleaseService through one governed path, without a poll of the system of record for every change.
This is the integration PBI of the I2 delivery that decision D135 adds before the complete delivery of I5, so that PipelineExecutionService and ReleaseService of I2 receive review states, merges and pipeline runs and the outcome of I2 can be met. Its thin scope, stated in model/backlog/features/integration.yaml, has three parts. ConnectorRegistryService creates an Azure DevOps inbound Subscription of a project with its GW-06 ingress identity through CreateSubscription, announces it as ConnectorSubscriptionChanged and lists deliveries through ListDeliveries (AIFACTORY-US-1483); it records each verified inbound Azure DevOps delivery as a Delivery and announces it as DeliveryReceived in the same transaction, deduplicated on its key (AIFACTORY-US-1480); and it serves four internal reads under the scope factory.connections.read, Connectors.ReadPipelineRun and Connectors.ReadPullRequest for PipelineExecutionService and Connectors.ReadPackageFeed and Connectors.ReadContainerRegistry for ReleaseService (AIFACTORY-US-1481), through an Azure DevOps adapter of a new version that declares these capabilities and the webhook scheme of the service hooks and is certified again (AIFACTORY-US-1477). WebhookGatewayService, the conditional ingress GW-06, keeps its ingress table from ConnectorSubscriptionChanged through the handler RefreshIngressTable (AIFACTORY-US-1483), verifies an Azure DevOps delivery under the scheme of its ingress entry with the signing secret of the connection of the tenant, the replay window, deduplication, the size limit and the rate limit per ingress identity, captures the payload by hash, and announces InboundDeliveryVerified or InboundDeliveryRejected (AIFACTORY-US-1478, AIFACTORY-US-1479); it never dispatches anything itself. The registry keeps the surface of its thin delivery of I1 and now hosts nine operations; ReplayDelivery and Connectors.Deliver, the dispatch of a delivery to its target with DeliveryDispatched, DeliveryFailed and DeliveryReplayed, the worker OutboundDeliveryRetrier, the event ConnectorDeprecated, the handler PauseOnRevocation of ConnectionStateChanged and the other providers arrive with features connector-registry-service-complete and webhook-gateway-service in I5; the handler of DeletionOrderIssued is built in I4 by feature retention-residency-service. The connector-registry messaging profile now registers one consumed event, InboundDeliveryVerified, in its inbox with idempotency on the event id, and publishes ConnectorActivated, ConnectorSubscriptionChanged, DeliveryReceived and the audit evidence of its certifications under the run event envelope of the pinned contracts package through its outbox. The repository ConnectSoft.AI.SoftwareFactory.WebhookGatewayService is created by the steps of the repository checklist of feature repository-and-pipeline-conventions and scaffolded once from the pinned API gateway template package with UseFactoryProfile (feature component-api-gateway-template). The gateway is an edge service with a primary relational store, webhook-gateway-sql, an outbox and an inbox, which the Platform role of the template forbids; it is scaffolded with the BackendForFrontend role, the only role that admits persistence and messaging, with NHibernate persistence on SQL Server, migrations and the Orleans actor model named on the command line, because their defaults are None and off. The template offers no Orleans value of MessagingModelType, so the pinned Orleans messaging profile library (connectsoft-extensions-messaging-model-orleans) is added by reference after the scaffold under the messaging service name webhook-gateway, with its own transport credential messaging-transport by reference (ADR-0028 decision 7); the model of WebhookGatewayService names neither that option, that secret nor that library, which is reported to the owner. Its one exemption file names the InboundDelivery aggregate and the IngressEntry projection, their mappings and migrations, the publisher of its two events and the handler RefreshIngressTable, and the gateway keeps the API gateway template with the BackendForFrontend role and this one exemption file (D139). The gateway takes no token on ReceiveWebhook, because the signature is the authentication and the tenant comes from the ingress identity; WebhookHealth is internal under factory.health.read (SCN-WebhookGatewayService-002). It runs in the topologies saas-default and hybrid only (ADR-0017), on container apps with one to eight replicas and the port https 7950. The model secret webhook-signing-secrets is read as the Key Vault location of the signing secrets of the connections, which the broker references of owner kind webhook-scheme point at; the gateway names it by reference with its rotation of 90 days and never reads it directly, a reading reported to the owner. No payload, signature, signing secret, credential or credential reference reaches a log record, an activity, a metric or an event of either service (ADR-0019). The certification, the four reads and the signing secret of the gateway ask a credential issuance of the purpose delivery, which the platform bundle allows only for the service identities of ConnectorRegistryService and WebhookGatewayService (D139), so they are issued on a deployed instance and the same purpose asked by any other subject is denied. The descriptor of the new adapter version must be certified by a Platform admin, a signing secret reference must be registered for each connection, and the service hook must be configured at Azure DevOps, all by the runbook of AIFACTORY-TASK-6007; until then the behaviour is proven against fixtures and fakes.
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.WebhookGatewayService created by the repository checklist, whose first commit is the unchanged output of dotnet new connectsoft-apigateway -n ConnectSoft.AI.SoftwareFactory.WebhookGatewayService --UseFactoryProfile true --GatewayRole BackendForFrontend --persistence-model-type NHibernate --nhibernate-dialect-type SqlServer --migrations true --database-name WebhookGateway --actor-model-type Orleans from the pinned template package, followed by the pinned Orleans messaging profile library added by reference, when its pipeline runs with the work of this feature, then the solution builds, the tests pass with complete reports, the architecture test admits exactly the types its one exemption file names and a container image is published (ADR-0028, model/services/integration/WebhookGatewayService.yaml, model/template-parameters/connectsoft-apigateway.yaml). |
| AC2 | Given the service descriptor of ConnectorRegistryService for I2, when the contract test of the Factory profile compares it with the hosted surface, then exactly ConnectorRegistryService/ListConnectors, ConnectorRegistryService/CertifyConnector, ConnectorRegistryService/CreateSubscription, ConnectorRegistryService/ListDeliveries, ConnectorRegistryService/Connectors.ResolveCapability, ConnectorRegistryService/Connectors.ReadPipelineRun, ConnectorRegistryService/Connectors.ReadPullRequest, ConnectorRegistryService/Connectors.ReadPackageFeed and ConnectorRegistryService/Connectors.ReadContainerRegistry are hosted, a path of ReplayDelivery answers 404 over REST and Connectors.Deliver UNIMPLEMENTED over gRPC, and the test fails when an operation outside the scope of model/backlog/features/integration.yaml appears (ADR-0022). |
| AC3 | Given the connector-registry messaging profile and the webhook-gateway messaging profile, when their registrations are inspected, then the registry registers WebhookGatewayService/InboundDeliveryVerified as its one consumed event with idempotency on the event id and publishes ConnectorRegistryService/ConnectorActivated, ConnectorRegistryService/ConnectorSubscriptionChanged and ConnectorRegistryService/DeliveryReceived under the run event envelope, the gateway publishes WebhookGatewayService/InboundDeliveryVerified and WebhookGatewayService/InboundDeliveryRejected and consumes ConnectorRegistryService/ConnectorSubscriptionChanged only, and no other event of the model is declared by either (ADR-0012, docs/reference/schemas/run-event-envelope.schema.json). |
| AC4 | Given the gateway deployed, when WebhookGatewayService/WebhookHealth is probed, then liveness answers while the process runs and readiness answers 200 only while webhook-gateway-sql is migrated, the cache answers and ArtifactService and SecretBrokerService answer, and 503 with a problem response naming the dependency otherwise, while an outage of the transport to ConnectorRegistryService leaves readiness up because verified deliveries wait in the outbox (SCN-WebhookGatewayService-002, ADR-0017). |
| AC5 | Given the captured logs, activities and metrics of the acceptance suites of both repositories, when they are scanned, then none holds a payload, a signature, a signing secret, a credential or a credential reference, and the deployment manifest of the gateway names the topologies saas-default and hybrid, one to eight replicas, the port 7950, OrleansMessaging:ServiceName set to webhook-gateway and the secrets messaging-transport and webhook-signing-secrets by name and never by value (ADR-0019, ADR-0017, ADR-0028, model/services/integration/WebhookGatewayService.yaml). |
| Traces: services | ConnectorRegistryService, WebhookGatewayService |
| Traces: aggregates | ConnectorRegistryService/Subscription, ConnectorRegistryService/Delivery, WebhookGatewayService/InboundDelivery |
| Traces: apis | ConnectorRegistryService/ListConnectors, ConnectorRegistryService/CertifyConnector, ConnectorRegistryService/CreateSubscription, ConnectorRegistryService/ListDeliveries, ConnectorRegistryService/Connectors.ResolveCapability, ConnectorRegistryService/Connectors.ReadPipelineRun, ConnectorRegistryService/Connectors.ReadPullRequest, ConnectorRegistryService/Connectors.ReadPackageFeed, ConnectorRegistryService/Connectors.ReadContainerRegistry, WebhookGatewayService/ReceiveWebhook, WebhookGatewayService/WebhookHealth |
| Traces: events | ConnectorRegistryService/ConnectorActivated, ConnectorRegistryService/ConnectorSubscriptionChanged, ConnectorRegistryService/DeliveryReceived, WebhookGatewayService/InboundDeliveryVerified, WebhookGatewayService/InboundDeliveryRejected |
| Traces: scenarios | SCN-WebhookGatewayService-002 |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0015, ADR-0017, ADR-0019, ADR-0022, ADR-0028 |
| Traces: requirements | FR-05, NFR-18, XL-16 |
| Depends on | AIFACTORY-US-1477, AIFACTORY-US-1478, AIFACTORY-US-1479, AIFACTORY-US-1480, AIFACTORY-US-1481, AIFACTORY-US-1483, feature:connector-registry-service-thin, feature:integration-service-thin, feature:repository-and-pipeline-conventions, feature:component-api-gateway-template, feature:contracts-package, feature:component-observability-factory-conventions |
| Sources | model/backlog/features/integration.yaml, model/services/integration/ConnectorRegistryService.yaml, model/services/integration/WebhookGatewayService.yaml, model/template-parameters/connectsoft-apigateway.yaml, model/libraries.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0017-deployment-profiles.md, docs/planes/capability-tools/connectors/workflows.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-6001 Create the WebhookGatewayService repository, scaffold it from the API gateway template with its persistence and actor choices named and host its two operations |
implementation | The repository exists by the steps of the repository checklist of feature repository-and-pipeline-conventions; its first commit is the unchanged output of dotnet new connectsoft-apigateway -n ConnectSoft.AI.SoftwareFactory.WebhookGatewayService --UseFactoryProfile true --GatewayRole BackendForFrontend --persistence-model-type NHibernate --nhibernate-dialect-type SqlServer --migrations true --database-name WebhookGateway --actor-model-type Orleans from the pinned template package, whose version the repository records; the one exemption file names the InboundDelivery aggregate, the IngressEntry projection, their mappings, the migrations of InboundDeliveries and IngressEntries, the outbox publisher of InboundDeliveryVerified and InboundDeliveryRejected and the inbox handler RefreshIngressTable, each with its reason; ReceiveWebhook is public on GW-06 without a token and WebhookHealth internal under factory.health.read with liveness and readiness over webhook-gateway-sql, the cache, ArtifactService and SecretBrokerService; the deployment manifest states container apps, the replica range 1 to 8, the port https 7950, the topologies saas-default and hybrid, the secrets messaging-transport and webhook-signing-secrets by reference and Integration:Webhooks:MaxPayloadKb, ReplayWindowMinutes and RatePerMinutePerIngress at their modelled defaults; the two metrics of the model are registered through the pinned observability library. |
ConnectSoft.AI.SoftwareFactory.WebhookGatewayService |
AIFACTORY-TASK-6035 Add the pinned Orleans messaging profile library to WebhookGatewayService with the messaging service name webhook-gateway |
implementation | The pinned connectsoft-extensions-messaging-model-orleans package is referenced by version in the central package file; the OrleansMessaging section holds ServiceName webhook-gateway, the Outbox connection of webhook-gateway-sql, the subscription of ConnectorSubscriptionChanged and PublishedEvents with InboundDeliveryVerified and InboundDeliveryRejected routed to their topics; the outbox records carry the run event envelope of the pinned contracts package; the exemption file lists the outbox publisher and the inbox handler with their reasons; the transport credential is the secret messaging-transport by reference; a startup test fails when the section or a route is absent. |
ConnectSoft.AI.SoftwareFactory.WebhookGatewayService |
AIFACTORY-TASK-6002 Extend the surface of ConnectorRegistryService to I2: nine hosted operations, the consumed event and the three published events of the service |
implementation | The service descriptor file and the contract test of AIFACTORY-TASK-088 list CreateSubscription, ListDeliveries and the four reads beside the three operations of I1 and still answer 404 and UNIMPLEMENTED for ReplayDelivery and Connectors.Deliver; the connector-registry messaging profile registers InboundDeliveryVerified in its inbox with idempotency on the event id and publishes ConnectorActivated, ConnectorSubscriptionChanged and DeliveryReceived under the run event envelope of the pinned contracts package; the deployment manifest keeps Integration:Adapters:Enabled at azure-devops and sets Integration:Connectors:ReplayWindowMinutes at its modelled default; connectsoft.factory.integration.deliveries and connectsoft.factory.integration.subscriptions are registered with their modelled dimensions. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6003 Verify the hosting of WebhookGatewayService by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build in the pipeline of ConnectSoft.AI.SoftwareFactory.WebhookGatewayService and dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-WebhookGatewayService-002"; a run that discovers no test counts as a failure; the runs pass and prove AC1, the gateway half of AC3, AC4 and AC5 of AIFACTORY-US-1476, that is the scaffold with its named choices, the added messaging profile and the exemption file, the two published events and ConnectorSubscriptionChanged as the one consumed event, readiness with each dependency stopped and the transport stopped, the deployment manifest and the scan of logs, activities and metrics for payloads, signatures and secrets. |
ConnectSoft.AI.SoftwareFactory.WebhookGatewayService |
AIFACTORY-TASK-6004 Verify the I2 surface of ConnectorRegistryService by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build in the pipeline of ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService; a run that discovers no test counts as a failure; the runs pass and prove AC2 and the registry half of AC3 and AC5 of AIFACTORY-US-1476, that is exactly the nine hosted operations with the 404 and UNIMPLEMENTED of the two others, InboundDeliveryVerified as the one consumed event, the three published events and the scan of logs, activities and metrics for payloads, credentials and credential references. |
ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-US-1477: The Azure DevOps adapter of a new version declares the four read capabilities and the service-hook webhook scheme and is certified again¶
behavior · persona platform-admin
As a platform admin, I want the Azure DevOps connector to declare the reads and the webhook scheme the second outcome needs and to pass the conformance suite again before anything relies on them, so that no delivery is accepted and no read is served through a capability that has not proven itself against a sandbox connection.
The descriptor of I1 declares the repository capabilities, read a repository at a commit, push a branch and open a pull request, and the package feed capability, list the versions of a package (AIFACTORY-US-1001). The second outcome needs more of the same connector, and a connector without a webhook scheme accepts no inbound deliveries (invariant of the model). The Azure DevOps adapter of this feature is therefore a new version, still built on the first-party Azure DevOps client library (ext-client-libraries), that adds four capability interfaces: read one pipeline run with its stages and results, read one pull request with its review state, commits and merge commit, read whether a package version with its digest is in an Azure Artifacts feed, and read whether an image with its digest is in a container registry reached through the Azure DevOps connection. It declares the webhook scheme of the Azure DevOps service hooks, which the model defines as signature algorithm, header, replay window and deduplication key: the header that carries the signature, the signature algorithm, the payload member that carries the event time checked against the replay window, the replay window itself, the member that carries the delivery identifier used as the deduplication key, the member that carries the event type, and the service-hook event types the adapter accepts, a push, a pull request update, a review, a merge and a completed pipeline run. The scheme holds no secret and no secret reference: the descriptor belongs to the platform tenant and every tenant reads it (AIFACTORY-US-1001), so a signing secret in it would be one secret for the ingress identities of every tenant. The signing secret belongs to the connection of a tenant and is registered with the broker under owner kind webhook-scheme (AIFACTORY-US-1478, AIFACTORY-TASK-6007). The model fixes none of the scheme values for Azure DevOps; they come from the adapter, no value is fixed elsewhere in code, and they are reported to the owner. A changed adapter version re-runs certification (invariant of the model), so at startup the service writes, as AIFACTORY-US-1001 does, a new descriptor version of the platform tenant in state Draft with the new capabilities and the scheme, and the earlier version keeps its state Active, because the Deprecate transition arrives in I5. Where two versions are Active, the four reads, Connectors.ResolveCapability of I1 and CreateSubscription take the highest Active version that declares the capability or the scheme; ConnectorActivated names the new version and ToolAdapterService handles it in its own feature. A Platform admin of the platform tenant certifies the new version through ConnectorRegistryService/CertifyConnector exactly as AIFACTORY-US-1002 describes, against the sandbox project whose sandbox Azure DevOps organization holds a pipeline run, a pull request, a feed package and a registry image, and the conformance suite of this version exercises the four reads as well; on a passing suite the version moves from Draft through Certified to Active with ConnectorActivated, and on a failing one it stays Draft while the earlier version keeps serving. The runbook names that call and its evidence. Until the version is Active, the four reads answer NOT_FOUND, CreateSubscription answers 409 and the ingress has no scheme to verify against.
Acceptance criteria
| AC1 | Given the Active Azure DevOps descriptor of I1 and the build carrying the adapter of the new version, when the service starts twice, then one new ConnectorRegistryService/ConnectorDescriptor version of the platform tenant exists in state Draft with the four read capabilities beside the earlier ones and the webhook scheme of the service hooks, the second start wrote no row, and the earlier version is still Active (model/services/integration/ConnectorRegistryService.yaml). |
| AC2 | Given the Draft descriptor of the new version and a sandbox Azure DevOps system that holds a pipeline run, a pull request, a feed package and a registry image, when a Platform admin of the platform tenant calls ConnectorRegistryService/CertifyConnector for that version, then the conformance suite exercises every capability including the four reads, the version moves to Active with its certificationRef and ConnectorRegistryService/ConnectorActivated is written in the same transaction; given one read capability failing, the version stays Draft and the earlier version keeps serving; given both versions Active, then ConnectorRegistryService/Connectors.ResolveCapability resolves a capability to the highest Active version that declares it (ADR-0022). |
| AC3 | Given the written descriptor, when ConnectorRegistryService/ListConnectors returns it, then its webhook scheme names the signature header, the signature algorithm, the event-time member, the replay window, the deduplication-key member, the event-type member and the accepted event types, and holds neither a secret value nor a secret reference, and a test fails when a scheme value is fixed anywhere in code outside the adapter or when a scheme carries a secret reference (model/services/integration/ConnectorRegistryService.yaml, model/services/governance/SecretBrokerService.yaml). |
| Traces: services | ConnectorRegistryService |
| Traces: aggregates | ConnectorRegistryService/ConnectorDescriptor |
| Traces: apis | ConnectorRegistryService/ListConnectors, ConnectorRegistryService/CertifyConnector, ConnectorRegistryService/Connectors.ResolveCapability |
| Traces: events | ConnectorRegistryService/ConnectorActivated |
| Traces: adrs | ADR-0022 |
| Traces: requirements | FR-05, NFR-05 |
| Depends on | feature:connector-registry-service-thin |
| Sources | model/services/integration/ConnectorRegistryService.yaml, model/externals.yaml, docs/planes/capability-tools/connectors/workflows.md, docs/planes/capability-tools/connectors/services/connector-registry-service/index.md#domain-model |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-6005 Azure DevOps adapter of the new version with the four read capabilities and the service-hook webhook scheme without a secret reference |
implementation | The adapter wraps the first-party Azure DevOps client library behind the capability interfaces of I1 and the four reads of pipeline runs, pull requests, package versions with digests and container images with digests, declares the webhook scheme with its signature header, signature algorithm, event-time member, replay window, deduplication-key member, event-type member and accepted event types and with no secret or secret reference, writes its new descriptor version in Draft at startup idempotently on connectorId and version, holds no credential and receives one per call; the lookup of an Active descriptor takes the highest Active version that declares the capability or the scheme; no scheme value is fixed outside the adapter and a test fails when one is or when a scheme carries a secret reference. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6006 Extend the sandbox Azure DevOps stub of AIFACTORY-TASK-4036 with pipeline runs, pull requests, feed packages and registry images |
fixture | The recording stub of the sandbox Azure DevOps system answers the four reads with a pipeline run with stages and results, a pull request with review state, commits and merge commit, a feed package version with its digest and a registry image with its digest, can be made to fail one capability or to stop answering, and the conformance suite of the new adapter version exercises the four reads against it. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6007 Runbook to certify the new descriptor version, register the signing secret of a connection and subscribe a project on a deployed I2 instance |
documentation | The repository documentation extends the runbook of AIFACTORY-TASK-4069 in three steps. First, a Platform admin of the platform tenant calls CertifyConnector with an Idempotency-Key and the projectId of the sandbox project for the new version, whose sandbox organization must hold a pipeline run, a pull request, a feed package and a registry image; the evidence of success is ListConnectors answering 200 with the new version Active beside the earlier one and its ConnectorActivated record in the outbox. Second, for each Azure DevOps connection of a tenant that will receive service hooks, a Platform admin registers through RegisterSecretReference of SecretBrokerService a reference of kind SigningKey in the tenant of the connection, with owner kind webhook-scheme, the connectionId as owner, the allowed purpose delivery that the gateway asks, and the rotation of the model secret webhook-signing-secrets; the value is placed in Key Vault and in the service hook by the admin and never in the runbook. Third, a Workspace admin of the project calls CreateSubscription with an Idempotency-Key, the projectId, the connector and the event types, and configures the Azure DevOps service hooks of the project with the ingress path the 201 reply returns and the signing secret of the connection; the evidence is a delivery recorded with outcome Verified at the gateway and a DeliveryReceived record in the outbox of the registry. It states that the platform bundle allows a credential issuance of the purpose delivery only for the service identities of ConnectorRegistryService and WebhookGatewayService (D139), which covers the certification, the four Azure DevOps reads and the signing secret of the gateway, and that the same purpose asked by any other subject is denied, and it holds no token, credential, reference value or limit. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6008 Verify the adapter of the new version and its certification through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Feature=AzureDevOpsAdapterNextVersion"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1477: two starts with one new Draft version and the earlier version still Active, the passing certification with ConnectorActivated, a failing read capability with the version in Draft, the resolution to the highest Active version, the webhook scheme in the listed descriptor without a secret value or a secret reference and the test that fails on a scheme value fixed outside the adapter; the runbook of AIFACTORY-TASK-6007 is present with its three steps. |
ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-US-1478: Receive an Azure DevOps service hook, verify it with the signing secret of the connection of its tenant, capture its payload and announce InboundDeliveryVerified¶
behavior · persona operator
As an operator, I want every Azure DevOps service hook of a project to be verified at the ingress with the signing secret of its own tenant and handed to the connector registry exactly once, so that a review, a merge or a pipeline run reaches the delivery services from a delivery whose origin is proven and whose payload is kept by hash.
Azure DevOps posts a service hook of a project to WebhookGatewayService/ReceiveWebhook at /webhooks/{ingressRef}, the ingress identity of the subscription. The route is public on GW-06 and takes no token: the signature is the authentication (scope factory.webhooks.receive), and the tenant, the subscription and the connector come from the ingress entry, never from the body or a header. The ingress entries are written by the handler RefreshIngressTable from ConnectorSubscriptionChanged into the table IngressEntries of webhook-gateway-sql (AIFACTORY-US-1483); each names the ingress identity, the tenant, the subscription, the connector and the connection of the subscription, the descriptor version whose webhook scheme verifies it and that scheme (AIFACTORY-US-1477), and whether it is active. The model gives ConnectorSubscriptionChanged only subscriptionId, tenantId, connectorId and active and lists no dependency of the gateway through which it could read the rest, so the event carries the ingress identity, the connection, the descriptor version and the scheme as well, and the gateway keeps them in a table, although the model says it is stateless beyond the deduplication cache; both are model gaps reported to the owner. The signing secret belongs to the connection of the tenant of the entry, never to the shared descriptor: the gateway asks SecretBrokerService/SecretBroker.Issue for the reference of owner kind webhook-scheme whose owner is that connection, in the tenant of the entry, so a delivery signed with the secret of tenant A never verifies at an ingress identity of tenant B. The broker is addressed by owner and no reference value travels in an event or an entry, a reading of the request of SecretBroker.Issue reported to the owner. The gateway holds the secret in memory until the issuance expires and never in the cache, the store, a log record or telemetry. The gateway asks with the purpose delivery, the purpose of the deliveries of the connector, which the platform bundle allows only for the service identities of ConnectorRegistryService and WebhookGatewayService (D139). The model gives ReceiveWebhook the idempotency key-header; a vendor-sent hook carries no such header, so the delivery identifier that the scheme reads from the body stands in for it, a reading reported to the owner. The replay window is the window of the scheme bounded above by Integration:Webhooks:ReplayWindowMinutes, so the smaller of the two applies, a reading reported to the owner. The gateway applies its checks in the order this PBI states: the ingress identity is known and active, the identity has not exceeded Integration:Webhooks:RatePerMinutePerIngress deliveries in the current minute across the replicas, the body is within Integration:Webhooks:MaxPayloadKb, the signature verifies under the scheme with the signing secret of the connection, the body carries the event time, the event type and the delivery identifier the scheme names, the event time lies inside the replay window, and the delivery identifier is not already held; the refusals are AIFACTORY-US-1479. Deduplication follows the signature check, so an unsigned body never learns an inboundId, and the rate limit precedes it, so a vendor retry of an accepted delivery that arrives over the limit is answered 429 and answered 202 with the same inboundId when the vendor retries it inside the window. A delivery whose deduplication key the cache already holds inside the window is the repeat of an accepted one: the answer is 202 with the same inboundId, and nothing is captured, recorded or published again. A new delivery is captured by hash through ArtifactService/Artifacts.Store under the tenant of the ingress entry, idempotent on tenant and hash; the InboundDelivery is recorded with signatureValid true, outcome Verified, dedupKey, externalId, payloadRef and payloadHash, and the InboundDeliveryVerified outbox record is written in the same transaction; the answer is 202 with the inboundId. The dispatcher publishes the event on connectors.ingress.v1.inbound-delivery-verified under the run event envelope with inboundId, tenantId, subscriptionId, connectorId, externalId, dedupKey, payloadRef and payloadHash and never the payload, and retries a transport outage with backoff so the event is neither lost nor duplicated; ConnectorRegistryService records it (AIFACTORY-US-1480). ArtifactService, SecretBrokerService, the cache and webhook-gateway-sql are required and fail-fast: when one does not answer, the answer is 503 with a problem response naming it (D137). When SecretBrokerService answers but refuses the issuance, PERMISSION_DENIED or FAILED_PRECONDITION, the answer is 503 with the reason credential-refused, counted with the outcome dimension value CredentialRefused, so that a refusal is told apart from an outage; D137 speaks of an unavailable dependency, and answering a refusal with 503 so the vendor retries is a reading reported to the owner. In each case nothing is recorded or published and Azure DevOps retries the service hook. The scheduled purge deletes rows of InboundDeliveries older than their modelled retention of 30 days; the model names no worker for it, which is reported. The counter connectsoft.factory.integration.webhooks_received counts each delivery by connector and outcome and the histogram connectsoft.factory.integration.webhook_latency records the verification latency.
Acceptance criteria
| AC1 | Given an active ingress entry of tenant A with the Active Azure DevOps scheme and the connection C of tenant A, and a service hook whose signature verifies with the secret issued through SecretBrokerService/SecretBroker.Issue for the reference of owner kind webhook-scheme owned by C and whose event time lies inside the replay window, when WebhookGatewayService/ReceiveWebhook is called without a token, then the response is 202 with the inboundId, the payload is captured through ArtifactService/Artifacts.Store under tenant A, and the WebhookGatewayService/InboundDelivery with outcome Verified and the WebhookGatewayService/InboundDeliveryVerified outbox record are written in the same transaction (SCN-WebhookGatewayService-001). |
| AC2 | Given the same service hook repeated with the same deduplication key inside the replay window, when it arrives at WebhookGatewayService/ReceiveWebhook, then the response is 202 with the same inboundId, and nothing is captured, recorded or published a second time; given the repeat arriving over the rate limit, then it is answered 429 and the next retry inside the window 202 with the same inboundId; given a scheme window larger than Integration:Webhooks:ReplayWindowMinutes, then the option bounds it; given a body or header that names another tenant, then the delivery is recorded under the tenant of the ingress entry only (SCN-WebhookGatewayService-001, ADR-0015). |
| AC3 | Given ArtifactService, SecretBrokerService, the cache or webhook-gateway-sql that does not answer, when a valid service hook arrives, then the response is 503 with a problem response naming the dependency; given SecretBrokerService refusing the issuance, then the response is 503 with the reason credential-refused and the counter records CredentialRefused; in each case no WebhookGatewayService/InboundDelivery is recorded, no event is written, and the signing secret appears in no cache entry, row, log record, activity or metric (SCN-WebhookGatewayService-001, ADR-0019). |
| AC4 | Given the recorded delivery, when the outbox dispatcher publishes WebhookGatewayService/InboundDeliveryVerified on connectors.ingress.v1.inbound-delivery-verified, then the event is sent under the run event envelope with inboundId, tenantId, subscriptionId, connectorId, externalId, dedupKey, payloadRef and payloadHash and without the payload, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-WebhookGatewayService-003, ADR-0012). |
| AC5 | Given rows of InboundDeliveries older and younger than the retention of 30 days, when the scheduled purge of the gateway runs, then only the older rows are deleted, a second run deletes nothing more, and no ingress entry is touched (model/services/integration/WebhookGatewayService.yaml, ADR-0019). |
| Traces: services | WebhookGatewayService, ArtifactService, SecretBrokerService |
| Traces: aggregates | WebhookGatewayService/InboundDelivery |
| Traces: apis | WebhookGatewayService/ReceiveWebhook, ArtifactService/Artifacts.Store, SecretBrokerService/SecretBroker.Issue |
| Traces: events | WebhookGatewayService/InboundDeliveryVerified |
| Traces: scenarios | SCN-WebhookGatewayService-001, SCN-WebhookGatewayService-003 |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0015, ADR-0019 |
| Traces: requirements | FR-05, NFR-02, NFR-09 |
| Depends on | AIFACTORY-US-1477, AIFACTORY-US-1483, feature:secret-broker-service, feature:artifact-service, feature:contracts-package |
| Sources | model/services/integration/WebhookGatewayService.yaml, model/services/governance/SecretBrokerService.yaml, model/services/knowledge/ArtifactService.yaml, docs/planes/capability-tools/connectors/services/webhook-gateway-service/index.md#apis, docs/planes/capability-tools/connectors/workflows.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-6009 Contract of ReceiveWebhook: OpenAPI document, problem responses and the shape of the ingress entry |
contract | The OpenAPI document fixes POST /webhooks/{ingressRef} without a security requirement, the 202 reply with the inboundId and the problem responses of 400, 401, 404, 409, 413, 429 and 503, the last with the reasons naming a dependency and credential-refused; the ingress entry names ingressRef, tenantId, subscriptionId, connectorId, connectionId, the descriptor version of the scheme, the scheme and active, as RefreshIngressTable writes it from ConnectorSubscriptionChanged, and holds no secret value and no secret reference; golden files hold the shapes and the payload of InboundDeliveryVerified under the run event envelope. | ConnectSoft.AI.SoftwareFactory.WebhookGatewayService |
AIFACTORY-TASK-6010 Verification pipeline of ReceiveWebhook with the signing secret of the connection, the deduplication cache, payload capture and the InboundDeliveryVerified outbox record |
implementation | ReceiveWebhook reads the ingress entry from IngressEntries and applies, in the order AIFACTORY-US-1478 states, the known and active ingress, the rate limit, the size limit, the signature check with the secret issued through SecretBroker.Issue for the reference of owner kind webhook-scheme owned by the connection of the entry in its tenant and held in memory until it expires, the body check, the replay window of the scheme bounded by Integration:Webhooks:ReplayWindowMinutes and the deduplication cache; it answers 202 with the same inboundId for a deduplication key the cache holds inside the window, captures a new payload through Artifacts.Store under the tenant of the entry, records the InboundDelivery as Verified with the InboundDeliveryVerified outbox record in one transaction, answers 503 naming an unavailable dependency and 503 with the reason credential-refused for a refused issuance, and logs and measures neither the payload, the signature nor the secret. | ConnectSoft.AI.SoftwareFactory.WebhookGatewayService |
AIFACTORY-TASK-6033 Scheduled purge of InboundDeliveries after the modelled retention of 30 days |
implementation | A scheduled job of the gateway deletes the rows of InboundDeliveries whose ReceivedAt is older than 30 days in batches, idempotently, touching no row of IngressEntries; its run and the number of rows it deleted are logged without a payload or a reference. | ConnectSoft.AI.SoftwareFactory.WebhookGatewayService |
AIFACTORY-TASK-6011 Fakes of Artifacts.Store and SecretBroker.Issue, fixture ingress entries of two tenants and signed recorded Azure DevOps service hooks |
fixture | The acceptance suite holds fakes of ArtifactService/Artifacts.Store and SecretBrokerService/SecretBroker.Issue that record their calls, issue a distinct test secret per tenant and connection, refuse with PERMISSION_DENIED and FAILED_PRECONDITION and can be stopped; fixture ingress entries of two tenants with distinct connections, in the shape RefreshIngressTable writes, inserted directly into the isolated test database; recorded Azure DevOps service hooks for a push, a pull request update, a review, a merge and a pipeline run signed with the test secret of each tenant under the scheme of the new adapter version; and variants with a wrong signature, a signature of the other tenant, an old event time, an oversized body and a missing delivery identifier. | ConnectSoft.AI.SoftwareFactory.WebhookGatewayService |
AIFACTORY-TASK-6012 Verify the accepted path of ReceiveWebhook, InboundDeliveryVerified and the purge through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-WebhookGatewayService-001\|Scenario=SCN-WebhookGatewayService-003)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-1478: the accepted service hook with its capture and outbox record, the repeat inside the window and the repeat over the rate limit, the scheme window bounded by the option, the tenant taken from the ingress entry, each dependency and the store stopped with the 503, the refused issuance with credential-refused, the publication under the run event envelope with retry, the purge of rows older than 30 days, and the scan of the cache, rows, logs, activities and metrics for the secret and the payload. |
ConnectSoft.AI.SoftwareFactory.WebhookGatewayService |
AIFACTORY-US-1479: Reject a webhook that fails a check of the ingress with its outcome, rate-limit an ingress identity and announce InboundDeliveryRejected¶
behavior · persona operator
As an operator, I want every delivery that fails a check of the ingress to be refused with its outcome and recorded as evidence, so that a rotated signing secret, a delivery signed for another tenant, a replayed delivery or a flood is visible and audited, and nothing unverified reaches the connector registry.
Every check of WebhookGatewayService/ReceiveWebhook that fails refuses the delivery before its payload is captured or forwarded, so no payload of a rejected delivery is dispatched or stored (invariant of the model). An unknown or inactive ingressRef is answered 404; the delivery has no tenant, so it is counted with outcome UnknownIngress and nothing is recorded or published. For a known ingress identity, in the order of AIFACTORY-US-1478, a delivery beyond Integration:Webhooks:RatePerMinutePerIngress in the current minute is answered 429 with outcome RateLimited, a body over Integration:Webhooks:MaxPayloadKb 413 with outcome Oversized, a signature that does not verify with the signing secret of the connection of the ingress entry 401 with outcome BadSignature and signatureValid false, and an event time outside the replay window 409 with outcome Replayed; each is recorded as an InboundDelivery under the tenant of the ingress entry with its outcome, without payloadRef or payloadHash, together with the InboundDeliveryRejected outbox record in the same transaction. A delivery signed with the signing secret of tenant A and posted to an ingress identity of tenant B does not verify, because the gateway checks it with the secret of the connection of tenant B, and is answered 401 with outcome BadSignature under tenant B. A body that fails validation, unparseable or without the event time, the event type or the delivery identifier the scheme names, is answered 400; the enum VerificationOutcome has no value for it, so it is counted with the outcome dimension value Invalid, a value outside the enum, and nothing is recorded or published, an open point reported to the owner. Every refusal carries a problem response that names the check and never echoes the payload or the signature. The dispatcher publishes InboundDeliveryRejected on connectors.ingress.v1.inbound-delivery-rejected under the run event envelope with inboundId, tenantId, ingressRef and outcome, retrying a transport outage with backoff so the event is neither lost nor duplicated; AuditService records it in its own suite. Two failure modes of the model show here: a signing secret rotated at the vendor raises the BadSignature rate of one connector, deliveries are rejected until the reference of the connection is rotated through the broker and Azure DevOps retries them, and an ingress flood is held by the per-ingress limit, the vendor backs off and no accepted delivery loses its payload. The counter connectsoft.factory.integration.webhooks_received counts every refusal by connector and outcome.
Acceptance criteria
| AC1 | Given a known ingress identity, when WebhookGatewayService/ReceiveWebhook receives a delivery with a signature that does not verify, an event time outside the replay window, a body over the size limit, or more deliveries in a minute than the rate limit, then the response is 401, 409, 413 or 429 with a problem response, the WebhookGatewayService/InboundDelivery is recorded with outcome BadSignature, Replayed, Oversized or RateLimited and no payload reference, and the WebhookGatewayService/InboundDeliveryRejected outbox record is written in the same transaction; given a delivery signed with the secret of tenant A at an ingress identity of tenant B, then the response is 401 with outcome BadSignature recorded under tenant B and nothing is captured (SCN-WebhookGatewayService-004, ADR-0015). |
| AC2 | Given an unknown or inactive ingressRef, or a body that fails validation at a known ingress identity, when WebhookGatewayService/ReceiveWebhook is called, then the response is 404 or 400 with a problem response, nothing is captured, recorded or published, and connectsoft.factory.integration.webhooks_received counts the delivery with UnknownIngress or Invalid (SCN-WebhookGatewayService-004, model/services/integration/WebhookGatewayService.yaml). |
| AC3 | Given a rejection recorded, when the outbox dispatcher publishes WebhookGatewayService/InboundDeliveryRejected on connectors.ingress.v1.inbound-delivery-rejected, then the event is sent under the run event envelope with inboundId, tenantId, ingressRef and outcome and nothing of the payload, and a transport outage is retried with backoff so the event is neither lost nor duplicated (SCN-WebhookGatewayService-004, ADR-0012). |
| AC4 | Given a flood at one ingress identity while another identity receives its normal deliveries, when the limit of the first is reached, then only the first is answered 429, every delivery accepted before the limit keeps its captured payload and its WebhookGatewayService/InboundDeliveryVerified record, and the second identity is not limited (SCN-WebhookGatewayService-004, NFR-09). |
| Traces: services | WebhookGatewayService |
| Traces: aggregates | WebhookGatewayService/InboundDelivery |
| Traces: apis | WebhookGatewayService/ReceiveWebhook |
| Traces: events | WebhookGatewayService/InboundDeliveryRejected, WebhookGatewayService/InboundDeliveryVerified |
| Traces: scenarios | SCN-WebhookGatewayService-004 |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0015, ADR-0019 |
| Traces: requirements | NFR-09, XL-16 |
| Depends on | AIFACTORY-US-1478 |
| Sources | model/services/integration/WebhookGatewayService.yaml, docs/planes/capability-tools/connectors/services/webhook-gateway-service/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-6013 Refusals of ReceiveWebhook with their outcomes, the per-ingress rate limit and the InboundDeliveryRejected outbox record |
implementation | ReceiveWebhook answers 404 for an unknown or inactive ingress and 400 for an invalid body without a row or an event, answers 429, 413, 401 and 409 for a known ingress with the outcomes RateLimited, Oversized, BadSignature and Replayed recorded under the tenant of the ingress entry without a payload reference together with the InboundDeliveryRejected outbox record in one transaction, verifies every signature with the secret of the connection of the entry only, applies Integration:Webhooks:RatePerMinutePerIngress per ingress identity across the replicas through the pinned rate-limiting library, counts the unrecorded refusals with UnknownIngress and Invalid, and names the failed check in each problem response without the payload or the signature. | ConnectSoft.AI.SoftwareFactory.WebhookGatewayService |
AIFACTORY-TASK-6014 Verify the refusals and InboundDeliveryRejected through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-WebhookGatewayService-004"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1479 with the fixtures of AIFACTORY-TASK-6011: the four recorded outcomes with their outbox records, the delivery signed for tenant A at the ingress of tenant B answered 401, the unknown ingress and the invalid body without a row, the publication under the run event envelope with retry, and a flood at one ingress identity beside a second one with no accepted payload lost. |
ConnectSoft.AI.SoftwareFactory.WebhookGatewayService |
AIFACTORY-US-1480: Record a verified Azure DevOps delivery once, deduplicated on its key, and announce DeliveryReceived in the same transaction¶
behavior · persona operator
As an operator, I want each verified Azure DevOps delivery to be recorded once as an inbound delivery and announced to the services that act on it, so that pushes, review states, merges and pipeline runs reach PipelineExecutionService without a duplicate and without a delivery that the subscription does not admit.
The inbox of the connector-registry messaging profile consumes WebhookGatewayService/InboundDeliveryVerified with the handler RecordAndDispatch, idempotent on the event id, run by the worker InboundDispatcher with its modelled retry, exponential with five attempts and a backoff of 30 seconds, its idempotency key dedupKey and at most eight in parallel partitioned by SubscriptionId. The handler reads the Subscription that the event names under the tenant of the event; a subscription that does not exist in that tenant, as one of another tenant is under the row filter, records nothing, because a Delivery needs the connection of its subscription, and is counted. It fetches the captured payload through ArtifactService/Artifacts.Fetch by payloadRef and checks it against payloadHash, and reads the event type through the event-type member of the webhook scheme. When the subscription is active, the event type is one of its eventTypes, the connector has an Active Azure DevOps descriptor with a webhook scheme and the hash matches, it records an inbound Delivery with connectorId, connectionId of the subscription, subscriptionId, externalId, dedupKey, payloadRef, payloadHash and receivedAt, written in Received and moved to Verified (SignatureAndReplayChecked, the check the event announces), and writes the DeliveryReceived outbox record in the same transaction (invariant of the model, D135). Otherwise the delivery is recorded and moved from Received to Rejected (VerificationFailed) and nothing is published. Deduplication follows one rule. The unique index UX_Deliveries_Dedup holds one row per tenant, connector and dedupKey with no window, while the model speaks of the same key within Integration:Connectors:ReplayWindowMinutes. A verified delivery whose key already has a row for the tenant and connector is a duplicate, whether it arrives inside or after that window, as long as the earlier row is kept: no second row is written, nothing is published, the counter records the state Deduplicated, and the inbox message completes, so a repeated key never spends the five attempts. The handler checks for the row before it writes, and a violation of the unique index by a concurrent handler is treated the same way. The option therefore has no effect of its own in I2, and the conflict between the index and the window stays reported to the owner. The dispatcher publishes DeliveryReceived on connectors.deliveries.v1.delivery-received under the run event envelope with deliveryId, tenantId, connectorId, subscriptionId, eventType and payloadHash, never the payload or a credential, and retries a transport outage with backoff, so the event is neither lost nor duplicated (ADR-0012); PipelineExecutionService (ApplyDelivery) and KnowledgeIngestionService (IngestOnDelivery) handle it in their own suites (D140). ArtifactService and connector-registry-sql are required: when one does not answer, the handler fails and the inbox retries it; when the five attempts are spent the message stays failed with its reason, nothing is recorded or published, and the consumers reconcile from the system of record through the reads of AIFACTORY-US-1481. Dispatch of a delivery to the target of its subscription, with Dispatched, Acknowledged, Failed and Replayed, arrives in I5, so no inbound delivery of I2 carries a receiptRef. The event carries neither payloadRef nor the project, an open point reported to the owner. The counter connectsoft.factory.integration.deliveries counts each outcome by tenant, connector, direction and state. The tables Deliveries and Subscriptions are created together as modelled by AIFACTORY-TASK-6015 of AIFACTORY-US-1483, because the foreign key of Deliveries names Subscriptions; CreateSubscription writes the subscriptions, and this suite inserts fixture subscriptions directly into the isolated test database. A scheduled purge deletes rows of Deliveries older than their modelled retention of 90 days and spares every row whose ReceiptRef is set, the receipts that audit evidence references for seven years; the model names no worker for it, which is reported. After a purge a repeated key is recorded again as a new delivery.
Acceptance criteria
| AC1 | Given a ConnectorRegistryService/Subscription of tenant A that is active for the event type of a captured pull-request delivery and the Active Azure DevOps descriptor with its webhook scheme, when WebhookGatewayService/InboundDeliveryVerified arrives, then one inbound ConnectorRegistryService/Delivery exists in state Verified with the connection of the subscription, and the ConnectorRegistryService/DeliveryReceived outbox record is written in the same transaction (SCN-ConnectorRegistryService-011, D135). |
| AC2 | Given the same event delivered twice, or a second verified delivery with the same dedupKey for the same tenant and connector inside or after Integration:Connectors:ReplayWindowMinutes while the earlier row is kept, or two such deliveries handled concurrently, when it is handled, then no second ConnectorRegistryService/Delivery exists, nothing more is published, connectsoft.factory.integration.deliveries records the state Deduplicated and the inbox message completes without a retry; given an inactive subscription, an event type outside its eventTypes, a connector without an Active descriptor with a webhook scheme or a payload whose hash does not match, then the delivery is recorded Rejected and no ConnectorRegistryService/DeliveryReceived is written (SCN-ConnectorRegistryService-011). |
| AC3 | Given an event that names a subscription of tenant B while its tenant is A, or a subscription that does not exist, when it is handled, then nothing is recorded or published and the subscription of tenant B is never read; given ArtifactService/Artifacts.Fetch or connector-registry-sql unavailable, then the inbox retries five times with exponential backoff, and when the attempts are spent the message stays failed with its reason and nothing is recorded or published (SCN-ConnectorRegistryService-011, ADR-0015). |
| AC4 | Given the delivery recorded, when the outbox dispatcher of the connector-registry profile publishes ConnectorRegistryService/DeliveryReceived on connectors.deliveries.v1.delivery-received, then the event is sent under the run event envelope with deliveryId, tenantId, connectorId, subscriptionId, eventType and payloadHash and without the payload, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ConnectorRegistryService-011, ADR-0012). |
| AC5 | Given rows of Deliveries older and younger than the retention of 90 days, one older row with a ReceiptRef, when the scheduled purge of the registry runs, then only the older rows without a receipt are deleted, a second run deletes nothing more, and a key of a purged row is recorded again as a new ConnectorRegistryService/Delivery (model/services/integration/ConnectorRegistryService.yaml, ADR-0019). |
| Traces: services | ConnectorRegistryService, WebhookGatewayService, ArtifactService |
| Traces: aggregates | ConnectorRegistryService/Delivery, ConnectorRegistryService/Subscription |
| Traces: apis | ArtifactService/Artifacts.Fetch |
| Traces: events | WebhookGatewayService/InboundDeliveryVerified, ConnectorRegistryService/DeliveryReceived |
| Traces: scenarios | SCN-ConnectorRegistryService-011 |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0015, ADR-0019 |
| Traces: requirements | FR-05, NFR-05, XL-10 |
| Depends on | AIFACTORY-US-1477, AIFACTORY-US-1478, AIFACTORY-US-1483, feature:artifact-service, feature:contracts-package |
| Sources | model/services/integration/ConnectorRegistryService.yaml, model/services/devops-gitops/PipelineExecutionService.yaml, docs/planes/capability-tools/connectors/services/connector-registry-service/index.md#workers-and-jobs, docs/planes/capability-tools/connectors/workflows.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-6016 RecordAndDispatch on InboundDeliveryVerified with one deduplication rule, the Rejected path and the DeliveryReceived outbox record |
implementation | The handler RecordAndDispatch, run by InboundDispatcher with exponential retry of five attempts, a backoff of 30 seconds, the idempotency key dedupKey and eight in parallel by SubscriptionId, reads the subscription under the tenant of the event, fetches the payload through Artifacts.Fetch and checks its hash, reads the event type through the scheme, records the inbound Delivery in Verified with the DeliveryReceived outbox record in one transaction, records Rejected for an inactive subscription, an event type outside the subscription, a connector without an Active descriptor with a scheme or a hash mismatch, writes nothing for an unknown subscription, and for a key that already has a row for the tenant and connector, inside or after the window, or a violation of UX_Deliveries_Dedup by a concurrent handler, writes and publishes nothing, records the state Deduplicated and completes the message; connectsoft.factory.integration.deliveries is recorded by tenant, connector, direction and state. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6034 Scheduled purge of Deliveries after the modelled retention of 90 days, sparing rows with a receipt |
implementation | A scheduled job of the registry deletes the rows of Deliveries whose ReceivedAt is older than 90 days and whose ReceiptRef is not set, in batches and idempotently, under the tenant row filter of each tenant it purges, and logs its run and the number of rows it deleted without a payload or a reference. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6017 Fixture subscriptions, recorded InboundDeliveryVerified events and the fake of Artifacts.Fetch |
fixture | The acceptance suite holds fixture subscriptions of two tenants inserted directly into the isolated test database, active and inactive, recorded InboundDeliveryVerified events for a push, a pull request update, a review, a merge and a pipeline run, a fake of ArtifactService/Artifacts.Fetch that serves the captured payloads, can serve a payload with another hash and can be stopped, fixture delivery rows older and younger than 90 days with and without a receipt, and a stoppable transport for the outbox. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6018 Verify the recording of verified deliveries, DeliveryReceived and the purge through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ConnectorRegistryService-011"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-1480: the Verified delivery with its outbox record, the repeated event, the repeated key inside and after the window and the concurrent pair with the message completed, the four Rejected cases, the subscription of another tenant and the unknown one, the stopped fetch and store with the spent retries, the publication under the run event envelope with retry, and the purge that spares young rows and rows with a receipt. |
ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-US-1481: Read an Azure DevOps pipeline run, pull request, package version or container image through the connection of the project for PipelineExecutionService and ReleaseService¶
behavior · persona operator
As an operator, I want the delivery and release services to read a pipeline run, a pull request, a package version or an image from Azure DevOps through the governed connection of the project, so that a missed delivery is never assumed, the state of a run or a proposal always comes from the system of record, and a release cites publication evidence that was read and never assumed.
PipelineExecutionService calls ConnectorRegistryService/Connectors.ReadPipelineRun and ConnectorRegistryService/Connectors.ReadPullRequest when a delivery names a run or a pull request it does not know and for reconciliation, from its DeliveryApplier and RunReconciler workers. ReleaseService calls ConnectorRegistryService/Connectors.ReadPackageFeed to read whether a package version with its digest is in an Azure Artifacts feed, and ConnectorRegistryService/Connectors.ReadContainerRegistry to read whether an image with its digest is in a container registry reached through the Azure DevOps connection of the project, as publication evidence. The four methods share one path. The caller presents a workload token that holds factory.connections.read, the scope of the four methods (D135), and forwards its tenant and project in the gRPC metadata; such a token carries no tenant claim, so the service reads the forwarded scope only under that scope (ADR-0015 amendment D114). The request names the execution scope and what to read: the run or the pull request in Azure DevOps, the feed, package and version, or the registry, repository and digest. The service takes the highest Active Azure DevOps descriptor that declares the capability among those of the platform tenant and the forwarded tenant (AIFACTORY-US-1477), resolves the connection of the forwarded project through IntegrationService/Connections.Resolve, which checks the Project grant, exchanges the broker ticket through SecretBrokerService/SecretBroker.Issue for a short-lived credential of the purpose delivery and calls Azure DevOps through the adapter, the credential in memory for the call only. delivery is the purpose the model gives the credentials of this service and the one the certification uses (D129), and the platform bundle allows it only for the service identities of ConnectorRegistryService and WebhookGatewayService (D139). The run is read with its state, commit, stages and the results the system of record reports, the pull request with its review state, commits and merge commit; the feed and registry results state whether the version or the image is present and the digest the system reports, so that a digest that differs from the requested one is visible, and an absent version or image is an answer and not an error, with status Succeeded, on which ReleaseService decides in its own feature. The result is stored by hash through ArtifactService/Artifacts.Store under the forwarded tenant and project, and the reply is a tool-receipt-v1 receipt whose resultRef names it and whose status is Succeeded, without a credential, a ticket or a credential reference. The methods have the side-effect class read, yet storing the result through Artifacts.Store, idempotent on tenant and hash, is a write in another service; it is a reading of the resultRef of the receipt under a read-class method, reported to the owner. The service writes nothing to connector-registry-sql. tool-receipt-v1 requires an invocationId that a read does not have and execution-scope-v1 has no member for what to read, so the request and reply messages are provisional golden files until the owner names them. Refusals: a call without a workload identity, or one that forwards no tenant, UNAUTHENTICATED; a token without the scope, PERMISSION_DENIED; an execution scope of another tenant than the forwarded one, PERMISSION_DENIED with the reason scope-mismatch; a request without a project, INVALID_ARGUMENT with the reason project-required, and one without what to read, INVALID_ARGUMENT; no Active descriptor that declares the capability, NOT_FOUND; the answers of Connections.Resolve and SecretBroker.Issue return with their status and reason, NOT_FOUND among them for a connection of another tenant (ADR-0015); a run or pull request unknown to Azure DevOps, NOT_FOUND. Azure DevOps that does not answer is retried within the deadline of the call under the retry profile of the descriptor, then the call fails with UNAVAILABLE and the reason provider-unavailable and connectsoft.factory.integration.adapter_health reports the adapter degraded; IntegrationService, SecretBrokerService, ArtifactService and the store are required and fail-fast, and their outage answers UNAVAILABLE. No refusal returns a partial reply. The model declares ReleaseService as a caller with the failure mode degrade, so an UNAVAILABLE answer leaves the evidence unread and never stated as present.
Acceptance criteria
| AC1 | Given an Active Azure DevOps descriptor that declares the pipeline-run and pull-request reads and a workload token of PipelineExecutionService with factory.connections.read that forwards tenant A and project P, when ConnectorRegistryService/Connectors.ReadPipelineRun or ConnectorRegistryService/Connectors.ReadPullRequest is called with a reference the sandbox stub holds, then the connection of P is resolved through IntegrationService/Connections.Resolve, a credential of the purpose delivery is issued through SecretBrokerService/SecretBroker.Issue, the result is stored through ArtifactService/Artifacts.Store and the reply is a receipt whose resultRef names the run with its stages and results or the pull request with its review state, commits and merge commit (SCN-ConnectorRegistryService-015, SCN-ConnectorRegistryService-016). |
| AC2 | Given an Active descriptor that declares the package-feed and container-registry reads and a workload token of ReleaseService with factory.connections.read that forwards tenant A and project P, when ConnectorRegistryService/Connectors.ReadPackageFeed or ConnectorRegistryService/Connectors.ReadContainerRegistry is called for a version or an image that is present, absent, or present with another digest than the requested one, then the receipt has status Succeeded and the stored result states the presence with the reported digest, the absence or the differing digest (SCN-ConnectorRegistryService-017, SCN-ConnectorRegistryService-018). |
| AC3 | Given a call without a workload identity, one that forwards no tenant, a token without the scope, an execution scope of another tenant, a request without a project or without what to read, no Active descriptor that declares the capability, or a run or pull request unknown to Azure DevOps, when one of the four methods is called, then it is refused with UNAUTHENTICATED, UNAUTHENTICATED, PERMISSION_DENIED, PERMISSION_DENIED with the reason scope-mismatch, INVALID_ARGUMENT with the reason project-required or INVALID_ARGUMENT, NOT_FOUND or NOT_FOUND, with no partial reply and no state change (SCN-ConnectorRegistryService-015, SCN-ConnectorRegistryService-016, SCN-ConnectorRegistryService-017, SCN-ConnectorRegistryService-018, ADR-0015). |
| AC4 | Given IntegrationService/Connections.Resolve answering no-grant, a connection that is not Active or is Degraded, or NOT_FOUND for a connection of another tenant, SecretBrokerService/SecretBroker.Issue refusing, Azure DevOps that does not answer within the deadline, or IntegrationService, SecretBrokerService, ArtifactService or connector-registry-sql unavailable, when one of the four methods is called, then the status and reason of the refusing service return unchanged, or the call fails with UNAVAILABLE, with the reason provider-unavailable for Azure DevOps, and no partial reply (SCN-ConnectorRegistryService-015, SCN-ConnectorRegistryService-017, ADR-0015). |
| AC5 | Given the captured replies, stored results, log records, activities and metrics of the suite, when they are scanned, then none holds the credential, the broker ticket or its credential reference, nothing was written to connector-registry-sql, and the contract test marks the request and reply messages of the four methods provisional because docs/reference/schemas/execution-scope.schema.json has no member for what to read and docs/reference/schemas/tool-invocation.schema.json requires an invocationId (SCN-ConnectorRegistryService-018, ADR-0019). |
| Traces: services | ConnectorRegistryService, IntegrationService, SecretBrokerService, ArtifactService |
| Traces: aggregates | ConnectorRegistryService/ConnectorDescriptor |
| Traces: apis | ConnectorRegistryService/Connectors.ReadPipelineRun, ConnectorRegistryService/Connectors.ReadPullRequest, ConnectorRegistryService/Connectors.ReadPackageFeed, ConnectorRegistryService/Connectors.ReadContainerRegistry, IntegrationService/Connections.Resolve, SecretBrokerService/SecretBroker.Issue, ArtifactService/Artifacts.Store |
| Traces: scenarios | SCN-ConnectorRegistryService-015, SCN-ConnectorRegistryService-016, SCN-ConnectorRegistryService-017, SCN-ConnectorRegistryService-018 |
| Traces: descriptors | execution-scope-v1, tool-receipt-v1 |
| Traces: adrs | ADR-0015, ADR-0019 |
| Traces: requirements | FR-05, FR-11, NFR-02, XL-15 |
| Depends on | AIFACTORY-US-1477, feature:integration-service-thin, feature:secret-broker-service, feature:artifact-service |
| Sources | model/services/integration/ConnectorRegistryService.yaml, model/services/integration/IntegrationService.yaml, model/services/devops-gitops/PipelineExecutionService.yaml, model/services/devops-gitops/ReleaseService.yaml, docs/reference/schemas/execution-scope.schema.json, docs/reference/schemas/tool-invocation.schema.json |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-6019 Provisional request and reply messages of the four Azure DevOps reads |
contract | The proto fixes one request message per read, the execution scope beside what to read (a run, a pull request, a package with its version and digest, an image with its digest), and the reply as the tool-receipt-v1 receipt with status, startedAt, finishedAt, resultRef and receiptHash and no credential member, as provisional golden files marked so in the contract test until the owner names the descriptors, because docs/reference/schemas/execution-scope.schema.json has no member for what to read and docs/reference/schemas/tool-invocation.schema.json requires an invocationId. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6020 Shared read path and Connectors.ReadPipelineRun and Connectors.ReadPullRequest over the connection of the project |
implementation | The shared read path reads the forwarded scope only under factory.connections.read, takes the highest Active descriptor that declares the capability, resolves the connection through Connections.Resolve, exchanges the ticket through SecretBroker.Issue for a credential of the purpose delivery used in memory for the call, reads through the adapter within the deadline under the retry profile of the descriptor, stores the result through Artifacts.Store and replies with its resultRef, returns the refusals of the dependencies with their reason, answers UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND and UNAVAILABLE as AIFACTORY-US-1481 states, writes nothing to connector-registry-sql and logs and measures neither the ticket nor its credential reference; the pipeline-run and pull-request methods use it with their adapter calls. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6022 Connectors.ReadPackageFeed and Connectors.ReadContainerRegistry over the shared read path |
implementation | The two methods use the shared read path of AIFACTORY-TASK-6020, read through the adapter whether the package version or the image is present and the digest the feed or the registry reports, store that result through Artifacts.Store and reply with its resultRef and status Succeeded also for an absent version or image, and answer the refusals and failures as AIFACTORY-US-1481 states. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6023 Extend the sandbox stub with absent versions, absent images and differing digests |
fixture | The recording stub of AIFACTORY-TASK-6006 also answers a package version and an image that are absent and ones present with another digest than the requested one, and can be stopped, so the present, absent and differing answers of both reads run without a real organization. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6021 Verify the pipeline-run and pull-request reads through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ConnectorRegistryService-015\|Scenario=SCN-ConnectorRegistryService-016)"; a zero-match filter counts as a failure; the tests prove AC1, AC3, AC4 and AC5 of AIFACTORY-US-1481 for these two methods with the fakes of AIFACTORY-TASK-4036 and the stub of AIFACTORY-TASK-6006: both reads for project P of tenant A, the eight refusals, each refusal of Connections.Resolve and SecretBroker.Issue, the stub that stops answering, each dependency and the store stopped, the scan for the credential and the ticket, no row written and the provisional golden files. |
ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6024 Verify the package-feed and container-registry reads through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ConnectorRegistryService-017\|Scenario=SCN-ConnectorRegistryService-018)"; a zero-match filter counts as a failure; the tests prove AC2 to AC5 of AIFACTORY-US-1481 for these two methods with the stub of AIFACTORY-TASK-6023: the present version and image, the absent ones and the differing digests, the refusals and failures of the shared path, no row written, the scan for the credential and the ticket and the provisional golden files. |
ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-US-1483: Subscribe a project to its Azure DevOps service hooks with an ingress identity, refresh the ingress table and list deliveries¶
behavior · persona workspace-admin
As a workspace admin, I want to subscribe my project to the Azure DevOps service hooks it needs, receive the ingress identity the hooks post to, and see the inbound deliveries and their states, so that review states, merges and pipeline runs of my project reach the Factory from a subscription I created, and a rejected or failed delivery is visible.
A caller whose scope carries factory.connections.admin, a Workspace admin of the project or a Platform admin, subscribes a project to Azure DevOps service hooks through ConnectorRegistryService/CreateSubscription (POST /factory/subscriptions) with an Idempotency-Key. The body names the required projectId, the connectorId of the Azure DevOps connector, the eventTypes, a non-empty list of event types that the webhook scheme of the connector accepts, and the target; the scope of I2 is Azure DevOps inbound subscriptions only. A call without projectId or with an invalid body is answered 400, and a project that the roles of the token do not grant 403 (D129). The service takes the highest Active Azure DevOps descriptor with a webhook scheme (AIFACTORY-US-1477); a connector that does not exist or that another tenant registered is answered 404 (ADR-0015), and one with no Active version with a webhook scheme 409. It resolves the connection of the project through IntegrationService/Connections.Resolve with its workload token and the forwarded tenant and project, which checks the Project grant and the state of the connection: no-grant is answered 403, a connection that is not Active or is Degraded 409, and a connection the tenant does not hold 404 (ADR-0015). The model asks for a grant of subject kind Source or Tool; the thin IntegrationService resolves through the Project grant, which stands in for it, a reading reported to the owner. The model lists neither 404 nor 503 for the operation; ADR-0015 and D137 give both, which is reported. On success the service writes, in one transaction, the Subscription with tenantId, projectId, connectorId, connectionId, eventTypes, target, active true and a new ingressRef, an opaque identity that cannot be guessed and is unique under UX_Subscriptions_Ingress, and the ConnectorSubscriptionChanged outbox record; the answer is 201 with the subscriptionId and the ingress path /webhooks/{ingressRef}. A repeated call with the same key returns the same result and changes nothing; the same key with another body is answered 409. The operation has the side-effect class external, because the model subscribes at the provider through the connection; in I2 the service hook is configured at Azure DevOps by the admin by the runbook of AIFACTORY-TASK-6007 with that path and the signing secret of the connection, and the registration at the provider arrives in I5, a reading reported to the owner. AuditService records the subscription from ConnectorSubscriptionChanged (RecordEvidence), so the command writes no evidence record of its own. The dispatcher publishes ConnectorSubscriptionChanged on connectors.subscriptions.v1.connector-subscription-changed under the run event envelope with subscriptionId, tenantId, connectorId and active, and, because the gateway has no other source and no dependency to read them, with ingressRef, connectionId, the descriptor version and its webhook scheme, never a secret or a secret reference, a model gap reported to the owner; a transport outage is retried with backoff so the event is neither lost nor duplicated. StudioBff and AuditService handle it in their own suites. The handler RefreshIngressTable of WebhookGatewayService consumes it through the inbox of the webhook-gateway profile, idempotent on the event id, and writes or updates the ingress entry of the ingressRef in the table IngressEntries of webhook-gateway-sql; an event with active false makes the entry inactive, after which a delivery to it is answered 404. No operation of I2 changes or deactivates a subscription; that arrives with PauseOnRevocation in I5. A caller whose scope carries factory.connections.read lists deliveries through ConnectorRegistryService/ListDeliveries (GET /factory/deliveries), a read, filtered by direction, connector, state and a time range on receivedAt and paged; the reply holds the deliveries of the tenant of the token only under the row filter, each with deliveryId, direction, connectorId, subscriptionId, externalId, state, payloadHash, receivedAt, settledAt and receiptRef, never the payload, so an operator sees a Rejected or Deduplicated inbound delivery. In I2 only inbound Azure DevOps deliveries exist, so a filter on Outbound returns an empty page. A delivery of another tenant never appears. A call without a token is answered 401, a token without the scope 403, an unknown filter value 400, a code the model does not list and reports, and an unavailable connector-registry-sql 503 with a problem response (D137). The gauge connectsoft.factory.integration.subscriptions counts active subscriptions by tenant and connector. This PBI creates the tables Subscriptions and Deliveries of connector-registry-sql together, because the foreign key of Deliveries names Subscriptions.
Acceptance criteria
| AC1 | Given a Workspace admin of project P of tenant A with factory.connections.admin, the Active Azure DevOps descriptor with its webhook scheme and IntegrationService/Connections.Resolve granting the Active connection C of P, when ConnectorRegistryService/CreateSubscription is called with an Idempotency-Key, projectId P, the connector, event types the scheme accepts and a target, then the response is 201 with the subscriptionId and the ingress path, the ConnectorRegistryService/Subscription is active with the connection C and a unique ingressRef, and the ConnectorRegistryService/ConnectorSubscriptionChanged outbox record is written in the same transaction; the same call repeated with the same key returns the same result and changes nothing (SCN-ConnectorRegistryService-003). |
| AC2 | Given a body without projectId, an event type the scheme does not accept, a token without the scope or for a project it does not grant, a connector unknown or registered by tenant B, a connector without an Active version with a webhook scheme, the key reused with another body, IntegrationService/Connections.Resolve answering no-grant, a connection that is not Active or is Degraded, or NOT_FOUND, or IntegrationService or connector-registry-sql unavailable, when ConnectorRegistryService/CreateSubscription is called, then the response is 400, 400, 403, 404, 409, 409, 403, 409, 404 or 503 with a problem response, and no subscription, ingress identity or event is written (SCN-ConnectorRegistryService-003, ADR-0015). |
| AC3 | Given the subscription committed, when the outbox dispatcher of the connector-registry profile publishes ConnectorRegistryService/ConnectorSubscriptionChanged on connectors.subscriptions.v1.connector-subscription-changed, then the event is sent under the run event envelope with subscriptionId, tenantId, connectorId, active, ingressRef, connectionId, the descriptor version and its webhook scheme and without a secret or a secret reference, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ConnectorRegistryService-010, ADR-0012). |
| AC4 | Given the event received by WebhookGatewayService, when RefreshIngressTable handles it once or twice, then one ingress entry of the ingressRef exists with the tenant, the subscription, the connector, the connection, the descriptor version and the scheme, and a signed delivery to that ingress identity is accepted by WebhookGatewayService/ReceiveWebhook; given a later event with active false, then the entry is inactive and a delivery to it is answered 404 (SCN-ConnectorRegistryService-010, model/services/integration/WebhookGatewayService.yaml). |
| AC5 | Given fixture deliveries of tenant A and tenant B in the states Verified, Rejected and Deduplicated, when a caller of tenant A with factory.connections.read calls ConnectorRegistryService/ListDeliveries with or without the filters of direction, connector, state and time, then the response is 200 with the matching inbound deliveries of tenant A and their states, never one of tenant B and never a payload, an Outbound filter returns an empty page, and a call without a token, a token without the scope, an unknown filter value or an unavailable connector-registry-sql is answered 401, 403, 400 or 503 with a problem response (SCN-ConnectorRegistryService-004, ADR-0015). |
| Traces: services | ConnectorRegistryService, WebhookGatewayService, IntegrationService |
| Traces: aggregates | ConnectorRegistryService/Subscription, ConnectorRegistryService/Delivery |
| Traces: apis | ConnectorRegistryService/CreateSubscription, ConnectorRegistryService/ListDeliveries, IntegrationService/Connections.Resolve, WebhookGatewayService/ReceiveWebhook |
| Traces: events | ConnectorRegistryService/ConnectorSubscriptionChanged |
| Traces: scenarios | SCN-ConnectorRegistryService-003, SCN-ConnectorRegistryService-004, SCN-ConnectorRegistryService-010 |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0015, ADR-0022 |
| Traces: requirements | FR-05, FUX-02, NFR-13 |
| Relates: screens | connectors |
| Depends on | AIFACTORY-US-1477, feature:integration-service-thin, feature:contracts-package |
| Sources | model/services/integration/ConnectorRegistryService.yaml, model/services/integration/WebhookGatewayService.yaml, model/services/integration/IntegrationService.yaml, docs/planes/capability-tools/connectors/services/connector-registry-service/index.md#apis, docs/planes/capability-tools/connectors/workflows.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-6015 Migration and mappings of Deliveries and Subscriptions in connector-registry-sql |
migration | The tables Deliveries and Subscriptions of model/services/integration/ConnectorRegistryService.yaml exist with their columns, keys, the foreign key of Deliveries on SubscriptionId and the indexes UX_Deliveries_Dedup, IX_Deliveries_State_ReceivedAt and UX_Subscriptions_Ingress; the mappings carry the tenant row filter of the Factory profile; mapping tests run against an isolated test database, never a shared one. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6025 Contract of CreateSubscription and ListDeliveries: OpenAPI document, problem responses and the extended payload of ConnectorSubscriptionChanged |
contract | The OpenAPI document fixes POST /factory/subscriptions with the body members projectId, connectorId, eventTypes and target, the Idempotency-Key header, the 201 reply with subscriptionId and the ingress path and the problem responses of 400, 403, 404, 409 and 503, and GET /factory/deliveries with the filters of direction, connector, state and time, the page and the problem responses of 400, 401, 403 and 503; golden files hold the shapes, a delivery item without a payload member, and the payload of ConnectorSubscriptionChanged under the run event envelope with the four modelled members and ingressRef, connectionId, the descriptor version and the webhook scheme, without a secret or a secret reference. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6026 CreateSubscription with its Idempotency-Key, the connection of the project, the ingress identity and the ConnectorSubscriptionChanged outbox record |
implementation | CreateSubscription validates the body and the event types against the scheme, admits the project only when the roles of the token grant it, takes the highest Active Azure DevOps descriptor with a webhook scheme, resolves the connection of the project through Connections.Resolve with its workload token and the forwarded scope, writes the Subscription with a new opaque unique ingressRef and the ConnectorSubscriptionChanged outbox record with its extended payload in one transaction, answers 201, 400, 403, 404, 409 and 503 as AIFACTORY-US-1483 states, returns the same result for a repeated key and 409 for a key reused with another body, writes no evidence record of its own, and updates connectsoft.factory.integration.subscriptions. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6027 ListDeliveries read model over the deliveries of the tenant of the caller |
implementation | ListDeliveries returns, under the tenant row filter, the deliveries of the trusted tenant of the caller filtered by direction, connector, state and a time range on receivedAt and paged, each item without a payload or a payload reference, answers 401 and 403 through the policies of the Factory profile, 400 for an unknown filter value and 503 with a problem response when the store is unavailable, and writes nothing. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6029 Migration and mapping of IngressEntries in webhook-gateway-sql |
migration | The table IngressEntries holds IngressRef as key with TenantId, SubscriptionId, ConnectorId, ConnectionId, the descriptor version, the webhook scheme and Active, and no secret or secret reference column; the mapping carries the tenant column and is named in the exemption file; mapping tests run against an isolated test database, never a shared one. | ConnectSoft.AI.SoftwareFactory.WebhookGatewayService |
AIFACTORY-TASK-6028 RefreshIngressTable on ConnectorSubscriptionChanged through the inbox of the webhook-gateway profile |
implementation | The inbox handler RefreshIngressTable, idempotent on the event id, writes or updates the ingress entry of the ingressRef of the event with its tenant, subscription, connector, connection, descriptor version, scheme and active state, makes the entry inactive for active false, writes through the repository of IngressEntries only, and logs neither the scheme of a tenant nor any reference; ReceiveWebhook reads the entry it writes. | ConnectSoft.AI.SoftwareFactory.WebhookGatewayService |
AIFACTORY-TASK-6030 Tokens, fixture deliveries of two tenants and recorded ConnectorSubscriptionChanged events |
fixture | The registry suite holds tokens of a Workspace admin of project P of tenant A, of a caller without the scope, of a caller whose roles do not grant P and of a caller of tenant B, fixture descriptors of the platform tenant and of tenant B and fixture delivery rows of two tenants in the states Verified, Rejected and Deduplicated inserted directly into the isolated test database, and the fake of IntegrationService/Connections.Resolve of AIFACTORY-TASK-4036 answering a grant, no-grant, a Degraded connection, NOT_FOUND and no answer. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6036 Recorded ConnectorSubscriptionChanged events in the extended payload shape for the gateway suite |
fixture | The gateway suite holds recorded ConnectorSubscriptionChanged events under the run event envelope with active true and false, in the extended payload shape of AIFACTORY-TASK-6025, for ingress identities of two tenants with distinct connections, and the delivery of one event twice with the same event id. | ConnectSoft.AI.SoftwareFactory.WebhookGatewayService |
AIFACTORY-TASK-6031 Verify CreateSubscription, ConnectorSubscriptionChanged and ListDeliveries through the acceptance suite of the registry |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ConnectorRegistryService-003\|Scenario=SCN-ConnectorRegistryService-004\|Scenario=SCN-ConnectorRegistryService-010)"; a zero-match filter counts as a failure; the tests prove AC1, AC2, AC3 and AC5 of AIFACTORY-US-1483: the created subscription with its unique ingress identity and outbox record, the repeated key, each of the ten refusals with nothing written, the publication with the extended payload under the run event envelope with retry and without a secret reference, and the list of tenant A without a row of tenant B or a payload with its four refusals. |
ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-6032 Verify RefreshIngressTable through the acceptance suite of the gateway |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ConnectorRegistryService-010" in ConnectSoft.AI.SoftwareFactory.WebhookGatewayService; a zero-match filter counts as a failure; the tests prove AC4 of AIFACTORY-US-1483 with the recorded events of AIFACTORY-TASK-6036: one entry after the event handled twice, a signed delivery accepted at the new ingress identity, and the entry made inactive with a delivery to it answered 404. |
ConnectSoft.AI.SoftwareFactory.WebhookGatewayService |