forge/doc.go at main · datariot/forge · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
// 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.
package forge