servekit

servekit

A collection of reusable Go components for building HTTP and gRPC APIs. Designed to reduce boilerplate and provide consistent patterns across services.

Warning: Pre-v1.0.0 - expect breaking changes.

Install

go get github.com/marsolab/servekit

Requires Go 1.25+.

Quick Start

package main

import (
    "github.com/marsolab/servekit"
    "github.com/marsolab/servekit/httpkit"
    "github.com/marsolab/servekit/logkit"
)

func main() {
    logger := logkit.New(logkit.WithJSON())

    // Create a server that manages multiple listeners.
    srv := servekit.NewServer(logger)

    // Create an HTTP listener with built-in health checks and metrics.
    http := httpkit.NewListenerHTTP(":8080",
        httpkit.WithLogger(logger),
        httpkit.WithHealthCheck(),
        httpkit.WithMetrics(),
    )

    srv.RegisterListener("http", http)

    // Serve blocks until all listeners stop or the context is canceled.
    if err := srv.Serve(context.Background()); err != nil {
        logger.Error("server failed", slog.String("error", err.Error()))
        os.Exit(1)
    }
}

Architecture

The foundation is a Listener-based architecture:

• Server orchestrates multiple listeners, runs them concurrently via errgroup, and handles graceful shutdown.
• Listener is any component implementing Serve(ctx context.Context) error.
• Built-in listeners: httpkit.ListenerHTTP and grpckit.ListenerGRPC.
• Graceful shutdown propagates through context cancellation with configurable timeouts.

Configuration throughout the codebase uses the functional options pattern:

listener := httpkit.NewListenerHTTP(":8080",
    httpkit.WithLogger(logger),
    httpkit.WithHealthCheck(),
    httpkit.WithMetrics(),
    httpkit.WithCORS(corsOpts),
)

Packages

Core

Database

All database packages implement the hc.HealthChecker interface for health checks.

Authentication

Error Handling

Utilities

HTTP Middleware

httpkit provides composable middleware following chi's func(http.Handler) http.Handler pattern:

• LoggingMiddleware - structured request/response logging
• MetricsMiddleware - Prometheus metrics collection via VictoriaMetrics
• RecoveryMiddleware - panic recovery with error reporting
• CORSMiddleware - CORS configuration via go-chi/cors

Response Helpers

Standardized response functions for both HTTP and gRPC:

// HTTP responses.
httpkit.JSON(w, http.StatusOK, data)
httpkit.HTML(w, http.StatusOK, template, data)
httpkit.TEXT(w, http.StatusOK, "ok")
httpkit.ErrorHTTP(w, r, err) // maps errkit errors to HTTP status codes automatically

// gRPC responses.
grpckit.Error(err) // maps errkit errors to gRPC status codes

Health Checks

Components implement the hc.HealthChecker interface. The HTTP listener can expose a health endpoint aggregating checks from all registered services:

listener := httpkit.NewListenerHTTP(":8080",
    httpkit.WithHealthCheck(pgConn, redisConn, mongoConn),
)
// GET /health returns aggregated health status.

Testing

go test ./...

The project uses go-testdeep for assertions and table-driven tests throughout.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT