Loading documentation...

Helix Framework Overview

Note: This is a developer-maintained documentation page. The content here is not auto-generated and should be updated manually to explain the core concepts and architecture of the Helix package.

About This Package

Import Path: github.com/kolosys/helix

Package helix provides a zero-dependency, context-aware, high-performance HTTP web framework for Go with stdlib compatibility.

Architecture Overview

Helix is built on Go's standard library (net/http) and provides a thin, high-performance layer on top. The architecture follows these principles:

Zero Dependencies: Built entirely on Go's standard library
Performance First: Zero-allocation hot paths using sync.Pool
Type Safety: Generic handlers with compile-time type checking
Developer Experience: Fluent APIs and sensible defaults
Standards Compliant: RFC 7807 Problem Details, stdlib compatibility

Core Components

Server: Main HTTP server with middleware support
Router: Radix tree-based route matching
Ctx: Unified context wrapper for handlers
Binding: Type-safe request data binding
Problem: RFC 7807 error responses
Middleware: Request/response processing pipeline

Data Flow

HTTP Request
    ↓
Middleware Chain (RequestID, Logger, etc.)
    ↓
Router (matches route, extracts parameters)
    ↓
Handler (Ctx handler, typed handler, or http.HandlerFunc)
    ↓
Response (JSON, Problem, etc.)
    ↓
Middleware Chain (response processing)
    ↓
HTTP Response

Design Patterns

Functional Options: Configuration via option functions
Middleware Chain: Composable request/response processing
Dependency Injection: Type-safe service registry
Module Pattern: Organize routes into modules
Resource Pattern: REST resource builder

Core Concepts

Server Creation

Helix provides two ways to create a server:

// Basic server (no middleware)
s := helix.New()

// Default server (includes RequestID, Logger, Recover)
s := helix.Default()

Handler Types

Helix supports three handler styles:

#1. Standard Handler: Works with any http.HandlerFunc

s.GET("/", func(w http.ResponseWriter, r *http.Request) {
    helix.OK(w, data)
})

#2. Ctx Handler: Uses Ctx for fluent API

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

#3. Typed Handler: Generic handlers with automatic binding

s.POST("/users", helix.Handle(func(ctx context.Context, req CreateRequest) (User, error) {
    return userService.Create(ctx, req)
}))

Request Binding

Bind request data using struct tags:

