vital

Vital

Production-ready HTTP server utilities for Go with built-in observability, health checks, and middleware.

Features

• Server Management: Graceful shutdown, TLS support, configurable timeouts
• Health Checks: Liveness and readiness endpoints with custom checkers
• Middleware: Timeout, OpenTelemetry, request logging, recovery, basic auth
• Error Responses: RFC 9457 ProblemDetail for consistent error handling
• Structured Logging: Context-aware logging with trace correlation

Installation

go get github.com/monkescience/vital

Quick Start

package main

import (
	"log/slog"
	"net/http"
	"os"
	"time"

	"github.com/monkescience/vital"
)

func main() {
	// Create logger with context support
	logger := slog.New(vital.NewContextHandler(
		slog.NewJSONHandler(os.Stdout, nil),
		vital.WithBuiltinKeys(),
	))
	slog.SetDefault(logger)

	// Create router
	mux := http.NewServeMux()

	// Add health checks
	mux.Handle("/", vital.NewHealthHandler(
		vital.WithVersion("1.0.0"),
		vital.WithEnvironment("production"),
	))

	// Add your routes
	mux.HandleFunc("GET /api/hello", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("Hello, World!"))
	})

	// Wrap with middleware
	handler := vital.Recovery(logger)(
		vital.RequestLogger(logger)(
			vital.Timeout(30 * time.Second)(mux),
		),
	)

	// Create and run server
	server := vital.NewServer(handler,
		vital.WithPort(8080),
		vital.WithLogger(logger),
	)

	server.Run()
}

Test the server:

curl http://localhost:8080/health/live
curl http://localhost:8080/health/ready
curl http://localhost:8080/api/hello

Server Configuration

Create a server with functional options:

server := vital.NewServer(handler,
	vital.WithPort(8080),
	vital.WithTLS("cert.pem", "key.pem"),
	vital.WithShutdownTimeout(30 * time.Second),
	vital.WithReadTimeout(10 * time.Second),
	vital.WithWriteTimeout(10 * time.Second),
	vital.WithIdleTimeout(120 * time.Second),
	vital.WithLogger(logger),
)

// Start server (blocks until shutdown signal)
server.Run()

// Or manage lifecycle manually
go server.Start()
// ... do other work ...
server.Stop()

Server Options

Health Checks

Basic Health Endpoints

// Simple health handler with version and environment
healthHandler := vital.NewHealthHandler(
	vital.WithVersion("1.0.0"),
	vital.WithEnvironment("production"),
)

mux.Handle("/", healthHandler)

This creates two endpoints:

• GET /health/live - Liveness probe (always returns 200 OK)
• GET /health/ready - Readiness probe (runs health checks)

Custom Health Checkers

Implement the Checker interface for custom health checks:

type DatabaseChecker struct {
	db *sql.DB
}

func (c *DatabaseChecker) Name() string {
	return "database"
}

func (c *DatabaseChecker) Check(ctx context.Context) (vital.Status, string) {
	if err := c.db.PingContext(ctx); err != nil {
		return vital.StatusError, err.Error()
	}
	return vital.StatusOK, "connected"
}

// Add to health handler
healthHandler := vital.NewHealthHandler(
	vital.WithVersion("1.0.0"),
	vital.WithCheckers(&DatabaseChecker{db: db}),
	vital.WithReadyOptions(
		vital.WithOverallReadyTimeout(5 * time.Second),
	),
)

Health Check Response Format

Liveness response:

{
  "status": "ok"
}

Readiness response:

{
  "status": "ok",
  "version": "1.0.0",
  "environment": "production",
  "checks": [
    {
      "name": "database",
      "status": "ok",
      "message": "connected",
      "duration": "2.5ms"
    }
  ]
}

Middleware

Timeout

Enforce request timeout with automatic error response:

handler := vital.Timeout(30 * time.Second)(mux)

If the handler exceeds the timeout, returns:

{
  "status": 503,
  "title": "Service Unavailable",
  "detail": "request timeout exceeded"
}

