svckit

svckit

A Go microservice toolkit built on standard-library contracts.

svckit is the set of building blocks a service needs before it does anything useful: configuration, logging, resilient connections to Postgres, Redis and RabbitMQ, a signed event bus, HTTP middleware, health checks, secrets and graceful shutdown. It grew out of a 17-service platform and was extracted once the pieces had stopped changing shape.

Design

Standard-library contracts, frameworks as adapters. Everything here is written against net/http, database/sql, log/slog and context.Context — never against a web framework or an ORM. Middleware is func(http.Handler) http.Handler. The database layer hands back *sql.DB. Logging ships slog.Handler implementations rather than a logger type.

The practical consequence: the core module depends on no web framework and no ORM. Chi and the Go 1.22+ http.ServeMux consume the middleware natively — chi.Use takes exactly func(http.Handler) http.Handler. Gin needs translation, so it gets its own module. GORM or Ent bind to the *sql.DB in about ten lines.

Adapters are separate modules, so importing svckit never pulls in a framework you did not choose, and a project pinned to a different framework version is unaffected by what an adapter requires.

Where the abstraction stops. Some things are not worth hiding: go-redis, Prometheus and RabbitMQ appear as themselves. Small interfaces at the edges (Publisher, Subscriber, Store, IdentityProvider) keep alternatives possible without pre-building them.

Install

go get github.com/dobrevit/svckit

Optional modules — take only what you use:

go get github.com/dobrevit/svckit/testkit  # test harness (Docker, testcontainers)
go get github.com/dobrevit/svckit/chix     # chi router adapter
go get github.com/dobrevit/svckit/ginx     # Gin framework adapter

Using it from chi

Nothing to adapt — chi consumes the middleware directly:

r := chi.NewRouter()
r.Use(chix.Route())                        // label metrics by route template
r.Use(middleware.Tracing())
r.Use(middleware.Metrics("orders"))
r.Use(middleware.RequestLogging("orders"))

chix.Route() is the only piece that needs a shim: chi knows the matched pattern only after routing, and without it every path parameter becomes its own Prometheus label value.

Using it from Gin

Gin has its own handler type, context and response writer, so each middleware needs translating — that is what ginx is:

router := gin.New()
router.Use(ginx.Route())
router.Use(ginx.TracingMiddleware())
router.Use(ginx.PrometheusMiddleware("orders"))
router.Use(ginx.LoggingMiddleware())

ginx.Use adapts any func(http.Handler) http.Handler into a gin.HandlerFunc, covering anything it does not wrap explicitly.

Packages

Quick start

package main

import (
	"log"
	"net/http"

	"github.com/dobrevit/svckit/app"
)

func main() {
	a, err := app.New("orders",
		app.WithDatabase(),
		app.WithOptionalEventPublisher(),
	)
	if err != nil {
		log.Fatalf("bootstrap failed: %v", err)
	}
	defer a.Close()

	mux := http.NewServeMux()
	mux.HandleFunc("GET /orders/{id}", handleGetOrder)

	// Handler adds tracing, metrics and request logging, and serves
	// /health, /ready, /metrics and the profiling endpoints in front of
	// your routes.
	a.Run(a.Handler(mux))
}

Migrations stay yours: app.WithMigration(func(db *sql.DB) error { ... }) takes goose, Atlas or anything else that accepts a *sql.DB.

Testing

The unit tier needs nothing running:

go test -race -short ./...

The integration tier needs Postgres, Redis and RabbitMQ, and is gated behind a build tag so a plain go test ./... never reaches it:

docker compose up -d
go test -race -tags integration ./...

compose.yaml in this repository starts the three services on the ports the tests expect. Override any of them with REDIS_TEST_URL, POSTGRES_TEST_URL or RABBITMQ_TEST_URL.

Status

v0.x — the API may still move. The packages are in production use, but the names and shapes are not yet frozen; that happens at v1.0.0. Changes are recorded in CHANGELOG.md.

Contributing

See CONTRIBUTING.md for the workflow and the design stance that shapes review feedback. Contributions require a signed CLA; the bot prompts you on your first pull request.

Security

Please report vulnerabilities privately rather than through an issue — SECURITY.md has the process and what to expect.

License

Apache License 2.0 — see LICENSE.