App, Group, Operation. A group is a prefix and what holds under it, an operation
is one typed route declared there, and the verb methods are generic methods —
which Go 1.27 allows on a concrete type and still refuses on an interface. So In
and Out come from the handler and the caller writes no type arguments:
users := app.Group("/v1/users")
users.Post("/", api.Create)
mint := users.Group("/mint").With(middleware.Mint(gate))
mint.Post("/deposit", api.Deposit)
A Group is a CLOSED HANDLE: two unexported fields, and no method that hands back
the app, the parent or the fiber underneath. A subsystem given the group at its
own prefix cannot reach above it, so confinement is a property of the type
instead of a rule something has to police — which is what a host needs in order
to hand out a bounded surface and know what comes back.
That is bought by giving up the router interface, deliberately. Router and
OpTarget are gone, and with them the ability to implement a route table outside
this package: a decorator is no longer a router, a gate is middleware on a group,
and a bound is a path. The five package-level verb functions go the same way —
a registration is a method on the thing it registers into.
Raw carries what is not a typed operation: a stream, an upgrade, a probe, a
foreign subtree. It names its method, and it is the longer spelling because
opting out of the typed model is the exception and should read like one.
Co-authored-by: Hanzo Dev <[email protected]>
App.Test says it "builds the program if nothing is live, exactly as serving
would, so a test exercises the same generation a request would". It did not.
Serving calls prepare, which installs the DEFERRED PROJECTIONS — /mcp, the
OpenAPI document, the op-call plane, the plugin route. Building alone installs
none of them, so those four addresses answered 404 under Test and 200 in
production.
That is the worst shape a test can have: it cannot see the surface it was written
to check, and the closer it gets to the real program the more confidently it
reports the wrong thing. hanzoai/cloud's MCP tests only passed because callers
reached for an exported Prepare and remembered to call it — which is why
unexporting Prepare broke them rather than fixing them. The projections belong to
"run the program", not to the caller's discipline.
prepare is sync.Once, so a table test that calls Test in a loop still installs
them once; TestTestPreparesIdempotently holds that.
Co-authored-by: Hanzo Dev <[email protected]>
zeekayandHanzo Dev