web

Documentation

Overview

Package web provides web page support for GlyphLang: static file serving, HTML template rendering, content-type-aware response helpers, and template management with auto-escaping for XSS prevention.

Index

• func ContentTypeForResponse(rt ResponseType) string
• type CacheConfig
  • func DefaultCacheConfig() CacheConfig
  • func (cc CacheConfig) MaxAgeForExtension(ext string) (int, bool)
• type MockHTTPResponseWriter
  • func NewMockHTTPResponseWriter() *MockHTTPResponseWriter
  • func (m *MockHTTPResponseWriter) Header() http.Header
  • func (m *MockHTTPResponseWriter) Write(b []byte) (int, error)
  • func (m *MockHTTPResponseWriter) WriteHeader(statusCode int)
• type PageData
  • func (pd PageData) Set(key string, value interface{}) PageData
• type ResponseHelper
  • func NewResponseHelper() *ResponseHelper
  • func (rh *ResponseHelper) SendFile(w http.ResponseWriter, r *http.Request, rootDir, targetPath string) error
  • func (rh *ResponseHelper) SendHTML(w http.ResponseWriter, status int, htmlContent string)
  • func (rh *ResponseHelper) SendRaw(w http.ResponseWriter, status int, contentType string, body []byte)
  • func (rh *ResponseHelper) SendTemplate(w http.ResponseWriter, engine *TemplateEngine, name string, status int, ...) error
  • func (rh *ResponseHelper) SendText(w http.ResponseWriter, status int, textContent string)
• type ResponseType
• type StaticFileServer
  • func NewStaticFileServer(root string, opts ...StaticOption) (*StaticFileServer, error)
  • func (s *StaticFileServer) Prefix() string
  • func (s *StaticFileServer) Root() string
  • func (s *StaticFileServer) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type StaticOption
  • func WithDirectoryListing(allow bool) StaticOption
  • func WithIndex(filename string) StaticOption
  • func WithMaxAge(seconds int) StaticOption
  • func WithPrefix(prefix string) StaticOption
• type TemplateEngine
  • func NewTemplateEngine(baseDir string) (*TemplateEngine, error)
  • func NewTemplateEngineFromStrings() *TemplateEngine
  • func (e *TemplateEngine) AddFunc(name string, fn interface{})
  • func (e *TemplateEngine) HasTemplate(name string) bool
  • func (e *TemplateEngine) LoadTemplate(name string) error
  • func (e *TemplateEngine) LoadTemplateString(name, content string) error
  • func (e *TemplateEngine) Render(w io.Writer, name string, data interface{}) error
  • func (e *TemplateEngine) RenderString(name string, data interface{}) (string, error)
  • func (e *TemplateEngine) TemplateNames() []string

Functions

func ContentTypeForResponse

func ContentTypeForResponse(rt ResponseType) string

ContentTypeForResponse returns the MIME content-type for a ResponseType.

Types

type CacheConfig

type CacheConfig struct {
	MaxAge         int            // Default max-age in seconds
	ExtensionRules map[string]int // Per-extension max-age overrides
	NoCache        []string       // Extensions that should not be cached
}

CacheConfig holds cache configuration for static files.

func DefaultCacheConfig

func DefaultCacheConfig() CacheConfig

DefaultCacheConfig returns a reasonable default cache configuration.

func (CacheConfig) MaxAgeForExtension

func (cc CacheConfig) MaxAgeForExtension(ext string) (int, bool)

MaxAgeForExtension returns the max-age for a file extension and whether it was an explicit rule.

type MockHTTPResponseWriter

type MockHTTPResponseWriter struct {
	StatusCode int
	HeaderMap  http.Header
	Body       []byte
}

MockHTTPResponseWriter is a minimal mock for testing HTTP responses.

func NewMockHTTPResponseWriter

func NewMockHTTPResponseWriter() *MockHTTPResponseWriter

NewMockHTTPResponseWriter creates a new MockHTTPResponseWriter.

func (*MockHTTPResponseWriter) Header

func (m *MockHTTPResponseWriter) Header() http.Header

func (*MockHTTPResponseWriter) Write

func (m *MockHTTPResponseWriter) Write(b []byte) (int, error)

func (*MockHTTPResponseWriter) WriteHeader

func (m *MockHTTPResponseWriter) WriteHeader(statusCode int)

type PageData

type PageData map[string]interface{}

PageData is a convenience type for template data.

func (PageData) Set

func (pd PageData) Set(key string, value interface{}) PageData

Set adds a key-value pair to the page data and returns the PageData for chaining.

type ResponseHelper

type ResponseHelper struct{}

ResponseHelper provides helpers for writing typed HTTP responses.

func NewResponseHelper

func NewResponseHelper() *ResponseHelper

