golib/hws

HWS (H Web Server)

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

go get git.haelnorr.com/h/golib/hws

Quick Start

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.

Key Topics

• Configuration
• Routing
• Middleware
• Error Handling
• Logging
• Static Files
• Graceful Shutdown
• Complete Examples

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 file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related Projects

• HWSAuth - JWT authentication middleware for HWS
• hlog - Structured logging with zerolog
• jwt - JWT token generation and validation