guikit

README

GUIKit

A high-performance, full-stack Go web framework featuring reactive Live-Components, a custom GML markup engine, and an embedded database.

Features

• Reactive Live-Components: Real-time DOM patching over thread-safe WebSockets, inspired by LiveView architectures.
• GML Markup Engine: A custom lexical parser and AST evaluator for a clean, component-driven template syntax.
• Embedded Database: Deep integration with ultimate_db for seamless persistence and session management without external dependencies.
• Production-Grade Security: Built-in Content Security Policy (CSP) noncing, path-traversal guards, and strict HTTP headers to prevent XSS and file-system exploits.
• In-Memory Caching: High-performance template caching to eliminate disk I/O on active routes.
• Virtual File System: Package your entire application (templates, assets, and database) into a single .gweb zip archive for trivial deployment.

Installation

GUIKit requires Go 1.25.10. Initialize your module and fetch GUIKit alongside its custom database dependency:

go mod init guikit
go get github.com/gorilla/websocket
go get github.com/gddisney/ultimate_db
go get github.com/gddisney/guikit
go mod tidy

Quick Start

1. Initialize the Engine (main.go)

package main

import (
	"log"
	"guikit"
)

func main() {
	// Initialize the framework with DB and WAL file paths
	engine, err := guikit.New("app.db", "app.wal")
	if err != nil {
		log.Fatalf("Failed to initialize GUIKit: %v", err)
	}

	// Define a protected route
	engine.Get("/", func(c *guikit.Context) {
		c.Data["Title"] = "Welcome to GUIKit"
		engine.Render(c, "views/index")
	})

	// Run the CLI / Server
	engine.Run()
}

2. Create a View (views/index.gml)

<wrapper "views/layout.gml">
	<h1 class="text-2xl font-bold">{{ .Title }}</h1>
	<p>This is a fast, secure, and reactive web interface running on GUIKit.</p>
</wrapper>

CLI Usage

GUIKit includes a built-in command-line interface for packing and serving your application seamlessly.

Serve Locally

Run your application in development mode on a specified port:

go run main.go serve 8080

Pack for Production

Bundle your entire application into a .gweb virtual file system archive:

go run main.go pack . build/app.gweb

Serve an Archive

Deploy by serving assets and routes directly out of a packed .gweb file:

go run main.go serve build/app.gweb 8080

Security & Architecture

GUIKit is hardened out-of-the-box for production stability:

• CSP Noncing: Every request generates a unique cryptographic nonce applied to all inline scripts via internal middleware to mitigate XSS vulnerabilities.
• Path Traversal Prevention: The GML engine strictly sanitizes all <wrapper> and <import> paths to restrict directory traversal escapes.
• Concurrent Write Safety: WebSocket connections are entirely thread-safe to prevent memory corruption and race condition panics under high traffic.
• Dead-Connection Sweeping: Automatic heartbeats (ping/pong) and failed client pruning cleanly sweep resources behind load balancers.

Documentation

Index

• Variables
• type Context
• type Element
  • func (e Element) Eval() string
• type GUIKit
  • func New(dbPath, walPath string) (*GUIKit, error)
  • func (gk *GUIKit) Broadcast(event string, payload interface{})
  • func (gk *GUIKit) Get(pattern string, handler func(c *Context))
  • func (gk *GUIKit) GetGlobal(key string) (interface{}, bool)
  • func (gk *GUIKit) GetGlobalMap() map[string]interface{}
  • func (gk *GUIKit) GetNonce(r *http.Request) string
  • func (gk *GUIKit) GetSession(key string) string
  • func (gk *GUIKit) HandleWebSocket(w http.ResponseWriter, r *http.Request)
  • func (gk *GUIKit) Post(pattern string, handler func(c *Context))
  • func (gk *GUIKit) RegisterComponent(comp LiveComponent)
  • func (gk *GUIKit) Render(c *Context, viewPath string)
  • func (gk *GUIKit) Run()
  • func (gk *GUIKit) SecureHeaders(next http.HandlerFunc) http.HandlerFunc
  • func (gk *GUIKit) SetGlobal(key string, value interface{})
  • func (gk *GUIKit) SetSession(key string, value string) error
  • func (gk *GUIKit) SetSessionTTL(key string, value string, ttl time.Duration) error
