120 lines
3.5 KiB
Markdown
120 lines
3.5 KiB
Markdown
# hws
|
|
|
|
[](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`.
|
|
|
|
## 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
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
go get git.haelnorr.com/h/golib/hws
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"git.haelnorr.com/h/golib/hws"
|
|
"net/http"
|
|
)
|
|
|
|
func main() {
|
|
// Load configuration from environment variables
|
|
config, _ := hws.ConfigFromEnv()
|
|
|
|
// Create server
|
|
server, _ := hws.NewServer(config)
|
|
|
|
// Define routes
|
|
routes := []hws.Route{
|
|
{
|
|
Path: "/",
|
|
Method: hws.MethodGET,
|
|
Handler: http.HandlerFunc(homeHandler),
|
|
},
|
|
{
|
|
Path: "/api/users/{id}",
|
|
Method: hws.MethodGET,
|
|
Handler: http.HandlerFunc(getUserHandler),
|
|
},
|
|
}
|
|
|
|
// Add routes and middleware
|
|
server.AddRoutes(routes...)
|
|
server.AddMiddleware()
|
|
|
|
// Start server
|
|
ctx := context.Background()
|
|
server.Start(ctx)
|
|
|
|
// Wait for server to be ready
|
|
<-server.Ready()
|
|
}
|
|
|
|
func homeHandler(w http.ResponseWriter, r *http.Request) {
|
|
w.Write([]byte("Hello, World!"))
|
|
}
|
|
|
|
func getUserHandler(w http.ResponseWriter, r *http.Request) {
|
|
id := r.PathValue("id")
|
|
w.Write([]byte("User ID: " + id))
|
|
}
|
|
```
|
|
|
|
## Documentation
|
|
|
|
Comprehensive documentation is available in the [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` |
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## Contributing
|
|
|
|
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
|
|
- [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
|