keelab/keelith

English | 中文

Keelith is a contract-first Go runtime for production microservices. It gives generated services one consistent way to compose HTTP and gRPC transports, middleware, configuration, discovery, governance, background work, observability, and graceful lifecycle management.

Keelith is intentionally modular: start with the core contracts, add only the integrations your service needs, and keep infrastructure-specific dependencies at the edge.

• One application lifecycle — deterministic startup, readiness, graceful shutdown, and bounded cleanup for servers, workers, components, and configuration watchers.
• Transport-neutral contracts — shared operations, metadata, errors, validation, identity, and placement across HTTP, gRPC, Hertz, and Kitex.
• Composable governance — timeout, retry, hedging, circuit breaking, bulkheads, rate limiting, load shedding, admission control, fallback, and outlier detection.
• Programmable workloads — durable continuations, projections, topology plans, sagas, jobs, workers, cache invalidation, and idempotency primitives.
• Observable by default — structured logging, metrics, tracing, health, diagnostics, and secret-free runtime descriptions.
• Explicit extension boundaries — optional adapters live in the separate github.com/keelab/contrib module; CloudWeGo profiles live in the separate github.com/keelab/x module.

Requirements: Go 1.26 or newer. Generated service bindings are the recommended entry point. The CLI creates a minimal runnable HTTP service:

go install github.com/keelab/keelith/cmd/keelith@latest
keelith new hello
cd hello
go run .
# in another terminal
curl http://127.0.0.1:8080/ping

For a complete generated service, follow the projects in Keelab examples or use the scaffold tools in internal/scaffold. The public API is documented on pkg.go.dev.

Install the core module:

go get github.com/keelab/keelith
go install github.com/keelab/keelith/cmd/protoc-gen-go-keelith@latest

The core module provides standard HTTP and gRPC implementations. The optional github.com/keelab/x module adds CloudWeGo integrations:

go get github.com/keelab/x/transport/hertz
go get github.com/keelab/x/transport/kitex

Use x/transport/hertz for Hertz HTTP services and x/transport/kitex for generated Kitex servers and clients. Keelith owns middleware, metadata, error, retry, and picker policy; avoid enabling a second independent retry budget in the underlying client.

keelith/
├── app/             lifecycle and dependency-aware runtime
├── transport/       HTTP, gRPC, streaming, auth, and protocol helpers
├── governance/      resilience and traffic policies
├── programmable/    continuations, projections, and topology
├── observability/   logging, metrics, tracing, and diagnostics
└── ...              optional adapters and profiles are maintained in separate repositories

• API reference
• Keelab examples
• Contrib integrations
• Kubernetes operator
• CloudWeGo profiles

go test ./...
go vet ./...

The contrib, operator, and x repositories are validated independently. Some integration checks require external services or a Kubernetes test cluster; see the corresponding repository README files before running them.

Keelith follows semantic, contract-oriented APIs within each module. Review SECURITY.md for vulnerability reporting. Do not place credentials, raw payloads, or sensitive endpoint data in logs or runtime descriptions; use the secret, metadata policy, and redaction packages.

Keelith is released under the MIT License.