type CreateUserRequest struct {
    ID    int    `path:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
    Page  int    `query:"page"`
}

req, err := helix.Bind[CreateUserRequest](r)

Error Handling

Errors are automatically converted to RFC 7807 Problem responses:

s.GET("/users/{id}", helix.HandleCtx(func(c *helix.Ctx) error {
    user, err := userService.Get(c.Context(), c.Param("id"))
    if err != nil {
        return helix.NotFoundf("user not found")
    }
    return c.OK(user)
}))

Routing

Routes support path parameters, groups, modules, and resources:

// Path parameters
s.GET("/users/{id}", handler)

// Groups
api := s.Group("/api/v1")
api.GET("/users", handler)

// Modules
s.Mount("/users", &UserModule{})

// Resources
s.Resource("/users").CRUD(list, create, get, update, delete)

Design Decisions

Zero Dependencies

Helix has zero external dependencies because:

Reliability: Fewer dependencies = fewer breaking changes
Performance: No dependency overhead
Compatibility: Works with any Go version that supports stdlib
Simplicity: Easier to understand and maintain

Performance Considerations

Object Pooling: Ctx and path parameters use sync.Pool
Radix Tree: O(k) route matching where k is path length
Pre-compilation: Middleware chain compiled before serving
Zero Allocations: Hot paths avoid allocations

API Design Choices

Functional Options: Type-safe, extensible configuration
Generic Handlers: Compile-time type checking
Fluent API: Chainable methods for readability
Error Returns: Explicit error handling

Backward Compatibility

Helix prioritizes:

stdlib Compatibility: Works with any http.Handler middleware
API Stability: Breaking changes are avoided when possible
Migration Path: Easy to migrate from other frameworks

Usage Patterns

Basic Server

package main

import (
    "github.com/kolosys/helix"
)

func main() {
    s := helix.Default()

    s.GET("/", func(w http.ResponseWriter, r *http.Request) {
        helix.OK(w, map[string]string{"message": "Hello, World!"})
    })

    s.Start(":8080")
}

RESTful API

s := helix.Default()

api := s.Group("/api/v1")

// Users resource
api.Resource("/users").CRUD(
    listUsers,
    createUser,
    getUser,
    updateUser,
    deleteUser,
)

Modular Architecture

// users/module.go
type UserModule struct {
    service *UserService
}

func (m *UserModule) Register(r helix.RouteRegistrar) {
    r.GET("/", m.list)
    r.POST("/", m.create)
    r.GET("/{id}", m.get)
}

// main.go
s.Mount("/api/v1/users", &UserModule{service: userService})

Production Server

s := helix.New(
    helix.WithAddr(":8080"),
    helix.WithReadTimeout(30 * time.Second),
    helix.WithWriteTimeout(30 * time.Second),
    helix.WithGracePeriod(30 * time.Second),
)

// Production middleware
for _, mw := range middleware.Production() {
    s.Use(mw)
}

s.OnStart(func(s *helix.Server) {
    // Initialize services
})

s.OnStop(func(ctx context.Context, s *helix.Server) {
    // Cleanup
})

s.Start()

Common Pitfalls

Pitfall 1: Not Returning Errors

Problem: Handlers must return errors for proper response handling.

Solution: Always return errors (or nil):

// ❌ Wrong
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    c.OK(users)  // Missing return
}))

// ✅ Correct
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    return c.OK(users)
}))

Pitfall 2: Reading Body Multiple Times

Problem: HTTP request bodies can only be read once.

Solution: Let binding handle the body:

// ❌ Wrong
body, _ := io.ReadAll(r.Body)
var req CreateRequest
helix.BindJSON[CreateRequest](r)  // Fails

// ✅ Correct
var req CreateRequest
helix.BindJSON[CreateRequest](r)  // Reads body automatically

Pitfall 3: Route Order

Problem: More specific routes must be registered before catch-all routes.

Solution: Register specific routes first:

// ❌ Wrong
s.GET("/files/{path...}", catchAll)
s.GET("/files/users", users)  // Never matches

// ✅ Correct
s.GET("/files/users", users)
s.GET("/files/{path...}", catchAll)

Integration Guide

With Standard Library

Helix is fully compatible with net/http:

// Use stdlib middleware
s.Use(func(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Your middleware
        next.ServeHTTP(w, r)
    })
})

// Use stdlib handlers
s.Handle("/legacy", legacyHandler)

With Other Frameworks

Helix can be integrated with other frameworks:

// Mount Helix server as sub-router
mux := http.NewServeMux()
helixServer := helix.Default()
mux.Handle("/api/", helixServer)

With Database Libraries

Helix works with any database library:

// Using sql.DB
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    rows, err := db.QueryContext(c.Context(), "SELECT...")
    // ...
}))

// Using gorm
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    var users []User
    db.WithContext(c.Context()).Find(&users)
    return c.OK(users)
}))

Helix Framework Overview

Note: This is a developer-maintained documentation page. The content here is not auto-generated and should be updated manually to explain the core concepts and architecture of the Helix package.

About This Package

Import Path: github.com/kolosys/helix

Package helix provides a zero-dependency, context-aware, high-performance HTTP web framework for Go with stdlib compatibility.

Architecture Overview

Helix is built on Go's standard library (net/http) and provides a thin, high-performance layer on top. The architecture follows these principles:

Zero Dependencies: Built entirely on Go's standard library
Performance First: Zero-allocation hot paths using sync.Pool
Type Safety: Generic handlers with compile-time type checking
Developer Experience: Fluent APIs and sensible defaults
Standards Compliant: RFC 7807 Problem Details, stdlib compatibility

Core Components

Server: Main HTTP server with middleware support
Router: Radix tree-based route matching
Ctx: Unified context wrapper for handlers
Binding: Type-safe request data binding
Problem: RFC 7807 error responses
Middleware: Request/response processing pipeline

Data Flow

HTTP Request
    ↓
Middleware Chain (RequestID, Logger, etc.)
    ↓
Router (matches route, extracts parameters)
    ↓
Handler (Ctx handler, typed handler, or http.HandlerFunc)
    ↓
Response (JSON, Problem, etc.)
    ↓
Middleware Chain (response processing)
    ↓
HTTP Response

Design Patterns

Functional Options: Configuration via option functions
Middleware Chain: Composable request/response processing
Dependency Injection: Type-safe service registry
Module Pattern: Organize routes into modules
Resource Pattern: REST resource builder

Core Concepts

Server Creation

Helix provides two ways to create a server:

// Basic server (no middleware)
s := helix.New()

// Default server (includes RequestID, Logger, Recover)
s := helix.Default()

Handler Types

Helix supports three handler styles:

#1. Standard Handler: Works with any http.HandlerFunc

s.GET("/", func(w http.ResponseWriter, r *http.Request) {
    helix.OK(w, data)
})

#2. Ctx Handler: Uses Ctx for fluent API

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

#3. Typed Handler: Generic handlers with automatic binding

s.POST("/users", helix.Handle(func(ctx context.Context, req CreateRequest) (User, error) {
    return userService.Create(ctx, req)
}))

Request Binding

Bind request data using struct tags:

type CreateUserRequest struct {
    ID    int    `path:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
    Page  int    `query:"page"`
}

