h/golib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated documentation for JWT, HWS, and HWSAuth packages.

Browse Source 
- 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>
This commit is contained in:
Haelnorr
2026-01-13 13:37:37 +11:00
parent 52341aba56
commit bdae21ec0b
5 changed files with 217 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
hws/README.md
View File

@@ -1,21 +1,19 @@
# HWS (H Web Server) # HWS (H Web Server) - v0.2.1-hlogdoc
[![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 ## 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 ## Installation
@@ -30,8 +28,8 @@ package main
import ( import (
"context" "context"
"git.haelnorr.com/h/golib/hws"
"net/http" "net/http"
"git.haelnorr.com/h/golib/hws"
) )
func main() { func main() {
@@ -79,34 +77,13 @@ func getUserHandler(w http.ResponseWriter, r *http.Request) {
## Documentation ## 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).
### 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 ## 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 ## Contributing
@@ -114,6 +91,6 @@ Contributions are welcome! Please feel free to submit a Pull Request.
## Related Projects ## 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 - [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 - [jwt](https://git.haelnorr.com/h/golib/jwt) - JWT token generation and validation

144
hws/doc.go Normal file
View File

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

54
hwsauth/README.md
View File

@@ -1,19 +1,19 @@
# HWSAuth # HWSAuth - v0.3.1-hlogdoc
[![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 ## 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 ## Installation
@@ -29,9 +29,9 @@ package main
import ( import (
"context" "context"
"database/sql" "database/sql"
"net/http"
"git.haelnorr.com/h/golib/hwsauth" "git.haelnorr.com/h/golib/hwsauth"
"git.haelnorr.com/h/golib/hws" "git.haelnorr.com/h/golib/hws"
"github.com/rs/zerolog"
) )
type User struct { type User struct {
@@ -69,6 +69,15 @@ func main() {
serverCfg, _ := hws.ConfigFromEnv() serverCfg, _ := hws.ConfigFromEnv()
server, _ := hws.NewServer(serverCfg) 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 // Create authenticator
auth, _ := hwsauth.NewAuthenticator[User, *sql.Tx]( auth, _ := hwsauth.NewAuthenticator[User, *sql.Tx](
cfg, cfg,
@@ -93,7 +102,7 @@ func main() {
// Add authentication middleware // Add authentication middleware
server.AddMiddleware(auth.Authenticate()) server.AddMiddleware(auth.Authenticate())
// Optionally ignore public paths // Ignore public paths
auth.IgnorePaths("/", "/login", "/register", "/static") auth.IgnorePaths("/", "/login", "/register", "/static")
// Start server // Start server
@@ -106,18 +115,9 @@ func main() {
## Documentation ## 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).
### 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 ## Supported ORMs
@@ -128,7 +128,7 @@ Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/
## License ## 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 ## 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 - [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 - [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

16
hwsauth/doc.go
View File

@@ -179,18 +179,18 @@
// //
// # Environment Variables // # 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_ACCESS_TOKEN_EXPIRY: Access token expiry in minutes (default: 5)
// - HWSAUTH_REFRESH_TOKEN_EXPIRY: Refresh token expiry in minutes (default: 1440) // - HWSAUTH_REFRESH_TOKEN_EXPIRY: Refresh token expiry in minutes (default: 1440)
// - HWSAUTH_TOKEN_FRESH_TIME: Token fresh time in minutes (default: 5) // - 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 // # Security Considerations
// //

45
jwt/README.md
View File

@@ -1,20 +1,19 @@
# JWT Package # JWT - v0.10.0-hlogdoc
[![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. JWT (JSON Web Token) generation and validation with database-backed token revocation support.
## Features ## 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 ## Installation
@@ -41,7 +40,7 @@ func main() {
// Create a transaction getter function // Create a transaction getter function
txGetter := func(ctx context.Context) (jwt.DBTransaction, error) { txGetter := func(ctx context.Context) (jwt.DBTransaction, error) {
return db.Begin() return db.BeginTx(ctx, nil)
} }
// Create token generator // Create token generator
@@ -78,16 +77,9 @@ func main() {
## Documentation ## 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).
### 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 ## Supported Databases
@@ -98,8 +90,13 @@ Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/
## License ## License
See LICENSE file in the repository root. This project is licensed under the MIT License - see the LICENSE file for details.
## Contributing ## 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