Documentation
¶
Overview ¶
Package embedcheck is the build-time gate for server actions on embeddable surfaces.
G.serverAction does not work inside an embed frame: the action registry is app-global, keyed by (componentID, action) with no relationship to any surface, so honouring an embed grant at /__gofastr/action would let a credential minted for one surface invoke any action registered anywhere. framework/uihost already panics at boot when a surface's screen registers one (enforceNoServerActionsOnEmbeds in embed_actions.go). This package catches the same condition at `gofastr build` / `make build`, before anything runs.
The signal ¶
The property "this action posts to the server" is carried by the ClientJS passed to component.WithClientJS. The compiler rewrites only the canonical "G.serverAction(" spelling. This analyzer also detects legal whitespace before "(", then reports the canonical spelling instead of allowing a dead call to ship.
component.Server(...) and ActionDef.Server look like the marker but are dead API: Server(...) has one call site in the whole repo (a unit test), and On() never sets ActionDef.Server nor does the compiler read it. Keying on either would record a *declaration* rather than the property — the exact failure mode issue #150 rejected a marker interface for — so they are deliberately not matched.
Reachability, and where each step gives up ¶
embed.Surface now carries the screen value, so the link from a surface to the component tree it renders is a Go value graph. findFindings resolves as much of it as go/analysis + go/types honestly can, per package:
- embed.Surface{...} composite literals — identified by resolved type, so a same-named struct elsewhere is never mistaken for one.
- The Screen field → the app.NewScreen(path, comp) call that built it, following one level of identifier → initializer within the package.
- comp → its concrete named type, following an identifier whose declared type is the component.Component interface back to its initializer.
- that type's Actions() method → executable component.On(...) calls with a literal component.WithClientJS(...) option containing a G.serverAction call outside JavaScript comments and strings.
The analyzer gives up on computed screens, runtime-selected components, cross-package screen/component values, non-literal ClientJS, and registrations nested inside a function literal. The boot walk inspects the compiled registry and catches those cases when they execute. Silence is intentional when static reachability is not provable.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Analyzer = &analysis.Analyzer{
Name: "check_embed",
Doc: "report embeddable surfaces whose screen's component registers a G.serverAction, which is refused inside a frame",
Run: runPass,
}
Analyzer is the go/analysis pass. analysistest exercises it directly, and a future `go vet` attachment would run it; the cmd/check-embed CLI and the `gofastr build` gate both call the same findFindings core via Check.
Functions ¶
This section is empty.
Types ¶
type Finding ¶
type Finding struct {
Pos token.Pos
Surface string // the surface Name; "<dynamic>" when not a string literal
Component string // concrete component type name
Action string // the On() event name; "<dynamic>" when not a string literal
}
Finding is one provable server action reachable from an embeddable surface.
func Check ¶
Check loads the non-test packages matching pattern (e.g. "./...") and returns any server-action-on-embed finding. It is the shared driver used by the cmd/check-embed CLI and the `gofastr build` gate, so both report identically.
Findings take precedence over load errors: a real violation is the actionable signal and is returned with a nil error. When a package failed to parse or type-check and no findings were produced, Check returns that as an error so the caller can surface an infrastructure failure rather than a false "clean".
Source Files