AppKit – Go Application Framework Utilities

A comprehensive Go utility package providing common application framework components for building production-ready HTTP services.

Features

Core Utilities

• Version Management: Automatically extracts version information from VCS (Git) build info
• HTTP Headers: Pre-configured internal service headers with app name and version

Echo Framework Integration

• Pre-configured Echo Server: Ready-to-use Echo instance with security and monitoring middleware
• IP Extraction: Proper IP handling with real IP header support and CIDR trust ranges
• Sentry Integration: Built-in error tracking with Sentry middleware
• Route Rendering: Automatic HTML route listing for service discovery

Monitoring & Metrics

• Prometheus Integration: Comprehensive HTTP metrics (request count, response duration)
• Metadata Management: Service configuration tracking and metrics registration
• pprof Support: Built-in profiling endpoint handler

Service Metadata

• Service Discovery: Track internal and external service dependencies
• Database Monitoring: Connection tracking and replica status
• API Exposure: Public/private API configuration tracking

HTTP Client

• Pre-configured Client: HTTP client with automatic metrics and internal headers
• Transport Wrappers: Composable transport layers for metrics and header injection
• Caller Tracking: Context-based caller identification for metrics

Request Management

• X-Request-ID: Automatic generation, validation, and propagation
• Context Integration: Request ID stored in context for easy access
• Header Management: CORS and custom header support

Context Utilities

• Metadata Context: Store and retrieve request metadata (IP, User-Agent, Platform, Version, Country)
• Debug Support: Debug ID and SQL group tracking for logging
• Integration Support: Sentry Hub and method tracking

Usage Examples

Please see example/main.go

Basic HTTP Server with Metrics

e := appkit.NewEcho()

// Add Prometheus metrics
e.Use(appkit.HTTPMetrics("api-service"))

// Route rendering for service discovery
e.GET("/", appkit.RenderRoutes("API Service", e))

// pprof endpoints
e.GET("/debug/pprof/*", appkit.PprofHandler)

Service Metadata Configuration

metadata := appkit.NewMetadataManager(appkit.MetadataOpts{
    DBs: []appkit.DBMetadata{
        appkit.NewDBMetadata("postgres", 10, false),
        appkit.NewDBMetadata("redis", 5, true),
    },
    HasPublicAPI:      true,
    HasPrivateAPI:     false,
    HasBrokersrvQueue: true,
    HasCronJobs:       true,
    Services: []appkit.ServiceMetadata{
        appkit.NewServiceMetadata("auth-service", appkit.MetadataServiceTypeSync),
        appkit.NewServiceMetadata("payment-service", appkit.MetadataServiceTypeExternal),
    },
})

// Register metrics
metadata.RegisterMetrics()

// Add metadata endpoint
e.GET("/metadata", metadata.Handler)

Internal Service Communication

func callInternalService() {
    headers := appkit.NewInternalHeaders("worker-service", appkit.Version())
    
    req, _ := http.NewRequest("GET", "http://api-service/internal/data", nil)
    req.Header = headers
    
    // Make request with proper internal headers
    client.Do(req)
}

HTTP Client with Metrics

// Create pre-configured HTTP client for internal service calls
client := appkit.NewHTTPClient("externalsrv", appkit.Version(), 30*time.Second)

// Set caller name in context for metrics tracking
ctx := appkit.NewCallerNameContext(context.Background(), "externalsrv")

req, _ := http.NewRequestWithContext(ctx, http.MethodGet, "http://api-service/endpoint", nil)
resp, _ := client.Do(req)

// Usage with clients generated by vmkteam/rpcgen
arithsrvClient := arithsrv.NewClient(arithsrvUrl, appkit.NewHTTPClient("arithsrv", appkit.Version(), 5*time.Second))

API Reference

Core Functions

• Version() string - Returns VCS revision or "devel"
• NewInternalHeaders(appName, version string) http.Header - Creates standardized internal headers

Echo Framework

• NewEcho() *echo.Echo - Creates pre-configured Echo instance
• RenderRoutes(appName string, e *echo.Echo) echo.HandlerFunc - HTML route renderer
• PprofHandler(c echo.Context) error - pprof endpoint handler
• EchoHandlerFunc(next http.HandlerFunc) echo.HandlerFunc - HTTP handler wrapper

