SprinGo Framework 🚀

High-performance, opinionated Go framework for Spring Boot developers.

---

⚠️ Release status: v1.0.0-rc19 is a Release Candidate. Validate it in a staging environment before adopting it for production workloads; public APIs may still receive release-blocking corrections before v1.0.0.

---

⚡ Quick Start

1. Install SprinGo CLI

go install github.com/NeftaliAcosta/springo/cmd/springo@v1.0.0-rc19

2. Scaffold a New Enterprise Service

springo new my-service
cd my-service
go run cmd/app/main.go

Your API is now live at http://localhost:8080 with Actuator Dashboard at http://localhost:8080/actuator/dashboard! 🎉

---

🚀 Key Features

Category	Feature	Description
🛠️ CLI Tooling	Code Generators & Scaffolding	springo new and springo make for instant Hexagonal Architecture components.
🎛️ Management	Spring-style Actuator	Embedded Glassmorphic UI Dashboard for Health, Goroutine Dumps, Beans & DLQ.
🧩 Core Engine	IoC & Auto-Wiring	Dependency injection container with reflection & tag-based field autowiring (spring:"beanName").
🔄 Lifecycle	Initializer, Ready & Shutdown Hooks	Ordered, fail-safe application hooks keep infrastructure setup out of main.go.
📤 Web Binding	JSON & Multipart DTOs	Declarative request binding for JSON, path/query values and streamed multipart files with configurable limits.
🔒 Security	Enterprise JWT & CSRF	Support for HS256, RS256 (Keycloak/Auth0 JWKS), OWASP Security Headers & CSRF.
⚡ Database	GORM & ShedLock	Declarative transactions with REQUIRED propagation and cluster-wide cron locking.
📡 Messaging	Event Bus & Outbox/DLQ	Domain Pub/Sub with Outbox buffer, automatic retries, and Dead Letter Queue management.
⚙️ Config	Profiles & Validation	Fail-fast property validation with application-{profile}.yaml environments.

---

🏗️ Architecture

SprinGo enforces a Flattened Professional Hexagonal Architecture with a dedicated Kernel:

springo/
├── framework/                 # 🛠️ THE KERNEL (SprinGo Engine Library)
│   ├── app.go
│   ├── runner.go
│   ├── cache/                 # Multi-provider cache abstraction
│   ├── config/                # YAML Profile loader & validation
│   ├── database/              # GORM datasource & ShedLock migrator
│   ├── event/                 # Pub/Sub EventBus, Outbox & DLQ
│   ├── ioc/                   # Dependency Injection Container
│   ├── lifecycle/             # Ordered startup, readiness & shutdown hooks
│   ├── scheduler/             # Cron manager with ShedLock
│   ├── security/              # JWT & LDAP providers
│   └── web/                   # Chi router, Actuator & Validation
├── cmd/
│   ├── cli/                   # 🛠️ SprinGo CLI implementation
│   └── springo/               # Installable `springo` entrypoint (v1.0.0-rc19)
├── demo-api/                  # 🚀 Reference Application
└── README.md

---

🛠️ SprinGo CLI (springo)

The springo CLI automates daily development workflows:

Scaffolding & Code Generation

# 1. Create a new microservice
springo new billing-service

# 2. Generate Hexagonal domain components
springo make model Invoice
springo make dto Invoice
springo make repository Invoice
springo make service Invoice
springo make controller Invoice
springo make migration CreateInvoicesTable

Database Migrations & Route Discovery

# Migration controls
springo migrate
springo migrate status
springo migrate rollback --steps=1

# Terminal route discovery
springo routes

# Regenerate OpenAPI/Swagger documentation when controllers or DTOs change
springo swagger

Controllers registrados con web.Dispatch pueden recibir http.ResponseWriter para adaptar headers o cookies sin mover detalles HTTP al application service:

func (c *AuthController) login(
    ctx context.Context,
    writer http.ResponseWriter,
    req request.LoginRequestDTO,
) (any, error) {
    http.SetCookie(writer, refreshCookie)
    return c.authUseCase.Login(ctx, req.Email, req.Password)
}

Cuando un POST exitoso conserva semántica 200 OK, declarar web.Dispatch(c.login, web.WithSuccessStatus(http.StatusOK)). Sin override, POST continúa respondiendo 201.

springo run keeps hot reload fast by compiling only the application. Swagger generation is intentionally explicit because dependency-aware documentation analysis is considerably slower than an incremental Go build. Use springo swagger --quiet for silent generation or springo swagger --main path/to/main.go for a custom entry point.

