Cross-service contract tests for the AS↔DC back-channel (lightweight shared-fixture, no Spring Cloud) #150

Summary

Filed per the senior-architect review during PR D scoping (issue #148): the proper validation pattern for "do AS and DC actually agree on the back-channel JSON wire format at runtime" is a consumer-driven contract test (Spring Cloud Contract or Pact), NOT "two Spring contexts in one JVM" and NOT an in-process mock of either side.

Already-shipped coverage establishes the foundation:

• DataCustodianBackchannelClientTest (PR C4) — AS as consumer, validates the wire shape against a MockRestServiceServer stubbed JSON contract
• SubscriptionProvisioningControllerTest (PR B2) — DC as provider, validates the controller's request/response handling

What's missing is a shared contract artifact that both sides bind to, with a CI-enforced compatibility check.

Why contract testing is the right pattern

For independently-deployed Spring Boot services that communicate over HTTP, contract tests are the industry-standard pattern because they:

1. Catch breaking changes when either side updates their DTO without the other knowing
2. Run fast (no Spring context startup, no Docker, no real network)
3. Are honest about what they cover (the contract; not customer UX, not production wiring, not network layers)
4. Scale (adding a new endpoint requires one contract, not a cross-service integration test setup)

The "two Spring contexts in one JVM" alternative considered in #148 was rejected as non-idiomatic and brittle — it pretends to validate the cross-service flow but doesn't catch the failures that actually happen in production (proxy timeouts, CORS, TLS, ingress config).

Scope

Two interacting wire contracts to formalize:

Contract 1: AS → DC /internal/backchannel/v1/subscriptions

• Request: BackchannelRequest (correlation_id, client_id, granted_scope, retail_customer_id, selected_usage_point_ids, customer_resource_uri)
• Response 201: BackchannelResponse (authorization_id, resource_subscription_id, customer_subscription_id, resource_uri, authorization_uri, customer_resource_uri)
• Response 400/500: error envelope shape

Contract 2: DC → AS /oauth2/introspect

• Request: standard RFC 7662 (token + Basic auth)
• Response 200: standard RFC 7662 + ESPI-specific claims (resourceURI, authorizationURI, customerResourceURI, authorization_id, resource_subscription_id, customer_subscription_id) per PR C4's customizer

Recommended approach

Spring Cloud Contract is the natural fit for a Spring Boot 4 monorepo:

• Contracts live in the producer module's src/test/resources/contracts/
• Producer module (DC for Bump commons-io:commons-io from 2.4 to 2.14.0 in /openespi-datacustodian #1, AS for Bump org.postgresql:postgresql from 42.7.4 to 42.7.7 in /openespi-datacustodian/OpenESPI-GreenButton-Workspace/OpenESPI-DataCustodian-java #2) verifies contracts via auto-generated tests during its own mvn test
• Consumer module (AS for Bump commons-io:commons-io from 2.4 to 2.14.0 in /openespi-datacustodian #1, DC for Bump org.postgresql:postgresql from 42.7.4 to 42.7.7 in /openespi-datacustodian/OpenESPI-GreenButton-Workspace/OpenESPI-DataCustodian-java #2) gets generated stubs via @AutoConfigureStubRunner for its own integration tests
• Contract changes can break either side's build immediately — true CI-enforced compatibility

Pact is a viable alternative but adds a Pact Broker deployment burden the project doesn't currently need.

Sub-tasks

1. Add spring-cloud-contract-verifier to AS and DC parent POM
2. Author Contract 1 in DC's src/test/resources/contracts/ — Groovy DSL files for the happy path + 400 + 500 cases
3. Author Contract 2 in AS's src/test/resources/contracts/ — happy path + non-existent-token (active=false) cases
4. AS consumer-side stubs — replace MockRestServiceServer in DataCustodianBackchannelClientTest with @AutoConfigureStubRunner (cleaner; the stub is generated from DC's contract)
5. DC consumer-side stubs — wire AS's introspection contract into DC's resource-server tests
6. CI enforcement — both modules' mvn verify fails if their contracts diverge from the published wire format
7. Documentation — README section explaining the contract test pattern for future endpoints

Acceptance

• Both wire contracts are formalized as machine-checkable artifacts
• AS and DC builds verify their respective contracts on every CI run
• Adding a new field to either DTO requires updating the contract (which fails CI until both producer + consumer agree)
• PR D's DataCustodianBackchannelClientTest is migrated to use the generated stubs
• Documentation exists for adding new cross-service contracts

Out of scope

• Browser end-to-end testing (deferred to TP bring-up: missing JAXB Atom marshaller, narrow component scan, and broader OAuth2-client wiring gaps #146 territory)
• Production smoke tests (deferred to whenever staging exists)
• The Phase 2.0 orchestration test (PR D: Phase 2.0 integration test — auth-code flow + introspection + token-response augmentation end-to-end (closes #122 Step 6) #148) — different concern; this issue is the cross-service-contract layer

Effort estimate

2-3 working days for someone familiar with Spring Cloud Contract. First-timers should expect 4-5 days including learning curve.

Related

• Phase 2.0 — Stand up auth-server in dev with opaque tokens + subscription-bound introspection (Phase 2 precursor) #122 — Phase 2.0 umbrella; this issue + PR D: Phase 2.0 integration test — auth-code flow + introspection + token-response augmentation end-to-end (closes #122 Step 6) #148 + Repair AS integration test infrastructure (pre-existing pre-#122) #149 collectively close it once delivered
• PR D: Phase 2.0 integration test — auth-code flow + introspection + token-response augmentation end-to-end (closes #122 Step 6) #148 — PR D Phase 2.0 integration test (the in-process orchestration test)
• Repair AS integration test infrastructure (pre-existing pre-#122) #149 — Repair AS integration test infrastructure (blocks PR D: Phase 2.0 integration test — auth-code flow + introspection + token-response augmentation end-to-end (closes #122 Step 6) #148)
• PR feat(#122 PR C4): AS-side back-channel call + token-response augmentation #147 (PR C4) — back-channel client + customizer + success handler; the producer/consumer side of Contract 1