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

Reviewed-on: #3
Merge branch 'master' into hlogdoc
2026-01-13 13:53:12 +11:00 · 2026-01-13 13:52:54 +11:00 · 2026-01-13 13:49:21 +11:00 · 2026-01-13 13:40:25 +11:00 · 2026-01-13 13:37:37 +11:00 · 2026-01-13 13:33:39 +11:00
8 changed files with 241 additions and 102 deletions
--- a/RULES.md
+++ b/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
--- a/hlog/LICENSE
+++ b/hlog/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 haelnorr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/hlog/README.md
+++ b/hlog/README.md
@@ -1,4 +1,4 @@
-# HLog - v0.10.2
+# HLog - v0.10.3

 A structured logging package for Go built on top of [zerolog](https://github.com/rs/zerolog). HLog provides simple configuration via environment variables, flexible output options, and automatic log file management.

@@ -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).

--- a/hws/README.md
+++ b/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
- 🎯 Structured error handling with customizable error pages
- 📝 Integrated logging with zerolog via hlog
- 🔧 Middleware support with predictable execution order
- 🗜️ GZIP compression support
- 🔒 Safe static file serving (prevents directory listing)
- ⚙️ Environment variable configuration
- ⏱️ Request timing and logging middleware
- 💚 Graceful shutdown support
- 🏥 Built-in health check endpoint
+- Built on Go 1.22+ routing patterns with method and path matching
+- Structured error handling with customizable error pages
+- Integrated logging with zerolog via hlog
+- Middleware support with predictable execution order
+- GZIP compression support
+- Safe static file serving (prevents directory listing)
+- Environment variable configuration with ConfigFromEnv
+- Request timing and logging middleware
+- Graceful shutdown support
+- 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
-
- [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` |
+Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/hws).

 ## 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
--- a/hws/doc.go
+++ b/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
--- a/hwsauth/README.md
+++ b/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](https://git.haelnorr.com/h/golib/hws) web framework.
+JWT-based authentication middleware for the HWS web framework.

 ## Features

- 🔐 JWT-based authentication with access and refresh tokens
- 🔄 Automatic token rotation and refresh
- 🎯 Generic over user model and transaction types
- 💾 ORM-agnostic transaction handling (works with GORM, Bun, sqlx, etc.)
- ⚙️ Environment variable configuration
- 🛡️ Middleware for protecting routes
- 🔒 SSL cookie security support
- 📦 Type-safe with Go generics
+- JWT-based authentication with access and refresh tokens
+- Automatic token rotation and refresh
+- Generic over user model and transaction types
+- ORM-agnostic transaction handling (works with GORM, Bun, sqlx, database/sql)
+- Environment variable configuration with ConfigFromEnv
+- Middleware for protecting routes
+- SSL cookie security support
+- 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
-
- [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)
+Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/hwsauth).

 ## 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
--- a/hwsauth/doc.go
+++ b/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_TRUSTED_HOST: Trusted host for SSL (required if SSL is true)
-//   - HWSAUTH_SECRET_KEY: Secret key for signing tokens (required)
+//   - HWSAUTH_SSL: Enable SSL secure cookies (default: false)
+//   - HWSAUTH_TRUSTED_HOST: Full server address for SSL (required if SSL is true)
+//   - 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_JWT_TABLE_NAME: Custom JWT table name (optional)
-//   - HWSAUTH_DATABASE_TYPE: Database type (e.g., "postgres", "mysql")
-//   - HWSAUTH_DATABASE_VERSION: Database version (e.g., "15")
+//   - HWSAUTH_LANDING_PAGE: Redirect destination for authenticated users (default: "/profile")
+//   - HWSAUTH_DATABASE_TYPE: Database type - postgres, mysql, sqlite, mariadb (default: "postgres")
+//   - HWSAUTH_DATABASE_VERSION: Database version string (default: "15")
+//   - HWSAUTH_JWT_TABLE_NAME: Custom JWT blacklist table name (default: "jwtblacklist")
 //
 // # Security Considerations
 //
--- a/jwt/README.md
+++ b/jwt/README.md
@@ -1,20 +1,19 @@
-# JWT Package
-
-[![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 - v0.10.1

 JWT (JSON Web Token) generation and validation with database-backed token revocation support.

 ## Features

- 🔐 Access and refresh token generation
- ✅ Token validation with expiration checking
- 🚫 Token revocation via database blacklist
- 🗄️ Multi-database support (PostgreSQL, MySQL, SQLite, MariaDB)
- 🔧 Compatible with database/sql, GORM, and Bun
- 🤖 Automatic table creation and management
- 🧹 Database-native automatic cleanup
- 🔄 Token freshness tracking
- 💾 "Remember me" functionality
+- Access and refresh token generation
+- Token validation with expiration checking
+- Token revocation via database blacklist
+- Multi-database support (PostgreSQL, MySQL, SQLite, MariaDB)
+- Compatible with database/sql, GORM, and Bun ORMs
+- Automatic table creation and management
+- Database-native automatic cleanup
+- Token freshness tracking for sensitive operations
+- "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
-
- [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)
+Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/jwt).

 ## 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
Author	SHA1	Message	Date
h	1c66e6dd66	Merge pull request 'hlogdoc' (#3 ) from hlogdoc into master Reviewed-on: #3	2026-01-13 13:53:12 +11:00
h	614be4ed0e	Merge branch 'master' into hlogdoc	2026-01-13 13:52:54 +11:00
Haelnorr	da8e3c2d10	fixed wiki links	2026-01-13 13:49:21 +11:00
Haelnorr	51045537b2	updated version numbers	2026-01-13 13:40:25 +11:00
Haelnorr	bdae21ec0b	Updated documentation for JWT, HWS, and HWSAuth packages. - 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>	2026-01-13 13:37:37 +11:00
h	ddd570230b	Merge pull request 'h-patch-1' (#2 ) from h-patch-1 into master Reviewed-on: #2	2026-01-13 13:33:39 +11:00
h	a255ee578e	Update hlog/README.md	2026-01-13 13:31:47 +11:00
h	1b1fa12a45	Add hlog/LICENSE	2026-01-13 13:31:15 +11:00