host-http

Go HTTP framework built on net/http with RMR pattern support.

Quick Start

package main

import hosthttp "github.com/Bofry/host-http"

type HelloRequest struct{}

func (r *HelloRequest) Get(w http.ResponseWriter, req *http.Request) {
    response.Text.Success(w, "Hello, World!")
}

type RequestManager struct {
    *HelloRequest `url:"/hello"`
}

type App struct{}

func main() {
    app := &App{}
    hosthttp.Startup(app).
        Middlewares(hosthttp.UseRequestManager(&RequestManager{})).
        Run()
}

Installation

go get github.com/Bofry/host-http

Documentation

• Getting Started - Setup and first application
• Architecture - Design principles and patterns
• App Lifecycle - Complete lifecycle management
• Performance Benchmarks - Performance analysis and optimization
• Migration Guide - Migrating from host-fasthttp

Examples

Complete working examples in _examples/basic/:

• hello-world - Minimal setup and basic usage
• health-check - Health endpoints with lifecycle
• middleware-chain - Middleware patterns
• json-api - RESTful API with structured responses
• tracing-example - OpenTelemetry + pprof integration
• pprof-profiling - Performance profiling with net/http/pprof

Run examples:

# Health check with lifecycle methods
cd _examples/basic/health-check && go run .

# Test endpoints
curl http://localhost:8080/health        # JSON status with uptime
curl http://localhost:8080/health/ping   # Basic connectivity test

Key Features

• Standard Library: Built on net/http for ecosystem compatibility
• RMR Pattern: Resource-Method-Representation architecture
• App Lifecycle: Complete application lifecycle management
• Zero Configuration: Works with sensible defaults
• Middleware Chain: Composable request processing
• Performance Optimized: Zero-allocation operations and object pooling

Core Concepts

RMR Architecture

• Resource: URL paths (/users, /products)
• Method: HTTP verbs map to Go methods (Get() → GET, Post() → POST)
• Representation: Structured response formatting (JSON/Text)

App Lifecycle Methods

type App struct {
    Host            *hosthttp.Host   `host:""`
    Config          *Config          `config:""`
    ServiceProvider *ServiceProvider `serviceProvider:""`
}

func (app *App) Init() { /* Basic initialization */ }
func (app *App) OnInit() { /* Service setup */ }
func (app *App) OnInitComplete() { /* Finalization */ }
func (app *App) OnStart(ctx context.Context) { /* Server ready */ }
func (app *App) OnStop(ctx context.Context) { /* Graceful shutdown */ }

Request Handling

type UserRequest struct {
    UserService *service.UserService `service:"UserService"`
}

func (r *UserRequest) Get(w http.ResponseWriter, req *http.Request) {
    userID := req.URL.Query().Get("id")
    user, err := r.UserService.GetUser(userID)
    if err != nil {
        response.JSON.Failure(w, err, http.StatusNotFound)
        return
    }
    response.JSON.Success(w, user)
}

Performance Analysis & Stress Testing

This project includes comprehensive performance analysis tools combining stress testing with profiling capabilities.

Integrated Performance Analysis

# Comprehensive stress test with pprof profiling (Recommended)
./stress_test.pl --pprof --hours 1 --verbose --stats-interval 5

# Extended analysis with detailed profiling
./stress_test.pl --pprof --hours 6 --pprof-interval 300

# CPU and memory focused profiling
./stress_test.pl --pprof --profile-cpu --profile-memory --hours 2

Traditional Stress Testing

# Default 3-hour stress test
./stress_test.pl

# Custom duration and concurrency
./stress_test.pl --hours 1 --concurrency 50 --verbose

# Test specific example
./stress_test.pl --server-dir _examples/basic/json-api --verbose

Recommended Test Server: The script automatically uses _examples/basic/tracing-example as the test target, which includes comprehensive endpoints for both functional and performance testing:

• /hello - Basic greeting endpoint
• /api/users - User management API (supports ?stress=memory|cpu)
• /api/orders - Order processing API
• /error?type=400|404|500|timeout - HTTP error scenario testing
• /health - Health check endpoint
• /profile/stats - Runtime statistics and pprof endpoints
• /memory?size=1024 - Memory allocation testing

Key Features

• Automatic Server Management: Auto-start and stop test targets
• Multi-threaded Concurrency: Configurable concurrent thread count
• Performance Profiling: Automated pprof data collection (heap, CPU, goroutine, block)
• Jaeger Integration: Automatic distributed tracing analysis
• Multi-format Reports: Generate Markdown, JSON, CSV detailed reports with pprof analysis
• Real-time Monitoring: Performance metrics output every 5-10 seconds
• Stress Test Endpoints: Memory and CPU stress testing capabilities

System Requirements

# Install Perl dependencies
cpan HTTP::Tiny JSON::PP Time::HiRes List::Util threads threads::shared

Test Reports

All reports are saved in stress_reports/ directory, including:

• stress_report_TIMESTAMP.md - Comprehensive stress test report
• stress_report_TIMESTAMP.json - Detailed JSON data
• stress_timeline_TIMESTAMP.csv - CSV timeline data
• stress_errors_TIMESTAMP.log - Error logs
• pprof_analysis_TIMESTAMP.md - Performance profiling analysis (when --pprof enabled)
• pprof_TIMESTAMP/ - Directory containing profile data files
• jaeger_analysis.json - Jaeger trace analysis (if available)

Performance Analysis Commands

When pprof is enabled, the reports include ready-to-use analysis commands:

# Memory analysis
go tool pprof -http=:8081 pprof_*/heap_001.pprof

# CPU profiling
go tool pprof -top pprof_*/cpu_001.pprof

# Goroutine analysis
go tool pprof -http=:8083 pprof_*/goroutine_001.pprof

# Blocking operations
go tool pprof -top pprof_*/block_001.pprof

Command Line Arguments

Parameter	Default	Description
--hours	3	Test execution time (hours)
--concurrency	25	Number of concurrent threads
--url	http://localhost:8080	Target server URL
--server-dir	Auto-detect	Server program directory
--stats-interval	10	Statistics output interval (seconds)
--output-dir	./stress_reports	Report output directory
--no-auto-server	-	Disable automatic server management
--no-jaeger	-	Disable Jaeger integration
--jaeger-url	http://127.0.0.1:16686	Jaeger service URL
--verbose	-	Enable verbose output
--pprof	-	Enable pprof profiling integration
--no-pprof	-	Disable pprof profiling
--pprof-port	6060	pprof server port
--pprof-interval	300	Profile capture interval (seconds)
--profile-cpu	-	Enable CPU profiling
--profile-memory	-	Enable memory profiling
--profile-goroutine	-	Enable goroutine profiling

Troubleshooting

Server startup failure

# Check Go environment
go version

# Manual test example
cd _examples/basic/hello-world && go run .

Missing Perl modules

# Check module installation
perl -MHTTP::Tiny -e "print 'OK'"
perl -MJSON::PP -e "print 'OK'"

Environment Variables

Variable	Description	Default
HTTP_LISTEN_ADDRESS	Server listen address	:8080
ENABLE_COMPRESS	Enable HTTP compression	false
SERVER_NAME	Server identification	host-http-app

Contributing

1. Fork the repository
2. Create feature branch
3. Add tests for new functionality
4. Run go test ./... and golangci-lint run
5. Submit pull request

License

MIT License - see LICENSE file for details.