README
¶
chassis-go
A composable Go toolkit providing standardized building blocks that services wire together explicitly. Toolkit, not framework — it never owns main().
Packages
Tier 1: Foundation
| Package | Purpose |
|---|---|
config |
Load env vars into structs via tags. Panic on missing required config. |
logz |
Structured JSON logging wrapping log/slog with TraceID extraction. |
lifecycle |
Graceful shutdown orchestration via errgroup. |
testkit |
Testing utilities: NewLogger, LoadConfig, GetFreePort. |
Tier 2: Transports & Clients
| Package | Purpose |
|---|---|
httpkit |
HTTP server middleware: RequestID, logging, recovery, JSON errors. |
grpckit |
gRPC server interceptors: logging, recovery, metrics. Health wiring. |
health |
Health check protocol with parallel aggregation. HTTP + gRPC. |
call |
Intelligent HTTP client: retries, circuit breaking, deadline propagation. |
Usage
func main() {
cfg := config.MustLoad[AppConfig]()
logger := logz.New(cfg.LogLevel)
svc := yourservice.New(
yourservice.WithLogger(logger),
)
lifecycle.Run(context.Background(),
func(ctx context.Context) error {
return httpServer.ListenAndServe()
},
func(ctx context.Context) error {
return grpcServer.Serve(lis)
},
)
}
Principles
- Toolkit, not framework — Chassis never owns
main(). You call it. - Zero cross-dependencies — Importing
configdoesn't pull ingrpc. - Consumer-owned interfaces — Libraries define what they need.
- Visible wiring — No magic startup.
- Fail fast — Missing config = panic on startup.
Install
go get github.com/ai8future/chassis-go
License
MIT
Documentation
¶
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package call provides a resilient HTTP client with retry, circuit breaker, and timeout support using a composable builder pattern.
|
Package call provides a resilient HTTP client with retry, circuit breaker, and timeout support using a composable builder pattern. |
|
cmd
|
|
|
demo-shutdown
command
Command demo-shutdown verifies that lifecycle.Run handles SIGTERM correctly, cancels Contexts, and drains gracefully.
|
Command demo-shutdown verifies that lifecycle.Run handles SIGTERM correctly, cancels Contexts, and drains gracefully. |
|
Package config provides a generic, reflection-based configuration loader that populates structs from environment variables using struct tags.
|
Package config provides a generic, reflection-based configuration loader that populates structs from environment variables using struct tags. |
|
examples
|
|
|
01-cli
command
Example 01-cli demonstrates a simple CLI tool using config + logz.
|
Example 01-cli demonstrates a simple CLI tool using config + logz. |
|
02-service
command
Example 02-service demonstrates a reference gRPC service using config + logz + lifecycle + grpckit + health.
|
Example 02-service demonstrates a reference gRPC service using config + logz + lifecycle + grpckit + health. |
|
03-client
command
Example 03-client demonstrates the call package with retries and circuit breaking.
|
Example 03-client demonstrates the call package with retries and circuit breaking. |
|
Package grpckit provides gRPC server utilities including standard interceptors for logging, panic recovery, and health-check registration.
|
Package grpckit provides gRPC server utilities including standard interceptors for logging, panic recovery, and health-check registration. |
|
Package health provides composable health checks with parallel execution and a standard HTTP handler that returns structured JSON results.
|
Package health provides composable health checks with parallel execution and a standard HTTP handler that returns structured JSON results. |
|
Package httpkit provides standard HTTP middleware and response utilities.
|
Package httpkit provides standard HTTP middleware and response utilities. |
|
Package lifecycle provides a minimal orchestration primitive for running concurrent components that share a single context for cancellation and graceful shutdown via OS signals.
|
Package lifecycle provides a minimal orchestration primitive for running concurrent components that share a single context for cancellation and graceful shutdown via OS signals. |
|
Package logz provides structured JSON logging with trace ID propagation.
|
Package logz provides structured JSON logging with trace ID propagation. |
|
Package testkit provides lightweight test helpers for chassis-go services.
|
Package testkit provides lightweight test helpers for chassis-go services. |
Click to show internal directories.
Click to hide internal directories.