From 345c9996e71ea55572ae60a94caf8eb1bc1f6b31 Mon Sep 17 00:00:00 2001 From: Duynh ne Date: Fri, 2 Oct 2026 17:13:36 +0700 Subject: [PATCH 1/2] Drop the ADR-017 aliases from edge and docs The homelab half of the ADR-017 contract step, shipping with payment-service v2.8.0 and shipping-service v1.10.0, which remove the aliases in-service. Both edges stop matching the pre-v3 /payment/v1/public/webhooks path. e2e-audit A7 and the k6 smoke suite now expect the shipping alias to answer 404, so a forgotten alias fails the gate instead of passing it. docs/api records the removals and drops the aliases from the known gaps. --- CHANGELOG.md | 9 ++++++++ docs/api/microservices.md | 6 ++--- docs/api/payments.md | 22 +++++++------------ docs/api/shipping.md | 10 ++++----- .../configs/envoy-gateway/routes/api.yaml | 7 +----- local-stack/docs/e2e-audit.md | 12 +++++----- local-stack/gateway/eg/routes.yaml | 12 +++------- scripts/k6/smoke.js | 18 +++++++-------- 8 files changed, 43 insertions(+), 53 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1c8c7fb47..e28e0d9f0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -99,6 +99,15 @@ Skeleton (copy what you need): reaching a Service past the gateway, a host without `/etc/hosts`) are one-line `kubectl port-forward` snippets under setup.md § Prerequisites. +#### Services +- **The ADR-017 expand-phase aliases are gone** (payment-service v2.8.0, + shipping-service v1.10.0). These now answer 404: payment's + `/protected/attempts/open`, `/protected/reconciliations/runs[/:id]`, + `/internal/reconciliation/runs[/:id]` and `/public/webhooks/mockpay`, and + shipping's `/public/track` and `/public/estimate`. Both edges drop the + webhook alias match; e2e-audit A7 and the k6 smoke suite now expect the + shipping alias to be 404. + ### Feature #### GitOps diff --git a/docs/api/microservices.md b/docs/api/microservices.md index ab443e6e5..1535d8248 100644 --- a/docs/api/microservices.md +++ b/docs/api/microservices.md @@ -86,8 +86,8 @@ availability vocabulary used by service At-a-glance tables. | Promo contention, asymmetric upstream errors, and parked confirm recovery | checkout | Accepted operational trade-offs | [checkout known gaps](./checkout.md#known-gaps) | | Committed-stock cancellation and workflow-start terminal failures | order | Accepted or alerted trade-offs | [order known gaps](./order.md#known-gaps) | | Real provider delivery, send idempotency, and unused SMS/HTTP twins | notification | Current limitations and no-caller surfaces | [notification known gaps](./notification.md#known-gaps) | -| Deprecated aliases, unpersisted destination, and demo quote math | shipping | Migration debt and accepted limitations | [shipping known gaps](./shipping.md#known-gaps) | -| Deprecated aliases, direct DB connection, reconciliation limits, and single-replica constraint | payment | Migration and scaling constraints | [payment known gaps](./payments.md#known-gaps) | +| Unpersisted destination and demo quote math | shipping | Migration debt and accepted limitations | [shipping known gaps](./shipping.md#known-gaps) | +| Direct DB connection, reconciliation limits, and single-replica constraint | payment | Migration and scaling constraints | [payment known gaps](./payments.md#known-gaps) | | Bounded review feed and write-once reviews | review | Accepted design limits | [review known gaps](./review.md#known-gaps) | | Backoffice availability and static-delivery hardening | Backoffice | Current platform gaps | [Backoffice known gaps](../frontend/admin-portal/README.md#known-gaps) | @@ -101,4 +101,4 @@ contracts; they are not ongoing-work rows here. - [Workflow registry](./workflows.md) - [Repository index](../README.md#repositories) -_Last updated: 2026-08-26 — removes duplicated deployment, route, RPC, and technique inventories; restores the catalog to feature ownership and current known-gap rollup._ +_Last updated: 2026-10-02 — deprecated aliases are no longer a known gap for shipping or payment (ADR-017 contract). Previously 2026-08-26 — removes duplicated deployment, route, RPC, and technique inventories; restores the catalog to feature ownership and current known-gap rollup._ diff --git a/docs/api/payments.md b/docs/api/payments.md index 75bd7ff71..0cf1a599c 100644 --- a/docs/api/payments.md +++ b/docs/api/payments.md @@ -16,7 +16,7 @@ reconciliation loop that proves the books match the provider. | **Temporal** | Money-step gRPC participant | Implemented | [Temporal participation](#temporal-participation) | | **Events** | Transactional outbox + signed inbound mockpay webhooks | Implemented | [Ledger + outbox](#ledger--outbox-settle-once-tell-everyone-at-least-once) · [Webhook HMAC](#mockpay--webhook-hmac) | -Known gaps: [aliases, pooler, and reconciliation limits](#known-gaps). +Known gaps: [pooler and reconciliation limits](#known-gaps). | Attribute | Value | |-----------|-------| @@ -116,9 +116,9 @@ Private responses are owner-scoped by the JWT `user_id`. Internal routes are never given an `HTTPRoute` at the edge; NetworkPolicy is the cluster boundary. The public webhook is not anonymous in practice: its HMAC signature is the credential (the edge's rate/size limits still apply — `BackendTrafficPolicy`). -The deprecated pre-v3 alias -`/payment/v1/public/webhooks/mockpay` stays mounted during the ADR-017 window -([Known gaps](#known-gaps)); shared conventions live in [api.md](./api.md). +Shared conventions live in [api.md](./api.md). The pre-v3 aliases +`/payment/v1/public/webhooks/mockpay` and `/payment/v1/internal/reconciliation/runs` +were removed in v2.8.0 (ADR-017 contract) and now answer 404. ## gRPC API @@ -398,11 +398,9 @@ Read-only: refunds and recon triggers stay `internal`. | `GET` | `/payment/v1/protected/payments/reconciliation/runs` | Run headers, newest first — the detect-only recon records' first reader | | `GET` | `/payment/v1/protected/payments/reconciliation/runs/:id` | Run + its discrepancies (`{run, discrepancies}`) — the triage view | -**Deprecated aliases (ADR-017 expand phase, payment-service v2.7.0).** The -pre-canonical `GET /payment/v1/protected/attempts/open` and -`GET /payment/v1/protected/reconciliations/runs[/:id]` still answer on the same -handlers. They are removed in the contract release, after the Backoffice has -shipped on the canonical paths. +The pre-canonical `GET /payment/v1/protected/attempts/open` and +`GET /payment/v1/protected/reconciliations/runs[/:id]` served as aliases in v2.7.0 +while the Backoffice moved over, and were removed in v2.8.0 (ADR-017 contract). ### mockpay provider API @@ -436,10 +434,6 @@ mockpay posts its events back to payment's signed webhook, ## Known gaps -- **Deprecated webhook alias** `/payment/v1/public/webhooks/mockpay` — pre-v3 - path kept at both edges during the ADR-017 window so in-flight mockpay - retries keep landing; remove at contract end. A matching deprecated internal - alias `/payment/v1/internal/reconciliation/runs` remains mounted in-service. - **No pooler for payment DB** — direct CNPG connection with `sslmode=require` because PgDog does not terminate TLS yet (RFC-0020 research). - **Reconciliation limits (deliberate, tracked):** refund *amounts* aren't @@ -545,4 +539,4 @@ Paths in [`duynhlab/payment-service`](https://github.com/duynhlab/payment-servic - [workflows.md](./workflows.md) · [Service contracts](./README.md#service-contracts) - [RFC-0010](../proposals/rfc/RFC-0010/) — full design; ADRs [007](../proposals/adr/ADR-007-double-entry-payment-ledger/) ledger · [008](../proposals/adr/ADR-008-mockpay-standalone-provider/) mockpay · [009](../proposals/adr/ADR-009-saga-authorize-early-capture-late/) auth-early/capture-late · [010](../proposals/adr/ADR-010-shared-idempotency-library/) idempotency · [011](../proposals/adr/ADR-011-detect-only-reconciliation/) detect-only · [012](../proposals/adr/ADR-012-reconciliation-auto-heal/) auto-heal -_Last updated: 2026-10-02 — protected attempt and reconciliation reads move under `payments/` (ADR-017 expand; old paths are deprecated aliases); mockpay provider API table added. Previously 2026-08-26 — adds evidence-backed capability and ownership summaries. Previously 2026-08-14 — RFC-0023 Train 3 shipped the protected Backoffice reads._ +_Last updated: 2026-10-02 — the ADR-017 aliases (protected, internal reconciliation, webhook) are removed in v2.8.0. Previously 2026-10-02 — protected attempt and reconciliation reads move under `payments/` (ADR-017 expand; old paths are deprecated aliases); mockpay provider API table added. Previously 2026-08-26 — adds evidence-backed capability and ownership summaries. Previously 2026-08-14 — RFC-0023 Train 3 shipped the protected Backoffice reads._ diff --git a/docs/api/shipping.md b/docs/api/shipping.md index 8c3aec607..bdc75ce25 100644 --- a/docs/api/shipping.md +++ b/docs/api/shipping.md @@ -14,7 +14,7 @@ Shipping turns "an order that must move" into a tracked shipment — and turns " | **Temporal** | Shipment-step gRPC participant | Implemented | [Temporal participation](#temporal-participation) | | **Events** | None | None | — | -Known gaps: [no-caller route, aliases, and unpersisted address](#known-gaps). +Known gaps: [no-caller route and unpersisted address](#known-gaps). | Attribute | Value | |-----------|-------| @@ -166,8 +166,8 @@ accepted for compatibility. | estimate | `400` | `VALIDATION_ERROR` | Missing params, or weight not a positive finite number | | both | `500` | `INTERNAL_ERROR` | Repository/infrastructure failure | -The deprecated pre-v3 paths `/shipping/v1/public/{track,estimate}` remain -temporary aliases during the ADR-017 expand phase (see [Known gaps](#known-gaps)). +The pre-v3 paths `/shipping/v1/public/{track,estimate}` were removed in v1.10.0 +(ADR-017 contract) and answer 404. ## gRPC API @@ -247,8 +247,6 @@ east-west gRPC surface is unauthenticated by design — the policy is the fence. - **Internal HTTP twin — No caller.** `GET /shipping/v1/internal/shipments/orders/:orderId` mirrors the gRPC lookup; order migrated to gRPC, so the route is kept documented but has no live consumer. -- **Pre-v3 aliases.** `/shipping/v1/public/track` and `/shipping/v1/public/estimate` - are deprecated ADR-017 expand-phase aliases; removal lands with the contract phase. - **`CreateShipmentRequest.address` not persisted.** Accepted for forward compatibility; the shipment row stores no destination yet. - **Estimate is demo math.** The public estimate is a deterministic formula, not a @@ -302,4 +300,4 @@ Paths in [`duynhlab/shipping-service`](https://github.com/duynhlab/shipping-serv - [checkout.md](./checkout.md) · [order.md](./order.md) — quote and enrichment callers - [Service contracts](./README.md#service-contracts) -_Last updated: 2026-08-26 — adds evidence-backed capability and ownership summaries. Previously 2026-08-14 — RFC-0023 Train 3 shipped the protected Backoffice reads._ +_Last updated: 2026-10-02 — the pre-v3 `/public/track` and `/public/estimate` aliases are removed in v1.10.0. Previously 2026-08-26 — adds evidence-backed capability and ownership summaries. Previously 2026-08-14 — RFC-0023 Train 3 shipped the protected Backoffice reads._ diff --git a/kubernetes/infra/configs/envoy-gateway/routes/api.yaml b/kubernetes/infra/configs/envoy-gateway/routes/api.yaml index 1d6b3f7dd..52e58a4b5 100644 --- a/kubernetes/infra/configs/envoy-gateway/routes/api.yaml +++ b/kubernetes/infra/configs/envoy-gateway/routes/api.yaml @@ -621,7 +621,7 @@ spec: --- # Payment webhooks — public, anonymous: the HMAC signature over the raw body # is the credential (mockpay signs, payment verifies). Rate/size limits still -# apply (btp-api.yaml). Both webhook paths are matched by one route. +# apply (btp-api.yaml). apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: @@ -639,11 +639,6 @@ spec: - path: type: PathPrefix value: /payment/v1/public/payments/webhooks - # Deprecated pre-v3 path — kept during the v3 rollout so in-flight - # mockpay retries keep landing. Remove at contract (ADR-017). - - path: - type: PathPrefix - value: /payment/v1/public/webhooks filters: - type: ResponseHeaderModifier responseHeaderModifier: diff --git a/local-stack/docs/e2e-audit.md b/local-stack/docs/e2e-audit.md index 0ae95a690..a688c5457 100644 --- a/local-stack/docs/e2e-audit.md +++ b/local-stack/docs/e2e-audit.md @@ -385,9 +385,9 @@ docker compose exec -T postgres psql -U postgres -lqt r.status === 200 }); + rowCheck(id, res, { [`${label} is ${want}`]: (r) => r.status === want }); } }, }, From ebed9e334498479e94b387c424b40fa4c8bfc246 Mon Sep 17 00:00:00 2001 From: Duynh ne Date: Fri, 2 Oct 2026 18:14:21 +0700 Subject: [PATCH 2/2] Pin payment 2.8.0 and shipping 1.10.0 The ADR-017 contract releases, which remove the expand-phase aliases in-service. Both passed the full local-stack release audit from scratch. --- CHANGELOG.md | 4 ++++ kubernetes/apps/mockpay.yaml | 2 +- kubernetes/apps/services/payment.yaml | 2 +- kubernetes/apps/services/shipping.yaml | 2 +- 4 files changed, 7 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 311e1f9b7..f99335d8d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -342,6 +342,10 @@ Skeleton (copy what you need): and compose pins, one grouped PR per plugin. #### Services +- **payment v2.8.0 (and mockpay) and shipping v1.10.0 on Kind** — the + ADR-017 contract releases that remove the expand-phase aliases. Both passed + the full local-stack release audit (A/B/C + C22) from scratch, with A7 + asserting the shipping alias is 404. - **payment v2.7.0 (and mockpay) and admin-service v0.4.3 on Kind.** payment serves the canonical protected paths beside their deprecated aliases; the Backoffice calls the canonical ones and its runtime image carries diff --git a/kubernetes/apps/mockpay.yaml b/kubernetes/apps/mockpay.yaml index ed9e6e97b..817c8e157 100644 --- a/kubernetes/apps/mockpay.yaml +++ b/kubernetes/apps/mockpay.yaml @@ -55,7 +55,7 @@ spec: # still. Re-aligned as an ADR-053-train ride-along BEFORE the first Kind # bring-up, because mockpay is on that path (the saga charges through it, # and the F1 GameDay finding was precisely an image skew here). - tag: "2.7.0" # {"$imagepolicy": "flux-system:payment:tag"} + tag: "2.8.0" # {"$imagepolicy": "flux-system:payment:tag"} pullPolicy: IfNotPresent args: ["mockpay"] service: diff --git a/kubernetes/apps/services/payment.yaml b/kubernetes/apps/services/payment.yaml index 1cb913558..7d58e7afa 100644 --- a/kubernetes/apps/services/payment.yaml +++ b/kubernetes/apps/services/payment.yaml @@ -52,7 +52,7 @@ spec: # registered is traced and logged as an ordinary 404 rather than vanishing. # Compose E2E audit passed on this code before the tag; measured 0 -> 15 spans # for /metrics and 0 for /health and /ready, unchanged. - image_tag: "2.7.0" # {"$imagepolicy": "flux-system:payment:tag"} + image_tag: "2.8.0" # {"$imagepolicy": "flux-system:payment:tag"} namespace: payment # RFC-0024 P3: authmw consumer — the domain template injects the explicit # OIDC_ISSUER/OIDC_JWKS_URL pair (Keycloak realm; pkg v0.37.0 contract). diff --git a/kubernetes/apps/services/shipping.yaml b/kubernetes/apps/services/shipping.yaml index 3a329535f..b18412d10 100644 --- a/kubernetes/apps/services/shipping.yaml +++ b/kubernetes/apps/services/shipping.yaml @@ -27,7 +27,7 @@ spec: # registered is traced and logged as an ordinary 404 rather than vanishing. # Compose E2E audit passed on this code before the tag; measured 0 -> 15 spans # for /metrics and 0 for /health and /ready, unchanged. - image_tag: "1.9.1" # {"$imagepolicy": "flux-system:shipping:tag"} + image_tag: "1.10.0" # {"$imagepolicy": "flux-system:shipping:tag"} namespace: shipping # Runs pkg/authmw (cmd/main.go) and serves /protected/, so both realm # pairs belong in the manifest rather than in compiled defaults.