Upgrader WSUpgrader

SessionStore SessionStore

Authenticator Authenticator // User authentication and session grouping

PubSubBroadcaster pubsub.Broadcaster // Optional: for distributed broadcasting across instances

AllowedOrigins []string // Allowed WebSocket origins (empty = allow all in dev, restrict in prod)

WebSocketDisabled bool

LoadingDisabled bool // Disables automatic loading indicator on page load

TemplateFiles []string // If set, overrides auto-discovery

TemplateBaseDir string // Base directory for template auto-discovery (default: directory of calling code via runtime.Caller)

IgnoreTemplateDirs []string // Additional directories to ignore during auto-discovery

DevMode bool // Development mode - use local client library instead of CDN

MaxConnections int64 // Maximum total connections (0 = unlimited)

MaxConnectionsPerGroup int64 // Maximum connections per group (0 = unlimited)

MessageRateLimit float64 // Messages per second per connection (0 = unlimited, default 10)

MessageRateBurst int // Burst capacity for rate limiting (default 20)

CookieMaxAge time.Duration // Session cookie max age (default: 1 year)

UploadConfigs map[string]uploadtypes.UploadConfig // Upload field configurations

WebSocketBufferSize int // WebSocket send buffer size per connection (default: 50)

ComponentTemplates []*TemplateSet // Component library templates (parsed before project templates)

ProgressiveEnhancement bool // Enable non-JS form submission support with PRG pattern (default: true)

TrustForwardedHeaders bool // Trust X-Forwarded-Proto header for scheme detection (default: true)

DispatchBufferSize int // Broadcast dispatch channel buffer per connection (default: 16)

// FS is the embedded filesystem containing the template files.

FS embed.FS

// Pattern is the glob pattern for matching template files within FS.

// Examples: "templates/*.tmpl", "*.tmpl"

Pattern string

// Namespace identifies the component type for this template set.

// Used for documentation and debugging purposes.

// Example: "dropdown" for templates like "lvt:dropdown:searchable:v1"

Namespace string

// Funcs provides additional template functions for this component.

// These are merged with the base template functions when parsing.

Funcs template.FuncMap

name string

templateStr string

tmpl *template.Template

wrapperID string

funcs template.FuncMap

mu sync.RWMutex // Protects mutable state fields below

lastHTML string

lastTree *treeNode // Store previous tree segments for comparison

hasInitialTree bool

keyGen *keyGenerator // Per-template key generation for wrapper approach

config Config // Template configuration

uploadRegistry interface{} // Upload registry for this connection (*upload.Registry)

cachedParseTemplate *parse.Template // Cached AST to avoid re-parsing on every render

cachedBodyContent string // Cached result of ExtractTemplateBodyContent(t.templateStr)

cachedBodyContentValid bool // Whether cachedBodyContent has been computed (empty string is valid)

if len(funcMap) == 0 {

return t

}

if t.funcs == nil {

t.funcs = make(template.FuncMap, len(funcMap))

}

for name, fn := range funcMap {

t.funcs[name] = fn

}

// Update the existing parsed template if one is available.

t.mu.Lock()

if t.tmpl != nil {

t.tmpl = t.tmpl.Funcs(t.funcs)

}

t.cachedParseTemplate = nil // Invalidate cached AST since funcMap changed

t.mu.Unlock()

return t

return func(c *Config) {

c.TemplateFiles = files

}

return func(c *Config) {

c.TemplateBaseDir = dir

}

return func(c *Config) {

c.Upgrader = upgrader

}

return func(c *Config) {

c.SessionStore = store

}

return func(c *Config) {

c.WebSocketDisabled = true

}

return func(c *Config) {

c.LoadingDisabled = true

}

return func(c *Config) {

c.DevMode = enabled

}

return func(c *Config) {

c.Authenticator = auth

}

return func(c *Config) {

c.AllowedOrigins = origins

}

return func(c *Config) {

c.TrustForwardedHeaders = trust

}

return func(c *Config) {

if gu, ok := c.Upgrader.(*GorillaUpgrader); ok {

gu.SetCheckOrigin(func(r *http.Request) bool {

return true

})

} else {

slog.Warn("WithPermissiveOriginCheck has no effect on non-Gorilla WSUpgrader implementations")

}

}

