uihost

package
v0.38.0 Latest Latest
Warning

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

 Go to latest Published: Jul 21, 2026 License: MIT Imports: 40 Imported by: 0

Documentation

Overview

Package uihost wires a core-ui application onto a framework.App's router. It mounts page rendering, runtime.js, compiled action JS, SSE island streaming, and sessions as routes — there is no standalone server. The framework.App owns the HTTP listener.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetBuilder 

func GetBuilder() *strings.Builder

GetBuilder gets a strings.Builder from the pool, reset to zero length.

func PutBuilder 

func PutBuilder(b *strings.Builder)

PutBuilder returns a builder to the pool.

func ReadCustomCSSFile 

func ReadCustomCSSFile(path string) string

ReadCustomCSSFile reads a CSS file and returns its content. This is a helper for the demo main.go.

Types

type AgentCardConfig added in v0.10.0 

type AgentCardConfig struct {
	// Name is the human-readable agent name (REQUIRED by A2A).
	Name string
	// Description is a short summary.
	Description string
	// Version is the agent/software version. Defaults to "1.0.0".
	Version string
	// URL is the agent's service endpoint (absolute). When empty,
	// derived from BaseURL.
	URL string
	// MCPEndpoint, when set (e.g. "/mcp"), advertises the MCP endpoint
	// as the card's JSON-RPC service interface and a skill pointing
	// agents at it.
	MCPEndpoint string

	// Skills are the agent's capabilities. When empty and MCPEndpoint is
	// set, a default "mcp" skill is emitted; hosts can declare richer
	// skills (one per domain capability).
	Skills []AgentSkill

	// Streaming / push-notification capability flags. Default false.
	Streaming         bool
	PushNotifications bool

	// SecuritySchemes, when non-nil, is emitted verbatim under
	// security_schemes (OpenAPI-style). nil omits the field.
	SecuritySchemes map[string]AgentSecurityScheme

	// DefaultInputModes / DefaultOutputModes are the MIME types the
	// agent accepts/emits. Default ["text/plain"].
	DefaultInputModes  []string
	DefaultOutputModes []string
}

AgentCardConfig configures the A2A /.well-known/agent-card.json. The card is the discovery artifact: even without a full A2A task server, a valid card advertises the agent's identity, service URL, and skills.

type AgentReadyConfig added in v0.10.0 

type AgentReadyConfig struct {
	// BaseURL is the canonical origin (scheme://host) used to
	// absolutize URLs in the agent card and Link headers. When empty,
	// handlers derive it per request from the forwarded Host + the
	// request TLS/scheme — correct behind a proxy that sets Host.
	BaseURL string

	// Title is the /llms.txt H1 and the agent-card name fallback.
	Title string
	// Summary is the /llms.txt blockquote lede and the agent-card
	// description fallback.
	Summary string
	// Sections are the /llms.txt file-list sections (H2 + links). When
	// nil, a default "Docs" section links the app's /llm-pages.md index
	// (requires WithPublicLLMMD) and the per-screen /llm.md docs.
	Sections []LLMsTxtSection

	// AgentCard, when non-nil, serves /.well-known/agent-card.json plus
	// the legacy /.well-known/agent.json alias. When nil but the bundle
	// is on, a minimal card is derived from Title/Summary/BaseURL.
	AgentCard *AgentCardConfig

	// AllowAIBots, when non-nil, augments robots.txt with explicit
	// rules for the common AI crawlers (GPTBot, ClaudeBot, Google-Extended,
	// …). true → allow; false → deny. nil → no AI-bot block.
	AllowAIBots *bool

	// ContentSignals, when set, emits a Content-Signal: directive line in
	// robots.txt declaring AI usage preferences (e.g.
	// "ai-train=no, search=yes, ai-input=yes"). See contentsignals.org.
	ContentSignals string

	// LinkHeaders, when non-nil, toggles Link response headers on every
	// HTML page. Default (nil → bundle sets true) advertises the sitemap,
	// llms.txt, agent card, and the per-page markdown alternate.
	LinkHeaders *bool

	// OpenAPIEndpoint, when set (e.g. "/openapi.json"), is advertised via
	// a Link: rel="service-desc" header so agents discover the API
	// catalog. Set it to the path the framework serves the OpenAPI spec
	// at (requires WithPublicOpenAPI so the spec is reachable).
	OpenAPIEndpoint string

	// ContentNegotiation, when non-nil, toggles serving a markdown
	// rendering of any HTML page when the request Accepts
	// text/markdown. Default off (nil → bundle leaves it off unless set).
	ContentNegotiation *bool
}

AgentReadyConfig configures the WithAgentReady bundle. The zero value is a no-op; set fields for the surfaces you want. Sensible defaults apply inside WithAgentReady.

type AgentSecurityScheme added in v0.10.0 

type AgentSecurityScheme map[string]any

AgentSecurityScheme is an OpenAPI-style security scheme emitted in the card's security_schemes. The raw map lets hosts express any scheme shape (apiKey, http OAuth2, etc.) without the framework modeling each.

type AgentSkill added in v0.10.0 

type AgentSkill struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	Examples    []string `json:"examples,omitempty"`
}

AgentSkill is one A2A AgentSkill. 

type HreflangLink struct {
	Lang string // BCP-47 tag (e.g. "en", "en-US", "x-default")
	URL  string // canonical URL for that locale
}

HreflangLink declares a locale → URL alternate for the current page. Emitted as <link rel="alternate" hreflang="…" href="…">. 

type LLMsTxtLink struct {
	Name  string // hyperlink text
	URL   string // absolute or root-relative URL
	Notes string // optional text after the colon
}

LLMsTxtLink is one entry in an /llms.txt section.

type LLMsTxtSection added in v0.10.0 

type LLMsTxtSection struct {
	// Title is the H2 heading. The special title "Optional" renders the
	// spec's skippable-context section.
	Title string
	// Links are the markdown `[name](url): notes` entries.
	Links []LLMsTxtLink
}

LLMsTxtSection is one H2 file-list section of /llms.txt.

type NotFoundRenderer 

type NotFoundRenderer interface {
	RenderNotFound(path string) render.HTML
}

NotFoundRenderer is an optional interface a custom 404 screen (see WithNotFoundScreen) may implement to receive the unmatched request path. The path arrives as an argument, so a single shared screen instance can render per-request detail without a data race. Screens that don't implement it just render via component.Component.Render.

type OG 

type OG struct {
	Title       string
	Description string
	Image       string
	URL         string
	Type        string
}

OG holds Open Graph meta tag values for social sharing. Zero-value fields are omitted from output.

type Option 

type Option func(*UIHost)

Option configures a UIHost.

func WithAgentCard added in v0.10.0 

func WithAgentCard(cfg AgentCardConfig) Option

WithAgentCard serves /.well-known/agent-card.json (+ legacy /.well-known/agent.json). Granular alternative to the bundle.

func WithAgentLinkHeaders added in v0.10.0 

func WithAgentLinkHeaders() Option

WithAgentLinkHeaders emits Link response headers on HTML pages advertising the configured discovery artifacts (sitemap, llms.txt, agent card, markdown alternate). Granular alternative to the bundle.

func WithAgentReady added in v0.10.0 

func WithAgentReady(cfg AgentReadyConfig) Option

WithAgentReady turns on the agent-discovery surface in one call. It is the recommended entry point; pass a populated AgentReadyConfig. Each piece is also available as a granular Option (WithLLMsTxt, WithAgentCard) for fine control.

func WithAppIcon added in v0.26.0 

func WithAppIcon(source []byte) Option

WithAppIcon derives the app's entire icon surface from ONE source image (PNG/JPEG/WebP…, ideally ≥512px; non-square sources are center-cropped). The host generates 32/180/192/512px PNGs at startup, serves them under /__gofastr/icons/, answers /favicon.ico with the 32px icon, and emits the matching <link rel="icon"> and <link rel="apple-touch-icon"> head tags. When WithPWA is enabled and PWAConfig.Icons is empty, the 192/512 icons also populate the manifest (explicitly declared icons always win).

Pair it with go:embed for a zero-file-management setup: 

