mirror of
https://github.com/zap-proto/zip.git
synced 2026-10-19 15:38:57 +00:00
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]>
94 lines
2.8 KiB
Go
94 lines
2.8 KiB
Go
// subsystem-mount example — HIP-0106 Mount(app, deps) idiom.
|
|
//
|
|
// One zip.App is composed from N subsystems via the Mount(...) contract.
|
|
// Each subsystem is a Go package that exposes:
|
|
//
|
|
// func Mount(app *zip.App, deps Deps) error
|
|
//
|
|
// matching the gin-side hanzoai/commerce/checkout.MountPublic pattern.
|
|
//
|
|
// Each subsystem declares TYPED ops, which is what makes composition compose the
|
|
// whole surface: the assembled binary's OpenAPI document, MCP tool list and
|
|
// command line are the union of what its subsystems registered, with nothing
|
|
// written twice and no subsystem knowing the others exist. A subsystem that
|
|
// registered untyped routes would contribute traffic and nothing else.
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"log"
|
|
|
|
"github.com/zap-proto/zip"
|
|
"github.com/zap-proto/zip/middleware"
|
|
)
|
|
|
|
// Deps is the typed dependency bag a unified Hanzo binary builds once
|
|
// and threads through every Mount(). Real deployments inject IAM, KMS,
|
|
// DocDB, ClickHouse, etc. — this example uses an opaque struct.
|
|
type Deps struct {
|
|
OrgScoped func(ctx context.Context, org string) any
|
|
}
|
|
|
|
// GetUserIn addresses one user. `id` is the path segment: the URL is the
|
|
// addressing authority, so it binds from there whatever else the request says.
|
|
type GetUserIn struct {
|
|
ID string `json:"id"`
|
|
}
|
|
|
|
// User is one user record.
|
|
type User struct {
|
|
ID string `json:"id"`
|
|
Org string `json:"org"`
|
|
}
|
|
|
|
// Health is what the probe answers.
|
|
type Health struct {
|
|
Status string `json:"status"`
|
|
}
|
|
|
|
// Nothing is an operation that takes no input.
|
|
type Nothing struct{}
|
|
|
|
// usersSubsystem mounts user routes at /v1/users.
|
|
type usersSubsystem struct{}
|
|
|
|
func (usersSubsystem) Mount(app *zip.App, _ Deps) error {
|
|
// The subsystem owns a prefix, so it takes a Group and declares its ops on
|
|
// that — the prefix is part of every op it registers, and the composition
|
|
// root never repeats it.
|
|
users := app.Group("/v1/users")
|
|
|
|
// GetUser returns one user, scoped to the caller's org.
|
|
users.Get("/:id", func(ctx context.Context, in *GetUserIn) (*User, error) {
|
|
// The gateway's identity reaches a typed handler through the ctx —
|
|
// c.Org() is the untyped spelling of the same headers.
|
|
return &User{ID: in.ID, Org: zip.CallerOf(ctx).Org}, nil
|
|
})
|
|
return nil
|
|
}
|
|
|
|
// healthSubsystem mounts health probes.
|
|
type healthSubsystem struct{}
|
|
|
|
func (healthSubsystem) Mount(app *zip.App, _ Deps) error {
|
|
app.Get("/healthz", func(context.Context, *Nothing) (*Health, error) {
|
|
return &Health{Status: "ok"}, nil
|
|
})
|
|
return nil
|
|
}
|
|
|
|
func main() {
|
|
app := zip.New(zip.Config{AppName: "subsystem-mount"})
|
|
app.Use(middleware.Recover(), middleware.RequestID())
|
|
|
|
deps := Deps{}
|
|
if err := (healthSubsystem{}).Mount(app, deps); err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
if err := (usersSubsystem{}).Mount(app, deps); err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
|
|
log.Fatal(app.Listen("http://:8080"))
|
|
}
|