gokit

gokit

A modular Go toolkit for building production services. Config, logging, resilience, observability, dependency injection, and infrastructure adapters — so teams can focus on business logic instead of reinventing plumbing.

Status — pre-1.0. Public surface is semver-stable per module; breaking changes are documented in CHANGELOG.md. See docs/policy/SEMVER.md.

Latest release — v0.2.0. The next development line being prepared is v0.3.0-alpha.1, a prerelease for evaluation and integration testing; APIs may change before the stable v0.3.0.

Sibling projects. gokit (Go, this repo) · rskit (Rust) · pykit (Python). Public abstractions (AppError, Component, Provider, Stream, lifecycle hooks) are evaluated for parity across all three.

Browse by Domain

Modules are organized into domains for scoped development. See Module Index for the full breakdown.

CI still runs full-workspace validation; on pull requests the changes job also publishes an affected domain list from ./scripts/affected-domains.sh so later workflow steps can consume the same domain mapping developers use locally with make check-<domain>.

Highlights

• Multi-module layout — light core (github.com/kbukum/gokit) + sub-modules (gokit/server, gokit/database, …) you opt into individually. No transitive heavy deps unless you ask.
• Lifecycle-managed components — uniform Component interface (start / stop / health) and bootstrap.App orchestrator with graceful shutdown.
• Production resilience — circuit breakers, retries with backoff + jitter, bulkheads, rate limiting, OpenTelemetry tracing & metrics.
• Provider pattern — typed RequestResponse[I,O], Stream, Sink, and Duplex traits with composable middleware and sink combinators.
• Per-module versioning — every module has its own matching tag, while normal releases are cut in lock-step for convenience. See docs/VERSIONING.md.
• Sibling parity — APIs mirror rskit (Rust) and pykit (Python).

Install

# Core (lightweight, zero heavy deps)
go get github.com/kbukum/gokit@latest

# Add sub-modules à la carte
go get github.com/kbukum/gokit/server@latest
go get github.com/kbukum/gokit/database@latest

Requires Go 1.26+.

Quickstart

package main

import (
    "context"

    "github.com/kbukum/gokit/bootstrap"
    "github.com/kbukum/gokit/config"
)

type Config struct {
    config.ServiceConfig `mapstructure:",squash"`
}

func main() {
    cfg := &Config{ServiceConfig: config.ServiceConfig{Name: "my-service", Version: "1.0.0"}}

    app, err := bootstrap.NewApp(cfg)
    if err != nil {
        panic(err)
    }

    app.OnConfigure(func(ctx context.Context, app *bootstrap.App[*Config]) error {
        // wire routes, handlers, business logic — components are already started
        return nil
    })

    // Init → Start → Configure → Ready → wait for signal → Stop
    if err := app.Run(context.Background()); err != nil {
        app.Logger.Fatal("app failed", map[string]any{"error": err})
    }
}

More examples → docs/EXAMPLES.md. Full package list → docs/PACKAGES.md.

Documentation

Development

make check    # build + vet + test (all modules)
make test     # tests with -race across all modules
make lint     # golangci-lint
make tidy     # go mod tidy for core + sub-modules

Contributing

We welcome contributions. See CONTRIBUTING.md for setup, coding standards, and the PR process. By participating you agree to the Code of Conduct.

Other community docs: SECURITY.md · GOVERNANCE.md · MAINTAINERS.md

License

MIT — Copyright (c) 2024 kbukum