//go:embed logo.png
var logo []byte
uihost.New(app, uihost.WithAppIcon(logo))

An undecodable source logs a warning and leaves the host without icons (the /favicon.ico 204 fallback still applies) — icons are decoration, not something worth failing startup over.

func WithCanonicalURL 

func WithCanonicalURL(url string) Option

WithCanonicalURL adds a <link rel="canonical"> tag to <head>. Unsafe URLs (non-http(s)/relative) are dropped.

func WithCustomCSS 

func WithCustomCSS(css string) Option

WithCustomCSS adds extra CSS to inject into every page.

func WithDescription 

func WithDescription(desc string) Option

WithDescription adds a <meta name="description"> tag to <head>.

func WithExtraScripts 

func WithExtraScripts(urls ...string) Option

WithExtraScripts adds external <script src="…"> URLs to inject before </body> on every page. Use for dev-only tooling like livereload. CSP-safe — every URL becomes an external resource, no inline JS.

func WithFavicon 

func WithFavicon(href string) Option

WithFavicon adds a <link rel="icon"> tag to <head>. The host also auto-serves 204 No Content at the configured URL when no static file matches, so a host that ships no favicon doesn't 404 on every page load. Place a real file at the path in staticDir / staticFS to override.

func WithHeadHTML 

func WithHeadHTML(html string) Option

WithHeadHTML injects raw HTML into every page's <head>. This is the escape hatch for arbitrary head content. The HTML is injected verbatim — callers must ensure it is CSP-compatible (no inline <script> or <style> tags). For safe, auto-escaped alternatives, see WithFavicon, WithThemeColor, WithDescription, WithOpenGraph, WithTwitterCard, WithCanonicalURL, and WithPreconnect.

func WithLLMsTxt added in v0.10.0 

func WithLLMsTxt(title, summary string, sections []LLMsTxtSection) Option

WithLLMsTxt serves /llms.txt from the given title, summary, and sections. Granular alternative to the WithAgentReady bundle.

func WithMarkdownNegotiation added in v0.10.0 

func WithMarkdownNegotiation() Option

WithMarkdownNegotiation makes HTML pages serve a markdown rendering when the request Accepts text/markdown. Requires WithPublicLLMMD so the per-screen markdown renderers are available.

func WithNotFoundScreen 

func WithNotFoundScreen(c component.Component) Option

WithNotFoundScreen overrides the default bare 404 fallback. When a request misses every registered screen, static file, and configured favicon, the host renders this component through the active layout — so the 404 page sees the same nav/footer chrome every other page gets. The component's Render() result is wrapped in the default layout; pages without their own layout end up with the framework's bare <main>.

func WithOpenGraph 

func WithOpenGraph(og OG) Option

WithOpenGraph adds Open Graph <meta property="og:..."> tags to <head>. Zero-value fields are omitted. URL-typed fields (Image, URL) are dropped if they fail the head-URL allow-list (http(s)/relative only) — a `javascript:`/`data:` URL there is reflected XSS via any social preview crawler that auto-clicks the link.

func WithPWA added in v0.22.0 

func WithPWA(cfg PWAConfig) Option

WithPWA opts the host into the installable-PWA surface: it mounts /manifest.webmanifest, /service-worker.js, /__gofastr/pwa/register.js, and /__gofastr/pwa/offline, and injects the manifest link + external registration script into every rendered page. The injection rides the generic headTags/extraScripts rails (all values are fixed at option time), so chrome assembly has a single code path.

func WithPreconnect 

func WithPreconnect(origins ...string) Option

WithPreconnect adds <link rel="preconnect"> tags for the given origins. Use for early DNS/TCP/TLS connections to external resources (fonts, CDNs).

func WithPublicLLMMD 

func WithPublicLLMMD() Option

WithPublicLLMMD opts the host into mounting the page-level LLM-friendly markdown routes (/llm-pages.md, /<screen>/llm.md). Disabled by default because the documents enumerate every screen and the data shape attached to it — useful for AI agents in trusted environments, schema disclosure elsewhere.

func WithRobots 

func WithRobots(cfg RobotsConfig) Option

