# hws

[![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`.

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