Documentation
¶
Overview ¶
Package renderx implements the SSR render pipeline (QuickJS engine pool, bundle build, prerender, cache, SEO companions).
This file owns the pipeline's TanStack Router SSR affordances. The JavaScript source of truth for both values below is packages/runtime/src/router-tanstack.tsx:
- PRELUDE_SHIMS — the QuickJS prelude addendum (URLSearchParams + AbortController) every TanStack SSR bundle needs before it evaluates.
- ESBUILD_ALIASES — the esbuild alias pinning @tanstack/router-core/isServer to the server variant. The default (client) variant evaluates `window?.origin` inside the sandbox, where window is deliberately never defined, and crashes the render.
The Go render pipeline must carry an executable copy of both: it builds the prelude string and the esbuild alias map natively, so a TS-only constant cannot reach it. Keeping that copy here (rather than in every product) exists because the alternative is a hand-maintained mirror per TanStack consumer: the TS runtime moves, the product copy does not, and the product silently runs an outdated shim with zero detection (exactly what happened in v0.10.1). Products import renderx.TanstackPrelude and renderx.AppendTanstackAliases instead of mirroring the constants.
tanstack_test.go is the drift guard: it parses router-tanstack.tsx and fails when this file diverges from the TS source. The framework repo is where drift can happen, so the guard runs there; from a module cache (no packages/ checkout) it skips.
Index ¶
- Constants
- Variables
- func AffectedPatterns(pattern string) []string
- func AppendTanstackAliases(base map[string]string, webDir string) map[string]string
- func BuildSSRBundle(opts BuildOptions) ([]byte, error)
- func DefaultPoolSize() int
- func DefaultSSRAliases(webDir, packagesDir string) map[string]string
- func ExpandPath(pattern string, params Params) (string, bool)
- func Handler(deps HandlerDeps) http.Handler
- func IndexNow(ctx context.Context, deps IndexNowDeps, urls []string) error
- func Invalidate(ctx context.Context, pattern string, params Params) error
- func PropsSHA256(propsJSON []byte) string
- func Reconcile(routes []RouteSpec) error
- func ReconcileEngine(ctx context.Context, r Renderer) error
- func Refresh(ctx context.Context, pattern string, params Params) error
- func RegisterDep(pagePattern, dependsOnPattern string)
- func RegisterLoader(pattern string, fn LoaderFn)
- func RegisterPaths(pattern string, fn PathsFn)
- func RegisterService(s *Service)
- func RenderDocument(doc Document) ([]byte, error)
- func ResetForTest()
- func RobotsHandler(opts RobotsOptions) http.Handler
- func SitemapHandler(routes []RouteSpec, baseURL string, opts SitemapOptions) http.Handler
- func TanstackPrelude() string
- func ValidParamValue(v string) bool
- func ValidateParams(p Params) error
- func ViteBuildID(data []byte) string
- func ViteManifestFiles(data []byte) ([]string, error)
- type BuildOptions
- type CacheConfig
- type CacheEntry
- type DevHandler
- type DevHandlerDeps
- type Directive
- type DirectiveSink
- type Document
- type EnginePool
- type HandlerDeps
- type HeadEntry
- type Hydrate
- type IndexNowDeps
- type LayeredCache
- func (c *LayeredCache) Delete(ctx context.Context, paths ...string) error
- func (c *LayeredCache) EvictMatching(ctx context.Context, match func(key string) bool) (int, error)
- func (c *LayeredCache) Get(ctx context.Context, path string) (CacheEntry, bool)
- func (c *LayeredCache) GetOrLoad(ctx context.Context, path string, ...) (CacheEntry, error)
- func (c *LayeredCache) GetOrLoadHit(ctx context.Context, path string, ...) (CacheEntry, bool, error)
- func (c *LayeredCache) GetStale(ctx context.Context, path string) (CacheEntry, bool)
- func (c *LayeredCache) Keys() []string
- func (c *LayeredCache) PurgeForeign(ctx context.Context, buildID string) error
- func (c *LayeredCache) Put(ctx context.Context, path string, ent CacheEntry) error
- type LoaderFn
- type Mode
- type PagePath
- type Params
- type PathsFn
- type PoolOptions
- type PrerenderDeps
- type PrerenderManifest
- type PrerenderManifestEntry
- type Registry
- func (r *Registry) AffectedPatterns(pattern string) []string
- func (r *Registry) LookupLoader(pattern string) (LoaderFn, error)
- func (r *Registry) LookupPaths(pattern string) (PathsFn, error)
- func (r *Registry) Reconcile(routes []RouteSpec) error
- func (r *Registry) RegisterDep(pagePattern, dependsOnPattern string)
- func (r *Registry) RegisterLoader(pattern string, fn LoaderFn)
- func (r *Registry) RegisterPaths(pattern string, fn PathsFn)
- type RenderResult
- type Renderer
- type RobotsOptions
- type RouteSpec
- type SEOSignals
- type Service
- type SitemapOptions
- type UnknownPathPolicy
- type ViteAssets
Constants ¶
const ( DefaultMemPages = 1024 DefaultTTL = time.Hour )
const ( DefaultMemoryLimit = 512 << 20 // WasmShadowStackSize is the physical C shadow stack baked into the // bundled quickjs.wasm at build time (wasm-ld -z stack-size=8MiB; see // internal/qjs/csrc/README.md). Exhausting it traps the wasm module with // an uncatchable "out of bounds memory access" and leaves the instance // unusable — QuickJS's own catchable guard must trip first, which is why // MaxStackSize is validated against this ceiling minus headroom. WasmShadowStackSize = 8 << 20 // MaxLogicalStackSize is the largest accepted PoolOptions.MaxStackSize: // the shadow stack minus a 1MiB headroom, so a guard trip on the deepest // legal budget still leaves real stack below it and the physical wall // stays unreachable by recursion. MaxLogicalStackSize = WasmShadowStackSize - 1<<20 // DefaultMaxStackSize is the QuickJS execution-stack cap applied when // PoolOptions.MaxStackSize is unset. QuickJS checks it on every nested // call and raises a CATCHABLE "Maximum call stack size exceeded" that // leaves the instance healthy (measured capacities: ~3.1k frames of // simple recursion at this budget, ~8k at MaxLogicalStackSize). History: // the pre-v0.17.0 engine silently disabled this guard under wasi, so the // only visible wall was the binary's 64KiB default shadow stack — the // original #15/#16 "phantom depth ceiling". Rebuilt wasm (csrc/, pinned // quickjs-ng v0.17.0) restores the guard; see ADR 0015. DefaultMaxStackSize = 1 << 20 DefaultRenderTimeout = 3 * time.Second )
const ( DefaultCacheControl = "max-age=60, stale-while-revalidate=300" DefaultPoisonTTL = 10 * time.Minute )
const ( TierEmbed = "embed" TierCache = "cache" TierRender = "render" TierStale = "stale" TierSPA = "spa" TierAsset = "asset" TierError = "error" TierRobots = "robots" TierSitemap = "sitemap" )
Tier values, most-specific-first in the serving order: embedded prerender artifact, layered-cache hit, on-the-spot render (miss path), stale copy on render failure, SPA shell fallback (index.html routes incl. the 404 form), static asset passthrough, product error page. The SEO companions carry their own values so traffic middleware can count crawler fetches of them.
const DefaultIndexNowEndpoint = "https://api.indexnow.org/indexnow"
const DefaultPrelude = `` /* 5289-byte string literal not displayed */
const HeaderTier = "X-Renderx-Tier"
HeaderTier names the response header carrying which serving layer produced the response — one of the Tier* values below. It exists for traffic observation (metrics.TrafficConfig consumes it: "did the crawler get cache or SSR?") and for debugging ("why was this request rendered?"). Readers must keep in mind that a CDN caching the HTML replays the header of the origin response that first populated the cache.
const MaxPropsBytes = 512 << 10
const OutputVersion = "rv1"
Variables ¶
var ( ErrRenderTimeout = errors.New("renderx: render timeout") ErrPoolClosed = errors.New("renderx: engine pool closed") )
var ( ErrEmptyRenderOutput = errors.New("renderx: empty render output") ErrMissingTitle = errors.New("renderx: head directives emitted but no <title>") // ErrServerSuspense marks output that contains React's client-rendering // fallback marker. renderToString does NOT wait for Suspense: a page that // lazily imports anything on its render path produces // `<!--$!--><template ...><!--/$-->` instead of the component's markup, and // the document is non-empty — so the empty-output assertion (A2) cannot see // it. Without this check the failure ships as "page renders blank in // production" (the marker is invisible in a browser, and the template // content is the only clue). ErrServerSuspense = errors.New("renderx: page suspended during server render (lazy import inside a static route?)") )
var ( ErrPatternNotFound = errors.New("renderx: pattern not registered") ErrPatternMismatch = errors.New("renderx: registered pattern not in route table") ErrMissingPaths = errors.New("renderx: static param route missing Paths") ErrInvalidParam = errors.New("renderx: invalid path param") ErrInvalidDirective = errors.New("renderx: invalid directive payload") ErrInvalidHeadTag = errors.New("renderx: invalid head tag or attr name") ErrInvalidCacheKey = errors.New("renderx: invalid cache key") ErrBuildIDMismatch = errors.New("renderx: cache entry buildId mismatch") ErrPropsTooLarge = errors.New("renderx: props exceed size limit") ErrPageNotFound = errors.New("renderx: page not found") )
Functions ¶
func AffectedPatterns ¶
func AppendTanstackAliases ¶ added in v0.10.2
AppendTanstackAliases adds the isServer alias (the Go side of the TS-side ESBUILD_ALIASES) on top of base, resolving the target against the same node_modules tree the rest of the SSR build reads: the web app's own node_modules first, then the npm-workspaces hoist root (webDir/../../node_modules — a web app that is a workspace member usually resolves @tanstack/router-core at the repo root). TanStack-agnostic callers can ignore the extra entry; the returned map is base.
func BuildSSRBundle ¶
func BuildSSRBundle(opts BuildOptions) ([]byte, error)
func DefaultPoolSize ¶
func DefaultPoolSize() int
func DefaultSSRAliases ¶
func Handler ¶
func Handler(deps HandlerDeps) http.Handler
func PropsSHA256 ¶
func RegisterDep ¶
func RegisterDep(pagePattern, dependsOnPattern string)
func RegisterLoader ¶
func RegisterPaths ¶
func RegisterService ¶
func RegisterService(s *Service)
func RenderDocument ¶
func ResetForTest ¶
func ResetForTest()
func RobotsHandler ¶ added in v0.7.2
func RobotsHandler(opts RobotsOptions) http.Handler
RobotsHandler serves /robots.txt: one "User-agent: *" group with the configured Disallow prefixes, the extra verbatim lines, and the Sitemap pointer. Options are validated and serialized once at construction — a malformed option panics at wiring time, never serving a silently wrong file.
func SitemapHandler ¶
func SitemapHandler(routes []RouteSpec, baseURL string, opts SitemapOptions) http.Handler
SitemapHandler serves /sitemap.xml from the route table + Paths registry. baseURL must be an absolute http(s) origin (e.g. "https://example.com") — a malformed value panics at construction time; mount the route only when an origin is actually known (see example wiring for the env-driven pattern).
func TanstackPrelude ¶ added in v0.10.2
func TanstackPrelude() string
TanstackPrelude returns the engine prelude for TanStack SSR bundles: the renderx default prelude plus the TanStack shims (the Go side of PRELUDE_SHIMS). Pass it as PoolOptions.Prelude:
renderx.NewEnginePool(bundle, renderx.PoolOptions{Prelude: renderx.TanstackPrelude()})
func ValidParamValue ¶
func ValidateParams ¶
func ViteBuildID ¶
func ViteManifestFiles ¶ added in v0.12.0
ViteManifestFiles returns every file path the build emitted, slash-prefixed and sorted, for use as an authoritative content-addressed asset list (webx.AssetCacheManifest).
Why this exists instead of relying on a filename heuristic: a build's manifest knows exactly which URLs carry a content hash, while any name-based rule has to guess and has a false-positive class that silently pins a replaceable file for a year (`Some-Page-Banner.png` looks like a hash; `CYhS-pAS` — a real hash — does not look like one to a tighter rule).
Every value's `file` and `css` are collected. Note that Vite lists the file relative to the build root, so no path cleaning beyond the leading slash is performed here.
Types ¶
type BuildOptions ¶
type CacheConfig ¶
type CacheEntry ¶
type CacheEntry struct {
HTML []byte `json:"html"`
PropsSHA256 string `json:"props_sha256"`
BuiltAt time.Time `json:"built_at"`
BuildID string `json:"build_id"`
}
func RenderOnce ¶ added in v0.4.0
func RenderOnce(ctx context.Context, r Renderer, pageID, location string, props json.RawMessage, lang string, assets ViteAssets, hydrate Hydrate) (CacheEntry, error)
RenderOnce 把单个页面渲染成完整 HTML 文档——不经过缓存与 HTTP 层的 一次性渲染入口,预渲染 / handler 未命中 / 缓存回填共用此组装。 预览(草稿渲染)、邮件合成、调试等场景直接调用即可,语义与预渲染管线 完全一致(props 规范化、空输出校验、head 指令与 <title> 校验)。
hydrate=none 的页面不注入 props 脚本与水合入口:两者唯一的消费者都是 客户端入口,没有它就没有意义——留在 HTML 里只会把 props 白发给所有人, 还会让缓存条目随 props 变化而失效。
type DevHandler ¶
type DevHandler struct {
// contains filtered or unexported fields
}
func NewDevHandler ¶
func NewDevHandler(deps DevHandlerDeps) (*DevHandler, error)
func (*DevHandler) Close ¶
func (d *DevHandler) Close()
func (*DevHandler) ServeHTTP ¶
func (d *DevHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
type DevHandlerDeps ¶
type DevHandlerDeps struct {
BuildOpts BuildOptions
PoolOpts PoolOptions
NewRenderer func(bundle []byte, opts PoolOptions) (Renderer, error)
Cache *LayeredCache
Routes []RouteSpec
BuildID string
Assets ViteAssets
Lang string
SPA http.Handler
Registry *Registry
Interval time.Duration
Warn func(format string, args ...any)
}
type Directive ¶
type Directive struct {
Kind string `json:"kind"`
Payload json.RawMessage `json:"payload,omitempty"`
Seq int `json:"seq"`
}
type DirectiveSink ¶
type DirectiveSink struct {
// contains filtered or unexported fields
}
func NewSink ¶
func NewSink() *DirectiveSink
func (*DirectiveSink) Append ¶
func (s *DirectiveSink) Append(kind string, payload json.RawMessage) Directive
func (*DirectiveSink) Directives ¶
func (s *DirectiveSink) Directives() []Directive
func (*DirectiveSink) Truncated ¶
func (s *DirectiveSink) Truncated() bool
type EnginePool ¶
type EnginePool struct {
// contains filtered or unexported fields
}
func NewEnginePool ¶
func NewEnginePool(bundle []byte, opts PoolOptions) (*EnginePool, error)
func (*EnginePool) Close ¶
func (p *EnginePool) Close()
func (*EnginePool) Render ¶
func (p *EnginePool) Render(ctx context.Context, pageID, location string, props json.RawMessage) (RenderResult, error)
type HandlerDeps ¶
type HandlerDeps struct {
PrerenderFS fs.FS
SPA http.Handler
Cache *LayeredCache
Renderer Renderer
Routes []RouteSpec
BuildID string
CacheControl string
ErrorPage func(http.ResponseWriter, *http.Request, error)
Warn func(format string, args ...any)
Assets ViteAssets
Lang string
Registry *Registry
PoisonTTL time.Duration
// UnknownPath selects the unmatched-path policy (see UnknownPathPolicy).
// Zero value keeps the v0.15.0 behavior: SPA shell with 200.
UnknownPath UnknownPathPolicy
// ShellMeta is injected into the <head> of every SPA shell response —
// both the plain fallback (spa) and its notFoundWriter-wrapped 404 form.
// The typical use is declaring the shell pages "not indexable" once for
// the whole site:
//
// ShellMeta: []renderx.HeadEntry{{
// Tag: "meta",
// Attrs: map[string]string{"name": "robots", "content": "noindex, follow"},
// }},
//
// Entries go through the same whitelist as renderer head directives
// (renderHeadEntry: tag/attr name rules, deny script/iframe/base,
// deny http-equiv) and a malformed entry panics at Handler construction.
// Full-document responses (embed/cache/render tiers) never get ShellMeta —
// they carry their own head.
ShellMeta []HeadEntry
}
type HeadEntry ¶
type HeadEntry struct {
Tag string `json:"tag"`
Attrs map[string]string `json:"attrs,omitempty"`
Children string `json:"children,omitempty"`
}
func HeadEntries ¶
type Hydrate ¶ added in v0.12.0
type Hydrate string
Hydrate 是路由表投影里的第二根轴(与 Mode 正交):服务端产出的 HTML 之后还要不要 JS。空串按 HydrateLoad 处理,旧路由表不声明该字段时行为 不变。
type IndexNowDeps ¶
type LayeredCache ¶
type LayeredCache struct {
// contains filtered or unexported fields
}
func NewLayeredCache ¶
func NewLayeredCache(cfg CacheConfig) (*LayeredCache, error)
func (*LayeredCache) Delete ¶
func (c *LayeredCache) Delete(ctx context.Context, paths ...string) error
func (*LayeredCache) EvictMatching ¶
func (*LayeredCache) Get ¶
func (c *LayeredCache) Get(ctx context.Context, path string) (CacheEntry, bool)
func (*LayeredCache) GetOrLoad ¶
func (c *LayeredCache) GetOrLoad(ctx context.Context, path string, load func(context.Context) (CacheEntry, error)) (CacheEntry, error)
func (*LayeredCache) GetOrLoadHit ¶ added in v0.7.2
func (c *LayeredCache) GetOrLoadHit(ctx context.Context, path string, load func(context.Context) (CacheEntry, error)) (CacheEntry, bool, error)
GetOrLoadHit is GetOrLoad plus a hit report: hit=true when an existing cache entry (memory or disk) was served — including the singleflight replay path, where a concurrent Put landed after this request's first check and the load never ran. hit=false when the request was answered through the load path (this request's own load, or a coincident one it joined as a singleflight waiter). The X-Renderx-Tier response header is built on it.
func (*LayeredCache) GetStale ¶
func (c *LayeredCache) GetStale(ctx context.Context, path string) (CacheEntry, bool)
func (*LayeredCache) Keys ¶
func (c *LayeredCache) Keys() []string
func (*LayeredCache) PurgeForeign ¶
func (c *LayeredCache) PurgeForeign(ctx context.Context, buildID string) error
func (*LayeredCache) Put ¶
func (c *LayeredCache) Put(ctx context.Context, path string, ent CacheEntry) error
type PoolOptions ¶
type PoolOptions struct {
Size int
MemoryLimit int
// MaxStackSize caps the QuickJS execution stack in bytes. QuickJS's
// guard trips BEFORE the wasm module's physical shadow stack and raises
// a catchable "Maximum call stack size exceeded" — the instance stays
// healthy — so this knob trades depth capacity against per-render stack
// budget. Values above MaxLogicalStackSize are rejected at construction:
// beyond it recursion could reach the physical wall (uncatchable trap,
// instance retired). 0 keeps DefaultMaxStackSize (1MiB).
MaxStackSize int
RenderTimeout time.Duration
Prelude string
}
type PrerenderDeps ¶
type PrerenderManifest ¶
type PrerenderManifest struct {
BuildID string `json:"buildId"`
GeneratedAt time.Time `json:"generatedAt"`
Pages []PrerenderManifestEntry `json:"pages"`
}
func Prerender ¶
func Prerender(ctx context.Context, deps PrerenderDeps) (PrerenderManifest, error)
type PrerenderManifestEntry ¶
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
func NewRegistry ¶
func NewRegistry() *Registry
func (*Registry) AffectedPatterns ¶
func (*Registry) RegisterDep ¶
func (*Registry) RegisterLoader ¶
func (*Registry) RegisterPaths ¶
type RenderResult ¶
type RenderResult struct {
HTML string
Sink *DirectiveSink
}
type RobotsOptions ¶ added in v0.7.2
type RobotsOptions struct {
// SitemapURL is emitted as a "Sitemap:" line when non-empty (pass an
// absolute URL, e.g. "https://example.com/sitemap.xml").
SitemapURL string
// Disallow lists path prefixes emitted as "Disallow:" lines under the
// default "User-agent: *" group (e.g. "/api/", "/admin").
Disallow []string
// Extra holds verbatim lines appended after the default block, for more
// elaborate rules (further user-agent groups, Allow exceptions). Blank
// lines are skipped.
Extra []string
}
RobotsOptions configures RobotsHandler.
type SEOSignals ¶ added in v0.7.2
type SEOSignals struct {
Title string
Description string
Canonical string
// CanonicalCount counts link[rel=canonical] elements (>1 = the page emits
// duplicates). The SSR path does not dedupe head entries — one page, one
// canonical is a product-side rule, and build-time audits warn on it.
CanonicalCount int
}
SEOSignals is the head-level SEO signal set AuditSEO extracts from a rendered document. Empty strings mean the signal is absent.
func AuditSEO ¶ added in v0.7.2
func AuditSEO(doc []byte) SEOSignals
AuditSEO extracts the title / meta description / canonical link from a rendered document. It understands the serialization this package's template emits (lowercase tags, double-quoted attributes) — it audits our own output, not arbitrary HTML. Values come back HTML-unescaped. Build chains use it to report SEO coverage of prerendered pages (cmd/render does).
type Service ¶
type Service struct {
Cache *LayeredCache
Renderer Renderer
Routes []RouteSpec
BuildID string
Assets ViteAssets
Lang string
Registry *Registry
Warn func(format string, args ...any)
RefreshTimeout time.Duration
// contains filtered or unexported fields
}
func (*Service) Invalidate ¶
type SitemapOptions ¶
type SitemapOptions struct {
Filter func(route RouteSpec, location string, params Params) bool
// Lastmod optionally reports the last-modified time for one sitemap URL.
// location is the root-relative path ("/blog/hello"); params carries the
// expanded route params (nil for parameterless routes). It runs per URL
// during sitemap generation and may do I/O (that is its purpose), hence
// the ctx — return ok=false to omit <lastmod> for that URL (unknown slug,
// lookup failure: the entry degrades to loc-only, never a 500). Emitted
// as a W3C date (YYYY-MM-DD, UTC-normalized) per sitemaps.org.
Lastmod func(ctx context.Context, route RouteSpec, location string, params Params) (time.Time, bool)
Registry *Registry
}
type UnknownPathPolicy ¶ added in v0.16.0
type UnknownPathPolicy string
UnknownPathPolicy selects what the handler does with a GET/HEAD path that matched no static route and hit no embedded prerender snapshot — the SPA fallback decision at the bottom of ServeHTTP.
const ( // UnknownPathSPAShell serves the SPA shell with status 200 — the v0.15.0 // behavior and still the zero-value default, so existing deployments keep // serving their CSR routes (e.g. /login) without touching wiring. // // NOTE: this default is kept for compatibility only, and new deployments // are recommended to migrate to UnknownPathNotFound. SPA-fallback-200 // turns every garbage URL (/random-page, /zh/fake, trailing-slash twins) // into an indexable soft-404 — the shell has no canonical, no noindex and // a generic title, and crawlers collect them (field report: // braceletmakeronline.com, GSC exposure on shell URLs). Consumers whose // CSR routes live at known paths should enumerate those as ModeCSR/ModeStatic // routes or serve them ahead of renderx, then flip this to not-found. UnknownPathSPAShell UnknownPathPolicy = "spa-shell" // UnknownPathNotFound wraps the same SPA shell in a 404 status via // notFoundWriter: human visitors still get the app shell (their client // router can take over), but crawlers see an honest 404 instead of an // indexable thin shell. UnknownPathNotFound UnknownPathPolicy = "not-found" )
type ViteAssets ¶
func ParseViteManifest ¶
func ParseViteManifest(data []byte, entryKey string) (ViteAssets, error)