WithRobots registers a /robots.txt handler. A nil-zero RobotsConfig is fine — it ships the open default (allow everything).

func WithRobotsMeta added in v0.26.0 

func WithRobotsMeta(directives string) Option

WithRobotsMeta adds a sitewide <meta name="robots"> tag to <head> (e.g. "noindex" for a staging deploy). Per-screen directives via ScreenRobots or SEO.Robots are emitted in addition to — and before — this global tag; crawlers apply the most restrictive combination.

func WithSitemap 

func WithSitemap(cfg SitemapConfig) Option

WithSitemap registers a /sitemap.xml handler.

func WithStaticDir 

func WithStaticDir(dir string) Option

WithStaticDir sets the directory to serve static files from.

func WithThemeColor 

func WithThemeColor(color string) Option

WithThemeColor adds a <meta name="theme-color"> tag to <head>.

func WithTwitterCard 

func WithTwitterCard(tc TwitterCard) Option

WithTwitterCard adds Twitter Card <meta name="twitter:..."> tags to <head>. Zero-value fields are omitted. URL-typed fields are scheme-restricted per WithOpenGraph.

type PWAConfig added in v0.22.0 

type PWAConfig struct {
	ID              string
	Name            string
	ShortName       string
	Description     string
	StartURL        string
	Scope           string
	Display         PWADisplay
	ThemeColor      string
	BackgroundColor string
	Icons           []PWAIcon

	// Precache lists extra same-origin root-absolute paths (static
	// assets, fonts, hero images) to keep available offline alongside
	// the runtime/app shell. Entries that point at sensitive framework
	// endpoints (API, auth, session, action, signal, SSE) or at another
	// origin are dropped — the app-shell cache can never hold them.
	Precache []string

	// OfflineScreen renders the offline fallback page served at
	// /__gofastr/pwa/offline and shown when a navigation fails with no
	// network. The page is precached at service-worker install time, so
	// it must not render personalized content; it is deliberately NOT
	// wrapped in the app layout for the same reason. Nil uses the
	// framework default.
	OfflineScreen component.Component

	// DenyPaths extends the built-in sensitive-path deny list
	// (/__gofastr/{sse,session,action,widgets}, /api, /auth)
	// with app-specific mounts — e.g. a CRUD API at a custom prefix or
	// an auth battery at a custom base path. Listed paths (and
	// everything under them) can never be precached and are never
	// intercepted by the service worker. Root-relative; a bare "/" is
	// ignored (it would deny the whole app).
	DenyPaths []string
}

PWAConfig configures WithPWA. Every field is optional; sensible defaults are derived at serve time:

  • Name defaults to the core-ui app title.
  • StartURL and Scope default to "/".
  • ID defaults to StartURL.
  • Display defaults to standalone.
  • OfflineScreen defaults to a framework-provided offline notice.

type PWADisplay added in v0.22.0 

type PWADisplay string

PWADisplay is the manifest display mode. 

const (
	PWADisplayStandalone PWADisplay = "standalone"
	PWADisplayFullscreen PWADisplay = "fullscreen"
	PWADisplayMinimalUI  PWADisplay = "minimal-ui"
	PWADisplayBrowser    PWADisplay = "browser"
)

Typed constants for the common manifest display modes.

type PWAIcon added in v0.22.0 

type PWAIcon struct {
	Src     string
	Sizes   string // e.g. "192x192"
	Type    string // e.g. "image/png"
	Purpose PWAIconPurpose
}

PWAIcon declares one manifest icon. Src must be a same-origin root-absolute path (usually a static asset, e.g. "/static/icon-192.png"). Chromium's installability check needs at least a 192x192 and a 512x512 icon; add a maskable variant for adaptive home-screen shapes.

type PWAIconPurpose added in v0.22.0 

type PWAIconPurpose string

PWAIconPurpose is the manifest icon purpose. 

const (
	PWAIconPurposeAny        PWAIconPurpose = "any"
	PWAIconPurposeMaskable   PWAIconPurpose = "maskable"
	PWAIconPurposeMonochrome PWAIconPurpose = "monochrome"
)

Typed constants for the common manifest icon purposes.