return func(c *Config) {

c.IgnoreTemplateDirs = append(c.IgnoreTemplateDirs, dirs...)

}

return func(c *Config) {

c.MaxConnections = max

}

return func(c *Config) {

c.MaxConnectionsPerGroup = max

}

return func(c *Config) {

if size <= 0 {

slog.Warn("Invalid WebSocketBufferSize, using default", slog.Int("value", size), slog.Int("default", 50))

c.WebSocketBufferSize = 50

} else {

c.WebSocketBufferSize = size

}

}

return func(c *Config) {

c.DispatchBufferSize = size

}

return func(c *Config) {

if gu, ok := c.Upgrader.(*GorillaUpgrader); ok {

gu.SetCompression(true)

} else {

slog.Warn("WithWebSocketCompression has no effect on non-Gorilla WSUpgrader implementations")

}

}

return func(c *Config) {

c.MessageRateLimit = messagesPerSecond

c.MessageRateBurst = burstCapacity

}

return func(c *Config) {

c.CookieMaxAge = maxAge

}

return func(c *Config) {

if c.UploadConfigs == nil {

c.UploadConfigs = make(map[string]uploadtypes.UploadConfig)

}

c.UploadConfigs[name] = config

}

return func(c *Config) {

c.PubSubBroadcaster = broadcaster

}

return func(c *Config) {

c.ComponentTemplates = append(c.ComponentTemplates, sets...)

}

return func(c *Config) {

c.ProgressiveEnhancement = enabled

}

if err != nil {

panic(err)

}

return t

return func(r *http.Request) bool {

// Development mode: allow all origins for convenience

if devMode {

return true

}

origin := r.Header.Get("Origin")

// No origin header: allow (same-origin requests may not include Origin)

if origin == "" {

return true

}

// If AllowedOrigins is specified, check against the list

if len(allowedOrigins) > 0 {

for _, allowed := range allowedOrigins {

if origin == allowed {

return true

}

}

// Origin not in allowed list

return false

}

// Default: same-origin only

// Compare origin against the request's Host header

host := r.Host

if host == "" {

return false

}

// Derive scheme from X-Forwarded-Proto (if trusted) or r.TLS (direct).

// See WithTrustForwardedHeaders godoc for security trade-offs.

scheme := ""

if trustForwardedHeaders {

if proto := r.Header.Get("X-Forwarded-Proto"); proto != "" {

first, _, _ := strings.Cut(proto, ",")

val := strings.ToLower(strings.TrimSpace(first))

if val == "http" || val == "https" {

scheme = val

}

}

}

if scheme == "" {

scheme = "https"

if r.TLS == nil {

scheme = "http"

}

}

// Check if origin matches scheme://host

expectedOrigin := scheme + "://" + host

return origin == expectedOrigin

}

// Default configuration

config := Config{

Upgrader: NewGorillaUpgrader(), // Default: gorilla with 1KB buffers

SessionStore: NewMemorySessionStore(),

Authenticator: &AnonymousAuthenticator{}, // Default: browser-based session grouping

MessageRateLimit: 10.0, // Default: 10 messages/sec

MessageRateBurst: 20, // Default: burst of 20

CookieMaxAge: 365 * 24 * time.Hour, // Default: 1 year

WebSocketBufferSize: defaultWebSocketBufferSize, // Override via WithWebSocketBufferSize or EnvConfig

ProgressiveEnhancement: true, // Default: enabled for non-JS form support

TrustForwardedHeaders: true, // Default: trust X-Forwarded-Proto (safe behind proxy)

}

// Apply options

for _, opt := range opts {

opt(&config)

}

// Set secure CheckOrigin on the default gorilla upgrader (after options are applied)

if gu, ok := config.Upgrader.(*GorillaUpgrader); ok {

if gu.inner.CheckOrigin == nil {

gu.SetCheckOrigin(createSecureOriginChecker(config.AllowedOrigins, config.DevMode, config.TrustForwardedHeaders))

}

}

// Log DevMode configuration for debugging

slog.Debug("Template created",

slog.String("name", name),

slog.Bool("dev_mode", config.DevMode))

tmpl := &Template{

name: name,

keyGen: compat.NewKeyGenerator(),

config: config,

}

// Parse component templates first (before project templates)

// This establishes a base layer of templates that project templates can override