req, err := helix.Bind[CreateUserRequest](r)

Error Handling

Errors are automatically converted to RFC 7807 Problem responses:

s.GET("/users/{id}", helix.HandleCtx(func(c *helix.Ctx) error {
    user, err := userService.Get(c.Context(), c.Param("id"))
    if err != nil {
        return helix.NotFoundf("user not found")
    }
    return c.OK(user)
}))

Routing

Routes support path parameters, groups, modules, and resources:

// Path parameters
s.GET("/users/{id}", handler)

// Groups
api := s.Group("/api/v1")
api.GET("/users", handler)

// Modules
s.Mount("/users", &UserModule{})

// Resources
s.Resource("/users").CRUD(list, create, get, update, delete)

Design Decisions

Zero Dependencies

Helix has zero external dependencies because:

Reliability: Fewer dependencies = fewer breaking changes
Performance: No dependency overhead
Compatibility: Works with any Go version that supports stdlib
Simplicity: Easier to understand and maintain

Performance Considerations

Object Pooling: Ctx and path parameters use sync.Pool
Radix Tree: O(k) route matching where k is path length
Pre-compilation: Middleware chain compiled before serving
Zero Allocations: Hot paths avoid allocations

API Design Choices

Functional Options: Type-safe, extensible configuration
Generic Handlers: Compile-time type checking
Fluent API: Chainable methods for readability
Error Returns: Explicit error handling

Backward Compatibility

Helix prioritizes:

stdlib Compatibility: Works with any http.Handler middleware
API Stability: Breaking changes are avoided when possible
Migration Path: Easy to migrate from other frameworks

Usage Patterns

Basic Server

package main

import (
    "github.com/kolosys/helix"
)

func main() {
    s := helix.Default()

    s.GET("/", func(w http.ResponseWriter, r *http.Request) {
        helix.OK(w, map[string]string{"message": "Hello, World!"})
    })

    s.Start(":8080")
}

RESTful API

s := helix.Default()

api := s.Group("/api/v1")

// Users resource
api.Resource("/users").CRUD(
    listUsers,
    createUser,
    getUser,
    updateUser,
    deleteUser,
)

Modular Architecture

// users/module.go
type UserModule struct {
    service *UserService
}

func (m *UserModule) Register(r helix.RouteRegistrar) {
    r.GET("/", m.list)
    r.POST("/", m.create)
    r.GET("/{id}", m.get)
}

// main.go
s.Mount("/api/v1/users", &UserModule{service: userService})

Production Server

s := helix.New(
    helix.WithAddr(":8080"),
    helix.WithReadTimeout(30 * time.Second),
    helix.WithWriteTimeout(30 * time.Second),
    helix.WithGracePeriod(30 * time.Second),
)

// Production middleware
for _, mw := range middleware.Production() {
    s.Use(mw)
}

s.OnStart(func(s *helix.Server) {
    // Initialize services
})

s.OnStop(func(ctx context.Context, s *helix.Server) {
    // Cleanup
})

s.Start()

Common Pitfalls

Pitfall 1: Not Returning Errors

Problem: Handlers must return errors for proper response handling.

Solution: Always return errors (or nil):

// ❌ Wrong
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    c.OK(users)  // Missing return
}))

// ✅ Correct
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    return c.OK(users)
}))

Pitfall 2: Reading Body Multiple Times

Problem: HTTP request bodies can only be read once.

Solution: Let binding handle the body:

// ❌ Wrong
body, _ := io.ReadAll(r.Body)
var req CreateRequest
helix.BindJSON[CreateRequest](r)  // Fails

// ✅ Correct
var req CreateRequest
helix.BindJSON[CreateRequest](r)  // Reads body automatically

Pitfall 3: Route Order

Problem: More specific routes must be registered before catch-all routes.

Solution: Register specific routes first:

// ❌ Wrong
s.GET("/files/{path...}", catchAll)
s.GET("/files/users", users)  // Never matches

// ✅ Correct
s.GET("/files/users", users)
s.GET("/files/{path...}", catchAll)

Integration Guide

With Standard Library

Helix is fully compatible with net/http:

// Use stdlib middleware
s.Use(func(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Your middleware
        next.ServeHTTP(w, r)
    })
})

// Use stdlib handlers
s.Handle("/legacy", legacyHandler)

With Other Frameworks

Helix can be integrated with other frameworks:

// Mount Helix server as sub-router
mux := http.NewServeMux()
helixServer := helix.Default()
mux.Handle("/api/", helixServer)

With Database Libraries

Helix works with any database library:

// Using sql.DB
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    rows, err := db.QueryContext(c.Context(), "SELECT...")
    // ...
}))

// Using gorm
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    var users []User
    db.WithContext(c.Context()).Find(&users)
    return c.OK(users)
}))

