Skip to content

Commit 58de954

Browse files
abitofhelpabitofhelp
committed
Expanding godoc
1 parent e30cf77 commit 58de954

File tree

13 files changed

+556
-13
lines changed

13 files changed

+556
-13
lines changed

‎di/doc.go‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
// Copyright (c) 2025 A Bit of Help, Inc.
2+
3+
// Package di provides a comprehensive dependency injection framework for Go applications.
4+
//
5+
// This package implements a flexible dependency injection system that helps manage
6+
// application dependencies and promotes loose coupling between components. It supports
7+
// various application architectures, with special focus on Domain-Driven Design (DDD)
8+
// and Clean Architecture patterns.
9+
//
10+
// Dependency injection is a design pattern that allows the separation of object creation
11+
// from object usage, making code more modular, testable, and maintainable. This package
12+
// provides containers that manage the lifecycle of dependencies and their relationships.
13+
//
14+
// Key features:
15+
// - Generic containers that work with any configuration type
16+
// - Support for layered architecture (repositories, domain services, application services)
17+
// - Type-safe dependency management using Go generics
18+
// - Integration with logging, validation, and context management
19+
// - Resource lifecycle management with proper cleanup
20+
// - Thread-safe operation for concurrent applications
21+
//
22+
// The package provides several container types for different use cases:
23+
// - BaseContainer: A foundational container with basic dependencies
24+
// - Container: A backward-compatible container using interface{} types
25+
// - GenericAppContainer: A type-safe container for layered applications
26+
// - RepositoryContainer: A specialized container for repository management
27+
// - ServiceContainer: A container focused on service management
28+
//
29+
// Example usage for a simple application:
30+
//
31+
// // Create a container with application configuration
32+
// container, err := di.NewContainer(ctx, logger, appConfig)
33+
// if err != nil {
34+
// log.Fatalf("Failed to create container: %v", err)
35+
// }
36+
// defer container.Close()
37+
//
38+
// // Use the container to access dependencies
39+
// validator := container.GetValidator()
40+
// logger := container.GetLogger()
41+
//
42+
// Example usage for a layered application:
43+
//
44+
// // Create a generic container with typed dependencies
45+
// container, err := di.NewGenericAppContainer(
46+
// ctx,
47+
// logger,
48+
// appConfig,
49+
// connectionString,
50+
// initUserRepository,
51+
// initUserDomainService,
52+
// initUserApplicationService,
53+
// )
54+
// if err != nil {
55+
// log.Fatalf("Failed to create container: %v", err)
56+
// }
57+
// defer container.Close()
58+
//
59+
// // Access typed dependencies
60+
// userRepo := container.GetRepository()
61+
// userService := container.GetApplicationService()
62+
//
63+
// The package is designed to be extended for specific application needs.
64+
// Custom containers can be created by embedding the provided containers
65+
// and adding application-specific dependencies and initialization logic.
66+
package di

‎env/doc.go‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
// Copyright (c) 2025 A Bit of Help, Inc.
2+
3+
// Package env provides utilities for working with environment variables.
4+
//
5+
// This package offers a simple and consistent way to access environment variables
6+
// with fallback values, making it easier to configure applications through the
7+
// environment. Using environment variables for configuration is a best practice
8+
// for cloud-native applications, following the principles of the Twelve-Factor App
9+
// methodology.
10+
//
11+
// The package is designed to be lightweight and focused on a single responsibility:
12+
// retrieving environment variables with sensible defaults. This helps prevent
13+
// application crashes due to missing environment variables and reduces the need
14+
// for conditional checks throughout the codebase.
15+
//
16+
// Key features:
17+
// - Retrieval of environment variables with fallback values
18+
// - Simple, consistent API for environment access
19+
// - Zero external dependencies
20+
//
21+
// Example usage:
22+
//
23+
// // Get database connection string with a default value
24+
// dbConnString := env.GetEnv("DATABASE_URL", "postgres://localhost:5432/mydb")
25+
//
26+
// // Get application port with a default value
27+
// port := env.GetEnv("PORT", "8080")
28+
//
29+
// // Get log level with a default value
30+
// logLevel := env.GetEnv("LOG_LEVEL", "info")
31+
//
32+
// The package is typically used during application startup to load configuration
33+
// values from the environment. It can be used directly or as part of a more
34+
// comprehensive configuration system.
35+
package env

‎model/doc.go‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
// Copyright (c) 2025 A Bit of Help, Inc.
2+
3+
// Package model provides utilities for working with domain models and DTOs (Data Transfer Objects).
4+
//
5+
// This package offers tools for managing the conversion and manipulation of data models
6+
// across different layers of an application. It focuses on simplifying the process of
7+
// copying data between domain models and DTOs, which is a common requirement in
8+
// applications following Clean Architecture or Hexagonal Architecture patterns.
9+
//
10+
// In layered architectures, different representations of the same data are often needed:
11+
// - Domain models: Rich objects with behavior used in the domain layer
12+
// - DTOs: Simple data containers used for API responses or persistence
13+
// - View models: Data structures tailored for specific UI requirements
14+
//
15+
// Converting between these representations manually can be error-prone and repetitive.
16+
// This package provides reflection-based utilities to automate these conversions while
17+
// maintaining type safety and handling complex nested structures.
18+
//
19+
// Key features:
20+
// - Field copying between structs based on field names
21+
// - Deep copying of complex objects with nested structures
22+
// - Support for various types including pointers, slices, and maps
23+
// - Type-safe operations with comprehensive error handling
24+
//
25+
// Example usage for copying fields between different struct types:
26+
//
27+
// // Domain model
28+
// type User struct {
29+
// ID string
30+
// FirstName string
31+
// LastName string
32+
// Email string
33+
// Password string // Sensitive field
34+
// CreatedAt time.Time
35+
// }
36+
//
37+
// // DTO for API responses
38+
// type UserDTO struct {
39+
// ID string
40+
// FirstName string
41+
// LastName string
42+
// Email string
43+
// // Password is omitted for security
44+
// CreatedAt time.Time
45+
// }
46+
//
47+
// // Copy fields from domain model to DTO
48+
// user := &User{
49+
// ID: "123",
50+
// FirstName: "John",
51+
// LastName: "Doe",
52+
// Email: "[email protected]",
53+
// Password: "secret",
54+
// CreatedAt: time.Now(),
55+
// }
56+
//
57+
// userDTO := &UserDTO{}
58+
// err := model.CopyFields(userDTO, user)
59+
// if err != nil {
60+
// log.Fatalf("Failed to copy fields: %v", err)
61+
// }
62+
//
63+
// // userDTO now contains all matching fields from user (except Password)
64+
//
65+
// Example usage for creating a deep copy of an object:
66+
//
67+
// // Create a deep copy of a complex object
68+
// originalUser := &User{
69+
// ID: "123",
70+
// FirstName: "John",
71+
// LastName: "Doe",
72+
// Email: "[email protected]",
73+
// Password: "secret",
74+
// CreatedAt: time.Now(),
75+
// }
76+
//
77+
// copiedUser := &User{}
78+
// err := model.DeepCopy(copiedUser, originalUser)
79+
// if err != nil {
80+
// log.Fatalf("Failed to create deep copy: %v", err)
81+
// }
82+
//
83+
// // copiedUser is now a complete copy of originalUser
84+
// // Modifying copiedUser will not affect originalUser
85+
//
86+
// The package is designed to be used in service layers or adapters where
87+
// conversion between different data representations is required.
88+
package model

