diff --git a/hws/README.md b/hws/README.md index 998d80e..22baebd 100644 --- a/hws/README.md +++ b/hws/README.md @@ -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 -- ๐Ÿš€ 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). -### 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 diff --git a/hws/doc.go b/hws/doc.go new file mode 100644 index 0000000..3ff6ad6 --- /dev/null +++ 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 diff --git a/hwsauth/README.md b/hwsauth/README.md index 4ba058e..70cbf0e 100644 --- a/hwsauth/README.md +++ b/hwsauth/README.md @@ -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](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). -### 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 diff --git a/hwsauth/doc.go b/hwsauth/doc.go index f0b1be7..bd6440b 100644 --- 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 // diff --git a/jwt/README.md b/jwt/README.md index 184140f..b6074e2 100644 --- 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.0-hlogdoc 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). -### 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