Helix Framework Overview

Note: This is a developer-maintained documentation page. The content here is not auto-generated and should be updated manually to explain the core concepts and architecture of the Helix package.

About This Package

Import Path: github.com/kolosys/helix

Package helix provides a zero-dependency, context-aware, high-performance HTTP web framework for Go with stdlib compatibility.

Architecture Overview

Helix is built on Go's standard library (net/http) and provides a thin, high-performance layer on top. The architecture follows these principles:

Zero Dependencies: Built entirely on Go's standard library
Performance First: Zero-allocation hot paths using sync.Pool
Type Safety: Generic handlers with compile-time type checking
Developer Experience: Fluent APIs and sensible defaults
Standards Compliant: RFC 7807 Problem Details, stdlib compatibility

Core Components

Server: Main HTTP server with middleware support
Router: Radix tree-based route matching
Ctx: Unified context wrapper for handlers
Binding: Type-safe request data binding
Problem: RFC 7807 error responses
Middleware: Request/response processing pipeline

Data Flow

text

HTTP Request
    ↓
Middleware Chain (RequestID, Logger, etc.)
    ↓
Router (matches route, extracts parameters)
    ↓
Handler (Ctx handler, typed handler, or http.HandlerFunc)
    ↓
Response (JSON, Problem, etc.)
    ↓
Middleware Chain (response processing)
    ↓
HTTP Response

HTTP Request
    ↓
Middleware Chain (RequestID, Logger, etc.)
    ↓
Router (matches route, extracts parameters)
    ↓
Handler (Ctx handler, typed handler, or http.HandlerFunc)
    ↓
Response (JSON, Problem, etc.)
    ↓
Middleware Chain (response processing)
    ↓
HTTP Response

Design Patterns

Functional Options: Configuration via option functions
Middleware Chain: Composable request/response processing
Dependency Injection: Type-safe service registry
Module Pattern: Organize routes into modules
Resource Pattern: REST resource builder

Core Concepts

Server Creation

Helix provides two ways to create a server:

// Basic server (no middleware)
s := helix.New()

// Default server (includes RequestID, Logger, Recover)
s := helix.Default()

// Basic server (no middleware)
s := helix.New()

// Default server (includes RequestID, Logger, Recover)
s := helix.Default()

Handler Types

Helix supports three handler styles:

#1. Standard Handler: Works with any http.HandlerFunc

s.GET("/", func(w http.ResponseWriter, r *http.Request) {
    helix.OK(w, data)
})

s.GET("/", func(w http.ResponseWriter, r *http.Request) {
    helix.OK(w, data)
})

#2. Ctx Handler: Uses Ctx for fluent API

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

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

#3. Typed Handler: Generic handlers with automatic binding

s.POST("/users", helix.Handle(func(ctx context.Context, req CreateRequest) (User, error) {
    return userService.Create(ctx, req)
}))

s.POST("/users", helix.Handle(func(ctx context.Context, req CreateRequest) (User, error) {
    return userService.Create(ctx, req)
}))

Request Binding

Bind request data using struct tags:

type CreateUserRequest struct {
    ID    int    `path:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
    Page  int    `query:"page"`
}

req, err := helix.Bind[CreateUserRequest](r)

type CreateUserRequest struct {
    ID    int    `path:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
    Page  int    `query:"page"`
}

req, err := helix.Bind[CreateUserRequest](r)

Error Handling

Errors are automatically converted to RFC 7807 Problem responses:

s.GET("/users/{id}", helix.HandleCtx(func(c *helix.Ctx) error {
    user, err := userService.Get(c.Context(), c.Param("id"))
    if err != nil {
        return helix.NotFoundf("user not found")
    }
    return c.OK(user)
}))

s.GET("/users/{id}", helix.HandleCtx(func(c *helix.Ctx) error {
    user, err := userService.Get(c.Context(), c.Param("id"))
    if err != nil {
        return helix.NotFoundf("user not found")
    }
    return c.OK(user)
}))

Routing

Routes support path parameters, groups, modules, and resources:

// Path parameters
s.GET("/users/{id}", handler)

// Groups
api := s.Group("/api/v1")
api.GET("/users", handler)

// Modules
s.Mount("/users", &UserModule{})

// Resources
s.Resource("/users").CRUD(list, create, get, update, delete)

// Path parameters
s.GET("/users/{id}", handler)

// Groups
api := s.Group("/api/v1")
api.GET("/users", handler)

// Modules
s.Mount("/users", &UserModule{})

// Resources
s.Resource("/users").CRUD(list, create, get, update, delete)

Design Decisions

Zero Dependencies

Helix has zero external dependencies because:

Reliability: Fewer dependencies = fewer breaking changes
Performance: No dependency overhead
Compatibility: Works with any Go version that supports stdlib
Simplicity: Easier to understand and maintain