Metrics & Monitoring

• HTTPMetrics(serverName string) echo.MiddlewareFunc - Prometheus HTTP metrics middleware
• MetadataManager - Service metadata configuration and metrics

HTTP Client

• NewHTTPClient(appName, version string, timeout time.Duration) *http.Client - Creates HTTP client with metrics and internal headers
• WithMetricsTransport(base http.RoundTripper) http.RoundTripper - Wraps transport with Prometheus metrics
• WithHeadersTransport(base http.RoundTripper, headers http.Header) http.RoundTripper - Wraps transport to inject headers for each request
• NewCallerNameContext(ctx context.Context, callerName string) context.Context - Creates context with caller name for metrics
• CallerNameFromContext(ctx context.Context) string - Retrieves caller name from context

Request ID & HTTP Handlers

• XRequestIDFromContext(ctx context.Context) string - Retrieves X-Request-ID from context
• NewXRequestIDContext(ctx context.Context, requestID string) context.Context - Creates context with X-Request-ID
• SetXRequestIDFromCtx(ctx context.Context, req *http.Request) - Adds X-Request-ID from context to request headers
• CORS(next http.Handler, headers ...string) http.Handler - CORS middleware for HTTP handlers
• XRequestID(next http.Handler) http.Handler - X-Request-ID middleware for HTTP handlers
• EchoHandler(next http.Handler) echo.HandlerFunc - Wraps HTTP handler as Echo handler
• EchoSentryHubContext() echo.MiddlewareFunc - Echo middleware to apply Sentry hub to context
• EchoIPContext() echo.MiddlewareFunc - Echo middleware to apply client IP to context

Context Utilities

• NewDebugIDContext(ctx context.Context, debugID uint64) context.Context - Creates context with debug ID
• DebugIDFromContext(ctx context.Context) uint64 - Retrieves debug ID from context
• NewSQLGroupContext(ctx context.Context, group string) context.Context - Creates context with SQL group for debug logging
• SQLGroupFromContext(ctx context.Context) string - Retrieves SQL group from context
• NewIPContext(ctx context.Context, ip string) context.Context - Creates context with IP address
• IPFromContext(ctx context.Context) string - Retrieves IP address from context
• NewUserAgentContext(ctx context.Context, ua string) context.Context - Creates context with User-Agent
• UserAgentFromContext(ctx context.Context) string - Retrieves User-Agent from context
• NewNotificationContext(ctx context.Context) context.Context - Creates context with JSONRPC2 notification flag
• NotificationFromContext(ctx context.Context) bool - Retrieves JSONRPC2 notification flag from context
• NewIsDevelContext(ctx context.Context, isDevel bool) context.Context - Creates context with isDevel flag
• IsDevelFromContext(ctx context.Context) bool - Retrieves isDevel flag from context
• NewPlatformContext(ctx context.Context, platform string) context.Context - Creates context with platform
• PlatformFromContext(ctx context.Context) string - Retrieves platform from context
• NewVersionContext(ctx context.Context, version string) context.Context - Creates context with version
• VersionFromContext(ctx context.Context) string - Retrieves version from context
• NewCountryContext(ctx context.Context, country string) context.Context - Creates context with country
• CountryFromContext(ctx context.Context) string - Retrieves country from context
• NewMethodContext(ctx context.Context, method string) context.Context - Creates context with method
• MethodFromContext(ctx context.Context) string - Retrieves method from context

Dependencies

• Echo - High performance HTTP framework
• Prometheus - Metrics collection and monitoring
• Sentry - Error tracking and monitoring

Metrics Exported

HTTP Server Metrics

• app_http_requests_total - Total HTTP requests by method/path/status
• app_http_responses_duration_seconds - Response time distribution

HTTP Client Metrics

• app_http_client_requests_total - Total client requests by code/method/caller/origin
• app_http_client_responses_duration_seconds - Client response time distribution
• app_http_client_requests_inflight - Current inflight client requests by caller/origin

Service Metadata Metrics

• app_metadata_service - Service configuration information
• app_metadata_db_connections_total - Database connection counts
• app_metadata_services - Service dependencies

License

MIT License - see LICENSE file for details.