Merge pull request 'hlogdoc' (#3) from hlogdoc into master

Reviewed-on: #3

RULES.md

@@ -12,7 +12,7 @@ The README for each module should be laid out as follows:
 - Feature list (DO NOT USE EMOTICONS)
 - Installation (go get)
 - Quick Start (brief example of setting up and using)
-- Documentation links to the wiki
+- Documentation links to the wiki (path is `../golib/wiki/<package>.md`)
 - Additional information (e.g. supported databases if package has database features)
 - License
 - Contributing

hlog/README.md

@@ -55,7 +55,7 @@ func main() {
 
 ## Documentation
 
-For detailed documentation, see the [HLog Wiki](https://git.haelnorr.com/h/golib-wiki/HLog).
+For detailed documentation, see the [HLog Wiki](https://git.haelnorr.com/h/golib/wiki/HLog.md).
 
 Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/hlog).
 

hws/README.md

@@ -1,21 +1,19 @@
-# HWS (H Web Server)
+# HWS (H Web Server) - v0.2.2
 
-[![Go Reference](https://pkg.go.dev/badge/git.haelnorr.com/h/golib/hws.svg)](https://pkg.go.dev/git.haelnorr.com/h/golib/hws)
+A lightweight, opinionated HTTP web server framework for Go built on top of the standard library's net/http.
-
-A lightweight, opinionated HTTP web server framework for Go built on top of the standard library's `net/http`.
 
 ## Features
 
-- 🚀 Built on Go 1.22+ routing patterns with method and path matching
+- Built on Go 1.22+ routing patterns with method and path matching
-- 🎯 Structured error handling with customizable error pages
+- Structured error handling with customizable error pages
-- 📝 Integrated logging with zerolog via hlog
+- Integrated logging with zerolog via hlog
-- 🔧 Middleware support with predictable execution order
+- Middleware support with predictable execution order
-- 🗜️ GZIP compression support
+- GZIP compression support
-- 🔒 Safe static file serving (prevents directory listing)
+- Safe static file serving (prevents directory listing)
-- ⚙️ Environment variable configuration
+- Environment variable configuration with ConfigFromEnv
-- ⏱️ Request timing and logging middleware
+- Request timing and logging middleware
-- 💚 Graceful shutdown support
+- Graceful shutdown support
-- 🏥 Built-in health check endpoint
+- Built-in health check endpoint
 
 ## Installation
 
@@ -30,8 +28,8 @@ package main
 
 import (
     "context"
-    "git.haelnorr.com/h/golib/hws"
     "net/http"
+    "git.haelnorr.com/h/golib/hws"
 )
 
 func main() {
@@ -79,34 +77,13 @@ func getUserHandler(w http.ResponseWriter, r *http.Request) {
 
 ## Documentation
 
-Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/h/golib/wiki/hws).
+For detailed documentation, see the [HWS Wiki](https://git.haelnorr.com/h/golib/wiki/HWS.md).
 
-### Key Topics
+Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/hws).
-
-- [Configuration](https://git.haelnorr.com/h/golib/wiki/hws#configuration)
-- [Routing](https://git.haelnorr.com/h/golib/wiki/hws#routing)
-- [Middleware](https://git.haelnorr.com/h/golib/wiki/hws#middleware)
-- [Error Handling](https://git.haelnorr.com/h/golib/wiki/hws#error-handling)
-- [Logging](https://git.haelnorr.com/h/golib/wiki/hws#logging)
-- [Static Files](https://git.haelnorr.com/h/golib/wiki/hws#static-files)
-- [Graceful Shutdown](https://git.haelnorr.com/h/golib/wiki/hws#graceful-shutdown)
-- [Complete Examples](https://git.haelnorr.com/h/golib/wiki/hws#complete-production-example)
-
-## Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `HWS_HOST` | Host to listen on | `127.0.0.1` |
-| `HWS_PORT` | Port to listen on | `3000` |
-| `HWS_TRUSTED_HOST` | Trusted hostname/domain | Same as Host |
-| `HWS_GZIP` | Enable GZIP compression | `false` |
-| `HWS_READ_HEADER_TIMEOUT` | Header read timeout (seconds) | `2` |
-| `HWS_WRITE_TIMEOUT` | Write timeout (seconds) | `10` |
-| `HWS_IDLE_TIMEOUT` | Idle connection timeout (seconds) | `120` |
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the LICENSE file for details.
 
 ## Contributing
 
@@ -114,6 +91,6 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## Related Projects
 
-- [HWSAuth](https://git.haelnorr.com/h/golib/hwsauth) - JWT authentication middleware for HWS
+- [hwsauth](https://git.haelnorr.com/h/golib/hwsauth) - JWT authentication middleware for HWS
 - [hlog](https://git.haelnorr.com/h/golib/hlog) - Structured logging with zerolog
 - [jwt](https://git.haelnorr.com/h/golib/jwt) - JWT token generation and validation

hws/doc.go

@@ -0,0 +1,144 @@
+// 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

hwsauth/README.md

@@ -1,19 +1,19 @@
-# HWSAuth
+# HWSAuth - v0.3.2
 
-[![Go Reference](https://pkg.go.dev/badge/git.haelnorr.com/h/golib/hwsauth.svg)](https://pkg.go.dev/git.haelnorr.com/h/golib/hwsauth)
+JWT-based authentication middleware for the HWS web framework.
-
-JWT-based authentication middleware for the [HWS](https://git.haelnorr.com/h/golib/hws) web framework.
 
 ## Features
 
-- 🔐 JWT-based authentication with access and refresh tokens
+- JWT-based authentication with access and refresh tokens
-- 🔄 Automatic token rotation and refresh
+- Automatic token rotation and refresh
-- 🎯 Generic over user model and transaction types
+- Generic over user model and transaction types
-- 💾 ORM-agnostic transaction handling (works with GORM, Bun, sqlx, etc.)
+- ORM-agnostic transaction handling (works with GORM, Bun, sqlx, database/sql)
-- ⚙️ Environment variable configuration
+- Environment variable configuration with ConfigFromEnv
-- 🛡️ Middleware for protecting routes
+- Middleware for protecting routes
-- 🔒 SSL cookie security support
+- SSL cookie security support
-- 📦 Type-safe with Go generics
+- Type-safe with Go generics
+- Path ignoring for public routes
+- Automatic re-authentication handling
 
 ## Installation
 
@@ -29,9 +29,9 @@ package main
 import (
     "context"
     "database/sql"
+    "net/http"
     "git.haelnorr.com/h/golib/hwsauth"
     "git.haelnorr.com/h/golib/hws"
-    "github.com/rs/zerolog"
 )
 
 type User struct {
@@ -69,6 +69,15 @@ func main() {
     serverCfg, _ := hws.ConfigFromEnv()
     server, _ := hws.NewServer(serverCfg)
 
+    // Create logger
+    logger, _ := hlog.NewLogger(loggerCfg, os.Stdout)
+
+    // Create error page function
+    errorPageFunc := func(w http.ResponseWriter, r *http.Request, status int) {
+        w.WriteHeader(status)
+        fmt.Fprintf(w, "Error: %d", status)
+    }
+
     // Create authenticator
     auth, _ := hwsauth.NewAuthenticator[User, *sql.Tx](
         cfg,
@@ -93,7 +102,7 @@ func main() {
     // Add authentication middleware
     server.AddMiddleware(auth.Authenticate())
 
-    // Optionally ignore public paths
+    // Ignore public paths
     auth.IgnorePaths("/", "/login", "/register", "/static")
 
     // Start server
@@ -106,18 +115,9 @@ func main() {
 
 ## Documentation
 
-Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/h/golib/wiki/hwsauth).
+For detailed documentation, see the [HWSAuth Wiki](https://git.haelnorr.com/h/golib/wiki/HWSAuth.md).
 
-### Key Topics
+Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/hwsauth).
-
-- [Configuration](https://git.haelnorr.com/h/golib/wiki/hwsauth#configuration)
-- [User Model](https://git.haelnorr.com/h/golib/wiki/hwsauth#user-model)
-- [Authentication Flow](https://git.haelnorr.com/h/golib/wiki/hwsauth#authentication-flow)
-- [Login & Logout](https://git.haelnorr.com/h/golib/wiki/hwsauth#login-logout)
-- [Route Protection](https://git.haelnorr.com/h/golib/wiki/hwsauth#route-protection)
-- [Token Refresh](https://git.haelnorr.com/h/golib/wiki/hwsauth#token-refresh)
-- [Using with ORMs](https://git.haelnorr.com/h/golib/wiki/hwsauth#using-with-orms)
-- [Security Best Practices](https://git.haelnorr.com/h/golib/wiki/hwsauth#security-best-practices)
 
 ## Supported ORMs
 
@@ -128,7 +128,7 @@ Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
+This project is licensed under the MIT License - see the LICENSE file for details.
 
 ## Contributing
 
@@ -138,4 +138,4 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 - [hws](https://git.haelnorr.com/h/golib/hws) - The web server framework
 - [jwt](https://git.haelnorr.com/h/golib/jwt) - JWT token generation and validation
-
+- [hlog](https://git.haelnorr.com/h/golib/hlog) - Structured logging with zerolog

hwsauth/doc.go

@@ -179,18 +179,18 @@
 //
 // # Environment Variables
 //
-// The following environment variables are supported:
+// The following environment variables are supported when using ConfigFromEnv:
 //
-//   - HWSAUTH_SSL: Enable SSL mode (default: false)
+//   - HWSAUTH_SSL: Enable SSL secure cookies (default: false)
-//   - HWSAUTH_TRUSTED_HOST: Trusted host for SSL (required if SSL is true)
+//   - HWSAUTH_TRUSTED_HOST: Full server address for SSL (required if SSL is true)
-//   - HWSAUTH_SECRET_KEY: Secret key for signing tokens (required)
+//   - HWSAUTH_SECRET_KEY: Secret key for signing JWT tokens (required)
 //   - HWSAUTH_ACCESS_TOKEN_EXPIRY: Access token expiry in minutes (default: 5)
 //   - HWSAUTH_REFRESH_TOKEN_EXPIRY: Refresh token expiry in minutes (default: 1440)
 //   - HWSAUTH_TOKEN_FRESH_TIME: Token fresh time in minutes (default: 5)
-//   - HWSAUTH_LANDING_PAGE: Landing page for logged in users (default: "/profile")
+//   - HWSAUTH_LANDING_PAGE: Redirect destination for authenticated users (default: "/profile")
-//   - HWSAUTH_JWT_TABLE_NAME: Custom JWT table name (optional)
+//   - HWSAUTH_DATABASE_TYPE: Database type - postgres, mysql, sqlite, mariadb (default: "postgres")
-//   - HWSAUTH_DATABASE_TYPE: Database type (e.g., "postgres", "mysql")
+//   - HWSAUTH_DATABASE_VERSION: Database version string (default: "15")
-//   - HWSAUTH_DATABASE_VERSION: Database version (e.g., "15")
+//   - HWSAUTH_JWT_TABLE_NAME: Custom JWT blacklist table name (default: "jwtblacklist")
 //
 // # Security Considerations
 //

jwt/README.md

@@ -1,20 +1,19 @@
-# JWT Package
+# JWT - v0.10.1
-
-[![Go Reference](https://pkg.go.dev/badge/git.haelnorr.com/h/golib/jwt.svg)](https://pkg.go.dev/git.haelnorr.com/h/golib/jwt)
 
 JWT (JSON Web Token) generation and validation with database-backed token revocation support.
 
 ## Features
 
-- 🔐 Access and refresh token generation
+- Access and refresh token generation
-- ✅ Token validation with expiration checking
+- Token validation with expiration checking
-- 🚫 Token revocation via database blacklist
+- Token revocation via database blacklist
-- 🗄️ Multi-database support (PostgreSQL, MySQL, SQLite, MariaDB)
+- Multi-database support (PostgreSQL, MySQL, SQLite, MariaDB)
-- 🔧 Compatible with database/sql, GORM, and Bun
+- Compatible with database/sql, GORM, and Bun ORMs
-- 🤖 Automatic table creation and management
+- Automatic table creation and management
-- 🧹 Database-native automatic cleanup
+- Database-native automatic cleanup
-- 🔄 Token freshness tracking
+- Token freshness tracking for sensitive operations
-- 💾 "Remember me" functionality
+- "Remember me" functionality with session vs persistent tokens
+- Manual cleanup method for on-demand token cleanup
 
 ## Installation
 
@@ -41,7 +40,7 @@ func main() {
 
     // Create a transaction getter function
     txGetter := func(ctx context.Context) (jwt.DBTransaction, error) {
-        return db.Begin()
+        return db.BeginTx(ctx, nil)
     }
 
     // Create token generator
@@ -78,16 +77,9 @@ func main() {
 
 ## Documentation
 
-Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/h/golib/wiki/JWT).
+For detailed documentation, see the [JWT Wiki](https://git.haelnorr.com/h/golib/wiki/JWT.md).
 
-### Key Topics
+Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/jwt).
-
-- [Configuration](https://git.haelnorr.com/h/golib/wiki/JWT#configuration)
-- [Token Generation](https://git.haelnorr.com/h/golib/wiki/JWT#token-generation)
-- [Token Validation](https://git.haelnorr.com/h/golib/wiki/JWT#token-validation)
-- [Token Revocation](https://git.haelnorr.com/h/golib/wiki/JWT#token-revocation)
-- [Cleanup](https://git.haelnorr.com/h/golib/wiki/JWT#cleanup)
-- [Using with ORMs](https://git.haelnorr.com/h/golib/wiki/JWT#using-with-orms)
 
 ## Supported Databases
 
@@ -98,8 +90,13 @@ Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/
 
 ## License
 
-See LICENSE file in the repository root.
+This project is licensed under the MIT License - see the LICENSE file for details.
 
 ## Contributing
 
-Contributions are welcome! Please open an issue or submit a pull request.
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Related Projects
+
+- [hwsauth](https://git.haelnorr.com/h/golib/hwsauth) - JWT-based authentication middleware for HWS
+- [hws](https://git.haelnorr.com/h/golib/hws) - HTTP web server framework