if len(config.ComponentTemplates) > 0 {

if err := tmpl.parseComponentTemplates(config.ComponentTemplates); err != nil {

return nil, fmt.Errorf("livetemplate.New(%q): failed to parse component templates: %w", name, err)

}

if config.DevMode {

slog.Debug("Parsed component template sets",

slog.Int("count", len(config.ComponentTemplates)))

}

}

// Auto-discover and parse templates if not explicitly provided

if len(config.TemplateFiles) == 0 {

// Use TemplateBaseDir from config if provided, otherwise fall back to runtime.Caller

files, err := discovery.DiscoverTemplateFiles(config.TemplateBaseDir, config.IgnoreTemplateDirs)

if err != nil {

return nil, fmt.Errorf("livetemplate.New(%q): template auto-discovery failed in %q: %w", name, config.TemplateBaseDir, err)

}

if len(files) == 0 {

return nil, fmt.Errorf("livetemplate.New(%q): no template files found in %q (ignored: %v)", name, config.TemplateBaseDir, config.IgnoreTemplateDirs)

}

if config.DevMode {

slog.Debug("Auto-discovered template files",

slog.Int("count", len(files)))

}

if _, err := tmpl.ParseFiles(files...); err != nil {

return nil, fmt.Errorf("livetemplate.New(%q): failed to parse discovered files %v: %w", name, files, err)

}

} else {

if _, err := tmpl.ParseFiles(config.TemplateFiles...); err != nil {

return nil, fmt.Errorf("livetemplate.New(%q): failed to parse template files %v: %w", name, config.TemplateFiles, err)

}

}

return tmpl, nil

// Acquire read lock to safely read template fields

t.mu.RLock()

name := t.name

templateStr := t.templateStr

wrapperID := t.wrapperID

config := t.config

tmpl := t.tmpl

funcs := t.funcs

cachedParse := t.cachedParseTemplate

bodyContent := t.cachedBodyContent

bodyContentValid := t.cachedBodyContentValid

t.mu.RUnlock()

// Share immutable data from master instead of re-creating per clone.

// Go's html/template.Execute() is safe for concurrent use after parsing

// (see go.dev/src/html/template/template.go line 118). The template is

// never modified after Parse(), so sharing is safe.

clone := &Template{

name: name,

templateStr: templateStr,

tmpl: tmpl, // Share parsed template (concurrent Execute is safe)

wrapperID: wrapperID,

funcs: funcs, // Share FuncMap (read-only after Parse)

config: config, // keyGen allocated lazily on first buildTree (nil-safe at line 1582)

cachedParseTemplate: cachedParse, // Share parsed AST + builtins

cachedBodyContent: bodyContent, // Share extracted body content

cachedBodyContentValid: bodyContentValid,

// Don't copy lastData, lastHTML, lastTree, etc. - start fresh per session

}

return clone, nil

t.mu.Lock()

defer t.mu.Unlock()

t.uploadRegistry = registry

// Normalize template spacing to handle formatter-added spaces

// This prevents issues when formatters add spaces like "{{ range" instead of "{{range"

text = compat.NormalizeTemplateSpacing(text)

// Determine if this is a full HTML document

isFullHTML := strings.Contains(text, "<!DOCTYPE") || strings.Contains(text, "<html")

// Always generate wrapper ID for consistent update targeting

t.wrapperID = compat.GenerateRandomID()

// First, parse WITHOUT wrapper to check if flattening is needed

baseTemplate := template.New(t.name)

if len(t.funcs) > 0 {

baseTemplate = baseTemplate.Funcs(t.funcs)

}

tmpl, err := baseTemplate.Parse(text)

if err != nil {

return nil, fmt.Errorf("template '%s' parse error: %w", t.name, err)

}

return t.parseInternal(text, tmpl, isFullHTML)

// Check if template uses composition features and flatten if needed

if parse.HasTemplateComposition(baseTemplate) {

// Flatten the template to resolve all {{define}}/{{template}}/{{block}}

flattenedStr, err := parse.FlattenTemplate(baseTemplate)

if err != nil {

return nil, fmt.Errorf("template flattening failed: %w", err)

}

// Store flattened version for tree generation (WITHOUT wrapper)

// This ensures updates use the flattened template

text = flattenedStr

}

// Expand multi-action bracket syntax before parsing.