Skip to content

chore: trim internal-wiring from the public API surface#97

Merged
joaomdsg merged 1 commit into
mainfrom
chore/trim-public-api-surface
Jun 9, 2026
Merged

chore: trim internal-wiring from the public API surface#97
joaomdsg merged 1 commit into
mainfrom
chore/trim-public-api-surface

Conversation

@joaomdsg

@joaomdsg joaomdsg commented Jun 9, 2026

Copy link
Copy Markdown
Member

Removes/clarifies public surface that existed only for internal wiring or was speculative. Pure API hygiene — no runtime behavior change.

Changes

# Item What & why
1 Export Upcaster RegisterEvent's param was an unexported alias (upcastFn) → godoc showed an un-nameable type. Now type Upcaster = func(old json.RawMessage) (json.RawMessage, error).
2 Delete StateAppCounter Documented as a shipped specialization but zero consumers (only its own unit test). Speculative; dropped until a real need appears. Docs now show the inline StateAppEvents[tick,int64] pattern.
3 Move WithTestServervt.Serve(t, app) The option pulled net/http/httptest into production config.go/app.go for a test-only need. App is its own http.Handler and ServeHTTP dispatches dynamically, so httptest.NewServer(app) is equivalent + order-independent. New vt.Serve auto-closes via t.Cleanup. All call sites migrated; internal package via tests use httptest.NewServer(app) directly (vt→via import cycle bars vt there).
4 Document the sealed readCtx param StateTab.Text / StateAppEvents.Text now state they accept *Ctx or *CtxR, matching the other Read/Text methods. readCtx stays unexported by design (sealing — only *Ctx/*CtxR can satisfy it).

Verification

go build ./..., go vet ./..., gofmt -l (clean), and go test -race ./... — all green.

Four changes, each removing or clarifying surface that was only there for
internal wiring or was speculative:

- Export Upcaster: RegisterEvent's param was an unexported alias (upcastFn),
  so godoc rendered an un-nameable type. Now `type Upcaster = func(...)`.

- Delete StateAppCounter: documented as a shipped specialization but had zero
  consumers (only its own unit test). Speculative surface; dropped until a
  real need appears. docs/distributed-state.md now shows the inline
  StateAppEvents[tick,int64] pattern instead.

- Move WithTestServer out of production into vt.Serve(t, app): the option
  pulled net/http/httptest into production config.go/app.go to serve a
  test-only need. App is its own http.Handler and ServeHTTP dispatches
  dynamically, so httptest.NewServer(app) is equivalent and order-independent.
  Added vt.Serve (auto-closes via t.Cleanup) and migrated all call sites;
  internal `package via` tests use httptest.NewServer(app) directly (vt->via
  import cycle bars vt there).

- Document the sealed readCtx param: StateTab.Text and StateAppEvents.Text now
  state they accept *Ctx or *CtxR, matching the other Read/Text methods, so the
  opaque (intentionally unexported) readCtx in the signature is explained.

Build, vet, gofmt, and `go test -race ./...` all green.
@joaomdsg
joaomdsg merged commit 8195559 into main Jun 9, 2026
6 checks passed
@joaomdsg
joaomdsg deleted the chore/trim-public-api-surface branch June 9, 2026 12:08
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