golem15/summercms
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(02): resolve parity proxy port split

Browse Source
This commit is contained in:
Jakub Zych
2026-09-16 16:27:50 +02:00
parent 9368a18530
commit a109b52ec6
2 changed files with 4 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.planning/phases/02-api-parity-harness-bootstrap/02-CONTEXT.md
View File

@@ -21,7 +21,7 @@ Not in this phase: any ported endpoint (Phase 3 ports the first one), the OpenAP
### Recording strategy ### Recording strategy
- **D-01:** Two capture paths, both producing the same fixture format. A recording reverse proxy (`summer parity:proxy`) sits in front of the PHP backend on `:8422`; the Nuxt dev app (`NUXT_DEV_BACKEND_ORIGIN`) and the MCP server (`FONOTEKA_API_URL`) are pointed at it and real sessions are recorded as ordered flows. A scripted runner (`summer parity:record`) drives a route manifest to guarantee coverage of all 154 routes, including error cases (404, 422, 401, 423, throttled). - **D-01:** Two capture paths, both producing the same fixture format. A recording reverse proxy (`summer parity:proxy`) sits in front of the PHP backend on `:8422`; the Nuxt dev app (`NUXT_DEV_BACKEND_ORIGIN`) and the MCP server (`FONOTEKA_API_URL`) are pointed at it and real sessions are recorded as ordered flows. A scripted runner (`summer parity:record`) drives a route manifest to guarantee coverage of all 154 routes, including error cases (404, 422, 401, 423, throttled).
- **D-02:** Recordings are made against a local PHP backend (`php artisan serve --port=8422`) on a fresh database holding a small deterministic parity dataset. Never against the developer's ad-hoc dev database and never against production. - **D-02:** Recordings are made against a local PHP backend (`php artisan serve --host=127.0.0.1 --port=8423`) on a fresh database holding a small deterministic parity dataset. The recording proxy binds `127.0.0.1:8422`, and Nuxt/MCP point to that proxy. Never record against the developer's ad-hoc dev database or production. The user confirmed this port split during planning on 2026-09-16.
- **D-03:** The parity dataset is created through the PHP API itself in a recorded seed flow (onboarding bootstrap, register, login, create collection, albums, artists, genres, styles, invitations, personal tokens, and so on). Only what the API cannot create (backend admin user, OAuth client via the existing `oauth-client` artisan command) uses artisan. No seeder code is added to the PHP repo; the PHP originals stay untouched. - **D-03:** The parity dataset is created through the PHP API itself in a recorded seed flow (onboarding bootstrap, register, login, create collection, albums, artists, genres, styles, invitations, personal tokens, and so on). Only what the API cannot create (backend admin user, OAuth client via the existing `oauth-client` artisan command) uses artisan. No seeder code is added to the PHP repo; the PHP originals stay untouched.
- **D-04:** The recorder and replayer are `summer parity:proxy`, `summer parity:record` and `summer parity:replay` commands implemented on the Phase 1 `bonfire` command interface, not a standalone binary and not `go test` env-var switches. Phase 2 waits for Phase 1's command kernel. - **D-04:** The recorder and replayer are `summer parity:proxy`, `summer parity:record` and `summer parity:replay` commands implemented on the Phase 1 `bonfire` command interface, not a standalone binary and not `go test` env-var switches. Phase 2 waits for Phase 1's command kernel.

6
.planning/phases/02-api-parity-harness-bootstrap/02-RESEARCH.md
View File

@@ -1,7 +1,7 @@
# Phase 2: API parity harness bootstrap — Research # Phase 2: API parity harness bootstrap — Research
**Researched:** 2026-09-16 **Researched:** 2026-09-16
**Status:** Ready for planning after the two context checkpoints below **Status:** Ready for planning; port split and five-plan count confirmed by user
## What exists ## What exists
@@ -30,7 +30,7 @@
## Risks and decisions to settle ## Risks and decisions to settle
1. **Port collision in locked decisions.** D-01 puts the proxy on `:8422`; D-02 and the PHP README put `php artisan serve` on `:8422`. Both cannot bind the same host address. The simplest local setup is PHP on `127.0.0.1:8423`, proxy on `127.0.0.1:8422`, with Nuxt/MCP pointed at the proxy. That changes D-02's literal PHP port and needs user confirmation or a CONTEXT.md correction before executable plans are written. Another viable arrangement binds PHP to `127.0.0.2:8422` and proxy to `127.0.0.1:8422`, preserving the number but adding host alias complexity. 1. **Port collision resolved.** D-01 originally put the proxy on `:8422`, while D-02 and the PHP README also used `:8422` for PHP. The user chose PHP on `127.0.0.1:8423` and proxy on `127.0.0.1:8422` on 2026-09-16; D-02 in CONTEXT.md now records this split. Nuxt/MCP point at the proxy.
2. **Scope is large.** `QA-01` asks for all 154 routes plus real client flows, while the roadmap's first success criterion says at least one captured route. The plan must satisfy QA-01 and separately show the one-route vertical slice early. It must not turn the 154-route corpus into a future-phase placeholder. 2. **Scope is large.** `QA-01` asks for all 154 routes plus real client flows, while the roadmap's first success criterion says at least one captured route. The plan must satisfy QA-01 and separately show the one-route vertical slice early. It must not turn the 154-route corpus into a future-phase placeholder.
3. **No Go app handler yet.** D-12's in-process app replay cannot honestly run against the real port before Phase 3. Use a synthetic handler with testcontainers in Phase 2 and preserve an app handler wiring seam for Phase 3. `pending|ported` gates Go regressions; PHP self-replay validates the full corpus now. 3. **No Go app handler yet.** D-12's in-process app replay cannot honestly run against the real port before Phase 3. Use a synthetic handler with testcontainers in Phase 2 and preserve an app handler wiring seam for Phase 3. `pending|ported` gates Go regressions; PHP self-replay validates the full corpus now.
4. **Secrets and proxy exposure.** Bind the proxy to loopback, require a fixed upstream URL rather than an arbitrary request-chosen destination, redact auth/cookie/query/body credential sources before disk/log output, reject unsanitized fixtures, and keep fixture writes atomic. Raw fixture bodies can still include private user data, so the parity dataset must contain only deterministic test identities. 4. **Secrets and proxy exposure.** Bind the proxy to loopback, require a fixed upstream URL rather than an arbitrary request-chosen destination, redact auth/cookie/query/body credential sources before disk/log output, reject unsanitized fixtures, and keep fixture writes atomic. Raw fixture bodies can still include private user data, so the parity dataset must contain only deterministic test identities.
@@ -49,4 +49,4 @@
--- ---
*Phase: 02-api-parity-harness-bootstrap* *Phase: 02-api-parity-harness-bootstrap*
*Ready for planning: after port and plan-count checkpoints* *Ready for planning: yes; five plans approved*