Documentation
¶
Overview ¶
Package handlergen turns structured handler annotations into the committed `*_gen.go` source that registers them in decorator form (see decorate/DESIGN.md, Phase 2).
It is intentionally decoupled from the scanner: Emit takes a plain []Annotation, so it is fully testable before deco.Scan exists. Phase 4 maps deco.Hit → handlergen.Annotation.
The emitted file calls github.com/paulmanoni/nexus/decorate, so a plain `go build`/`go install` (which never run a generate step or overlay) compiles the registrations as ordinary Go — the invariant that keeps nexus go-install-able.
Index ¶
Constants ¶
const DefaultModule = "app"
DefaultModule is the dashboard module name used when annotations live in the main package (or a package whose name makes a poor module label) — so those endpoints still group under a sensible node instead of "main".
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Annotation ¶
type Annotation struct {
Func string // the annotated function's name (same package as the generated file)
Keyword string // "rest","query","mutation","subscription","ws","worker","provide","auth","use"
Args []string // raw tokens after the keyword
File string // source file of the directive (as the caller wants it shown in errors)
Line int // source line — errors point here; also gives statements a stable order
Imports []string // import lines this directive's expression needs (//@use); e.g. `"github.com/x/rl"`
Recv, Method string // set for a method: its receiver type and name (Func is the method expression)
TypeLevel bool // a directive on a type (//@controller and its modifiers); Func is the type name
}
Annotation is one //@ directive found on a function. A function may carry one PRIMARY annotation (the registration kind) plus zero or more MODIFIER annotations (auth, …) that become per-op options.
type Config ¶
type Config struct {
Package string // package clause of the generated file (required)
Module string // nexus.Module name for the group; defaults to Package
Path string // nexus.Path prefix for the module (REST + GraphQL); "" = none
RoutePrefix string // nexus.RoutePrefix (REST-only) for the module; "" = none
NexusImport string // default github.com/paulmanoni/nexus
DecorateImport string // default github.com/paulmanoni/nexus/decorate
AuthImport string // default github.com/paulmanoni/nexus/extension/auth
// RouterDecls are this package's //@router declarations, emitted as
// nexus.RouterDecl calls; KnownRouters is every declared name across the
// scan, for validating //@on references. AutoRouter, when set (the
// package-named //@router <prefix> form), is the router every op in this
// package registers on unless it says //@on elsewhere.
RouterDecls []RouterDecl
KnownRouters map[string]bool
AutoRouter string
}
Config controls the generated file.
type Result ¶
Result is one generated file: the path to write and its formatted content.
func Generate ¶
Generate groups sites by directory and emits one `outName` file per package that has at least one primary registration. Results are sorted by Path for determinism; a directory whose annotations produce no registration is skipped (no empty file written). It errors if a directory mixes package names (a scan invariant violation).
type RouterDecl ¶ added in v1.65.0
type RouterDecl struct {
Name, Prefix, Parent string
AuthExpr string // "", or e.g. `auth.Requires("ADMIN")`
}
RouterDecl is one //@router declaration ready to emit.
type Site ¶
type Site struct {
Dir string // directory of the source file (one generated file per dir/package)
Pkg string // package name in that dir
File string // source file, as it should appear in error positions
Func string
Keyword string
Args []string
Line int
Imports []string // import lines a //@use expression needs (resolved by the caller)
// Recv and Method are set when the annotated function is a method: Recv
// is the receiver's type name, Method the method's, and Func the method
// expression the generated code calls, e.g. "(*UsersController).Show".
Recv, Method string
// TypeLevel marks a directive on a type's doc comment — //@controller and
// its //@auth//@session//@use modifiers. Func is then the type's name.
TypeLevel bool
// PackageLevel marks a directive found on the package doc comment
// (//@module, //@path, //@routeprefix) — it configures the generated
// module instead of registering a function.
PackageLevel bool
}
Site is one annotation plus the location context needed to route it to the right generated file: one file is emitted per package directory. Phase 4's CLI maps a deco scan Hit → Site (Hit.Pos.Filename's dir, Pkg, Func, Keyword, Args, Pos.Line); keeping Site deco-free lets the grouping logic be tested without the scanner.