‎shutdown/doc.go‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
// Copyright (c) 2025 A Bit of Help, Inc.
2+
3+
// Package shutdown provides functionality for graceful application shutdown.
4+
//
5+
// This package implements a robust system for handling application termination,
6+
// ensuring that resources are properly released and in-flight operations are
7+
// completed before the application exits. It handles OS signals (SIGINT, SIGTERM, SIGHUP)
8+
// and context cancellation to trigger graceful shutdown.
9+
//
10+
// Proper shutdown handling is critical for production applications to prevent:
11+
// - Data loss from incomplete operations
12+
// - Resource leaks from unclosed connections
13+
// - Inconsistent state from abrupt termination
14+
// - Service disruption for users during deployments
15+
//
16+
// Key features:
17+
// - Signal-based shutdown handling (SIGINT, SIGTERM, SIGHUP)
18+
// - Context-based shutdown initiation for programmatic control
19+
// - Timeout management to prevent hanging during shutdown
20+
// - Multiple signal handling with forced exit on second signal
21+
// - Comprehensive logging of shutdown events
22+
// - Error propagation from shutdown operations
23+
//
24+
// The package provides two main functions:
25+
// - GracefulShutdown: Blocks until shutdown is triggered, then executes cleanup
26+
// - SetupGracefulShutdown: Sets up background shutdown handling without blocking
27+
//
28+
// Example usage with GracefulShutdown (blocking approach):
29+
//
30+
// func main() {
31+
// // Initialize application components
32+
// logger := logging.NewContextLogger(zapLogger)
33+
// server := startServer()
34+
// db := connectToDatabase()
35+
//
36+
// // Define shutdown function
37+
// shutdownFunc := func() error {
38+
// // Close resources in reverse order of creation
39+
// serverErr := server.Shutdown(context.Background())
40+
// dbErr := db.Close()
41+
//
42+
// // Return combined error if any
43+
// if serverErr != nil || dbErr != nil {
44+
// return fmt.Errorf("shutdown errors: server=%v, db=%v", serverErr, dbErr)
45+
// }
46+
// return nil
47+
// }
48+
//
49+
// // Wait for shutdown signal and execute cleanup
50+
// if err := shutdown.GracefulShutdown(context.Background(), logger, shutdownFunc); err != nil {
51+
// logger.Error(context.Background(), "Shutdown completed with errors", zap.Error(err))
52+
// os.Exit(1)
53+
// }
54+
// }
55+
//
56+
// Example usage with SetupGracefulShutdown (non-blocking approach):
57+
//
58+
// func main() {
59+
// // Initialize application components
60+
// logger := logging.NewContextLogger(zapLogger)
61+
// server := startServer()
62+
// db := connectToDatabase()
63+
//
64+
// // Define shutdown function
65+
// shutdownFunc := func() error {
66+
// // Close resources in reverse order of creation
67+
// serverErr := server.Shutdown(context.Background())
68+
// dbErr := db.Close()
69+
//
70+
// // Return combined error if any
71+
// if serverErr != nil || dbErr != nil {
72+
// return fmt.Errorf("shutdown errors: server=%v, db=%v", serverErr, dbErr)
73+
// }
74+
// return nil
75+
// }
76+
//
77+
// // Set up graceful shutdown in the background
78+
// cancel, errCh := shutdown.SetupGracefulShutdown(context.Background(), logger, shutdownFunc)
79+
// defer cancel() // Ensure shutdown is triggered if main exits
80+
//
81+
// // Continue with application logic
82+
// // ...
83+
//
84+
// // Optionally wait for shutdown to complete and check for errors
85+
// if err := <-errCh; err != nil {
86+
// logger.Error(context.Background(), "Shutdown completed with errors", zap.Error(err))
87+
// os.Exit(1)
88+
// }
89+
// }
90+
//
91+
// The package is designed to be used at the application's entry point (main function)
92+
// to ensure proper resource cleanup during termination.
93+
package shutdown

‎telemetry/config.go‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
// Copyright (c) 2025 A Bit of Help, Inc.
22

3-
// Package telemetry provides functionality for monitoring and tracing application behavior.
4-
// It offers a unified interface for both metrics collection and distributed tracing
5-
// using OpenTelemetry and Prometheus.
3+
// Package telemetry provides functionality for collecting and exporting telemetry data,
4+
// including distributed tracing and metrics.
5+
//
6+
// This file contains the configuration structures and loading functions for the telemetry
7+
// package. It defines the configuration schema for all telemetry components, including
8+
// tracing, metrics, and OTLP exporters. The configuration can be loaded from a koanf
9+
// instance, and default values are provided for quick setup in development environments.
610
package telemetry
711

812
import (

0 commit comments

Comments
 (0)