README
¶
Sling
Sling is a lightweight, production-ready Go platform chassis and starter kit for microservices and modular monoliths.
Philosophy: Zero magic, explicit Go-way dependencies, zero overhead, and full infrastructure plumbing out of the box.
Key Highlights
- Dynamic Caddy Gateway: Zero-touch reverse proxy. Matches
/api/<service>/*, automatically strips the prefix, and routes internally to<service>:8080without label sprawl. - PostgreSQL 18 & Isolated Migrations: Automatic database and credential provisioning via Docker labels (
sling.postgres.init). Goose migrations isolated per domain table (e.g.goose_billing). - 3-in-1 Observability: A single lightweight middleware emits OpenTelemetry traces, route-parameterized Prometheus metrics (cardinality protected), and structured
slogentries with correlatedtrace_id. - Self-Healing Config: Struct-driven TOML configuration with auto-repair on startup in local environments. Preserves file inodes for seamless Docker mounts.
- Graceful Teardown Waterfall: Staged 3-phase shutdown: stops ingress HTTP traffic (
run.Group), closes databases/caches in reverse registration order (LIFO), and flushes telemetry buffers.
[!NOTE] Security Notice (Local Dev vs Production): The label-based PostgreSQL provisioner (
postgres-init) and Docker Socket discovery in Prometheus/Promtail are developer conveniences designed specifically for zero-touch local development. In production, databases and credentials should be provisioned via Infrastructure-as-Code (Terraform, Kubernetes Operators, managed DBs) without mounting the Docker socket.
🚀 Quick Start
1. Install Sling CLI
go install github.com/blessed-go/sling/cmd/sling@latest
2. Initialize a New Project
# Initialize a project with an initial 'billing' microservice
sling init myproject billing
cd myproject
3. Add Services or Domains
# Add another standalone microservice
sling add orders
# Add a domain module inside an existing service (modular monolith)
sling add billing/analytics
4. Run Locally
# Boot the local stack (Postgres, Caddy, Prometheus, Grafana, Jaeger, Loki, Migrations, and Air hot reload)
task up
# Run end-to-end Bruno tests
task test:e2e
CLI Commands
| Command | Description |
|---|---|
sling init <project> [service] |
Scaffolds a new project root with docker compose, observability stack, and optional first service |
sling add <service> |
Creates a new deployable microservice (internal/<service>, cmd/<service>, compose fragment, and tests) |
sling add <service>/<domain> |
Adds a domain module to an existing service without spinning up new containers |
sling link <path-to-sling> |
Links local Sling checkout via go.work and docker override for platform development |
sling unlink |
Removes local development overrides, restoring standalone project config |
Ready-to-Use
Sling includes pre-tested platform components:
platform/app: Central runtime coordinator for HTTP/gRPC servers, background runners, and graceful teardown.platform/config: TOML configuration loader withfallback:"..."tags and disk auto-repair.platform/httpx: HTTP helpers, error mapping, observability middleware, and persistent outbound HTTP client.platform/postgres:pgx/v5connection pool with OTel tracing, Prometheus metrics, and Goose migrations.platform/redis:go-redis/v9client with OTel hooks, Prometheus pool stats, and read-through caching decorator.platform/jwt: HMAC-SHA256 token issuance and middleware with automatic logger and trace context enrichment.
For deep architectural patterns, design principles, and recipes, see PLATFORM.md.
📄 License
Sling is open-source software licensed under the MIT License.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
sling
command
|
|
|
platform
|
|
|
app
Package app provides the core runtime lifecycle harness for services.
|
Package app provides the core runtime lifecycle harness for services. |
|
config
Package config provides configuration loading, schema validation, fallback resolution, and automatic repair.
|
Package config provides configuration loading, schema validation, fallback resolution, and automatic repair. |
|
ctxerr
Package ctxerr allows storing and retrieving an error within a context.Context, enabling decoupled error reporting between handlers and middleware/interceptors.
|
Package ctxerr allows storing and retrieving an error within a context.Context, enabling decoupled error reporting between handlers and middleware/interceptors. |
|
grpcx
Package grpcx provides helpers for configuring, serving, and intercepting gRPC servers.
|
Package grpcx provides helpers for configuring, serving, and intercepting gRPC servers. |
|
jwt
Package jwt provides JWT signing, verification, and HTTP authentication middleware.
|
Package jwt provides JWT signing, verification, and HTTP authentication middleware. |
|
logger
Package logger provides structured logging with slog, tint-based human-readable output, and OpenTelemetry trace correlation.
|
Package logger provides structured logging with slog, tint-based human-readable output, and OpenTelemetry trace correlation. |
|
postgres
Package postgres provides PostgreSQL connection pool management with OpenTelemetry tracing, transaction orchestration (Unit of Work), and migration utilities.
|
Package postgres provides PostgreSQL connection pool management with OpenTelemetry tracing, transaction orchestration (Unit of Work), and migration utilities. |
|
redis
Package redis provides Redis client initialization with OpenTelemetry tracing and connection pool metrics.
|
Package redis provides Redis client initialization with OpenTelemetry tracing and connection pool metrics. |
|
run
Package run provides primitives for running concurrent components as a unified group.
|
Package run provides primitives for running concurrent components as a unified group. |
|
system
Package system aggregates platform-level configurations for services.
|
Package system aggregates platform-level configurations for services. |
|
telemetry
Package telemetry provides OpenTelemetry tracing, metrics, and Prometheus exporter setup.
|
Package telemetry provides OpenTelemetry tracing, metrics, and Prometheus exporter setup. |
|
Package template provides embedded project and service templates for the Sling CLI.
|
Package template provides embedded project and service templates for the Sling CLI. |
|
project/cmd/migrate
command
|
|
Click to show internal directories.
Click to hide internal directories.