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>
This commit is contained in:
@@ -1,21 +1,19 @@
|
||||
# HWS (H Web Server)
|
||||
# HWS (H Web Server) - v0.2.1-hlogdoc
|
||||
|
||||
[](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
|
||||
|
||||
144
hws/doc.go
Normal file
144
hws/doc.go
Normal 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
|
||||
Reference in New Issue
Block a user