Gortex - High-Performance Go Web Framework

⚠️ [RESEARCH ONLY] This project is a local replica of past commonly used infrastructure architectural philosophies. It is maintained for record-keeping and architectural learning, and is NOT intended for production use.

繁體中文

Why Gortex?

// Traditional: Manual route registration
r.GET("/", homeHandler)
r.GET("/users/:id", userHandler)
r.GET("/api/v1/users", apiV1UserHandler)
// ... dozens more routes

// Gortex: Automatic discovery from struct tags
type HandlersManager struct {
    Home  *HomeHandler  `url:"/"`
    Users *UserHandler  `url:"/users/:id"`
    API   *APIGroup     `url:"/api"`
}

Quick Start

go get github.com/yshengliao/gortex

package main

import (
    "github.com/yshengliao/gortex/core/app"
    "github.com/yshengliao/gortex/core/types"
)

type HandlersManager struct {
    Home   *HomeHandler   `url:"/"`
    Users  *UserHandler   `url:"/users/:id"`
    Admin  *AdminGroup    `url:"/admin" middleware:"auth"`
}

type HomeHandler struct{}
func (h *HomeHandler) GET(c types.Context) error {
    return c.JSON(200, map[string]string{"message": "Welcome to Gortex!"})
}

type UserHandler struct{}
func (h *UserHandler) GET(c types.Context) error {
    return c.JSON(200, map[string]string{"id": c.Param("id")})
}

type AdminGroup struct {
    Dashboard *DashboardHandler `url:"/dashboard"`
}

type DashboardHandler struct{}
func (h *DashboardHandler) GET(c types.Context) error {
    return c.JSON(200, map[string]string{"data": "admin only"})
}

func main() {
    app, _ := app.NewApp(
        app.WithHandlers(&HandlersManager{
            Home:  &HomeHandler{},
            Users: &UserHandler{},
            Admin: &AdminGroup{
                Dashboard: &DashboardHandler{},
            },
        }),
    )
    app.Run() // :8080
}

Core Concepts

Struct Tag Routing

type HandlersManager struct {
    Users    *UserHandler    `url:"/users/:id"`                   // Dynamic params
    Static   *FileHandler    `url:"/static/*"`                    // Wildcards
    API      *APIGroup       `url:"/api"`                         // Nested groups
    Profile  *ProfileHandler `url:"/profile" middleware:"jwt"`    // Protected
    Chat     *ChatHandler    `url:"/chat" hijack:"ws"`            // WebSocket
}

HTTP Method Mapping

type UserHandler struct{}

func (h *UserHandler) GET(c types.Context) error    { /* GET /users/:id */ }
func (h *UserHandler) POST(c types.Context) error   { /* POST /users/:id */ }
func (h *UserHandler) DELETE(c types.Context) error { /* DELETE /users/:id */ }
func (h *UserHandler) Profile(c types.Context) error { /* POST /users/:id/profile */ }

Middleware

// Via struct tags
type HandlersManager struct {
    Public  *PublicHandler  `url:"/public"`
    Private *PrivateHandler `url:"/private" middleware:"auth"`
    Admin   *AdminHandler   `url:"/admin" middleware:"auth,rbac"`
}

// Or globally
app.Router().Use(middleware.Logger(logger), middleware.RequestID())

Configuration (Multi-source)

cfg := config.NewConfigBuilder().
    LoadYamlFile("config.yaml").       // Local dev
    LoadDotEnv(".env").                // Overrides
    LoadEnvironmentVariables("GORTEX"). // K8s env injection
    MustBuild()

Framework Highlights

Category	Features
Routing	Struct-tag auto-discovery, segment-trie, nested groups, zero-allocation context pooling
Security	Path-traversal-safe File, origin-locked Redirect, CORS guard, 1 MiB body cap, CSRF, secret redaction
Observability	Jaeger/OTel tracing, sharded metrics, health checks (healthy/degraded/unhealthy), /_routes & /_monitor
Resilience	Circuit breaker, token-bucket rate limiter with TTL cleanup, graceful shutdown
Real-time	WebSocket Hub with read-size limits, type whitelist, and authoriser hooks

Performance

Routing hot path achieves 0 allocations per request (Apple M3 Pro, Go 1.25):

Benchmark	ns/op	B/op	allocs/op
Static route (/api/v1/health)	~71	0	0
Param route (/users/:id)	~65	0	0
Deep params (3 params, 7 segments)	~134	0	0
Wildcard (/static/*)	~58	0	0
JSON response	~308	416	5

Examples

go run ./examples/basic      # Struct-tag routing, binder, middleware chain
go run ./examples/auth       # JWT login / refresh / /me
go run ./examples/websocket  # Hub with message limits and authoriser

Documentation

Full technical documentation is available in both English and Traditional Chinese:

• 📖 English Documentation — API reference, security guide, architecture philosophy, design patterns, best practices
• 📖 繁體中文文件 — API 參考、安全指南、架構哲學、設計模式、最佳實踐
• 🔒 SECURITY.md — Vulnerability reporting process

Changelog

v0.6.1-alpha (2026-04-25)

• Documentation audit: fixed typos, verified all Chinese text uses Taiwanese Traditional Chinese terminology.
• Updated CLAUDE.md with current performance data and feature inventory.
• Updated SECURITY.md supported version line.
• Consolidated version references across all docs.

v0.5.4-alpha (2026-04-25)

• Zero-allocation routing: eliminated map[string]string and strings.Split from hot path; embedded responseWriter in pooled context. 0 allocs/op for static, param, wildcard, and deep-param routes.

v0.5.3-alpha (2026-04-24)

• Simplified root READMEs; moved detailed content to docs/ index pages.
• Added deployment guide (Dockerfile, Docker Compose, K8s manifests, DevOps notes).

v0.5.2-alpha (2026-04-24)

• Restructured docs/ into docs/en/ and docs/zh-tw/ with full bilingual coverage.
• Added architecture philosophy and design patterns learning guide.

v0.5.1-alpha (2026-04-24)

• Marked as research and architectural record project.

v0.4.1-alpha (2026-04-24)

• Security hardening (body cap, idempotent shutdown, rate limiter TTL).
• Removed duplicate router; dependency count reduced from 50 → 41 modules.

v0.4.0-alpha

• Path-traversal-safe file serving, CORS/CSRF/JWT hardening.
• 8-level severity tracing, ShardedCollector, CI/CD pipeline.

License

MIT License — see LICENSE.