Haelnorr
bdae21ec0b
- Updated JWT README.md with proper format and version number - Updated HWS README.md and created comprehensive doc.go - Updated HWSAuth README.md and doc.go with proper environment variable documentation - All documentation now follows GOLIB rules format 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
145 lines
3.9 KiB
Go
145 lines
3.9 KiB
Go
// Package hws provides a lightweight HTTP web server framework built on top of Go's standard library.
|
|
//
|
|
// HWS (H Web Server) is an opinionated framework that leverages Go 1.22+ routing patterns
|
|
// with built-in middleware, structured error handling, and production-ready defaults. It
|
|
// integrates seamlessly with other golib packages like hlog for logging and hwsauth for
|
|
// authentication.
|
|
//
|
|
// # Basic Usage
|
|
//
|
|
// Create a server with environment-based configuration:
|
|
//
|
|
// cfg, err := hws.ConfigFromEnv()
|
|
// if err != nil {
|
|
// log.Fatal(err)
|
|
// }
|
|
//
|
|
// server, err := hws.NewServer(cfg)
|
|
// if err != nil {
|
|
// log.Fatal(err)
|
|
// }
|
|
//
|
|
// routes := []hws.Route{
|
|
// {
|
|
// Path: "/",
|
|
// Method: hws.MethodGET,
|
|
// Handler: http.HandlerFunc(homeHandler),
|
|
// },
|
|
// }
|
|
//
|
|
// server.AddRoutes(routes...)
|
|
// server.AddMiddleware()
|
|
//
|
|
// ctx := context.Background()
|
|
// server.Start(ctx)
|
|
//
|
|
// <-server.Ready()
|
|
//
|
|
// # Configuration
|
|
//
|
|
// HWS can be configured via environment variables using ConfigFromEnv:
|
|
//
|
|
// HWS_HOST=127.0.0.1 # Host to listen on (default: 127.0.0.1)
|
|
// HWS_PORT=3000 # Port to listen on (default: 3000)
|
|
// HWS_GZIP=false # Enable GZIP compression (default: false)
|
|
// HWS_READ_HEADER_TIMEOUT=2 # Header read timeout in seconds (default: 2)
|
|
// HWS_WRITE_TIMEOUT=10 # Write timeout in seconds (default: 10)
|
|
// HWS_IDLE_TIMEOUT=120 # Idle connection timeout in seconds (default: 120)
|
|
//
|
|
// Or programmatically:
|
|
//
|
|
// cfg := &hws.Config{
|
|
// Host: "0.0.0.0",
|
|
// Port: 8080,
|
|
// GZIP: true,
|
|
// ReadHeaderTimeout: 5 * time.Second,
|
|
// WriteTimeout: 15 * time.Second,
|
|
// IdleTimeout: 120 * time.Second,
|
|
// }
|
|
//
|
|
// # Routing
|
|
//
|
|
// HWS uses Go 1.22+ routing patterns with method-specific handlers:
|
|
//
|
|
// routes := []hws.Route{
|
|
// {
|
|
// Path: "/users/{id}",
|
|
// Method: hws.MethodGET,
|
|
// Handler: http.HandlerFunc(getUser),
|
|
// },
|
|
// {
|
|
// Path: "/users/{id}",
|
|
// Method: hws.MethodPUT,
|
|
// Handler: http.HandlerFunc(updateUser),
|
|
// },
|
|
// }
|
|
//
|
|
// Path parameters can be accessed using r.PathValue():
|
|
//
|
|
// func getUser(w http.ResponseWriter, r *http.Request) {
|
|
// id := r.PathValue("id")
|
|
// // ... handle request
|
|
// }
|
|
//
|
|
// # Middleware
|
|
//
|
|
// HWS supports middleware with predictable execution order. Built-in middleware includes
|
|
// request logging, timing, and GZIP compression:
|
|
//
|
|
// server.AddMiddleware()
|
|
//
|
|
// Custom middleware can be added using standard http.Handler wrapping:
|
|
//
|
|
// server.AddMiddleware(customMiddleware)
|
|
//
|
|
// # Error Handling
|
|
//
|
|
// HWS provides structured error handling with customizable error pages:
|
|
//
|
|
// errorPageFunc := func(w http.ResponseWriter, r *http.Request, status int) {
|
|
// w.WriteHeader(status)
|
|
// fmt.Fprintf(w, "Error: %d", status)
|
|
// }
|
|
//
|
|
// server.AddErrorPage(errorPageFunc)
|
|
//
|
|
// # Logging
|
|
//
|
|
// HWS integrates with hlog for structured logging:
|
|
//
|
|
// logger, _ := hlog.NewLogger(loggerCfg, os.Stdout)
|
|
// server.AddLogger(logger)
|
|
//
|
|
// The server will automatically log requests, errors, and server lifecycle events.
|
|
//
|
|
// # Static Files
|
|
//
|
|
// HWS provides safe static file serving that prevents directory listing:
|
|
//
|
|
// server.AddStaticFiles("/static", "./public")
|
|
//
|
|
// # Graceful Shutdown
|
|
//
|
|
// HWS supports graceful shutdown via context cancellation:
|
|
//
|
|
// ctx, cancel := context.WithCancel(context.Background())
|
|
// defer cancel()
|
|
//
|
|
// server.Start(ctx)
|
|
//
|
|
// // Wait for shutdown signal
|
|
// sigChan := make(chan os.Signal, 1)
|
|
// signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
|
|
// <-sigChan
|
|
//
|
|
// // Cancel context to trigger graceful shutdown
|
|
// cancel()
|
|
//
|
|
// # Integration
|
|
//
|
|
// HWS integrates with:
|
|
// - git.haelnorr.com/h/golib/hlog: For structured logging with zerolog
|
|
// - git.haelnorr.com/h/golib/hwsauth: For JWT-based authentication
|
|
// - git.haelnorr.com/h/golib/jwt: For JWT token management
|
|
package hws
|