Initial commit

Author: fegger-ducksify

.github/workflows/test.yml

@@ -0,0 +1,27 @@
+name: Test
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Go
+      uses: actions/setup-go@v5
+      with:
+        go-version-file: 'go.mod'
+    
+    - name: Run tests
+      run: go test ./... -v -coverprofile=coverage.out
+    
+    - name: Generate coverage report
+      if: always()
+      run: go tool cover -func=coverage.out
+

README.md

@@ -0,0 +1,166 @@
+# httpserver
+
+A simple and opinionated HTTP server package for Go that provides easy server creation, graceful shutdown, and JSON response helpers.
+
+## Features
+
+- **Simple Server Creation**: Create HTTP servers with route patterns and handlers
+- **TLS Support**: Built-in TLS/HTTPS support
+- **Graceful Shutdown**: Handles context cancellation and OS signals (SIGINT, SIGTERM)
+- **JSON Helpers**: Convenient function for writing JSON responses
+- **Error Handling**: Proper error handling and logging
+
+## Installation
+
+```bash
+go get github.com/ducksify/httpserver
+```
+
+## Usage
+
+### Basic Example
+
+```go
+package main
+
+import (
+    "context"
+    "net/http"
+    "github.com/ducksify/httpserver"
+)
+
+func main() {
+    // Define handlers
+    helloHandler := func(w http.ResponseWriter, r *http.Request) {
+        httpserver.WriteJSON(w, http.StatusOK, map[string]string{
+            "message": "Hello, World!",
+        })
+    }
+
+    healthHandler := func(w http.ResponseWriter, r *http.Request) {
+        httpserver.WriteJSON(w, http.StatusOK, map[string]string{
+            "status": "ok",
+        })
+    }
+
+    // Create server with routes
+    patterns := []string{"/hello", "/health"}
+    handlers := []http.HandlerFunc{helloHandler, healthHandler}
+    
+    server, err := httpserver.NewServer(":8080", patterns, handlers...)
+    if err != nil {
+        panic(err)
+    }
+
+    // Run server with graceful shutdown
+    ctx := context.Background()
+    if err := httpserver.RunServer(ctx, server, "config/tls/tls.crt", "config/tls/tls.key"); err != nil {
+        panic(err)
+    }
+}
+```
+
+### API Reference
+
+#### `NewServer(port string, patterns []string, handlers ...http.HandlerFunc) (*http.Server, error)`
+
+Creates a new HTTP server with the specified routes and handlers.
+
+**Parameters:**
+- `port`: The address to listen on (e.g., `:8080`)
+- `patterns`: Slice of URL patterns (routes)
+- `handlers`: Variadic slice of handler functions corresponding to each pattern
+
+**Returns:**
+- `*http.Server`: The configured HTTP server
+- `error`: Error if patterns and handlers lengths don't match
+
+**Example:**
+```go
+patterns := []string{"/api/users", "/api/posts"}
+handlers := []http.HandlerFunc{usersHandler, postsHandler}
+server, err := httpserver.NewServer(":8080", patterns, handlers...)
+```
+
+#### `RunServer(ctx context.Context, server *http.Server, certFile, keyFile string) error`
+
+Runs the server with TLS support and handles graceful shutdown. The server will:
+- Start listening with TLS using the provided certificate and key files
+- Handle context cancellation
+- Listen for OS signals (SIGINT, SIGTERM) for graceful shutdown
+- Return errors from server startup failures
+
+**Parameters:**
+- `ctx`: Context for cancellation
+- `server`: The HTTP server instance to run
+- `certFile`: Path to the TLS certificate file
+- `keyFile`: Path to the TLS private key file
+
+**Returns:**
+- `error`: Error from server startup or shutdown
+
+**Example:**
+```go
+ctx, cancel := context.WithCancel(context.Background())
+defer cancel()
+
+if err := httpserver.RunServer(ctx, server, "config/tls/tls.crt", "config/tls/tls.key"); err != nil {
+    log.Fatal(err)
+}
+```
+
+#### `WriteJSON(w http.ResponseWriter, status int, payload interface{})`
+
+Writes a JSON response to the HTTP response writer.
+
+**Parameters:**
+- `w`: The HTTP response writer
+- `status`: HTTP status code (e.g., `http.StatusOK`)
+- `payload`: The data to encode as JSON (any JSON-serializable type)
+
+**Example:**
+```go
+httpserver.WriteJSON(w, http.StatusOK, map[string]interface{}{
+    "id": 1,
+    "name": "John Doe",
+    "email": "john@example.com",
+})
+```
+
+## TLS Configuration
+
+The `RunServer` function requires TLS certificate and key file paths as parameters. Make sure these files exist before running your server.
+
+Common locations:
+- Certificate: `config/tls/tls.crt`
+- Private Key: `config/tls/tls.key`
+
+## Graceful Shutdown
+
+The server supports graceful shutdown through:
+1. **Context Cancellation**: Cancel the context passed to `RunServer`
+2. **OS Signals**: Send SIGINT or SIGTERM to the process
+
+The shutdown process allows up to 10 seconds for in-flight requests to complete.
+
+## Testing
+
+Run tests with:
+
+```bash
+go test ./...
+```
+
+Run tests with coverage:
+
+```bash
+go test ./... -coverprofile=coverage.out
+go tool cover -html=coverage.out
+```
+
+Current test coverage: **78.8%**
+
+## License
+
+[Add your license here]
+

go.mod

@@ -0,0 +1,3 @@
+module github.com/ducksify/httpserver
+
+go 1.25.5

httpserver.go

@@ -0,0 +1,77 @@
+package httpserver
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+)
+
+func NewServer(port string, patterns []string, handlers ...http.HandlerFunc) (*http.Server, error) {
+	if len(patterns) != len(handlers) {
+		return nil, errors.New("patterns and handlers must have the same length")
+	}
+	mux := http.NewServeMux()
+	for i, pattern := range patterns {
+		mux.HandleFunc(pattern, handlers[i])
+	}
+
+	return &http.Server{
+		Addr:    port,
+		Handler: mux,
+	}, nil
+}
+
+func RunServer(ctx context.Context, server *http.Server, certFile, keyFile string) error {
+	serverError := make(chan error, 1)
+	go func() {
+		if err := server.ListenAndServeTLS(certFile, keyFile); err != nil && err != http.ErrServerClosed {
+			serverError <- err
+		}
+		close(serverError)
+	}()
+
+	stop := make(chan os.Signal, 1)
+	signal.Notify(stop, os.Interrupt, syscall.SIGTERM)
+	defer signal.Stop(stop)
+
+	select {
+	case <-ctx.Done():
+		if err := shutdownServer(context.Background(), server); err != nil {
+			return err
+		}
+	case err := <-serverError:
+		if err != nil {
+			slog.Error("Server error", "error", err)
+			return err
+		}
+	case <-stop:
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		if err := shutdownServer(shutdownCtx, server); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func shutdownServer(ctx context.Context, server *http.Server) error {
+	if err := server.Shutdown(ctx); err != nil {
+		slog.Error("Failed to shutdown server", "error", err)
+		return err
+	}
+	return nil
+}
+
+func WriteJSON(w http.ResponseWriter, status int, payload interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	if err := json.NewEncoder(w).Encode(payload); err != nil {
+		slog.Error("Failed to encode JSON response", "error", err)
+	}
+}