Performance Considerations

Object Pooling: Ctx and path parameters use sync.Pool
Radix Tree: O(k) route matching where k is path length
Pre-compilation: Middleware chain compiled before serving
Zero Allocations: Hot paths avoid allocations

API Design Choices

Functional Options: Type-safe, extensible configuration
Generic Handlers: Compile-time type checking
Fluent API: Chainable methods for readability
Error Returns: Explicit error handling

Backward Compatibility

Helix prioritizes:

stdlib Compatibility: Works with any http.Handler middleware
API Stability: Breaking changes are avoided when possible
Migration Path: Easy to migrate from other frameworks

Usage Patterns

Basic Server

package main

import (
    "github.com/kolosys/helix"
)

func main() {
    s := helix.Default()

    s.GET("/", func(w http.ResponseWriter, r *http.Request) {
        helix.OK(w, map[string]string{"message": "Hello, World!"})
    })

    s.Start(":8080")
}

package main

import (
    "github.com/kolosys/helix"
)

func main() {
    s := helix.Default()

    s.GET("/", func(w http.ResponseWriter, r *http.Request) {
        helix.OK(w, map[string]string{"message": "Hello, World!"})
    })

    s.Start(":8080")
}

RESTful API

s := helix.Default()

api := s.Group("/api/v1")

// Users resource
api.Resource("/users").CRUD(
    listUsers,
    createUser,
    getUser,
    updateUser,
    deleteUser,
)

s := helix.Default()

api := s.Group("/api/v1")

// Users resource
api.Resource("/users").CRUD(
    listUsers,
    createUser,
    getUser,
    updateUser,
    deleteUser,
)

Modular Architecture

// users/module.go
type UserModule struct {
    service *UserService
}

func (m *UserModule) Register(r helix.RouteRegistrar) {
    r.GET("/", m.list)
    r.POST("/", m.create)
    r.GET("/{id}", m.get)
}

// main.go
s.Mount("/api/v1/users", &UserModule{service: userService})

// users/module.go
type UserModule struct {
    service *UserService
}

func (m *UserModule) Register(r helix.RouteRegistrar) {
    r.GET("/", m.list)
    r.POST("/", m.create)
    r.GET("/{id}", m.get)
}

// main.go
s.Mount("/api/v1/users", &UserModule{service: userService})

Production Server

s := helix.New(
    helix.WithAddr(":8080"),
    helix.WithReadTimeout(30 * time.Second),
    helix.WithWriteTimeout(30 * time.Second),
    helix.WithGracePeriod(30 * time.Second),
)

// Production middleware
for _, mw := range middleware.Production() {
    s.Use(mw)
}

s.OnStart(func(s *helix.Server) {
    // Initialize services
})

s.OnStop(func(ctx context.Context, s *helix.Server) {
    // Cleanup
})

s.Start()

s := helix.New(
    helix.WithAddr(":8080"),
    helix.WithReadTimeout(30 * time.Second),
    helix.WithWriteTimeout(30 * time.Second),
    helix.WithGracePeriod(30 * time.Second),
)

// Production middleware
for _, mw := range middleware.Production() {
    s.Use(mw)
}

s.OnStart(func(s *helix.Server) {
    // Initialize services
})

s.OnStop(func(ctx context.Context, s *helix.Server) {
    // Cleanup
})

s.Start()

Common Pitfalls

Pitfall 1: Not Returning Errors

Problem: Handlers must return errors for proper response handling.

Solution: Always return errors (or nil):

// ❌ Wrong
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    c.OK(users)  // Missing return
}))

// ✅ Correct
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    return c.OK(users)
}))

// ❌ Wrong
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    c.OK(users)  // Missing return
}))

// ✅ Correct
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    return c.OK(users)
}))

Pitfall 2: Reading Body Multiple Times

Problem: HTTP request bodies can only be read once.

Solution: Let binding handle the body:

// ❌ Wrong
body, _ := io.ReadAll(r.Body)
var req CreateRequest
helix.BindJSON[CreateRequest](r)  // Fails

// ✅ Correct
var req CreateRequest
helix.BindJSON[CreateRequest](r)  // Reads body automatically

// ❌ Wrong
body, _ := io.ReadAll(r.Body)
var req CreateRequest
helix.BindJSON[CreateRequest](r)  // Fails

// ✅ Correct
var req CreateRequest
helix.BindJSON[CreateRequest](r)  // Reads body automatically

Pitfall 3: Route Order

Problem: More specific routes must be registered before catch-all routes.

Solution: Register specific routes first:

// ❌ Wrong
s.GET("/files/{path...}", catchAll)
s.GET("/files/users", users)  // Never matches