type PWAStaticExport added in v0.24.0 

type PWAStaticExport struct {
	// Pages are the exported route paths — precached atomically.
	Pages []string
	// Assets are framework-generated files (runtime, CSS, widget chrome,
	// llm.md) — precached atomically with the pages.
	Assets []string
	// OptionalAssets are user static-dir files — precached best-effort:
	// one un-servable file (a dotfile a host strips, say) must not brick
	// the install and pin clients to a previous deployment forever.
	OptionalAssets []string
	// ContentHash fingerprints the exported tree's bytes: a redeploy
	// that edits content without changing the path list must still
	// produce a byte-different worker, or browsers would never rotate
	// the stale cache.
	ContentHash string
}

PWAStaticExport describes a completed static export to the full-site worker generator.

type RobotsConfig 

type RobotsConfig struct {
	// UserAgent is the target crawler. Empty defaults to "*" (all
	// crawlers).
	UserAgent string

	// Allow lists the path prefixes the crawler may visit. Empty +
	// empty Disallow is the open default ("Allow: /").
	Allow []string

	// Disallow lists path prefixes the crawler must not visit.
	Disallow []string

	// SitemapURL is the absolute URL of the sitemap. When empty and
	// WithSitemap was also configured, the handler derives it from
	// SitemapConfig.BaseURL + "/sitemap.xml".
	SitemapURL string

	// CrawlDelay seconds between requests. Zero omits the directive.
	CrawlDelay int
}

RobotsConfig configures the /robots.txt endpoint.

type SEO 

type SEO struct {
	Description string         // <meta name="description">
	Canonical   string         // <link rel="canonical">
	Hreflangs   []HreflangLink // <link rel="alternate" hreflang>
	Robots      string         // <meta name="robots"> (e.g. "noindex,nofollow")
	OG          *OG            // Open Graph block
	Twitter     *TwitterCard   // Twitter Card block
	Schema      []seo.Thing    // JSON-LD items
}

SEO bundles every per-page SEO declaration in one struct. Use it as the return type of ScreenSEO when you'd rather declare everything from one method than implement the per-concern interfaces individually. Empty fields are silently skipped — only what's set is emitted.

type SEOScreen 

type SEOScreen interface {
	HeadHTML() string
}

SEOScreen is an optional interface that screens can implement to inject per-screen HTML into <head>. This enables per-page SEO: Open Graph tags, description meta, structured data, etc. The returned HTML is injected alongside any global head tags from WithHeadHTML / WithFavicon / etc.

WARNING: the returned HTML is injected verbatim. Implementers must escape any dynamic content (e.g. html.EscapeString for user-supplied titles or descriptions) to prevent XSS.

type ScreenCanonical 

type ScreenCanonical interface {
	ScreenCanonical() string
}

ScreenCanonical is an optional screen interface that declares the canonical URL for the current page. Emitted as <link rel="canonical" href="…">. Use to prevent duplicate-content issues when a page is reachable at multiple URLs (filters, sorts).

type ScreenHreflangs 

type ScreenHreflangs interface {
	ScreenHreflangs() []HreflangLink
}

ScreenHreflangs is an optional screen interface that declares per-page hreflang alternates for multi-locale apps. When present, the host emits one <link rel="alternate"> per returned link.

type ScreenRobots added in v0.26.0 

type ScreenRobots interface {
	ScreenRobots() string
}

ScreenRobots is an optional screen interface that declares the per-page robots directive. Emitted as <meta name="robots"> (e.g. "noindex,nofollow" for drafts or duplicate views). The bundle-style SEO.Robots field overrides it when both are present.

type ScreenSEO 

type ScreenSEO interface {
	ScreenSEO() SEO
}

ScreenSEO is the bundle-style alternative to the per-concern interfaces. When a screen implements both ScreenSEO AND any of ScreenDescriber / ScreenCanonical / ScreenHreflangs / ScreenSchema, ScreenSEO wins — its fields override.

Returning a zero-value SEO from ScreenSEO opts out of all per-page emission for the screen (useful for routes you want fully naked).

type ScreenSchema 

type ScreenSchema interface {
	ScreenSchema() []seo.Thing
}

