zeekayandHanzo Dev
5f71d2496b
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]>
zip middleware
Generic middleware for the zip framework. Auth-specific middleware
(JWT validation, identity-header stripping) lives in
github.com/hanzoai/gateway/middleware
— see "Why auth lives in gateway" below.
Available middleware
| Name | Purpose |
|---|---|
Recover() |
panic → JSON 500 |
Logger(luxlog.Logger) |
request log via luxfi/log |
RequestID() |
X-Request-Id propagation |
Timeout(d) |
per-request ctx deadline |
MaxBody(n) |
request size limit |
CORS(opts) |
standard CORS |
RateLimit(opts) |
per-key token bucket |
Telemetry(o11yClient) |
OTel span + request metrics |
Why auth lives in gateway
JWT validation + identity-header minting are the responsibility of the
gateway subsystem (per HIP-0106). Other subsystems mounted inside the
unified cloud binary trust the gateway-minted X-Org-Id header and do
NOT re-validate JWTs themselves — re-running JWT validation per-subsystem
is wasteful and risks divergent validation rules.
Subsystems that need to ASSERT the request was gateway-minted import
github.com/hanzoai/gateway and call gateway.AssertGatewayMinted(c).
Pipeline order
Recommended order for a service that mounts zip behind hanzoai/gateway:
app.Use(
middleware.Recover(), // 1. always first
middleware.RequestID(), // 2. mint request id
middleware.Logger(app.Logger()), // 3. log with request id
middleware.Telemetry(o11y), // 4. metrics
middleware.RateLimit(rlCfg), // 5. limit
middleware.CORS(corsCfg), // 6. last — close to response
)
JWT validation + identity-header stripping/minting is owned by the
gateway subsystem; see
github.com/hanzoai/gateway/middleware.