OpenTelemetry

Add distributed tracing and metrics:

vital.OTel validates metric instrument setup and returns an error if initialization fails.

import (
	"go.opentelemetry.io/otel/sdk/trace"
	"go.opentelemetry.io/otel/sdk/metric"
)

// Setup providers
tp := trace.NewTracerProvider(...)
mp := metric.NewMeterProvider(...)

// Apply middleware
otelMiddleware, err := vital.OTel(
	vital.WithTracerProvider(tp),
	vital.WithMeterProvider(mp),
)
if err != nil {
	panic(err)
}

handler := otelMiddleware(mux)

Features:

• Creates spans for each HTTP request
• Propagates W3C traceparent headers
• Records http.server.request.duration histogram
• Adds trace_id and span_id to request context

Request Logger

Log all HTTP requests with structured logging:

handler := vital.RequestLogger(logger)(mux)

Logs include:

• HTTP method and path
• Status code
• Request duration
• Remote address and user agent
• Trace context (if OTel middleware is used)

Example log output:

{
  "time": "2025-01-26T10:30:00Z",
  "level": "INFO",
  "msg": "http request",
  "method": "GET",
  "path": "/api/users",
  "status": 200,
  "duration": "15ms",
  "remote_addr": "192.168.1.1:54321",
  "user_agent": "curl/7.68.0",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7"
}

Recovery

Recover from panics and return 500 error:

handler := vital.Recovery(logger)(mux)

Catches panics, logs the error, and returns:

{
  "status": 500,
  "title": "Internal Server Error",
  "detail": "internal server error"
}

Basic Auth

Protect endpoints with HTTP Basic Authentication:

handler := vital.BasicAuth("admin", "secret", "Admin Area")(mux)

Uses constant-time comparison to prevent timing attacks.

Middleware Chaining

Chain multiple middleware together (applied right-to-left):

otelMiddleware, err := vital.OTel(
	vital.WithTracerProvider(tp),
	vital.WithMeterProvider(mp),
)
if err != nil {
	panic(err)
}

handler := vital.Recovery(logger)(
	vital.RequestLogger(logger)(
		otelMiddleware(vital.Timeout(30 * time.Second)(mux)),
	),
)

Recommended order (innermost to outermost):

1. Timeout - enforce request deadlines
2. OTel - trace and metrics
3. RequestLogger - log requests
4. Recovery - catch panics

Error Responses

Use RFC 9457 ProblemDetail for consistent error responses:

Standard Errors

// 400 Bad Request
vital.RespondProblem(r.Context(), w, vital.BadRequest("invalid input"))

// 401 Unauthorized
vital.RespondProblem(r.Context(), w, vital.Unauthorized("authentication required"))

// 403 Forbidden
vital.RespondProblem(r.Context(), w, vital.Forbidden("insufficient permissions"))

// 404 Not Found
vital.RespondProblem(r.Context(), w, vital.NotFound("user not found"))

// 409 Conflict
vital.RespondProblem(r.Context(), w, vital.Conflict("email already exists"))

// 422 Unprocessable Entity
vital.RespondProblem(r.Context(), w, vital.UnprocessableEntity("validation failed"))

// 500 Internal Server Error
vital.RespondProblem(r.Context(), w, vital.InternalServerError("database error"))

// 503 Service Unavailable
vital.RespondProblem(r.Context(), w, vital.ServiceUnavailable("service temporarily unavailable"))

Custom ProblemDetail

problem := vital.NewProblemDetail(
	http.StatusTeapot,
	"I'm a teapot",
	vital.WithType("https://example.com/errors/teapot"),
	vital.WithDetail("Cannot brew coffee, I'm a teapot"),
	vital.WithInstance("/api/coffee/123"),
	vital.WithExtension("retry_after", 300),
)

vital.RespondProblem(r.Context(), w, problem)

Response:

{
  "type": "https://example.com/errors/teapot",
  "title": "I'm a teapot",
  "status": 418,
  "detail": "Cannot brew coffee, I'm a teapot",
  "instance": "/api/coffee/123",
  "retry_after": 300
}

Structured Logging

Context-Aware Logger

Create a logger that automatically extracts trace context:

logger := slog.New(vital.NewContextHandler(
	slog.NewJSONHandler(os.Stdout, nil),
	vital.WithBuiltinKeys(), // Adds trace_id, span_id, trace_flags
))

slog.SetDefault(logger)

Custom Context Keys

Add your own context keys:

var UserIDKey = vital.ContextKey{Name: "user_id"}

logger := slog.New(vital.NewContextHandler(
	slog.NewJSONHandler(os.Stdout, nil),
	vital.WithBuiltinKeys(),
	vital.WithContextKeys(UserIDKey),
))

// In your handler
ctx := context.WithValue(r.Context(), UserIDKey, "user-123")
slog.InfoContext(ctx, "processing request") // Includes user_id in log

Logger Configuration

Create logger from configuration:

config := vital.LogConfig{
	Level:     "info",
	Format:    "json",
	AddSource: true,
}

handler, err := vital.NewHandlerFromConfig(config,
	vital.WithBuiltinKeys(),
)
if err != nil {
	log.Fatal(err)
}

logger := slog.New(handler)

Complete Example

package main

import (
	"context"
	"database/sql"
	"encoding/json"
	"log/slog"
	"net/http"
	"os"
	"time"

	"github.com/monkescience/vital"
	_ "github.com/lib/pq"
)

type DatabaseChecker struct {
	db *sql.DB
}

func (c *DatabaseChecker) Name() string {
	return "database"
}

func (c *DatabaseChecker) Check(ctx context.Context) (vital.Status, string) {
	if err := c.db.PingContext(ctx); err != nil {
		return vital.StatusError, err.Error()
	}
	return vital.StatusOK, "connected"
}

type CreateUserRequest struct {
	Name  string `json:"name"`
	Email string `json:"email"`
}

func main() {
	// Setup logger
	logger := slog.New(vital.NewContextHandler(
		slog.NewJSONHandler(os.Stdout, nil),
		vital.WithBuiltinKeys(),
	))
	slog.SetDefault(logger)

	// Setup database
	db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
	if err != nil {
		logger.Error("failed to connect to database", slog.Any("error", err))
		os.Exit(1)
	}
	defer db.Close()

	// Create router
	mux := http.NewServeMux()

	// Health checks
	mux.Handle("/", vital.NewHealthHandler(
		vital.WithVersion("1.0.0"),
		vital.WithEnvironment("production"),
		vital.WithCheckers(&DatabaseChecker{db: db}),
	))

	// API routes
	mux.HandleFunc("POST /api/users", func(w http.ResponseWriter, r *http.Request) {
		var req CreateUserRequest
		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
			vital.RespondProblem(r.Context(), w, vital.BadRequest(err.Error()))
			return
		}

		// Create user in database
		_, err = db.ExecContext(r.Context(),
			"INSERT INTO users (name, email) VALUES ($1, $2)",
			req.Name, req.Email,
		)
		if err != nil {
			logger.ErrorContext(r.Context(), "failed to create user", slog.Any("error", err))
			vital.RespondProblem(r.Context(), w, vital.InternalServerError("failed to create user"))
			return
		}

		w.WriteHeader(http.StatusCreated)
	})

	// Apply middleware
	handler := vital.Recovery(logger)(
		vital.RequestLogger(logger)(
			vital.Timeout(30 * time.Second)(mux),
		),
	)

	// Create and run server
	server := vital.NewServer(handler,
		vital.WithPort(8080),
		vital.WithLogger(logger),
	)

	logger.Info("starting server", slog.Int("port", 8080))
	server.Run()
}

Configuration Reference

Server Options

Health Check Options

Readiness Options

OTel Options

Logger Options

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run go test ./... and go vet ./...
5. Submit a pull request

License

MIT License - see LICENSE for details.