ScreenSchema is an optional screen interface that returns one or more typed Schema.org items (from core-ui/seo) to emit as <script type="application/ld+json"> blocks.

Implementations typically return: 

[]seo.Thing{
    seo.NewArticle(),
    seo.NewBreadcrumbList(...),
}

type Session 

type Session struct {
	ID      string
	Created time.Time
	Token   string
}

Session represents a connected browser session. ID ("sess-…") is the bare identifier used as the SSE stream / presence key and embedded in page chrome; Token is the signed credential stored in the session cookie — the ID plus mint time plus an HMAC any replica sharing the key can verify. Only the Token proves anything; the bare ID is public.

type SitemapConfig 

type SitemapConfig struct {
	// BaseURL is the canonical origin (scheme + host) for emitted
	// <loc> elements. Required — sitemap.xml entries must be absolute
	// URLs per the protocol spec.
	BaseURL string

	// LastMod sets the <lastmod> timestamp emitted for every page.
	// Zero defaults to the time the server started, which is a
	// reasonable signal that anything older was content the build
	// already covered.
	LastMod time.Time

	// ExcludePaths lists route prefixes to omit from the sitemap.
	// Useful for admin routes, drafts, etc. Prefix match.
	ExcludePaths []string
}

SitemapConfig configures the /sitemap.xml endpoint.

type TwitterCard 

type TwitterCard struct {
	Card        string // e.g. "summary", "summary_large_image"
	Title       string
	Description string
	Image       string
	Site        string // @username
}

TwitterCard holds Twitter Card meta tag values. Zero-value fields are omitted from output.

type UIHost 

type UIHost struct {
	App     *app.App
	Islands *island.Manager
	// contains filtered or unexported fields
}

UIHost mounts a core-ui application onto a router. It serves rendered pages with runtime.js, compiled action JS, SSE streaming for islands, and sessions. The framework.App is responsible for ListenAndServe.

func New 

func New(application *app.App, opts ...Option) *UIHost

New creates a new development server.

func (*UIHost) ActiveTheme 

func (ds *UIHost) ActiveTheme() style.Theme

ActiveTheme returns the configured theme or the default if unset. Exposed for tooling (e.g. the static-site builder) that needs to resolve theme tokens at build time.

func (*UIHost) AppCSS 

func (ds *UIHost) AppCSS() string

AppCSS returns the merged app-level stylesheet body: theme :root custom properties + every registered theme override (.fui-theme-<hash> blocks for ui.Themed wrappers) + customCSS + every style.Contribute'd fragment, in that order. Used by the SSG so static export ships the same single asset the live server serves.

The :root block is ALWAYS emitted, even when the host has no explicit App.Theme. Per-component CSS emits bare var(--*) references (no in-CSS fallbacks); without the :root floor every component would render with UA defaults. The DefaultTheme() floor guarantees var() resolution.

func (*UIHost) AppIconAssets added in v0.26.0 

func (ds *UIHost) AppIconAssets() map[string][]byte

AppIconAssets returns the generated icon files (URL path → PNG bytes) plus the /favicon.ico alias. Empty when WithAppIcon was not configured (or its source failed to decode). The static exporter dumps these so a serverless deploy ships the same icon surface as the live server.

func (*UIHost) AutoCompileActions 

func (ds *UIHost) AutoCompileActions()

AutoCompileActions scans all registered screens and compiles actions for any that implement InteractiveComponent. The component ID is derived from ScreenComponentID.ComponentID() if implemented, otherwise from the route path.

func (*UIHost) CompileActions 

func (ds *UIHost) CompileActions(componentID string, comp component.Component) string

CompileActions compiles a component's action methods to JS and caches them. It also stores the action registry so handleServerAction can invoke Go handlers.

func (*UIHost) ComponentCSSFiles 

func (ds *UIHost) ComponentCSSFiles() map[string]string

ComponentCSSFiles returns one asset per registered component: urlPath ("/__gofastr/comp/<name>.css") and the scoped CSS body resolved under the active theme. Used by the static-site builder.

func (*UIHost) CreateSession 

func (ds *UIHost) CreateSession() *Session

