refactor(go): shrink internal/api to consumed models-only, adopt generated types in internal/rest - #237
Merged
Conversation
…— date-time→string Go overlay preserves Node's isoMillis wire format past the golden timestamp folding; spec requiredness tightened to Node's actual always-emit behavior; architecture doc §2/§5.5 updated to describe the shipped hand-written-chi design instead of the never-built strict-server one
…onDTO/endpointDTO/authSessionView + status envelopes replaced, response shapes now compile-checked against the frozen spec
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
internal/apiwas 7,485 generated lines (oapi-codegen strict-server + chi plumbing) that nothing imported — the CI drift gate guarded code with zero consumers, anddocs/go-backend-architecture.md§5.5 described a strict-server design that was never built (internal/resthand-writes every handler).Change
Generate only what's consumed.
docs/api/oapi-codegen.yamldropschi-server/strict-server;api.gen.goshrinks 7,485 → 1,409 lines of model types.Go-binding overlay for timestamps. New
docs/api/openapi-go-overlay.yamlbinds everydate-timeproperty to a plain Gostring. Rationale:time.Timemarshals as RFC3339Nano while Node emits.toISOString()millis, and the goldens fold timestamps to placeholders — that format drift would be invisible to the parity oracle. Handlers keep formatting explicitly viarest.isoMillis, so wire bytes stay identical to Node. The overlay is Go-toolchain-local;openapi.yamlstays the language-agnostic contract.Spec requiredness tightened to Node's actual behavior (each verified against the Node source):
TerminalSession.lastActivityAt, all sixAuthSessionViewkeys, and theStatus{Created,Updated,Deleted}fields are always emitted by Node, so they're nowrequired.pnpm api:lintpasses.Adopt the models in
internal/rest.sessionDTO,endpointDTO,authSessionView, and the ad-hoc status-envelope maps are replaced byapi.TerminalSession,api.Endpoint,api.AuthSessionView,api.Status{Created,Updated,Deleted}— response shapes for these routes are compile-checked against the frozen spec, and the drift gate finally guards consumed code. Deliberately not adopted: WebAuthn ceremony envelopes (loose by design), audit pages (serialized frominternal/auditdomain types), pending-action view (discriminated union with custom marshaling).Docs match reality. Architecture doc §2 table + §5.5 now describe the shipped hand-written-chi design, when to revisit strict-server (post-cutover, if the spec unfreezes: re-enable it in
oapi-codegen.yaml; models are already adopted so the remaining migration is handler signatures), and two more doc-reality gaps found along the way (the claimed kin-openapi request-validation middleware; the nonexistentapierrpackage).Net: −6,198 / +145 lines.
Verification
go build ./...,go vet ./..., fullgo test ./...— including the golden parity suite and route-coverage test, exactly the tests that would redden if any wire byte movedscripts/check-api-codegen.sh(CI drift gate) passespnpm api:lint,pnpm spdx:checkpass