// ✅ Correct
s.GET("/files/users", users)
s.GET("/files/{path...}", catchAll)

// ❌ Wrong
s.GET("/files/{path...}", catchAll)
s.GET("/files/users", users)  // Never matches

// ✅ Correct
s.GET("/files/users", users)
s.GET("/files/{path...}", catchAll)

Integration Guide

With Standard Library

Helix is fully compatible with net/http:

// Use stdlib middleware
s.Use(func(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Your middleware
        next.ServeHTTP(w, r)
    })
})

// Use stdlib handlers
s.Handle("/legacy", legacyHandler)

// Use stdlib middleware
s.Use(func(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Your middleware
        next.ServeHTTP(w, r)
    })
})

// Use stdlib handlers
s.Handle("/legacy", legacyHandler)

With Other Frameworks

Helix can be integrated with other frameworks:

// Mount Helix server as sub-router
mux := http.NewServeMux()
helixServer := helix.Default()
mux.Handle("/api/", helixServer)

// Mount Helix server as sub-router
mux := http.NewServeMux()
helixServer := helix.Default()
mux.Handle("/api/", helixServer)

With Database Libraries

Helix works with any database library:

// Using sql.DB
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    rows, err := db.QueryContext(c.Context(), "SELECT...")
    // ...
}))

// Using gorm
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    var users []User
    db.WithContext(c.Context()).Find(&users)
    return c.OK(users)
}))

// Using sql.DB
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    rows, err := db.QueryContext(c.Context(), "SELECT...")
    // ...
}))

// Using gorm
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    var users []User
    db.WithContext(c.Context()).Find(&users)
    return c.OK(users)
}))

Helix Framework Overview

Note: This is a developer-maintained documentation page. The content here is not auto-generated and should be updated manually to explain the core concepts and architecture of the Helix package.

About This Package

Import Path: github.com/kolosys/helix

Package helix provides a zero-dependency, context-aware, high-performance HTTP web framework for Go with stdlib compatibility.

Architecture Overview

Helix is built on Go's standard library (net/http) and provides a thin, high-performance layer on top. The architecture follows these principles:

Zero Dependencies: Built entirely on Go's standard library
Performance First: Zero-allocation hot paths using sync.Pool
Type Safety: Generic handlers with compile-time type checking
Developer Experience: Fluent APIs and sensible defaults
Standards Compliant: RFC 7807 Problem Details, stdlib compatibility

Core Components

Server: Main HTTP server with middleware support
Router: Radix tree-based route matching
Ctx: Unified context wrapper for handlers
Binding: Type-safe request data binding
Problem: RFC 7807 error responses
Middleware: Request/response processing pipeline

Data Flow

text

HTTP Request
    ↓
Middleware Chain (RequestID, Logger, etc.)
    ↓
Router (matches route, extracts parameters)
    ↓
Handler (Ctx handler, typed handler, or http.HandlerFunc)
    ↓
Response (JSON, Problem, etc.)
    ↓
Middleware Chain (response processing)
    ↓
HTTP Response

HTTP Request
    ↓
Middleware Chain (RequestID, Logger, etc.)
    ↓
Router (matches route, extracts parameters)
    ↓
Handler (Ctx handler, typed handler, or http.HandlerFunc)
    ↓
Response (JSON, Problem, etc.)
    ↓
Middleware Chain (response processing)
    ↓
HTTP Response

Design Patterns

Functional Options: Configuration via option functions
Middleware Chain: Composable request/response processing
Dependency Injection: Type-safe service registry
Module Pattern: Organize routes into modules
Resource Pattern: REST resource builder

Core Concepts

Server Creation

Helix provides two ways to create a server:

// Basic server (no middleware)
s := helix.New()

// Default server (includes RequestID, Logger, Recover)
s := helix.Default()

// Basic server (no middleware)
s := helix.New()

// Default server (includes RequestID, Logger, Recover)
s := helix.Default()

Handler Types

Helix supports three handler styles:

#1. Standard Handler: Works with any http.HandlerFunc

s.GET("/", func(w http.ResponseWriter, r *http.Request) {
    helix.OK(w, data)
})

s.GET("/", func(w http.ResponseWriter, r *http.Request) {
    helix.OK(w, data)
})

#2. Ctx Handler: Uses Ctx for fluent API

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

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

#3. Typed Handler: Generic handlers with automatic binding

s.POST("/users", helix.Handle(func(ctx context.Context, req CreateRequest) (User, error) {
    return userService.Create(ctx, req)
}))

s.POST("/users", helix.Handle(func(ctx context.Context, req CreateRequest) (User, error) {
    return userService.Create(ctx, req)
}))

Request Binding

Bind request data using struct tags:

type CreateUserRequest struct {
    ID    int    `path:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
    Page  int    `query:"page"`
}

req, err := helix.Bind[CreateUserRequest](r)

type CreateUserRequest struct {
    ID    int    `path:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
    Page  int    `query:"page"`
}

