forge

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 1, 2025 License: MIT Imports: 0 Imported by: 0

README

Forge

A batteries-included Go framework for building production-ready microservices.

Overview

Forge is inspired by DropWizard but designed specifically for Go's strengths - interfaces, goroutines, and clean composition. It provides opinionated defaults while maintaining flexibility through a pluggable architecture.

Features

  • Clean Architecture: Component-based design with clear separation of concerns
  • Observability Built-in: OpenTelemetry tracing, structured logging, Prometheus metrics
  • Health Checks: Comprehensive liveness and readiness checks
  • Graceful Lifecycle: Sophisticated startup and shutdown orchestration
  • Configuration Management: Environment-based config with validation
  • Database Integration: Transaction-safe PostgreSQL patterns
  • Event Publishing: Redis Streams integration
  • Security First: No hardcoded credentials, explicit validation requirements

Quick Start

package main

import (
    "context"
    "github.com/datariot/forge/framework"
    "github.com/datariot/forge/bundles/postgresql"
)

func main() {
    cfg := MustLoadConfig()

    myComponent := NewMyComponent(cfg)

    app := framework.New(
        framework.WithConfig(&cfg.BaseConfig),
        framework.WithVersion("1.0.0"),
        framework.WithComponent(myComponent),
        framework.WithBundle(postgresql.Bundle()),
    )

    if err := app.Run(context.Background()); err != nil {
        log.Fatal(err)
    }
}

Installation

go get github.com/datariot/forge

Development

Prerequisites
  • Go 1.25+
  • Docker & Docker Compose (for integration tests)
  • Task (optional, for task runner)
Common Commands
# Run tests
task test
# OR
go test ./...

# Run tests with coverage
task test:coverage

# Run integration tests (requires Docker)
task test:integration

# Build framework and examples
task build:all

# Format and lint code
task lint

# See all available tasks
task --list
Testing

Unit Tests (no external dependencies):

task test

Integration Tests (requires Docker):

task docker:up           # Start PostgreSQL + Redis
task test:integration    # Run integration tests
task docker:down         # Stop services

Coverage Report:

task test:coverage       # Generates coverage.html

Current test coverage: 29.7% (Target: 70%+)

See TESTING.md for comprehensive testing strategy.

Architecture

Forge follows Clean Architecture principles:

  • Framework: Core application lifecycle and interfaces
  • Bundles: Pre-built integrations (PostgreSQL, Redis, Prometheus, etc.)
  • Components: Your business logic implementing framework interfaces
  • Adapters: Infrastructure integrations
  • Config: Environment-driven configuration management

Documentation

CI/CD

GitHub Actions automatically runs on all PRs:

  • Unit tests with race detection
  • Code formatting checks
  • Linting (go vet + golangci-lint)
  • Build verification (framework + examples)
  • Coverage reporting (70% threshold)

See .github/workflows/test.yml for details.

License

MIT License - see LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for your changes
  4. Ensure task ci passes
  5. Submit a pull request

All contributions must:

  • Include tests (maintain 70%+ coverage)
  • Follow Go best practices
  • Include documentation
  • Pass CI/CD checks

Documentation

Overview

Package forge provides a batteries-included Go framework for building production-ready microservices.

Forge is inspired by DropWizard but designed specifically for Go's strengths - interfaces, goroutines, and clean composition. It provides opinionated defaults while maintaining flexibility through a pluggable architecture.

Features

  • Clean Architecture with component-based design
  • Built-in observability (OpenTelemetry tracing & metrics)
  • Comprehensive health checks (liveness/readiness)
  • Graceful lifecycle management with sophisticated shutdown
  • Environment-based configuration with validation
  • Structured logging with development/production modes
  • Bundle system for reusable integrations

Quick Start

Create a service by implementing the Component interface: 

type MyService struct {
	db *sql.DB
}

func (s *MyService) Start(ctx context.Context) error {
	// Initialize your service
	return s.db.PingContext(ctx)
}

func (s *MyService) Stop(ctx context.Context) error {
	// Clean up resources
	return s.db.Close()
}

func (s *MyService) HealthChecks() []health.Check {
	return []health.Check{
		health.NewAlwaysHealthyCheck("my-service"),
	}
}

Configure and run your application: 

func main() {
	cfg := config.DefaultBaseConfig()
	cfg.ServiceName = "my-service"

	service := &MyService{}

	app, err := framework.New(
		framework.WithConfig(&cfg),
		framework.WithVersion("1.0.0"),
		framework.WithComponent(service),
		framework.WithHealthContributor(service),
	)
	if err != nil {
		log.Fatal(err)
	}

	if err := app.Run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

Architecture

Forge follows Clean Architecture principles with these key packages:

  • framework: Core application lifecycle and interfaces
  • config: Environment-based configuration management
  • health: Kubernetes-compatible health check system
  • errors: Structured error handling with classification

HTTP Endpoints

Forge automatically provides these HTTP endpoints:

  • :8080 - gRPC server (configurable via GRPC_ADDR)
  • :8081/health - Combined health status
  • :8081/health/live - Liveness probe
  • :8081/health/ready - Readiness probe

Configuration

All configuration is environment-driven with sensible defaults: 

SERVICE_NAME=my-service
APP_ENV=production
GRPC_ADDR=:8080
HTTP_ADDR=:8081
LOG_LEVEL=info
OTEL_ENDPOINT=https://otlp.example.com

Examples

See the examples/simple-service directory for a complete working example.

More Information

Visit https://github.com/datariot/forge for documentation, examples, and contribution guidelines.

Source Files

View all Source files

Directories

Path Synopsis
bundles
configloader
Package configloader provides automatic configuration loading and management for Forge applications.
 Package configloader provides automatic configuration loading and management for Forge applications.
httpclient
Package httpclient provides an HTTP client bundle for reliable service-to-service communication.
 Package httpclient provides an HTTP client bundle for reliable service-to-service communication.
jwt
Package jwt provides JWT authentication bundle for secure inter-service communication.
 Package jwt provides JWT authentication bundle for secure inter-service communication.
postgresql
Package postgresql provides a PostgreSQL integration bundle for Forge applications.
 Package postgresql provides a PostgreSQL integration bundle for Forge applications.
prometheus
Package prometheus provides Prometheus metrics integration bundle for Forge applications.
 Package prometheus provides Prometheus metrics integration bundle for Forge applications.
redis
Package redis provides a Redis integration bundle for Forge applications.
 Package redis provides a Redis integration bundle for Forge applications.
Package config provides configuration management for Forge microservices.
 Package config provides configuration management for Forge microservices.
Package errors provides domain-specific error handling patterns for Forge microservices.
 Package errors provides domain-specific error handling patterns for Forge microservices.
Package framework provides the core application lifecycle management for Forge microservices.
 Package framework provides the core application lifecycle management for Forge microservices.
Package health provides comprehensive health check functionality for Forge microservices.
 Package health provides comprehensive health check functionality for Forge microservices.
Package testutil provides testing utilities for the Forge framework.
 Package testutil provides testing utilities for the Forge framework.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.