---

🔄 Application Lifecycle

Infrastructure components can register ordered lifecycle hooks instead of adding setup and cleanup logic to main.go. This follows the same separation used by Spring Boot lifecycle callbacks while keeping Go registration explicit and type-safe.

package observability

import (
    "context"

    "github.com/NeftaliAcosta/springo/framework/lifecycle"
)

func init() {
    lifecycle.RegisterInitializer("observability.sentry", 100, initializeSentry)
    lifecycle.RegisterReady("observability.sentry", 100, verifySentry)
    lifecycle.RegisterShutdown("observability.sentry", 100, flushSentry)
}

func initializeSentry(ctx context.Context) error {
    // Load and validate the integration after configuration and IoC are available.
    return nil
}

func verifySentry(ctx context.Context) error {
    // Optionally verify readiness after the HTTP listener has been created.
    return nil
}

func flushSentry(ctx context.Context) error {
    // Flush and close the integration during graceful shutdown.
    return nil
}

The application entrypoint remains focused on composition:

func main() {
    framework.Bootstrap(framework.Options{
        Middlewares: []func(http.Handler) http.Handler{
            web.SecurityHeadersMiddleware,
        },
    }).Start()
}

• Hook names must be non-empty and unique within their lifecycle phase.
• Initializers run after configuration, datasources, migrations, and IoC initialization. They execute in ascending order and fail fast, so BootstrapE returns the error and performs registered cleanup.
• Ready hooks run in ascending order after the HTTP listener is created but before Application.Ready() is signaled. All errors are collected; any error prevents readiness and triggers graceful shutdown.
• Shutdown hooks run once during Application.Shutdown, in descending order, so resources close in reverse order. All errors are collected without skipping later hooks.
• Application.Start() handles SIGINT and SIGTERM, then invokes graceful shutdown before the process exits.
• Each hook receives a context.Context. A panic is recovered and returned as a named lifecycle error.

Use lifecycle.BackupRegistrations() only in tests to isolate global registrations and restore them afterward.

---

📊 Actuator Dashboard

SprinGo includes an embedded, zero-dependency Web Console inspired by Spring Boot Admin:

• Health Engine: Automatic discovery and status checks for all GORM datasources & Redis connections.
• Goroutine Dump: Real-time stack trace inspection for concurrency debugging.
• Bean Directory: Full visibility into active IoC container definitions.
• Dead Letter Queue: Web interface to inspect, retry (re-dispatch), or purge failed domain events.

Access it locally at: http://localhost:8080/actuator/dashboard

---

⚙️ Configuration & Profiles

Configuration is 100% optional. If omitted, SprinGo falls back to sensible enterprise defaults. Load specific profile files via SPRINGO_PROFILES_ACTIVE:

Application routes use /api/v1 by default. Override the prefix without changing the kernel:

server:
  api:
    base-path: /platform/v2

Use / to expose application routes without a common prefix. The value must begin with /; trailing slashes are normalized. Keep the Swagger @BasePath annotation and JWT public-paths synchronized with a custom prefix.

Multipart file binding

SprinGo binds multipart/form-data directly to request DTOs while preserving path and query binding:

type UploadRequest struct {
    ResourceUUID string             `path:"resource_uuid" validate:"required,uuid"`
    Description  string             `form:"description"`
    File         *web.MultipartFile `form:"file" validate:"required"`
}

func (c *ResourceController) upload(ctx context.Context, dto UploadRequest) (any, error) {
    file, err := dto.File.Open()
    if err != nil {
        return nil, err
    }
    defer file.Close()
    return c.service.Upload(ctx, dto.ResourceUUID, dto.File.Filename, file)
}

Configure global upload limits in bytes. Content above memory-threshold is spooled to temporary storage and cleaned automatically after the controller returns:

server:
  multipart:
    enabled: true
    max-file-size: 104857600
    max-request-size: 115343360
    memory-threshold: 8388608

# Development profile (loads resources/application-dev.yaml)
SPRINGO_PROFILES_ACTIVE=dev go run cmd/app/main.go

# Production profile (loads resources/application-prod.yaml)
SPRINGO_PROFILES_ACTIVE=prod ./main

---

📖 Step-by-Step Tutorials & Documentation

Explore our comprehensive library of step-by-step guides from zero to production:

🚀 Getting Started & CLI