req, err := helix.Bind[CreateUserRequest](r)

Error Handling

Errors are automatically converted to RFC 7807 Problem responses:

s.GET("/users/{id}", helix.HandleCtx(func(c *helix.Ctx) error {
    user, err := userService.Get(c.Context(), c.Param("id"))
    if err != nil {
        return helix.NotFoundf("user not found")
    }
    return c.OK(user)
}))

s.GET("/users/{id}", helix.HandleCtx(func(c *helix.Ctx) error {
    user, err := userService.Get(c.Context(), c.Param("id"))
    if err != nil {
        return helix.NotFoundf("user not found")
    }
    return c.OK(user)
}))

Routing

Routes support path parameters, groups, modules, and resources:

// Path parameters
s.GET("/users/{id}", handler)

// Groups
api := s.Group("/api/v1")
api.GET("/users", handler)

// Modules
s.Mount("/users", &UserModule{})

// Resources
s.Resource("/users").CRUD(list, create, get, update, delete)

// Path parameters
s.GET("/users/{id}", handler)

// Groups
api := s.Group("/api/v1")
api.GET("/users", handler)

// Modules
s.Mount("/users", &UserModule{})

// Resources
s.Resource("/users").CRUD(list, create, get, update, delete)

Design Decisions

Zero Dependencies

Helix has zero external dependencies because:

Reliability: Fewer dependencies = fewer breaking changes
Performance: No dependency overhead
Compatibility: Works with any Go version that supports stdlib
Simplicity: Easier to understand and maintain

Performance Considerations

Object Pooling: Ctx and path parameters use sync.Pool
Radix Tree: O(k) route matching where k is path length
Pre-compilation: Middleware chain compiled before serving
Zero Allocations: Hot paths avoid allocations

API Design Choices

Functional Options: Type-safe, extensible configuration
Generic Handlers: Compile-time type checking
Fluent API: Chainable methods for readability
Error Returns: Explicit error handling

Backward Compatibility

Helix prioritizes:

stdlib Compatibility: Works with any http.Handler middleware
API Stability: Breaking changes are avoided when possible
Migration Path: Easy to migrate from other frameworks

Usage Patterns

Basic Server

package main

import (
    "github.com/kolosys/helix"
)

func main() {
    s := helix.Default()

    s.GET("/", func(w http.ResponseWriter, r *http.Request) {
        helix.OK(w, map[string]string{"message": "Hello, World!"})
    })

    s.Start(":8080")
}

package main

import (
    "github.com/kolosys/helix"
)

func main() {
    s := helix.Default()

    s.GET("/", func(w http.ResponseWriter, r *http.Request) {
        helix.OK(w, map[string]string{"message": "Hello, World!"})
    })

    s.Start(":8080")
}

RESTful API

s := helix.Default()

api := s.Group("/api/v1")

// Users resource
api.Resource("/users").CRUD(
    listUsers,
    createUser,
    getUser,
    updateUser,
    deleteUser,
)

s := helix.Default()

api := s.Group("/api/v1")

// Users resource
api.Resource("/users").CRUD(
    listUsers,
    createUser,
    getUser,
    updateUser,
    deleteUser,
)

Modular Architecture

// users/module.go
type UserModule struct {
    service *UserService
}

func (m *UserModule) Register(r helix.RouteRegistrar) {
    r.GET("/", m.list)
    r.POST("/", m.create)
    r.GET("/{id}", m.get)
}

// main.go
s.Mount("/api/v1/users", &UserModule{service: userService})

// users/module.go
type UserModule struct {
    service *UserService
}

func (m *UserModule) Register(r helix.RouteRegistrar) {
    r.GET("/", m.list)
    r.POST("/", m.create)
    r.GET("/{id}", m.get)
}

// main.go
s.Mount("/api/v1/users", &UserModule{service: userService})

Production Server

s := helix.New(
    helix.WithAddr(":8080"),
    helix.WithReadTimeout(30 * time.Second),
    helix.WithWriteTimeout(30 * time.Second),
    helix.WithGracePeriod(30 * time.Second),
)

// Production middleware
for _, mw := range middleware.Production() {
    s.Use(mw)
}

s.OnStart(func(s *helix.Server) {
    // Initialize services
})

s.OnStop(func(ctx context.Context, s *helix.Server) {
    // Cleanup
})

s.Start()

s := helix.New(
    helix.WithAddr(":8080"),
    helix.WithReadTimeout(30 * time.Second),
    helix.WithWriteTimeout(30 * time.Second),
    helix.WithGracePeriod(30 * time.Second),
)

// Production middleware
for _, mw := range middleware.Production() {
    s.Use(mw)
}