CreateSession mints a new stateless session token. Nothing is stored server-side: the returned Session is a parsed view of the token, and validity is a signature check (verifySessionToken), not a lookup.

func (*UIHost) CustomCSS 

func (ds *UIHost) CustomCSS() string

CustomCSS returns the extra CSS string injected into every page.

func (*UIHost) GetActionJS 

func (ds *UIHost) GetActionJS() string

GetActionJS returns all compiled action JS concatenated.

func (*UIHost) HasStaticFS 

func (ds *UIHost) HasStaticFS() bool

HasStaticFS reports whether an embedded static FS is configured.

func (*UIHost) Mount 

func (ds *UIHost) Mount(r *router.Router)

Mount registers the UI's HTTP handlers on the given router.

It registers:

  • All `/__gofastr/*` infrastructure endpoints (runtime.js, actions.js, SSE, session, server actions, widget JS, CSS chunks)
  • A NotFound handler that first attempts static-file resolution (from either staticDir or staticFS) and falls back to page rendering.

Mount must be called after the framework.App has registered its other routes (entity CRUD, custom endpoints) so the page handler only takes requests that nothing else claimed.

func (*UIHost) PWAEnabled added in v0.22.0 

func (ds *UIHost) PWAEnabled() bool

PWAEnabled reports whether WithPWA was configured. The static builder uses it to decide whether to emit the PWA assets.

func (*UIHost) PWAManifestJSON added in v0.22.0 

func (ds *UIHost) PWAManifestJSON(basePath string) ([]byte, error)

PWAManifestJSON renders the web app manifest. basePath prefixes start_url, scope, id, and same-origin icon paths for static exports mounted under a subpath; pass "" for the live server.

func (*UIHost) PWAOfflineHTML added in v0.22.0 

func (ds *UIHost) PWAOfflineHTML() string

PWAOfflineHTML renders the offline fallback page: the configured (or default) offline screen inside the standard document shell with the usual chrome (theme bootstrap, app.css, runtime). It is deliberately NOT wrapped in the app layout — the page is precached at service-worker install time, so nothing personalized may render into it. Returns "" when WithPWA was not configured.

func (*UIHost) PWARegisterJS added in v0.22.0 

func (ds *UIHost) PWARegisterJS(basePath string) string

PWARegisterJS generates the external, CSP-safe registration script. Registration on every page load doubles as the update check; when a new worker is installed and waiting behind a controlling one, the script dispatches "gofastr:pwa-update" on window so apps can show an "update available" prompt. Returns "" when WithPWA was not configured.

func (*UIHost) PWAServiceWorkerJS added in v0.22.0 

func (ds *UIHost) PWAServiceWorkerJS(basePath string) (string, error)

PWAServiceWorkerJS generates the service worker. The worker precaches the app shell under a deterministically versioned cache name, keeps document navigations network-first with the offline screen as fallback, never caches anything at runtime, and on activate deletes only obsolete caches owned by this application. It never calls skipWaiting — a new worker activates once existing tabs release the old one; pages hear about a waiting update via the "gofastr:pwa-update" window event dispatched by register.js.

func (*UIHost) PWAStaticServiceWorkerJS added in v0.24.0 

func (ds *UIHost) PWAStaticServiceWorkerJS(basePath string, export PWAStaticExport) (string, error)

PWAStaticServiceWorkerJS generates the service worker for a STATIC export ("static site as an app"). A static export is a closed, immutable page set, so the personalization concern that keeps the live worker's navigations network-first does not exist: this worker precaches the WHOLE exported site — app shell, every page, every component stylesheet (under the versioned ?v= URLs pages actually request), every asset (deny-filtered) — and serves navigations cache-first, tolerating the trailing-slash redirects of static hosts, so the installed PWA works fully offline from the first install. Everything else mirrors PWAServiceWorkerJS: exact URL matching, no skipWaiting, denied endpoints never intercepted. The cache prefix carries a "static" + basePath discriminator so a live deployment and static exports on the same origin never delete each other's caches.

func (*UIHost) PushUpdate 

func (ds *UIHost) PushUpdate(islandID string, html string, sessionID string)