• type IncomingEvent
• type LiveComponent
• type Node
• type OutgoingPatch
• type Parser
  • func NewParser(src string) *Parser
  • func (p *Parser) Parse() []Node
• type Text
  • func (t Text) Eval() string
• type ThreadSafeConn
  • func (s *ThreadSafeConn) Close() error
  • func (s *ThreadSafeConn) WriteJSON(v interface{}) error
  • func (s *ThreadSafeConn) WriteMessage(messageType int, data []byte) error

Variables

var AppFS fs.FS

Types

type Context

type Context struct {
	W        http.ResponseWriter
	R        *http.Request
	Data     map[string]interface{}
	CspNonce string
}

type Element

type Element struct {
	Tag        string
	Attributes map[string]string
	Children   []Node
}

func (Element) Eval

func (e Element) Eval() string

type GUIKit

type GUIKit struct {
	DB          *ultimate_db.DB
	BP          *ultimate_db.BufferPool
	Mux         *http.ServeMux
	SessionPage ultimate_db.PageID
	// contains filtered or unexported fields
}

func New

func New(dbPath, walPath string) (*GUIKit, error)

func (*GUIKit) Broadcast

func (gk *GUIKit) Broadcast(event string, payload interface{})

func (*GUIKit) Get

func (gk *GUIKit) Get(pattern string, handler func(c *Context))

func (*GUIKit) GetGlobal

func (gk *GUIKit) GetGlobal(key string) (interface{}, bool)

GetGlobal safely reads from the global state map

func (*GUIKit) GetGlobalMap

func (gk *GUIKit) GetGlobalMap() map[string]interface{}

GetGlobalMap returns a snapshot of the global state for rendering

func (*GUIKit) GetNonce

func (gk *GUIKit) GetNonce(r *http.Request) string

func (*GUIKit) GetSession

func (gk *GUIKit) GetSession(key string) string

func (*GUIKit) HandleWebSocket

func (gk *GUIKit) HandleWebSocket(w http.ResponseWriter, r *http.Request)

func (*GUIKit) Post

func (gk *GUIKit) Post(pattern string, handler func(c *Context))

func (*GUIKit) RegisterComponent

func (gk *GUIKit) RegisterComponent(comp LiveComponent)

func (*GUIKit) Render

func (gk *GUIKit) Render(c *Context, viewPath string)

func (*GUIKit) Run

func (gk *GUIKit) Run()

func (*GUIKit) SecureHeaders

func (gk *GUIKit) SecureHeaders(next http.HandlerFunc) http.HandlerFunc

func (*GUIKit) SetGlobal

func (gk *GUIKit) SetGlobal(key string, value interface{})

SetGlobal safely writes to the global state map

func (*GUIKit) SetSession

func (gk *GUIKit) SetSession(key string, value string) error

func (*GUIKit) SetSessionTTL

func (gk *GUIKit) SetSessionTTL(key string, value string, ttl time.Duration) error

type IncomingEvent

type IncomingEvent struct {
	CompID string            `json:"id"`
	Event  string            `json:"event"`
	Data   map[string]string `json:"data"`
}

type LiveComponent

type LiveComponent interface {
	ID() string
	Render() string
}

type Node

type Node interface {
	Eval() string
}

type OutgoingPatch

type OutgoingPatch struct {
	CompID string `json:"id"`
	HTML   string `json:"html"`
}

type Parser

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

func NewParser

func NewParser(src string) *Parser

func (*Parser) Parse

func (p *Parser) Parse() []Node

type Text

type Text string

func (Text) Eval

func (t Text) Eval() string

type ThreadSafeConn

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

ThreadSafeConn wraps a websocket connection to ensure synchronized write access.

func (*ThreadSafeConn) Close

func (s *ThreadSafeConn) Close() error

func (*ThreadSafeConn) WriteJSON

func (s *ThreadSafeConn) WriteJSON(v interface{}) error

func (*ThreadSafeConn) WriteMessage

func (s *ThreadSafeConn) WriteMessage(messageType int, data []byte) error