NewResponseHelper creates a new ResponseHelper.

func (*ResponseHelper) SendFile

func (rh *ResponseHelper) SendFile(w http.ResponseWriter, r *http.Request, rootDir, targetPath string) error

SendFile sends a file as the response. Content type is detected from the filename extension. The rootDir parameter restricts file access to the given directory tree. If rootDir is empty, the current working directory is used.

func (*ResponseHelper) SendHTML

func (rh *ResponseHelper) SendHTML(w http.ResponseWriter, status int, htmlContent string)

SendHTML writes an HTML response with the given status code.

func (*ResponseHelper) SendRaw

func (rh *ResponseHelper) SendRaw(w http.ResponseWriter, status int, contentType string, body []byte)

SendRaw writes raw bytes with a specified content type.

func (*ResponseHelper) SendTemplate

func (rh *ResponseHelper) SendTemplate(w http.ResponseWriter, engine *TemplateEngine, name string, status int, data interface{}) error

SendTemplate renders a named template and writes it as an HTML response.

func (*ResponseHelper) SendText

func (rh *ResponseHelper) SendText(w http.ResponseWriter, status int, textContent string)

SendText writes a plain text response with the given status code.

type ResponseType

type ResponseType string

ResponseType indicates the content type of a response.

const (
	JSON ResponseType = "json"
	HTML ResponseType = "html"
	Text ResponseType = "text"
	File ResponseType = "file"
)

type StaticFileServer

type StaticFileServer struct {
	// contains filtered or unexported fields
}

StaticFileServer serves static files from a directory with path-traversal protection. Uses filepath.EvalSymlinks to resolve symlinks and prevent escape from the root.

func NewStaticFileServer

func NewStaticFileServer(root string, opts ...StaticOption) (*StaticFileServer, error)

NewStaticFileServer creates a new static file server for the given directory. The root directory is resolved via filepath.EvalSymlinks to an absolute canonical path to prevent path traversal and symlink escape attacks.

func (*StaticFileServer) Prefix

func (s *StaticFileServer) Prefix() string

Prefix returns the URL prefix.

func (*StaticFileServer) Root

func (s *StaticFileServer) Root() string

Root returns the absolute root directory of the static file server.

func (*StaticFileServer) ServeHTTP

func (s *StaticFileServer) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves static files with path-traversal and symlink-escape protection. After resolving the file path, filepath.EvalSymlinks verifies the real path remains within the root directory.

type StaticOption

type StaticOption func(*StaticFileServer)

StaticOption configures the static file server.

func WithDirectoryListing

func WithDirectoryListing(allow bool) StaticOption

WithDirectoryListing enables directory listing.

func WithIndex

func WithIndex(filename string) StaticOption

WithIndex sets the default index file name.

func WithMaxAge

func WithMaxAge(seconds int) StaticOption

WithMaxAge sets the Cache-Control max-age header in seconds.

func WithPrefix

func WithPrefix(prefix string) StaticOption

WithPrefix sets the URL prefix to strip before serving files.

type TemplateEngine

type TemplateEngine struct {
	// contains filtered or unexported fields
}

TemplateEngine manages HTML templates with auto-escaping.

func NewTemplateEngine

func NewTemplateEngine(baseDir string) (*TemplateEngine, error)

NewTemplateEngine creates a new template engine. baseDir is the directory to load template files from. It validates that baseDir exists and is a directory.

func NewTemplateEngineFromStrings

func NewTemplateEngineFromStrings() *TemplateEngine

NewTemplateEngineFromStrings creates a template engine that only uses string-based templates (no file loading), bypassing directory validation.

func (*TemplateEngine) AddFunc

func (e *TemplateEngine) AddFunc(name string, fn interface{})

AddFunc registers a custom template function. Must be called before loading templates that use the function.

func (*TemplateEngine) HasTemplate

func (e *TemplateEngine) HasTemplate(name string) bool

HasTemplate checks if a template is registered.

func (*TemplateEngine) LoadTemplate

func (e *TemplateEngine) LoadTemplate(name string) error

LoadTemplate parses and caches a template file.

func (*TemplateEngine) LoadTemplateString

func (e *TemplateEngine) LoadTemplateString(name, content string) error

LoadTemplateString parses and caches a template from a string.

func (*TemplateEngine) Render

func (e *TemplateEngine) Render(w io.Writer, name string, data interface{}) error

Render executes a template with the given data and writes to w.

func (*TemplateEngine) RenderString

func (e *TemplateEngine) RenderString(name string, data interface{}) (string, error)

RenderString executes a template and returns the result as a string.

func (*TemplateEngine) TemplateNames

func (e *TemplateEngine) TemplateNames() []string

TemplateNames returns the names of all registered templates.