• 🚀 Zero-to-Production Beginner Guide: Scaffolding, architecture, database setup, Docker containerization, and cloud deployment.
• 🛠️ SprinGo CLI Complete Reference: All commands, generators, database migrations, route discovery, and Swagger tools.
• 🏗️ Flattened Hexagonal Architecture Guide: Clean separation of concerns, domain models, ports, services, and adapters.
• ☕ Java Spring Boot to SprinGo Migration Guide: Rosetta Stone mapping annotations, concepts, and architectural patterns to Go.

🧩 Core Framework & IoC

• ⚙️ Configuration Properties & Profiles: Fail-fast YAML binding, dynamic env fallbacks, Sentry/Redis setups, and multi-profile environments.
• 🧩 IoC Container & Bean Configuration: Factories (T, error), dynamic parameter injection, Provider[T], and field autowiring.
• 🔄 Lifecycle Hooks & Graceful Shutdown: Ordered startup initializers, readiness verification, and OS signal shutdown traps.

🌐 Web, REST & Security

• 🌐 REST Web Routing & DTO Validation: Chi router integration, web.Dispatch, JSON & Multipart file binding, and status overrides.
• 🛡️ Advanced DTO Validation & Groups: Validation groups (OnCreate, OnUpdate), custom validator tags, and Problem Details.
• 🌐 CORS & Origin Whitelist Configuration: Exact origin whitelist, dynamic wildcard patterns, credentials, and preflight caching.
• 🔐 JWT Security, OWASP Headers & Middleware: JWT (HS256/RS256 JWKS), claims extraction, security headers, CSRF, and custom middlewares.
• 🏢 Corporate Security & Active Directory LDAP: Active Directory / LDAP authentication, group-to-role mappings, and TLS/StartTLS.
• 🚨 Standardized Error Handling & RFC 7807: Domain error sentinels, Problem Details output, and field-level validation errors.

⚡ Data, Transactions & Background Jobs

• ⚡ Declarative Transaction Management: Spring-like propagation levels, panic/error rollback safety, and post-commit events.
• 🗄️ Multiple DataSources & Pool Tuning: Primary and named secondary datasources, read replicas, and connection pool sizing.
• 🗄️ SQL & Programmatic Go Migrations: Dual-engine migrations with db.AutoMigrate(&Entity{}), Flyway-style SQL, and ShedLock.
• 📜 Hibernate Envers-Style Auditing: Change data capture, dialect-native DDLs, and user context sanitization.
• 📦 Cache Abstraction & Redis Integration: Multi-driver cache engine, TTL expirations, and Actuator health integration.
• ⏰ Distributed Scheduling & ShedLock: Cluster-safe cron tasks, database locking, and multi-replica safety.
• 📡 Event-Driven Architecture & Outbox: Domain Pub/Sub EventBus, Transactional Outbox, automatic retries, and Dead Letter Queue.

📊 Observability & Testing

• 📊 Actuator Diagnostics & Observability: Glassmorphic dashboard, health probes, metrics, goroutine dumps, and DLQ management.
• 📊 Custom Health Indicators & Telemetry: web.RegisterHealthCheck, external ping health indicators, and Kubernetes probe privacy.
• 📝 Structured Logging & Distributed Tracing: log/slog structured logging, context propagation (request_id, trace_id), and JSON formats.
• 🧪 Unit & Integration Testing Guide: SprinGoTestContext, fluent HTTP client, automatic DB rollback, and bean mocking.

---

🔐 Security & Safety

• Actuator Health Privacy: Public unauthenticated GET /actuator/health returns minimal status {"status": "UP"}
• for load balancers and Kubernetes probes without exposing database connection pool metrics, goroutines, or system
• topology. Authenticated requests (and the embedded Glassmorphic Admin Dashboard via Basic Auth) receive full detailed
• component metrics.
• Production & Staging Hardening: Profile validation (prod, production, staging, stage) automatically
• enforces 256-bit JWT secret entropy, explicit non-empty Actuator Basic Auth passwords, and restricts algorithms to
• supported standard types (HS256, RS256).
• Boundary-Safe Path Matching: Segment-boundary route checking (/actuator and /actuator/*) prevents sibling
• paths from accidentally bypassing JWT security or entering Basic Auth.
• Modern OWASP Security Headers: SecurityHeadersMiddleware automatically enforces `Referrer-Policy:
• strict-origin-when-cross-origin, Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=()`,
• X-Permitted-Cross-Domain-Policies: none, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and conditional
• HSTS.

---

🤝 Contributors

Thank you to all the people who contribute to SprinGo Framework!

---

📄 License

SprinGo Framework is open-source software licensed under the MIT License.