Loading documentation...

Performance Tuning

This guide covers performance optimization techniques for Helix applications.

Built-in Performance Features

Helix is designed for high performance out of the box:

Zero Allocations in Hot Paths

Helix uses sync.Pool for frequently created objects:

Path Parameters: Reused for each request
Ctx Instances: Pooled and reset between requests
JSON Encoding Buffers: Pooled for response encoding

Radix Tree Router

The router uses a radix tree (compressed trie) for O(k) route matching where k is the path length:

Root
├── users (static)
│   ├── / (GET handler)
│   └── {id} (param)
│       └── / (GET handler)
└── posts (static)
    └── {id} (param)

Pre-compiled Middleware Chain

Call Build() after registering all routes to pre-compile the middleware chain:

s := helix.New(nil)

// Register routes and middleware
s.Use(middleware.RequestID())
s.Use(middleware.Logger(middleware.LogFormatJSON))
s.Use(middleware.Recover())

s.GET("/users", helix.HandleCtx(listUsers))
s.POST("/users", helix.HandleCtx(createUser))

// Pre-compile for production
s.Build()

s.Start(":8080")

Optimization Techniques

Use HandleCtx for Most Handlers

HandleCtx is optimized for common use cases with minimal overhead:

s.GET("/users/{id}", helix.HandleCtx(func(c *helix.Ctx) error {
    id := c.Param("id")
    return c.OK(user)
}))

Avoid Unnecessary Allocations

Use Typed Parameters

// ✅ Better - uses typed accessor
id, err := c.ParamInt("id")

// ❌ Worse - parses twice
idStr := c.Param("id")
id, _ := strconv.Atoi(idStr)

Reuse Slices for Query Parameters

// QuerySlice returns existing slice when possible
tags := c.QuerySlice("tags")

Binding Cache

Struct reflection information is cached automatically:

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

// First call: reflects and caches struct info
// Subsequent calls: uses cached info
req, err := helix.Bind[CreateUserRequest](r)

Skip Unnecessary Middleware

Use Skip functions to bypass middleware for specific routes:

s.Use(middleware.LoggerWithConfig(middleware.LoggerConfig{
    Format: middleware.LogFormatJSON,
    Skip: func(r *http.Request) bool {
        // Don't log health checks
        return r.URL.Path == "/health"
    },
}))

Server Configuration

Tune Timeouts

Configure appropriate timeouts for your use case:

s := helix.New(&helix.Options{
    ReadTimeout:  30 * time.Second,  // Max time to read request
    WriteTimeout: 30 * time.Second,  // Max time to write response
    IdleTimeout:  120 * time.Second, // Keep-alive timeout
    GracePeriod:  30 * time.Second,  // Shutdown grace period
})

Connection Limits

For high-traffic scenarios, consider connection limits at the load balancer level rather than in the application.

Middleware Performance

Compression Trade-offs

Compression reduces bandwidth but increases CPU usage:

// Enable compression for large responses
s.Use(middleware.CompressWithConfig(middleware.CompressConfig{
    Level: gzip.DefaultCompression,
    MinSize: 1024, // Only compress responses > 1KB
}))

Rate Limiting

Token bucket rate limiting is efficient but adds overhead:

// Only enable where needed
api := s.Group("/api")
api.Use(middleware.RateLimit(100, 10))  // 100 req/sec, burst 10

Benchmarking

Use Go's Built-in Benchmarks

func BenchmarkListUsers(b *testing.B) {
    s := helix.New(nil)
    s.GET("/users", helix.HandleCtx(listUsers))
    
    req := httptest.NewRequest(http.MethodGet, "/users", nil)
    
    b.ResetTimer()
    b.ReportAllocs()
    
    for i := 0; i < b.N; i++ {
        rec := httptest.NewRecorder()
        s.ServeHTTP(rec, req)
    }
}

Run benchmarks with:

go test -bench=. -benchmem -benchtime=5s

Sample Output

BenchmarkListUsers-8    500000    2450 ns/op    256 B/op    4 allocs/op

Compare Before/After

# Before changes
go test -bench=. -benchmem > before.txt

# After changes
go test -bench=. -benchmem > after.txt

# Compare
benchstat before.txt after.txt

Profiling

CPU Profiling

Use the profiling middleware (requires build tag):

//go:build profiling

s.Use(middleware.Profiling("/debug/pprof"))

Or use net/http/pprof directly:

import _ "net/http/pprof"

// Profiles available at /debug/pprof/

Memory Profiling

# Collect heap profile
curl http://localhost:8080/debug/pprof/heap > heap.prof

# Analyze
go tool pprof heap.prof

Tracing

# Collect trace
curl http://localhost:8080/debug/pprof/trace?seconds=5 > trace.out

# View trace
go tool trace trace.out

Common Performance Issues

Issue: High Memory Usage

Cause: Unbounded request body reading

Solution: Limit body size

s.Use(middleware.BodyLimit(1024 * 1024))  // 1MB limit

Issue: Slow Route Matching

Cause: Too many routes with overlapping patterns

Solution: Organize routes with groups

// Better organization
api := s.Group("/api/v1")
api.Mount("/users", &UserModule{})
api.Mount("/posts", &PostModule{})

Issue: Memory Leaks

Cause: Not closing response bodies in HTTP clients

Solution: Always close response bodies

resp, err := http.Get(url)
if err != nil {
    return err
}
defer resp.Body.Close()

Issue: Goroutine Leaks

Cause: Context not respected in background operations

Solution: Always check context cancellation

select {
case <-ctx.Done():
    return ctx.Err()
case result := <-resultChan:
    return result, nil
}

Production Checklist

Call s.Build() before starting the server
Configure appropriate timeouts
Enable compression for text responses
Add rate limiting to public endpoints
Use JSON logging format
Skip logging for health check endpoints
Profile under realistic load before deployment
Monitor memory usage and goroutine counts

Resources

This documentation should be updated by package maintainers to reflect the actual architecture and design patterns used.

Loading documentation...

Performance Tuning

This guide covers performance optimization techniques for Helix applications.

Built-in Performance Features

Helix is designed for high performance out of the box:

Zero Allocations in Hot Paths

Helix uses sync.Pool for frequently created objects:

Path Parameters: Reused for each request
Ctx Instances: Pooled and reset between requests
JSON Encoding Buffers: Pooled for response encoding

Radix Tree Router

The router uses a radix tree (compressed trie) for O(k) route matching where k is the path length:

Root
├── users (static)
│   ├── / (GET handler)
│   └── {id} (param)
│       └── / (GET handler)
└── posts (static)
    └── {id} (param)

Pre-compiled Middleware Chain

Call Build() after registering all routes to pre-compile the middleware chain:

s := helix.New(nil)

// Register routes and middleware
s.Use(middleware.RequestID())
s.Use(middleware.Logger(middleware.LogFormatJSON))
s.Use(middleware.Recover())

s.GET("/users", helix.HandleCtx(listUsers))
s.POST("/users", helix.HandleCtx(createUser))

// Pre-compile for production
s.Build()

s.Start(":8080")

Optimization Techniques

Use HandleCtx for Most Handlers

HandleCtx is optimized for common use cases with minimal overhead:

s.GET("/users/{id}", helix.HandleCtx(func(c *helix.Ctx) error {
    id := c.Param("id")
    return c.OK(user)
}))

Avoid Unnecessary Allocations

Use Typed Parameters

// ✅ Better - uses typed accessor
id, err := c.ParamInt("id")

// ❌ Worse - parses twice
idStr := c.Param("id")
id, _ := strconv.Atoi(idStr)

Reuse Slices for Query Parameters

// QuerySlice returns existing slice when possible
tags := c.QuerySlice("tags")

Binding Cache

Struct reflection information is cached automatically:

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

// First call: reflects and caches struct info
// Subsequent calls: uses cached info
req, err := helix.Bind[CreateUserRequest](r)

Skip Unnecessary Middleware

Use Skip functions to bypass middleware for specific routes:

s.Use(middleware.LoggerWithConfig(middleware.LoggerConfig{
    Format: middleware.LogFormatJSON,
    Skip: func(r *http.Request) bool {
        // Don't log health checks
        return r.URL.Path == "/health"
    },
}))

Server Configuration

Tune Timeouts

Configure appropriate timeouts for your use case:

s := helix.New(&helix.Options{
    ReadTimeout:  30 * time.Second,  // Max time to read request
    WriteTimeout: 30 * time.Second,  // Max time to write response
    IdleTimeout:  120 * time.Second, // Keep-alive timeout
    GracePeriod:  30 * time.Second,  // Shutdown grace period
})

Connection Limits

For high-traffic scenarios, consider connection limits at the load balancer level rather than in the application.

Middleware Performance

Compression Trade-offs

Compression reduces bandwidth but increases CPU usage:

// Enable compression for large responses
s.Use(middleware.CompressWithConfig(middleware.CompressConfig{
    Level: gzip.DefaultCompression,
    MinSize: 1024, // Only compress responses > 1KB
}))

Rate Limiting

Token bucket rate limiting is efficient but adds overhead:

// Only enable where needed
api := s.Group("/api")
api.Use(middleware.RateLimit(100, 10))  // 100 req/sec, burst 10

Benchmarking

Use Go's Built-in Benchmarks

func BenchmarkListUsers(b *testing.B) {
    s := helix.New(nil)
    s.GET("/users", helix.HandleCtx(listUsers))
    
    req := httptest.NewRequest(http.MethodGet, "/users", nil)
    
    b.ResetTimer()
    b.ReportAllocs()
    
    for i := 0; i < b.N; i++ {
        rec := httptest.NewRecorder()
        s.ServeHTTP(rec, req)
    }
}

Run benchmarks with:

go test -bench=. -benchmem -benchtime=5s

Sample Output

BenchmarkListUsers-8    500000    2450 ns/op    256 B/op    4 allocs/op

Compare Before/After

# Before changes
go test -bench=. -benchmem > before.txt

# After changes
go test -bench=. -benchmem > after.txt

# Compare
benchstat before.txt after.txt

Profiling

CPU Profiling

Use the profiling middleware (requires build tag):

//go:build profiling

s.Use(middleware.Profiling("/debug/pprof"))

Or use net/http/pprof directly:

import _ "net/http/pprof"

// Profiles available at /debug/pprof/

Memory Profiling

# Collect heap profile
curl http://localhost:8080/debug/pprof/heap > heap.prof

# Analyze
go tool pprof heap.prof

Tracing

# Collect trace
curl http://localhost:8080/debug/pprof/trace?seconds=5 > trace.out

# View trace
go tool trace trace.out

Common Performance Issues

Issue: High Memory Usage

Cause: Unbounded request body reading

Solution: Limit body size

s.Use(middleware.BodyLimit(1024 * 1024))  // 1MB limit

Issue: Slow Route Matching

Cause: Too many routes with overlapping patterns

Solution: Organize routes with groups

// Better organization
api := s.Group("/api/v1")
api.Mount("/users", &UserModule{})
api.Mount("/posts", &PostModule{})

Issue: Memory Leaks

Cause: Not closing response bodies in HTTP clients

Solution: Always close response bodies

resp, err := http.Get(url)
if err != nil {
    return err
}
defer resp.Body.Close()

Issue: Goroutine Leaks

Cause: Context not respected in background operations

Solution: Always check context cancellation

select {
case <-ctx.Done():
    return ctx.Err()
case result := <-resultChan:
    return result, nil
}

Production Checklist

Call s.Build() before starting the server
Configure appropriate timeouts
Enable compression for text responses
Add rate limiting to public endpoints
Use JSON logging format
Skip logging for health check endpoints
Profile under realistic load before deployment
Monitor memory usage and goroutine counts

Resources

This documentation should be updated by package maintainers to reflect the actual architecture and design patterns used.

Loading documentation...

Performance Tuning

This guide covers performance optimization techniques for Helix applications.

Built-in Performance Features

Helix is designed for high performance out of the box:

Zero Allocations in Hot Paths

Helix uses sync.Pool for frequently created objects:

Path Parameters: Reused for each request
Ctx Instances: Pooled and reset between requests
JSON Encoding Buffers: Pooled for response encoding

Radix Tree Router

The router uses a radix tree (compressed trie) for O(k) route matching where k is the path length:

text

Root
├── users (static)
│   ├── / (GET handler)
│   └── {id} (param)
│       └── / (GET handler)
└── posts (static)
    └── {id} (param)

Root
├── users (static)
│   ├── / (GET handler)
│   └── {id} (param)
│       └── / (GET handler)
└── posts (static)
    └── {id} (param)

Pre-compiled Middleware Chain

Call Build() after registering all routes to pre-compile the middleware chain:

s := helix.New(nil)

// Register routes and middleware
s.Use(middleware.RequestID())
s.Use(middleware.Logger(middleware.LogFormatJSON))
s.Use(middleware.Recover())

s.GET("/users", helix.HandleCtx(listUsers))
s.POST("/users", helix.HandleCtx(createUser))

// Pre-compile for production
s.Build()

s.Start(":8080")

s := helix.New(nil)

// Register routes and middleware
s.Use(middleware.RequestID())
s.Use(middleware.Logger(middleware.LogFormatJSON))
s.Use(middleware.Recover())

s.GET("/users", helix.HandleCtx(listUsers))
s.POST("/users", helix.HandleCtx(createUser))

// Pre-compile for production
s.Build()

s.Start(":8080")

Optimization Techniques

Use HandleCtx for Most Handlers

HandleCtx is optimized for common use cases with minimal overhead:

s.GET("/users/{id}", helix.HandleCtx(func(c *helix.Ctx) error {
    id := c.Param("id")
    return c.OK(user)
}))

s.GET("/users/{id}", helix.HandleCtx(func(c *helix.Ctx) error {
    id := c.Param("id")
    return c.OK(user)
}))

Avoid Unnecessary Allocations

Use Typed Parameters

// ✅ Better - uses typed accessor
id, err := c.ParamInt("id")

// ❌ Worse - parses twice
idStr := c.Param("id")
id, _ := strconv.Atoi(idStr)

// ✅ Better - uses typed accessor
id, err := c.ParamInt("id")

// ❌ Worse - parses twice
idStr := c.Param("id")
id, _ := strconv.Atoi(idStr)

Reuse Slices for Query Parameters

// QuerySlice returns existing slice when possible
tags := c.QuerySlice("tags")

// QuerySlice returns existing slice when possible
tags := c.QuerySlice("tags")

Binding Cache

Struct reflection information is cached automatically:

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

// First call: reflects and caches struct info
// Subsequent calls: uses cached info
req, err := helix.Bind[CreateUserRequest](r)

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

// First call: reflects and caches struct info
// Subsequent calls: uses cached info
req, err := helix.Bind[CreateUserRequest](r)

Skip Unnecessary Middleware

Use Skip functions to bypass middleware for specific routes:

s.Use(middleware.LoggerWithConfig(middleware.LoggerConfig{
    Format: middleware.LogFormatJSON,
    Skip: func(r *http.Request) bool {
        // Don't log health checks
        return r.URL.Path == "/health"
    },
}))

s.Use(middleware.LoggerWithConfig(middleware.LoggerConfig{
    Format: middleware.LogFormatJSON,
    Skip: func(r *http.Request) bool {
        // Don't log health checks
        return r.URL.Path == "/health"
    },
}))

Server Configuration

Tune Timeouts

Configure appropriate timeouts for your use case:

s := helix.New(&helix.Options{
    ReadTimeout:  30 * time.Second,  // Max time to read request
    WriteTimeout: 30 * time.Second,  // Max time to write response
    IdleTimeout:  120 * time.Second, // Keep-alive timeout
    GracePeriod:  30 * time.Second,  // Shutdown grace period
})

s := helix.New(&helix.Options{
    ReadTimeout:  30 * time.Second,  // Max time to read request
    WriteTimeout: 30 * time.Second,  // Max time to write response
    IdleTimeout:  120 * time.Second, // Keep-alive timeout
    GracePeriod:  30 * time.Second,  // Shutdown grace period
})

Connection Limits

For high-traffic scenarios, consider connection limits at the load balancer level rather than in the application.

Middleware Performance

Compression Trade-offs

Compression reduces bandwidth but increases CPU usage:

// Enable compression for large responses
s.Use(middleware.CompressWithConfig(middleware.CompressConfig{
    Level: gzip.DefaultCompression,
    MinSize: 1024, // Only compress responses > 1KB
}))

// Enable compression for large responses
s.Use(middleware.CompressWithConfig(middleware.CompressConfig{
    Level: gzip.DefaultCompression,
    MinSize: 1024, // Only compress responses > 1KB
}))

Rate Limiting

Token bucket rate limiting is efficient but adds overhead:

// Only enable where needed
api := s.Group("/api")
api.Use(middleware.RateLimit(100, 10))  // 100 req/sec, burst 10

// Only enable where needed
api := s.Group("/api")
api.Use(middleware.RateLimit(100, 10))  // 100 req/sec, burst 10

Benchmarking

Use Go's Built-in Benchmarks

func BenchmarkListUsers(b *testing.B) {
    s := helix.New(nil)
    s.GET("/users", helix.HandleCtx(listUsers))
    
    req := httptest.NewRequest(http.MethodGet, "/users", nil)
    
    b.ResetTimer()
    b.ReportAllocs()
    
    for i := 0; i < b.N; i++ {
        rec := httptest.NewRecorder()
        s.ServeHTTP(rec, req)
    }
}

func BenchmarkListUsers(b *testing.B) {
    s := helix.New(nil)
    s.GET("/users", helix.HandleCtx(listUsers))
    
    req := httptest.NewRequest(http.MethodGet, "/users", nil)
    
    b.ResetTimer()
    b.ReportAllocs()
    
    for i := 0; i < b.N; i++ {
        rec := httptest.NewRecorder()
        s.ServeHTTP(rec, req)
    }
}

Run benchmarks with:

bash

go test -bench=. -benchmem -benchtime=5s

go test -bench=. -benchmem -benchtime=5s

Sample Output

BenchmarkListUsers-8    500000    2450 ns/op    256 B/op    4 allocs/op

Compare Before/After

bash

# Before changes
go test -bench=. -benchmem > before.txt

# After changes
go test -bench=. -benchmem > after.txt

# Compare
benchstat before.txt after.txt

# Before changes
go test -bench=. -benchmem > before.txt

# After changes
go test -bench=. -benchmem > after.txt

# Compare
benchstat before.txt after.txt

Profiling

CPU Profiling

Use the profiling middleware (requires build tag):

//go:build profiling

s.Use(middleware.Profiling("/debug/pprof"))

//go:build profiling

s.Use(middleware.Profiling("/debug/pprof"))

Or use net/http/pprof directly:

import _ "net/http/pprof"

// Profiles available at /debug/pprof/

import _ "net/http/pprof"

// Profiles available at /debug/pprof/

Memory Profiling

bash

# Collect heap profile
curl http://localhost:8080/debug/pprof/heap > heap.prof

# Analyze
go tool pprof heap.prof

# Collect heap profile
curl http://localhost:8080/debug/pprof/heap > heap.prof

# Analyze
go tool pprof heap.prof

Tracing

bash

# Collect trace
curl http://localhost:8080/debug/pprof/trace?seconds=5 > trace.out

# View trace
go tool trace trace.out

# Collect trace
curl http://localhost:8080/debug/pprof/trace?seconds=5 > trace.out

# View trace
go tool trace trace.out

Common Performance Issues

Issue: High Memory Usage

Cause: Unbounded request body reading

Solution: Limit body size

s.Use(middleware.BodyLimit(1024 * 1024))  // 1MB limit

s.Use(middleware.BodyLimit(1024 * 1024))  // 1MB limit

Issue: Slow Route Matching

Cause: Too many routes with overlapping patterns

Solution: Organize routes with groups

// Better organization
api := s.Group("/api/v1")
api.Mount("/users", &UserModule{})
api.Mount("/posts", &PostModule{})

// Better organization
api := s.Group("/api/v1")
api.Mount("/users", &UserModule{})
api.Mount("/posts", &PostModule{})

Issue: Memory Leaks

Cause: Not closing response bodies in HTTP clients

Solution: Always close response bodies

resp, err := http.Get(url)
if err != nil {
    return err
}
defer resp.Body.Close()

resp, err := http.Get(url)
if err != nil {
    return err
}
defer resp.Body.Close()

Issue: Goroutine Leaks

Cause: Context not respected in background operations

Solution: Always check context cancellation

select {
case <-ctx.Done():
    return ctx.Err()
case result := <-resultChan:
    return result, nil
}

select {
case <-ctx.Done():
    return ctx.Err()
case result := <-resultChan:
    return result, nil
}

Production Checklist

Call s.Build() before starting the server
Configure appropriate timeouts
Enable compression for text responses
Add rate limiting to public endpoints
Use JSON logging format
Skip logging for health check endpoints
Profile under realistic load before deployment
Monitor memory usage and goroutine counts

Resources

This documentation should be updated by package maintainers to reflect the actual architecture and design patterns used.

Performance Tuning

This guide covers performance optimization techniques for Helix applications.

Built-in Performance Features

Helix is designed for high performance out of the box:

Zero Allocations in Hot Paths

Helix uses sync.Pool for frequently created objects:

Path Parameters: Reused for each request
Ctx Instances: Pooled and reset between requests
JSON Encoding Buffers: Pooled for response encoding

Radix Tree Router

The router uses a radix tree (compressed trie) for O(k) route matching where k is the path length:

text

Root
├── users (static)
│   ├── / (GET handler)
│   └── {id} (param)
│       └── / (GET handler)
└── posts (static)
    └── {id} (param)

Root
├── users (static)
│   ├── / (GET handler)
│   └── {id} (param)
│       └── / (GET handler)
└── posts (static)
    └── {id} (param)

Pre-compiled Middleware Chain

Call Build() after registering all routes to pre-compile the middleware chain:

s := helix.New(nil)

// Register routes and middleware
s.Use(middleware.RequestID())
s.Use(middleware.Logger(middleware.LogFormatJSON))
s.Use(middleware.Recover())

s.GET("/users", helix.HandleCtx(listUsers))
s.POST("/users", helix.HandleCtx(createUser))

// Pre-compile for production
s.Build()

s.Start(":8080")

s := helix.New(nil)

// Register routes and middleware
s.Use(middleware.RequestID())
s.Use(middleware.Logger(middleware.LogFormatJSON))
s.Use(middleware.Recover())

s.GET("/users", helix.HandleCtx(listUsers))
s.POST("/users", helix.HandleCtx(createUser))

// Pre-compile for production
s.Build()

s.Start(":8080")

Optimization Techniques

Use HandleCtx for Most Handlers

HandleCtx is optimized for common use cases with minimal overhead:

s.GET("/users/{id}", helix.HandleCtx(func(c *helix.Ctx) error {
    id := c.Param("id")
    return c.OK(user)
}))

s.GET("/users/{id}", helix.HandleCtx(func(c *helix.Ctx) error {
    id := c.Param("id")
    return c.OK(user)
}))

Avoid Unnecessary Allocations

Use Typed Parameters

// ✅ Better - uses typed accessor
id, err := c.ParamInt("id")

// ❌ Worse - parses twice
idStr := c.Param("id")
id, _ := strconv.Atoi(idStr)

// ✅ Better - uses typed accessor
id, err := c.ParamInt("id")

// ❌ Worse - parses twice
idStr := c.Param("id")
id, _ := strconv.Atoi(idStr)

Reuse Slices for Query Parameters

// QuerySlice returns existing slice when possible
tags := c.QuerySlice("tags")

// QuerySlice returns existing slice when possible
tags := c.QuerySlice("tags")

Binding Cache

Struct reflection information is cached automatically:

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

// First call: reflects and caches struct info
// Subsequent calls: uses cached info
req, err := helix.Bind[CreateUserRequest](r)

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

// First call: reflects and caches struct info
// Subsequent calls: uses cached info
req, err := helix.Bind[CreateUserRequest](r)

Skip Unnecessary Middleware

Use Skip functions to bypass middleware for specific routes:

s.Use(middleware.LoggerWithConfig(middleware.LoggerConfig{
    Format: middleware.LogFormatJSON,
    Skip: func(r *http.Request) bool {
        // Don't log health checks
        return r.URL.Path == "/health"
    },
}))

s.Use(middleware.LoggerWithConfig(middleware.LoggerConfig{
    Format: middleware.LogFormatJSON,
    Skip: func(r *http.Request) bool {
        // Don't log health checks
        return r.URL.Path == "/health"
    },
}))

Server Configuration

Tune Timeouts

Configure appropriate timeouts for your use case:

s := helix.New(&helix.Options{
    ReadTimeout:  30 * time.Second,  // Max time to read request
    WriteTimeout: 30 * time.Second,  // Max time to write response
    IdleTimeout:  120 * time.Second, // Keep-alive timeout
    GracePeriod:  30 * time.Second,  // Shutdown grace period
})

s := helix.New(&helix.Options{
    ReadTimeout:  30 * time.Second,  // Max time to read request
    WriteTimeout: 30 * time.Second,  // Max time to write response
    IdleTimeout:  120 * time.Second, // Keep-alive timeout
    GracePeriod:  30 * time.Second,  // Shutdown grace period
})

Connection Limits

For high-traffic scenarios, consider connection limits at the load balancer level rather than in the application.

Middleware Performance

Compression Trade-offs

Compression reduces bandwidth but increases CPU usage:

// Enable compression for large responses
s.Use(middleware.CompressWithConfig(middleware.CompressConfig{
    Level: gzip.DefaultCompression,
    MinSize: 1024, // Only compress responses > 1KB
}))

// Enable compression for large responses
s.Use(middleware.CompressWithConfig(middleware.CompressConfig{
    Level: gzip.DefaultCompression,
    MinSize: 1024, // Only compress responses > 1KB
}))

Rate Limiting

Token bucket rate limiting is efficient but adds overhead:

// Only enable where needed
api := s.Group("/api")
api.Use(middleware.RateLimit(100, 10))  // 100 req/sec, burst 10

// Only enable where needed
api := s.Group("/api")
api.Use(middleware.RateLimit(100, 10))  // 100 req/sec, burst 10

Benchmarking

Use Go's Built-in Benchmarks

func BenchmarkListUsers(b *testing.B) {
    s := helix.New(nil)
    s.GET("/users", helix.HandleCtx(listUsers))
    
    req := httptest.NewRequest(http.MethodGet, "/users", nil)
    
    b.ResetTimer()
    b.ReportAllocs()
    
    for i := 0; i < b.N; i++ {
        rec := httptest.NewRecorder()
        s.ServeHTTP(rec, req)
    }
}

func BenchmarkListUsers(b *testing.B) {
    s := helix.New(nil)
    s.GET("/users", helix.HandleCtx(listUsers))
    
    req := httptest.NewRequest(http.MethodGet, "/users", nil)
    
    b.ResetTimer()
    b.ReportAllocs()
    
    for i := 0; i < b.N; i++ {
        rec := httptest.NewRecorder()
        s.ServeHTTP(rec, req)
    }
}

Run benchmarks with:

bash

go test -bench=. -benchmem -benchtime=5s

go test -bench=. -benchmem -benchtime=5s

Sample Output

BenchmarkListUsers-8    500000    2450 ns/op    256 B/op    4 allocs/op

Compare Before/After

bash

# Before changes
go test -bench=. -benchmem > before.txt

# After changes
go test -bench=. -benchmem > after.txt

# Compare
benchstat before.txt after.txt

# Before changes
go test -bench=. -benchmem > before.txt

# After changes
go test -bench=. -benchmem > after.txt

# Compare
benchstat before.txt after.txt

Profiling

CPU Profiling

Use the profiling middleware (requires build tag):

//go:build profiling

s.Use(middleware.Profiling("/debug/pprof"))

//go:build profiling

s.Use(middleware.Profiling("/debug/pprof"))

Or use net/http/pprof directly:

import _ "net/http/pprof"

// Profiles available at /debug/pprof/

import _ "net/http/pprof"

// Profiles available at /debug/pprof/

Memory Profiling

bash

# Collect heap profile
curl http://localhost:8080/debug/pprof/heap > heap.prof

# Analyze
go tool pprof heap.prof

# Collect heap profile
curl http://localhost:8080/debug/pprof/heap > heap.prof

# Analyze
go tool pprof heap.prof

Tracing

bash

# Collect trace
curl http://localhost:8080/debug/pprof/trace?seconds=5 > trace.out

# View trace
go tool trace trace.out

# Collect trace
curl http://localhost:8080/debug/pprof/trace?seconds=5 > trace.out

# View trace
go tool trace trace.out

Common Performance Issues

Issue: High Memory Usage

Cause: Unbounded request body reading

Solution: Limit body size

s.Use(middleware.BodyLimit(1024 * 1024))  // 1MB limit

s.Use(middleware.BodyLimit(1024 * 1024))  // 1MB limit

Issue: Slow Route Matching

Cause: Too many routes with overlapping patterns

Solution: Organize routes with groups

// Better organization
api := s.Group("/api/v1")
api.Mount("/users", &UserModule{})
api.Mount("/posts", &PostModule{})

// Better organization
api := s.Group("/api/v1")
api.Mount("/users", &UserModule{})
api.Mount("/posts", &PostModule{})

Issue: Memory Leaks

Cause: Not closing response bodies in HTTP clients

Solution: Always close response bodies

resp, err := http.Get(url)
if err != nil {
    return err
}
defer resp.Body.Close()

resp, err := http.Get(url)
if err != nil {
    return err
}
defer resp.Body.Close()

Issue: Goroutine Leaks

Cause: Context not respected in background operations

Solution: Always check context cancellation

select {
case <-ctx.Done():
    return ctx.Err()
case result := <-resultChan:
    return result, nil
}

select {
case <-ctx.Done():
    return ctx.Err()
case result := <-resultChan:
    return result, nil
}

Production Checklist

Call s.Build() before starting the server
Configure appropriate timeouts
Enable compression for text responses
Add rate limiting to public endpoints
Use JSON logging format
Skip logging for health check endpoints
Profile under realistic load before deployment
Monitor memory usage and goroutine counts

Resources

This documentation should be updated by package maintainers to reflect the actual architecture and design patterns used.