Publish httpx as a package of the gonext module
- Dominant language
- Go
- Stars
- 0
- Forks
- 0
- Avg merge
- 3h 1m
- Merged PRs (30d)
- 29
Description
Move `httpx` out of `templates/backend/internal/presentation/httpx` and into a published package at gonext root, so generated projects import it rather than vendor a copy.
## This overrides a recorded deferral
`roadmap.md`'s *When `httpx` would have to be published* currently frames this as "a decision deferred, not avoided", gated on a trigger: **if feature packs ever become installable modules rather than scaffolded code**. That trigger is #21, still in Backlog. The deferral is being overridden ahead of its own trigger condition, deliberately.
The argument for publishing is unchanged and was already written down: a scaffolded `httpx` is a structurally identical but *distinct* type at an `internal`-sealed path in every generated project. A third-party feature pack — a Redis rate limiter, a background worker's admin routes — cannot mount an endpoint at all, because it has no way to name the `httpx.Register` or `httpx.Group` of the project it is being installed into. That is precisely the constraint publishing `auth/` solved.
## Consequences to accept explicitly
These are the reasons it was deferred. They do not disappear; they are the price.
- **A published contract pinned to the API protocol engine.** `httpx` imports Huma. `auth/` is stdlib-only by deliberate design, so a project taking gonext as a dependency compiles none of the CLI's tree. Publishing `httpx` breaks that property and ties a permanent semver commitment to Huma's own versioning, from a repo still at v0. A Huma major bump becomes a gonext major bump.
- **The publication bar in `roadmap.md` is not met on its own terms.** The recorded rule is that a port earns publication once its *second* implementation actually exists, and only when someone outside the repo might plausibly write one. `auth/` clears it — Clerk, Supabase and Auth0 are real and external. `httpx` has one implementation, so this is being published on an architectural argument rather than an observed shape.
- **A published contract cannot be withdrawn** without breaking consumers.
## Interaction with #37
This does not stand alone. Epic #37 reopened whether the published contract should be a separately tagged runtime module (`core`/`lib`, name undecided). If that lands, the question becomes *which module `httpx` goes in* — and a Huma-importing package sits badly in a module whose selling point is a small dependency footprint. **Settle #37's shape before doing the move**, or the move gets done twice.
## Scope of the move
- New package at gonext root holding `Ctx`, `NewCtx`, `Register`, `Group`, `NewGroup`, `Errors`, `ErrorMapping`, `Map`, the five verb functions, and the options.
- All eleven registrations in `templates/` import it instead of the project-local path; `[PROJECT-NAME]/backend/internal/presentation/httpx` disappears from the template tree.
- The `forbidigo` rule and its `internal/presentation/httpx/` path exclusion in `templates/.golangci.yml` need rework — the exclusion currently keys on a path that will no longer exist in a generated project.
- `roadmap.md`'s *When `httpx` would have to be published* section is rewritten from a deferral into a decision.
- The *Out of scope* line in `docs/superpowers/specs/2026-08-31-http-route-grouping-design.md` becomes stale and should be marked as superseded rather than silently left.
- `templates/CLAUDE.md`'s *Guarding an endpoint* needs its import path updated.
## Context
The `httpx.Group` this would publish landed in #50 (closes #48), which deliberately shipped it scaffolded per the then-current design. #50 is unaffected by this issue and should merge as-is; this is the follow-up that relocates it.
Contributor guide
No contributing guide indexed for this repository
Research direction
Settle epic #37's module shape first, then inspect templates/backend/internal/presentation/httpx and the eleven registrations under templates/. Review templates/.golangci.yml, roadmap.md, docs/superpowers/specs/2026-08-31-http-route-grouping-design.md, and templates/CLAUDE.md. Done means the root package is published, generated projects import it, the old template path is gone, and all listed documentation and lint references are updated.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100