PushUpdate pushes an island update for a specific session. This is a convenience method that wraps the island manager's push mechanism.

func (*UIHost) RenderStaticPage 

func (ds *UIHost) RenderStaticPage(ctx context.Context, path string) (string, error)

RenderStaticPage produces a fully-rendered page suitable for static-site generation: it runs the screen's Load(ctx) hook, applies layout/theme, and injects runtime.js, compiled actions, custom CSS, and the route graph — but skips the SSE meta tag because there is no live session. The result is safe to write to disk and serve from any static host.

func (*UIHost) RobotsTXT added in v0.26.0 

func (ds *UIHost) RobotsTXT(basePath string) (string, bool)

RobotsTXT builds the robots.txt document WithRobots configured. Like UIHost.SitemapXML it serves both the live handler and the static exporter. basePath only affects the derived Sitemap: URL (Allow/ Disallow prefixes are emitted as authored — they are the app's own route prefixes, and a subpath deploy that needs them prefixed should author them that way). ok is false when WithRobots was not configured.

func (*UIHost) ServeHTTP 

func (ds *UIHost) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP makes UIHost satisfy http.Handler by routing through a private router that has Mount called on it. Production wiring goes through framework.App.Mount(host); ServeHTTP exists so the host can also be used standalone (tests, embedded experiments) without dragging in the full framework App.

func (*UIHost) SetFanout added in v0.16.0 

func (ds *UIHost) SetFanout(f fanout.Fanout) (stop func(), err error)

SetFanout wires the island manager to a cross-replica fanout so island updates reach sessions whose SSE connection lives on another replica. framework.WithFanout calls this automatically when the host is mounted (via a duck-typed check), so apps normally never call it directly. See island.Manager.SetFanout for the delivery semantics (lossy real-time lane; the durable lane is the outbox's job).

func (*UIHost) SetSessionKey added in v0.38.0 

func (ds *UIHost) SetSessionKey(key []byte)

SetSessionKey replaces the session-signing key. Called once by framework.App.Mount (before any traffic) with the HKDF-derived key from the app secret; every replica configured with the same secret then accepts every other replica's session tokens. Not intended for per-request use.

func (*UIHost) SetStaticFS 

func (ds *UIHost) SetStaticFS(fsys fs.FS)

SetStaticFS sets an embedded filesystem for serving static files.

func (*UIHost) SitemapXML added in v0.26.0 

func (ds *UIHost) SitemapXML(basePath string) (string, bool)

SitemapXML builds the sitemap document WithSitemap configured. It is the single source for both the live /sitemap.xml handler and the static exporter (framework/static), which writes the same bytes to disk. basePath is the URL subpath a static deploy is mounted under (e.g. "/gofastr" for a GitHub Pages project site) and is inserted between the configured BaseURL and each route path; pass "" for the live server or an apex deploy. ok is false when WithSitemap was not configured.

func (*UIHost) StaticDir 

func (ds *UIHost) StaticDir() string

StaticDir returns the configured static directory path.

func (*UIHost) StaticFS 

func (ds *UIHost) StaticFS() fs.FS

StaticFS returns the configured embedded static FS, or nil if none.

Source Files

View all Source files

Directories

Path Synopsis
internal
sessiontoken
Package sessiontoken mints and verifies the stateless HMAC-signed tokens that replace the uihost's in-memory session map.
 Package sessiontoken mints and verifies the stateless HMAC-signed tokens that replace the uihost's in-memory session map.
Package uinoderender maps a validated ui.node.v1 tree (github.com/DonaldMurillo/gofastr/core-ui/uinodev1.Tree) to host-owned HTML by composing the framework's design-system primitives — github.com/DonaldMurillo/gofastr/framework/ui and github.com/DonaldMurillo/gofastr/core-ui/html.
 Package uinoderender maps a validated ui.node.v1 tree (github.com/DonaldMurillo/gofastr/core-ui/uinodev1.Tree) to host-owned HTML by composing the framework's design-system primitives — github.com/DonaldMurillo/gofastr/framework/ui and github.com/DonaldMurillo/gofastr/core-ui/html.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.