handlergen

package
v1.80.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 3, 2026 License: MIT Imports: 9 Imported by: 0

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

View Source
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

func Emit

func Emit(cfg Config, anns []Annotation) ([]byte, error)

Emit renders the generated source for one package. Returns (nil, nil) when anns contains no primary registration (caller should then write no file).

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

type Result struct {
	Path    string
	Content []byte
}

Result is one generated file: the path to write and its formatted content.

func Generate

func Generate(sites []Site, outName string) ([]Result, error)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL