gokit

README

gokit

Композируемый Go service kit. Около тридцати независимо импортируемых пакетов, покрывающих то, что каждый HTTP API сервис делает руками: роутинг, ошибки, БД, аутентификация, исходящие HTTP, NATS-стриминг, observability, resilience, audit, schedulers, file uploads, webhook'и.

Каждый пакет можно использовать отдельно. Вместе они уводят вас от main.go к сервису production-shape — либо постепенно (fibermap сам по себе), либо одним вызовом через service.New.

Статус: v1.0.0 — stable. Semver-обещания (что считается breaking / MINOR / PATCH, политика по min Go version, coexistence с будущими major'ами) — в docs/versioning.md. Pre-v1 audit-close список — в docs/v1-readiness.md.

Что в коробке

Базовые блоки

Пакет	Что делает
fibermap/	YAML-декларативный роутер для Fiber v2. Хендлеры и middleware по именам. Типизированный per-request контекст. OpenAPI генерация.
errs/	Типизированные доменные ошибки (Kind, Code, Details, Cause) с маппингом в HTTP. Только stdlib.
errs/errsval/	Конверсия validator.ValidationErrors → *errs.Error{KindValidation}.
reqctx/	Request-ID propagation primitive.

База данных

Пакет	Что делает
db/	pgx pool wrapper. Транзакции с savepoint'ами. Healthcheck. Маппинг ошибок в *errs.Error.
db/sqb/	Опциональная squirrel-обёртка, преднастроенная на $N placeholders.
db/migrate/	Zero-dependency migration runner на embed.FS.
db/lock/	pg_advisory_lock примитив для leader-election и mutual exclusion.
db/jobs/	Postgres-backed delayed job queue (gap между cron'ом и outbox'ом).
db/outbox/	Transactional outbox pattern (publish-side).
db/outbox/outboxnats/	Adapter — outbox.PublishFn → natsmap.
db/inbox/	Inbox table для effectively-once consumer'ов.
db/inbox/inboxnats/	Adapter — natsmap handler wrapper с дедупликацией.

Аутентификация

Пакет	Что делает
auth/	JWT issue/verify (EdDSA/ES256), Argon2id hashing, refresh-token rotation, Fiber middleware.
auth/refreshpg/	Postgres-backed RefreshStore.
auth/refreshredis/	Redis-backed RefreshStore (Lua-atomic).
auth/apikeypg/	Postgres-backed API-key store.
auth/sessions/	Server-side cookie sessions с revocation.
auth/fibermount/	Bridge между auth и fibermap middleware factories.

Исходящий HTTP

Пакет	Что делает
clients/httpc/	*http.Client с retry / per-attempt timeout / breaker / bulkhead / observability.
clients/apimap/	YAML-декларативные upstream API'и. Вызов по имени через Decode[T]/Exchange[Req,Resp].

NATS / JetStream

Пакет	Что делает
clients/nats/	Типизированная обёртка над JetStream. Publisher[T] / Subscribe[T].
clients/natsmap/	Декларативные подписчики/публишеры через YAML.
clients/natsmap/natsgw/	HTTP-gateway для NATS publish (для сервисов в network zone без NATS reachability).

Redis-инфраструктура

Пакет	Что делает
clients/redis/	*redis.Client bootstrap с initial-PING retry.
clients/cache/	Типизированный Redis read-through cache с positive/negative TTL.
clients/ratelimit/	Sliding-window rate limiter на Lua-скрипте.

Прочие clients

Пакет	Что делает
clients/s3/	aws-sdk-go-v2/service/s3 wrapper. AWS / MinIO / R2 / Spaces / B2.
clients/email/	Pluggable transactional email (SMTP / SES / Postmark).
clients/webhooks/	Outbound + inbound webhook'и (Subscription/Delivery/Fanout/Worker, HMAC signing).

Resilience

Пакет	Что делает
breaker/	3-state circuit breaker (closed/open/half_open).
bulkhead/	Concurrency cap с bounded queue + опциональный adaptive controller (AIMD).
batch/	Batched-handler dispatcher для bulk sink-операций.

Криптография

Пакет	Что делает
crypto/	AES-256-GCM at-rest sealing. MasterKey для single-key случая; Keychain (kid-routed) для rotation. Version-tagged blob format с cross-type isolation.

Идентификаторы

Пакет	Что делает
ids/	Prefixed ULIDs (user_01H…). New/Parse/Format + validate:"id_prefix=prod_" struct tag. 16-byte raw — совместимо с pgx uuid column через kit's auto-codec.

Observability

Пакет	Что делает
otelkit/	OpenTelemetry bootstrap (tracing + metrics + logs bridges).
sentrykit/	Sentry error-tracking + Fiber middleware + slog→breadcrumb bridge.

Scheduling

Пакет	Что делает
cronmap/	Declarative cron scheduler с YAML + handler-by-name. Per-run timeout, singleton (pg-advisory-lock), Sentry crons slug — всё YAML-аттрибутами. См. также db/jobs/ (Postgres-backed delayed/one-shot queue).

Operations

Пакет	Что делает
audit/	Append-only audit-log infrastructure (SOC2 / HIPAA / PCI-DSS). С v1.1.0: audit/auditfm/ — declarative per-handler decorator поверх fibermap.
runbook/	Runtime kill-switch для ops без redeploy.
fibermap/uploadguard/	File-upload validation middleware (pairs с clients/s3).

Bundle

Пакет	Что делает
service/	service.New(ctx, cfg, opts...) всё-в-одном wiring. Auto-detect optionality + startup log + Status() introspection.

Decision guide — "мне нужно X"

Полная таблица «задача → пакет» — в docs/decision-guide.md. Самое частое:

Задача	Бери
Описать routes снаружи кода	fibermap + routes.yaml
Postgres pool + транзакции	db
JWT-based authn	auth + auth/refreshpg/refreshredis
HTTP-клиент с retry + observability	clients/httpc
Описать upstream API'и в YAML	clients/apimap
Publish событий в NATS JetStream	clients/nats или clients/natsmap
Гарантированный publish после db.Commit	db/outbox + db/outbox/outboxnats
Periodic cron jobs (declarative YAML)	cronmap
Всё сразу одним вызовом	service

Правила зависимостей

errs                                        → только stdlib
reqctx                                      → только stdlib
db, db/sqb, db/migrate, db/lock             → errs + pgx
db/jobs, db/outbox, db/inbox                → db + errs
db/outbox/outboxnats, db/inbox/inboxnats    → db/outbox|inbox + clients/natsmap
breaker, bulkhead, batch                    → stdlib + prometheus
cronmap                                     → errs + robfig/cron + yaml.v3 (+ db/lock optional for PGLocker, sentrykit optional)
clients/httpc                               → errs + prometheus + breaker + bulkhead
clients/apimap                              → errs + clients/httpc + breaker + bulkhead + yaml.v3
clients/nats                                → errs + nats.go + prometheus
clients/natsmap                             → errs + clients/nats + yaml.v3
clients/redis, clients/cache, clients/ratelimit → errs + go-redis
clients/s3                                  → errs + aws-sdk-go-v2
clients/email                               → errs + (provider-specific)
clients/webhooks                            → errs + db + clients/httpc
auth                                        → errs + crypto + jwt + fiber
auth/refreshpg, auth/apikeypg, auth/sessions → auth + db
auth/refreshredis                           → auth + go-redis
auth/fibermount                             → auth + fibermap
fibermap                                    → errs + fiber
fibermap/uploadguard                        → fibermap + clients/s3
otelkit, sentrykit, runbook                 → fibermap + provider SDK
audit                                       → errs + db (audit/auditpg)
service                                     → почти всё (это и есть all-in-one)

Корневой пакет gokit пустой — без экспортируемых символов. Импорт одного подпакета не тянет остальные (service — единственное исключение).

Установка

# Минимум для роутера:
go get github.com/theizzatbek/gokit/fibermap
go get github.com/theizzatbek/gokit/errs

# Всё-в-одном:
go get github.com/theizzatbek/gokit/service

# Опциональный CLI для linting'а routes.yaml + экспорта schema:
go install github.com/theizzatbek/gokit/cmd/fibermap@latest

# CLI для scaffold'а нового сервиса:
go install github.com/theizzatbek/gokit/cmd/kit@latest

Требуется Go 1.26+ и Fiber v2 (для fibermap/).

Quickstart — fibermap роутер

# routes.yaml
groups:
  - prefix: /v1
    routes:
      - method: GET
        path:   /ping
        handler: ping
        name:   ping.get

package main

import (
    "context"

    "github.com/gofiber/fiber/v2"
    "github.com/theizzatbek/gokit/fibermap"
)

type AppCtx struct{ /* per-request data */ }

func main() {
    eng := fibermap.New[AppCtx]()
    eng.SetContextBuilder(func(c *fiber.Ctx) (AppCtx, error) {
        return AppCtx{}, nil
    })
    fibermap.RegisterHandler(eng, "ping", func(c *fibermap.Context[AppCtx]) error {
        return c.SendString("pong")
    })
    if err := eng.LoadFile("routes.yaml"); err != nil {
        panic(err)
    }
    if err := eng.Run(context.Background(), fibermap.WithAddr(":3000")); err != nil {
        panic(err)
    }
}

Для реальных endpoint'ов используйте типизированные регистры — они парсят body/query/params, валидируют через eng.SetValidator, авто-attach'ат схему для OpenAPI и сводят boilerplate к одной строке req argument:

type CreateTaskReq struct {
    Title string `json:"title" validate:"required,min=1,max=200"`
}

fibermap.RegisterHandlerWithBody(eng, "tasks.create",
    func(c *fibermap.Context[AppCtx], req CreateTaskReq) error {
        // req уже распарсен и провалидирован.
        return c.Status(201).JSON(...)
    },
    fibermap.WithResponse(201, Task{}),
)

Sibling-хелперы — RegisterHandlerWith{Query,Params,Headers}. Комбинированные кейсы (body+param и т.д.) — RegisterHandlerWithInput. См. fibermap/README.md § «Типизированный body-bound хендлер» и «Комбинированные binder'ы».

Quickstart — service.New (полный bundle)

svc, err := service.New[AppCtx, MyClaims](ctx, cfg,
    service.WithRoutes(),
    service.WithOpenAPI(),
    service.WithSentry(dsn, service.SentryOptions{
        ErrorCaptureLevel: service.LevelPtr(slog.LevelError),
    }),
)
if err != nil { return err }
defer svc.Close()

svc.SetContextBuilder(...)
fibermap.RegisterHandler(svc.Engine, ...)
return svc.Run()

На старте печатает один структурированный service ready log с booleanами по каждому подсистеме (db=true, auth=true, redis=false, ...); intospection через svc.Status(). Подробности — service/README.md.

Поддержка редактора для YAML-конфигов

Все встроенные YAML'ы кита (routes.yaml, crons.yaml, clients.yaml, subscribers.yaml/publishers.yaml) имеют JSON Schema (draft-07), сгружённые в schemas/. Добавьте modeline в начало соответствующего файла:

# yaml-language-server: $schema=https://raw.githubusercontent.com/theizzatbek/gokit/main/schemas/routes.schema.json

VS Code (с redhat.vscode-yaml), GoLand и Vim с coc-yaml дают автодополнение, hover-документацию и inline-диагностику — опечатки в middleware: подсвечиваются до go test. Полный список схем + примеры — в schemas/README.md.

CLI

fibermap validate routes.yaml    # schema-lint; ненулевой exit при проблемах
fibermap dump-schema             # печатает встроенную JSON Schema

validate проверяет схему (обязательные поля, валидные HTTP методы, циклы в middleware_set, форма middleware). НЕ проверяет, что имена handler / middleware / factory зарегистрированы — ваш Go-бинарь это единственное место, где они живут. Для полной валидации вызовите Engine.Validate() в Go-тесте или boot-скрипте.

cmd/kit — отдельный generator/scaffold CLI (см. cmd/kit/README.md).

Примеры

Пример	Что показывает
examples/urlshort/	Multi-binary microservice setup с outbox + apimap.
examples/resilience/	breaker + bulkhead через apimap YAML против flaky httptest сервера.
examples/inbox-outbox/	Effectively-once event flow с outboxnats + inboxnats (testcontainers postgres + nats).

Documentation

Overview

Package gokit is the umbrella for the Go service kit. Each subpackage is independently importable. Subpackages:

• fibermap: YAML-declarative Fiber router
• errs: typed domain errors + HTTP mapping
• db: pgx pool + transactions + healthcheck
• db/sqb: opt-in squirrel wrapper over db
• auth: JWT + refresh + ready-to-mount middleware
• clients/httpc: outbound *http.Client with retry/timeout
• clients/apimap: declarative outbound HTTP via YAML
• clients/nats: typed JetStream wrapper (package natsclient)

The root gokit package itself has no exported symbols. Importing one subpackage does not pull the others.

See README.md for the per-package overview and dependency rules.