ssr

Documentation

Index

• func ComposeLayouts(ctx LoadContext, stack LayoutStack, registry LayoutRegistry, body string) (string, error)
• func DefaultErrorHandler(w http.ResponseWriter, r *http.Request, err error)
• func ElementPath(value any, path string) (any, bool)
• func IsNativeRBACGuard(name string) bool
• func LoadPath(data map[string]any, path string) (any, bool)
• func Redirect(url string, status int) error
• func RedirectTarget(err error) (string, int, bool)
• func RedirectTo(url string) error
• func Register(router Router, routes []Route)
• func RegisterRegion(renderer RegionRenderer)
• func RenderRegions(html string, lists []ListSpec, conds []CondSpec, data map[string]any) string
• func RunGuards(ctx LoadContext, names []string, registry GuardRegistry) error
• func RunGuardsWithAuth(ctx LoadContext, names []string, registry GuardRegistry, ...) error
• type CommandEnvelope
• type CondSpec
• type ErrorHandler
• type GuardFunc
  • func NativeRBACGuard(name string, provider auth.Provider) GuardFunc
• type GuardRegistry
• type LayoutFunc
• type LayoutRegistry
• type LayoutStack
• type ListField
• type ListSpec
• type LoadContext
  • func NewLoadContext(request *http.Request, session map[string]any) LoadContext
• type LoadFunc
• type RedirectError
  • func (err RedirectError) Error() string
• type RegionLoadField
• type RegionPatch
  • func RenderInvalidatedRegions(request *http.Request, queries []string) []RegionPatch
• type RegionRenderer
• type Route
• type Router

Functions

func ComposeLayouts

func ComposeLayouts(ctx LoadContext, stack LayoutStack, registry LayoutRegistry, body string) (string, error)

ComposeLayouts wraps body with the declared layout stack. Layouts are listed from outermost to innermost, matching layout root, dashboard semantics.

func DefaultErrorHandler

func DefaultErrorHandler(w http.ResponseWriter, r *http.Request, err error)

DefaultErrorHandler renders a conservative SSR failure response.

func ElementPath

func ElementPath(value any, path string) (any, bool)

ElementPath resolves a dotted field path against an arbitrary value (map, struct, pointer, or interface), mirroring LoadPath's field-matching rules but rooted at a row element or the load data map.

func IsNativeRBACGuard

func IsNativeRBACGuard(name string) bool

IsNativeRBACGuard reports whether name is a built-in role or permission guard.

func LoadPath

func LoadPath(data map[string]any, path string) (any, bool)

LoadPath resolves a declared load {} path from generated SSR load data. Supported values are nested maps with string keys, structs, pointers, and interfaces. Struct fields may be matched by exported Go field name or json tag.

func Redirect

func Redirect(url string, status int) error

Redirect returns an error that generated SSR handlers translate into a no-store local redirect with the provided 3xx status.

func RedirectTarget

func RedirectTarget(err error) (string, int, bool)

RedirectTarget extracts a generated SSR redirect error.

func RedirectTo

func RedirectTo(url string) error

RedirectTo returns an error that generated SSR handlers translate into a no-store local redirect.

func Register

func Register(router Router, routes []Route)

Register adds generated SSR routes to a router.

func RegisterRegion

func RegisterRegion(renderer RegionRenderer)

RegisterRegion records a region renderer by query type. When two renderers register the same query type (the same query backs regions on more than one parameterless page), the type is marked ambiguous and single-flight falls back to the client refetch for it, since the command request cannot tell which page's region the submitter is viewing.

func RenderRegions

func RenderRegions(html string, lists []ListSpec, conds []CondSpec, data map[string]any) string

RenderRegions expands every top-level g:for list and g:if conditional in html by resolving their data from the request-time load data. Field values are always HTML-escaped, preserving GOWDK's escape-by-default contract for request-time server data.

func RunGuards

func RunGuards(ctx LoadContext, names []string, registry GuardRegistry) error

RunGuards executes guard IDs in declaration order.

func RunGuardsWithAuth

func RunGuardsWithAuth(ctx LoadContext, names []string, registry GuardRegistry, provider auth.Provider) error

RunGuardsWithAuth executes guard IDs in declaration order and resolves native RBAC guard IDs such as role:admin and permission:posts.write through provider.

Types

type CommandEnvelope

type CommandEnvelope struct {
	Result  any           `json:"result"`
	Patches []RegionPatch `json:"patches"`
}

CommandEnvelope wraps a command result with its single-flight region patches. A g:command adapter only emits this shape (signalled by the X-GOWDK-Patches response header) when it rendered at least one region; otherwise the raw command result body is returned unchanged, so non-browser callers are unaffected.

type CondSpec

type CondSpec struct {
	Placeholder string
	// SourcePath is the dotted field path for a simple field/!field condition,
	// resolved against the enclosing container. Empty when Expr is set.
	SourcePath string
	Negate     bool
	// Expr is a full bool expression (comparisons, logic, literals) evaluated
	// against the enclosing container at request time. When set it takes
	// precedence over SourcePath/Negate; used for top-level server g:if.
	Expr     string
	Template string
	Fields   []ListField
	Lists    []ListSpec
	Conds    []CondSpec
}

CondSpec describes one server-rendered g:if conditional. Its branch is rendered into the output only when SourcePath resolves to a truthy value (negated when Negate is set). The branch shares the enclosing container scope, so its fields and nested regions resolve against the same data as the conditional itself.

