Spring Boot Integration Lab

Overview

Spring Boot Integration Lab demonstrates a focused fulfillment gateway that calls an unreliable external partner API. Its central concern is not ordinary request/response plumbing but the uncertain state left behind by timeouts, retries, partner failures, and duplicate client requests. It is an independent engineering demonstration using a mock partner, not a client engagement or a production deployment.

Engineering Challenge

A write timeout does not prove that the partner did not process the request. The partner might have committed the operation and lost or delayed its response. Retrying without deduplication can repeat the effect; returning a definite failure can be false. The gateway therefore needs durable request ownership, explicit state semantics, a partner idempotency contract, and a way to reconcile uncertain outcomes.

Architecture

The gateway owns its public API, MySQL-backed fulfillment and idempotency state, outbound HTTP client, resilience policies, and metrics. A separate mock-partner service communicates with it over HTTP and simulates deterministic failures. MySQL is not shared with the partner. Optional Prometheus scraping is provided through a Compose profile.

Merchant client
      |
      v
Spring Boot gateway ---- MySQL (idempotency + fulfillment state)
      |
      +-- timeout / retry / circuit breaker / rate limiter
      |
      v
Mock partner API ---- in-memory partner deduplication

For a timeout-after-commit case, the gateway can query the partner by request identity. If completion is confirmed, it records the result; if not, it preserves an UNKNOWN outcome rather than treating uncertainty as a business failure.

Key Design Decisions

1. Register idempotency before partner execution. Database state establishes which request owns a key before network I/O. Transactions are not held open while waiting on the partner.
2. Use conservative response semantics. A partner write with an ambiguous outcome may remain 202 UNKNOWN; the gateway does not automatically reclassify it as a failure.
3. Retry only selected transient failures. Timeouts, retry policy, circuit breaking, and rate limits are explicit. A stable idempotency key is propagated to the mock partner.
4. Keep gateway and partner separate. HTTP is the integration boundary, avoiding shared tables or code that would hide assumptions about the external system.
5. Do not promise exactly-once execution. Gateway idempotency is not distributed exactly-once. Partner-side deduplication or another partner-supported contract is required to avoid duplicate effects across the boundary.

Implementation and Verification

The repository contains separate integration-gateway and mock-partner Spring services, MySQL schema and Compose configuration, resilience and observability code, and deterministic fault scenarios. Integration tests use Testcontainers MySQL and WireMock. The README documents coverage for normal fulfillment, duplicate requests, key conflicts, concurrent duplicates, retry classification, ambiguous timeout reconciliation, correlation IDs, and metrics exposure.

The latest visible GitHub Actions verification run for the inspected main commit succeeded. The README also reports local k6 observations, but those are single-run local demonstrations with explicit caveats; this case study does not present them as capacity benchmarks or production SLOs.

Limitations and Further Work

The partner simulator uses in-memory deduplication. The rate limiter is process-local and would not enforce a shared quota across multiple gateway instances. There is no authentication, alerting system, or background reconciliation worker. Production use would require threat modeling and controls matched to the partner contract, deployment topology, identity, and operational requirements.

Source

• GitHub repository
• README and setup instructions
• Architecture overview
• Failure scenarios