How infogulch/xtemplate works
Project type and purpose
• Project Type: Open-source Go library plus CLI/web server tool
• Purpose: Provide an in-memory, reloadable, html/template–based web server (“xtemplate”) that maps filesystem templates to HTTP routes, injects pluggable data sources (DB, FS, NATS, KV), and serves static assets efficiently.
File structure
• Top-level artifacts:
• cmd/main.go: the reference CLI that builds and runs an xtemplate Server
• config.go, server.go, instance.go: core library entrypoints
• handlers.go, build.go, dot_*.go: template loader, request handlers, and dot-provider implementations
• test/: end-to-end tests, migrations, templates, hurl scripts
• app/: example application showing how to wire xtemplate in code
• Patterns and conventions:
• Package layout follows library (root) + cmd + example + test
• Dot-provider pattern for pluggable context fields (DotDB, DotFS, DotNATS, DotKV)
• Build scripts (build.go, make_tool.cue) for codegen / releases
Key insights from README
• Architecture highlights:
• At startup, templates are parsed once and kept in memory
• A reloadable Server wraps an immutable Instance (http.Handler) that routes requests
• Routes are derived from template filenames or define directives
• Dot context provides request-scoped fields and custom data-source APIs
• Built-in providers: database/sql, filesystem, NATS, key-value store
• CLI flags allow embedding templates, watching files, adjusting delimiters, etc.
Main components and interactions (
a. xtemplate CLI / Caddy plugin (cmd/main.go / external Caddy module)
– Reads flags / config → builds a xtemplate.Config
→ calls Config.Server() → obtains a reloadable Server (implements http.Handler)
→ passed to Go’s http.ListenAndServe or Caddy
b. Server (server.go)
– Wraps an atomic pointer to the current Instance
– Exposes .Reload() to regenerate a new Instance on template or config change
c. Instance (instance.go)
– Implements http.Handler
– On initialization, walks templates/ directory → parses every .html file
– Builds a http.ServeMux mapping file paths or define "METHOD /path" names to handlers
– Precomputes static-asset hashes (gzip, brotli) for efficient caching
d. ServeMux & Handlers (handlers.go)
– TemplateHandler: invokes html/template with a DotContext for dynamic pages
– StaticHandler: serves non-template assets with negotiated encoding and cache headers
– SSEHandler: streams Server-Sent Events by invoking a template with .Flush
e. DotContext & Providers (dot_*.go)
– Core fields: .X (Instance metadata), .Req (request wrapper), .Resp (response control), .Flush (SSE)
– Optional providers wired via Config.ContextProviders:
• DotDB: run SQL queries / Exec
• DotFS: list/read files
• DotNATS: publish/request via NATS
• DotKV: read static key-value data
– Each provider’s Value(req) returns a per-request object available in templates
f. html/template + FuncMaps
– Templates execute with built-in and Sprig functions + xtemplate’s custom helpers (markdown, sanitize, trustHtml)
g. Tests & Examples
– test/ directory uses hurl scripts to exercise routing, FS, DB, flags, SSE, NATS
– app/ directory shows embedding xtemplate in a standalone Go app
Architectural patterns & design principles
• Separation of concerns:
• CLI vs. Server vs. Instance vs. Handlers vs. DotProviders
• Immutable instances + hot reload: atomic swap of request handler
• Convention-over-configuration: filesystem → routes mapping
• Provider pattern: inject dynamic capabilities into templates without recompilation
• Single binary deployment: templates on disk or embed via Go’s embed