type ErrorHandler

type ErrorHandler func(http.ResponseWriter, *http.Request, error)

ErrorHandler renders request-time SSR failures.

type GuardFunc

type GuardFunc = guard.Func

GuardFunc authorizes one generated request-time route access check.

func NativeRBACGuard

func NativeRBACGuard(name string, provider auth.Provider) GuardFunc

NativeRBACGuard returns a guard for a native role or permission guard ID.

type GuardRegistry

type GuardRegistry = guard.Registry

GuardRegistry resolves guard IDs to executable guard functions.

type LayoutFunc

type LayoutFunc func(LoadContext, string) (string, error)

LayoutFunc wraps already-rendered child HTML with request-aware layout HTML.

type LayoutRegistry

type LayoutRegistry map[string]LayoutFunc

LayoutRegistry maps layout IDs to request-aware layout functions.

type LayoutStack

type LayoutStack []string

LayoutStack is the ordered set of request-time layouts for an SSR page.

type ListField

type ListField struct {
	// Placeholder is the unique token inside the template replaced per render.
	Placeholder string
	// Path is the dotted path to the value (item-relative inside a row, or a
	// load field path inside a top-level region). Ignored when Index is true.
	Path string
	// Index is true when this field substitutes the zero-based row index.
	Index bool
	// URL is true when this field is substituted into a URL-bearing attribute.
	URL bool
}

ListField is one per-row scalar substitution inside a region template.

type ListSpec

type ListSpec struct {
	// Placeholder is the unique token embedded in the parent template that the
	// rendered rows replace.
	Placeholder string
	// SourcePath is the dotted path to the slice, resolved against the enclosing
	// container (the request-time load data at the top level, or a parent row
	// element when nested).
	SourcePath string
	// RowTemplate is the escaped HTML rendered once per slice element, still
	// containing this spec's Field, List, and Cond placeholders.
	RowTemplate string
	// Fields are the per-row scalar interpolations, each escaped at request time.
	Fields []ListField
	// Lists are nested g:for lists found inside RowTemplate.
	Lists []ListSpec
	// Conds are g:if conditionals found inside RowTemplate.
	Conds []CondSpec
}

ListSpec describes one server-rendered g:for list. It is generated at build time from a request-time page view and consumed by RenderRegions at request time. A spec is a tree: Lists and Conds describe nested g:for lists and g:if conditionals whose data is resolved relative to each parent row.

type LoadContext

type LoadContext = guard.Context

LoadContext is passed to generated request-time load {} functions.

func NewLoadContext

func NewLoadContext(request *http.Request, session map[string]any) LoadContext

NewLoadContext creates the first-slice request context for generated SSR load functions. Session storage is intentionally caller-supplied until the SSR addon defines secure session defaults.

type LoadFunc

type LoadFunc func(LoadContext) (map[string]any, error)

LoadFunc is generated from a request-time load {} block.

type RedirectError

type RedirectError struct {
	URL    string
	Status int
}

RedirectError asks generated SSR handlers to issue a safe local redirect.

func (RedirectError) Error

func (err RedirectError) Error() string

type RegionLoadField

type RegionLoadField struct {
	Path        string
	Placeholder string
	URL         bool
}

RegionLoadField is one scalar load {} substitution scoped to a region. It mirrors the page-level SSRLoadReplacement but is applied to a single region's rendered HTML.

type RegionPatch

type RegionPatch struct {
	Query string `json:"query"`
	HTML  string `json:"html"`
}

RegionPatch is the rendered HTML for one invalidated g:query region, returned inline in a g:command response so the submitting client applies it without a second page fetch (true single-flight).

func RenderInvalidatedRegions

func RenderInvalidatedRegions(request *http.Request, queries []string) []RegionPatch

RenderInvalidatedRegions renders the registered g:query regions for the given invalidated query types, using request for load context. Query types without an eligible, unambiguous renderer (or whose load fails) are skipped so the client refetches them. The returned patches follow the order of queries.

type RegionRenderer

type RegionRenderer struct {
	// QueryType is the fully-qualified query type that names this region, matching
	// the X-GOWDK-Queries header and the region's data-gowdk-query-type attribute.
	QueryType string
	// Template is the region element's outer HTML with its region and scalar
	// placeholders intact, ready for RenderRegions.
	Template string
	// Lists and Conds are the page's top-level g:for/g:if specs that fall inside
	// this region's template.
	Lists []ListSpec
	Conds []CondSpec
	// LoadFields are the scalar load {} substitutions that appear in the template.
	LoadFields []RegionLoadField
	// Load runs the region's page load {} against the command request, yielding
	// the same data a page GET would resolve the region from.
	Load func(*http.Request) (map[string]any, error)
}

RegionRenderer renders one request-time g:query region standalone from its page's load data. The app generator lowers each eligible region into a RegionRenderer and registers it by fully-qualified query type, so a g:command can render exactly the regions it invalidated inline in its response.

A region is only registered when it is renderable without route context the command request lacks: its page has no dynamic route params and its template carries no route-param placeholder. Everything else falls back to the client refetch path.

type Route

type Route struct {
	Pattern string
	Handler http.Handler
}

Route is one generated SSR route binding.

type Router

type Router interface {
	Handle(pattern string, handler http.Handler)
}

Router registers generated SSR page handlers.