Documentation
¶
Overview ¶
Package routetable exposes the route table ghtmx derives from Go source, so a consuming project can assert in its own tests that the routes the toolchain believes in are the routes its framework really serves (FR-064).
`ghtmx generate -check` verifies template-versus-generated-code drift. It does not — and cannot — verify annotation-versus-reality drift: once a project takes the //ghtmx:route escape hatch and registers routes outside routeScope, nothing checks that the annotated paths still match what the framework serves. Load reads the same table `ghtmx routes` prints, and Diff compares it against a list the consumer dumps from their own router, which turns that invariant back into a test.
This package is for build- and test-time tooling. Application code renders through the root package and an adapter and never needs it.
Index ¶
Constants ¶
const AnyVerb = "*"
AnyVerb is the verb of a route registered without one — a net/http pattern carrying no method, which serves every verb. It is rendered as "*", matching `ghtmx routes -json`.
Variables ¶
This section is empty.
Functions ¶
func NormalizePath ¶
func NormalizePath(path string, style ParamStyle) (string, []string)
NormalizePath converts a router-flavoured pattern to the normalized form the table uses, returning the path and its ordered parameter names (wildcards suffixed with "..."). It is the toolchain's own normalizer, so a consumer comparing framework paths against Load's output cannot drift from it.
Types ¶
type Mismatch ¶
type Mismatch struct {
Kind MismatchKind
Verb string
Path string
// Declared and Actual are the routes from each side; the one absent
// for the kind is nil.
Declared *Route
Actual *Route
}
Mismatch is one disagreement, carrying whichever side(s) exist.
func Diff ¶
Diff compares the route table ghtmx derived (declared — from Load, or from `ghtmx routes -json`) against the routes a framework really serves (actual — dumped by the consumer from its own router, then passed through Normalize). Routes are matched on verb and normalized path.
The result is sorted by path then verb, so a failing test prints the same report every run. An empty result means the two agree.
A handler comparison is only made when the actual side names one: most routers report paths and not Go symbols, so an empty HandlerName on the actual side means "not reported", never "different".
type MismatchKind ¶
type MismatchKind string
MismatchKind classifies one disagreement between two route lists.
const ( // KindMissing: declared holds a route actual does not — the // toolchain believes in a route the router never serves, so its // template bindings generate URLs that 404. KindMissing MismatchKind = "missing" // KindUnexpected: actual holds a route declared does not — the // router serves a route the toolchain cannot see, so no template can // bind it. KindUnexpected MismatchKind = "unexpected" // KindHandler: both hold the verb and path, but disagree on the // handler symbol. KindHandler MismatchKind = "handler" )
type ParamStyle ¶
type ParamStyle int
ParamStyle is a router flavour's path-parameter syntax.
const ( // BraceStyle is net/http and chi: /users/{id}, /files/{path...}. BraceStyle ParamStyle = ParamStyle(routes.BraceStyle) // ColonStyle is echo, gin, and fiber: /users/:id, /files/*. ColonStyle ParamStyle = ParamStyle(routes.ColonStyle) )
type Route ¶
type Route struct {
// Verb is the HTTP method, or "*" for a route serving every verb.
Verb string `json:"verb"`
// Path is the normalized pattern, using {name} and {name...}
// regardless of the source router's flavour.
Path string `json:"path"`
// OriginalPath preserves the registering router's own syntax.
OriginalPath string `json:"originalPath"`
// Params are the ordered path parameter names, wildcards suffixed
// with "...".
Params []string `json:"params,omitempty"`
// HandlerPkg is the import path of the handler's package.
HandlerPkg string `json:"handlerPackage"`
// HandlerName is the handler symbol's name.
HandlerName string `json:"handlerName"`
// Origin is "discovered" or "declared" (by a //ghtmx:route
// annotation).
Origin string `json:"origin"`
// Recognizer names the router flavour that produced the route:
// nethttp, chi, echo, gin, fiber, or annotation.
Recognizer string `json:"recognizer"`
// Source is the registration or declaration site, "file:line:col".
Source string `json:"source"`
// trailing "nav" marker), exempting it from GHTMX-W0104.
NavOnly bool `json:"navOnly,omitempty"`
}
Route is one entry of the route table. The JSON tags are the schema `ghtmx routes -json` emits, so its output unmarshals into []Route directly.
func FromTable ¶
FromTable converts an internal route table. It is the single place the public shape is built, so `ghtmx routes -json` and this package cannot describe the same route differently.
func Load ¶
Load runs route discovery over the module rooted at dir — the same analysis `ghtmx routes` performs, honouring that project's ghtmx.json (routeScope in particular) — and returns the table in the order the command prints it: by path, then verb.
Discovery diagnostics are not returned: a project whose table this reports on has already seen them from `ghtmx generate`. An error means the packages could not be loaded at all.
func Normalize ¶
func Normalize(rs []Route, style ParamStyle) []Route
Normalize returns a copy of rs with every Path normalized from style, keeping the input pattern in OriginalPath. Use it on a list dumped from a framework router — whose paths are in that router's own syntax — before handing it to Diff.