s.OnStart(func(s *helix.Server) {
    // Initialize services
})

s.OnStop(func(ctx context.Context, s *helix.Server) {
    // Cleanup
})

s.Start()

Common Pitfalls

Pitfall 1: Not Returning Errors

Problem: Handlers must return errors for proper response handling.

Solution: Always return errors (or nil):

// ❌ Wrong
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    c.OK(users)  // Missing return
}))

// ✅ Correct
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    return c.OK(users)
}))

// ❌ Wrong
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    c.OK(users)  // Missing return
}))

// ✅ Correct
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    return c.OK(users)
}))

Pitfall 2: Reading Body Multiple Times

Problem: HTTP request bodies can only be read once.

Solution: Let binding handle the body:

// ❌ Wrong
body, _ := io.ReadAll(r.Body)
var req CreateRequest
helix.BindJSON[CreateRequest](r)  // Fails

// ✅ Correct
var req CreateRequest
helix.BindJSON[CreateRequest](r)  // Reads body automatically

// ❌ Wrong
body, _ := io.ReadAll(r.Body)
var req CreateRequest
helix.BindJSON[CreateRequest](r)  // Fails

// ✅ Correct
var req CreateRequest
helix.BindJSON[CreateRequest](r)  // Reads body automatically

Pitfall 3: Route Order

Problem: More specific routes must be registered before catch-all routes.

Solution: Register specific routes first:

// ❌ Wrong
s.GET("/files/{path...}", catchAll)
s.GET("/files/users", users)  // Never matches

// ✅ Correct
s.GET("/files/users", users)
s.GET("/files/{path...}", catchAll)

// ❌ Wrong
s.GET("/files/{path...}", catchAll)
s.GET("/files/users", users)  // Never matches

// ✅ Correct
s.GET("/files/users", users)
s.GET("/files/{path...}", catchAll)

Integration Guide

With Standard Library

Helix is fully compatible with net/http:

// Use stdlib middleware
s.Use(func(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Your middleware
        next.ServeHTTP(w, r)
    })
})

// Use stdlib handlers
s.Handle("/legacy", legacyHandler)

// Use stdlib middleware
s.Use(func(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Your middleware
        next.ServeHTTP(w, r)
    })
})

// Use stdlib handlers
s.Handle("/legacy", legacyHandler)

With Other Frameworks

Helix can be integrated with other frameworks:

// Mount Helix server as sub-router
mux := http.NewServeMux()
helixServer := helix.Default()
mux.Handle("/api/", helixServer)

// Mount Helix server as sub-router
mux := http.NewServeMux()
helixServer := helix.Default()
mux.Handle("/api/", helixServer)

With Database Libraries

Helix works with any database library:

// Using sql.DB
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    rows, err := db.QueryContext(c.Context(), "SELECT...")
    // ...
}))

// Using gorm
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    var users []User
    db.WithContext(c.Context()).Find(&users)
    return c.OK(users)
}))

// Using sql.DB
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    rows, err := db.QueryContext(c.Context(), "SELECT...")
    // ...
}))

// Using gorm
s.GET("/users", helix.HandleCtx(func(c *helix.Ctx) error {
    var users []User
    db.WithContext(c.Context()).Find(&users)
    return c.OK(users)
}))

Helix Framework Overview

About This Package

Architecture Overview

Core Components

Data Flow

Design Patterns

Core Concepts

Server Creation

Handler Types

Request Binding

Error Handling

Routing

Design Decisions

Zero Dependencies

Performance Considerations

API Design Choices

Backward Compatibility

Usage Patterns

Basic Server

RESTful API

Modular Architecture

Production Server

Common Pitfalls

Pitfall 1: Not Returning Errors

Pitfall 2: Reading Body Multiple Times

Pitfall 3: Route Order

Integration Guide

With Standard Library

With Other Frameworks

With Database Libraries

Further Reading

Helix Framework Overview

About This Package

Architecture Overview

Core Components

Data Flow

Design Patterns

Core Concepts

Server Creation

Handler Types

Request Binding

Error Handling

Routing

Design Decisions

Zero Dependencies

Performance Considerations

API Design Choices

Backward Compatibility

Usage Patterns

Basic Server

RESTful API

Modular Architecture

Production Server

Common Pitfalls

Pitfall 1: Not Returning Errors

Pitfall 2: Reading Body Multiple Times

Pitfall 3: Route Order

Integration Guide

With Standard Library

With Other Frameworks

With Database Libraries

Further Reading

Helix Framework Overview

About This Package

Architecture Overview

Core Components

Data Flow

Design Patterns

Core Concepts

Server Creation

Handler Types

Request Binding

Error Handling

Routing

Design Decisions

Zero Dependencies

Performance Considerations

API Design Choices

Backward Compatibility

Usage Patterns