Skip to content

refactor(go): shrink internal/api to consumed models-only, adopt generated types in internal/rest - #237

Merged
rado0x54 merged 2 commits into
go-backendfrom
go-api-models-only
Jul 12, 2026
Merged

rado0x54 merged 2 commits into
go-backendfrom
go-api-models-only

Conversation

@rado0x54

Copy link
Copy Markdown
Owner

Problem

internal/api was 7,485 generated lines (oapi-codegen strict-server + chi plumbing) that nothing imported — the CI drift gate guarded code with zero consumers, and docs/go-backend-architecture.md §5.5 described a strict-server design that was never built (internal/rest hand-writes every handler).

Change

Generate only what's consumed. docs/api/oapi-codegen.yaml drops chi-server/strict-server; api.gen.go shrinks 7,485 → 1,409 lines of model types.

Go-binding overlay for timestamps. New docs/api/openapi-go-overlay.yaml binds every date-time property to a plain Go string. Rationale: time.Time marshals 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 via rest.isoMillis, so wire bytes stay identical to Node. The overlay is Go-toolchain-local; openapi.yaml stays the language-agnostic contract.

Spec requiredness tightened to Node's actual behavior (each verified against the Node source): TerminalSession.lastActivityAt, all six AuthSessionView keys, and the Status{Created,Updated,Deleted} fields are always emitted by Node, so they're now required. pnpm api:lint passes.

Adopt the models in internal/rest. sessionDTO, endpointDTO, authSessionView, and the ad-hoc status-envelope maps are replaced by api.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 from internal/audit domain 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 nonexistent apierr package).

Net: −6,198 / +145 lines.

Verification

  • go build ./..., go vet ./..., full go test ./... — including the golden parity suite and route-coverage test, exactly the tests that would redden if any wire byte moved
  • scripts/check-api-codegen.sh (CI drift gate) passes
  • pnpm api:lint, pnpm spdx:check pass

rado0x54 added 2 commits July 12, 2026 10:13
…— 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
@rado0x54
rado0x54 changed the base branch from develop to go-backend July 12, 2026 08:17
@rado0x54
rado0x54 merged commit 02b8278 into go-backend Jul 12, 2026
20 checks passed
@rado0x54
rado0x54 deleted the go-api-models-only branch July 12, 2026 08:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant