gokit

gokit

A modular Go toolkit for building production services.

gokit provides a shared foundation across Go services — config, logging, resilience, observability, dependency injection, and infrastructure adapters — so teams can focus on business logic instead of reinventing plumbing.

Architecture

gokit uses a multi-module layout:

• Core module (github.com/kbukum/gokit) — lightweight, zero heavy dependencies. Covers config, logging, errors, DI, resilience, and abstractions.
• Sub-modules (github.com/kbukum/gokit/{name}) — each has its own go.mod and brings in heavier dependencies (Gin, GORM, Kafka, gRPC, etc.) only when you need them.

Import the core for foundational utilities. Add sub-modules à la carte for infrastructure.

Compatibility Matrix

Module Map

Core Packages

Sub-Modules

Quick Start

Install the core

go get github.com/kbukum/gokit@latest

Add a sub-module

go get github.com/kbukum/gokit/server@latest
go get github.com/kbukum/gokit/database@latest

Usage Examples

Config + Logger

package main

import (
    "github.com/kbukum/gokit/config"
    "github.com/kbukum/gokit/logger"
)

type ServiceConfig struct {
    config.ServiceConfig `yaml:",inline" mapstructure:",squash"`
    Port int `yaml:"port"`
}

func main() {
    cfg := &ServiceConfig{}
    if err := config.LoadConfig("my-service", cfg,
        config.WithConfigFile("./config.yml"),
        config.WithEnvFile(".env"),
    ); err != nil {
        panic(err)
    }
    cfg.ApplyDefaults()

    log := logger.New(&logger.Config{
        Level:  "info",
        Format: "console",
    }, cfg.Name)

    log.Info("service configured", map[string]interface{}{
        "env": cfg.Environment,
    })
}

HTTP Server with Middleware

import "github.com/kbukum/gokit/server"

srvCfg := &server.Config{Host: "0.0.0.0", Port: 8080}
srvCfg.ApplyDefaults()

srv := server.New(srvCfg, log)
srv.ApplyDefaults("my-service", healthChecker)

srv.GinEngine().GET("/api/items", itemsHandler)

srv.Start(ctx)
defer srv.Stop(ctx)

Provider Pattern

import "github.com/kbukum/gokit/provider"

// Define a domain provider using the interaction pattern
type DiarizationProvider = provider.RequestResponse[AudioInput, []Segment]

// Use the manager for runtime selection
reg := provider.NewRegistry[DiarizationProvider]()
mgr := provider.NewManager(reg, &provider.HealthCheckSelector[DiarizationProvider]{})
p, _ := mgr.Get(ctx)
result, err := p.Execute(ctx, audioInput)

Subprocess Execution

import "github.com/kbukum/gokit/process"

result, err := process.Run(ctx, process.Command{
    Binary: "python", Args: []string{"diarize.py", "audio.wav"},
})
fmt.Println(string(result.Stdout))

Bootstrap Lifecycle

import "github.com/kbukum/gokit/bootstrap"

app := bootstrap.NewApp("my-service", "1.0.0",
    bootstrap.WithLogger(log),
    bootstrap.WithGracefulTimeout(15 * time.Second),
)

app.RegisterComponent(db)    // component.Component
app.RegisterComponent(cache) // component.Component

app.OnConfigure(func(ctx context.Context, app *bootstrap.App) error {
    // All components started — set up routes, handlers, business logic
    return nil
})

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

Module Details

Each module has its own documentation. Refer to the package-level Go docs or source:

Multi-Module Versioning

Core and sub-modules version independently. Each sub-module has its own go.mod and release tags:

v0.5.0              ← core module
server/v0.3.2       ← server sub-module
database/v0.4.1     ← database sub-module

This means:

• Upgrading gokit/server does not force an upgrade of gokit/database.
• Core can ship breaking changes without touching sub-modules (and vice versa).
• Each module follows semver on its own timeline.

Development

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

Contributing

See CONTRIBUTING.md for development workflow, coding standards, and how to submit pull requests.

We follow the Contributor Covenant Code of Conduct.

License

MIT — Copyright (c) 2024 kbukum