goexpress

GoExpress

A fast, lightweight, and Express.js-inspired web framework for Go. GoExpress provides an intuitive API for building web applications and microservices with built-in support for routing, middleware, CORS, authentication, and more.

Features

• 🚀 Fast & Lightweight - Minimal overhead with maximum performance
• 🛣️ Powerful Routing - Path parameters, wildcards, and route groups
• 🔐 Authentication - JWT, Basic Auth, API Keys, and Session support
• 🌐 CORS Support - Configurable CORS middleware
• 🔄 Middleware - Composable middleware system
• 📝 Request Parsing - JSON, XML, Form data support
• 🎯 Type-Safe - Fully type-safe with Go's type system
• 🔧 Extensible - Easy to extend with custom middleware
• 📦 Production Ready - Graceful shutdown, logging, recovery
• 🎨 Express.js-like API - Familiar API for JavaScript developers

Installation

go get github.com/yourusername/goexpress

Quick Start

package main

import (
    "github.com/yourusername/goexpress"
    "github.com/yourusername/goexpress/middleware"
)

func main() {
    app := goexpress.New()

    // Middleware
    app.Use(middleware.Logger())
    app.Use(middleware.CORS())

    // Routes
    app.GET("/", func(c *goexpress.Context) error {
        return c.JSON(map[string]interface{}{
            "message": "Hello, World!",
        })
    })

    app.Listen("3000")
}

Table of Contents

• Configuration
• Routing
• Context
• Middleware
• Authentication
• Error Handling
• Examples

Configuration

Create an app with custom configuration:

app := goexpress.New(&goexpress.Config{
    Port:            "8080",
    ReadTimeout:     15 * time.Second,
    WriteTimeout:    15 * time.Second,
    ShutdownTimeout: 30 * time.Second,
    EnableLogging:   true,
})

Routing

Basic Routes

app.GET("/users", getUsersHandler)
app.POST("/users", createUserHandler)
app.PUT("/users/:id", updateUserHandler)
app.PATCH("/users/:id", patchUserHandler)
app.DELETE("/users/:id", deleteUserHandler)

Route Parameters

app.GET("/users/:id", func(c *goexpress.Context) error {
    id := c.Param("id")
    return c.JSON(map[string]string{"id": id})
})

app.GET("/posts/:category/:id", func(c *goexpress.Context) error {
    category := c.Param("category")
    id := c.Param("id")
    return c.JSON(map[string]string{
        "category": category,
        "id": id,
    })
})

Query Parameters

app.GET("/search", func(c *goexpress.Context) error {
    query := c.Query("q")
    page := c.QueryDefault("page", "1")
    limit, err := c.QueryInt("limit")
    
    return c.JSON(map[string]interface{}{
        "query": query,
        "page": page,
        "limit": limit,
    })
})

Route Groups

// API v1 routes
api := app.Group("/api/v1")
{
    api.GET("/users", listUsers)
    api.POST("/users", createUser)
    
    // Nested groups
    admin := api.Group("/admin", authMiddleware)
    {
        admin.GET("/stats", getStats)
        admin.POST("/settings", updateSettings)
    }
}

Wildcard Routes

app.GET("/files/*", func(c *goexpress.Context) error {
    filepath := c.Param("*")
    return c.String("File path: " + filepath)
})

Context

The Context object provides methods to interact with the request and response.

Request Data

// Body parsing
var user User
if err := c.BodyParser(&user); err != nil {
    return err
}

// Raw body
body, err := c.Body()

// Form values
name := c.FormValue("name")

// File upload
file, err := c.FormFile("avatar")

// Headers
authHeader := c.Header("Authorization")

// Client IP
ip := c.IP()

// User Agent
ua := c.UserAgent()

Response Methods

// JSON response
return c.JSON(map[string]string{"message": "Success"})

// Status code + JSON
return c.Status(201).JSON(user)

// String response
return c.String("Hello, World!")

// HTML response
return c.HTML("<h1>Welcome</h1>")

// XML response
return c.XML(data)

// Redirect
return c.Redirect("/login", 302)

// Set headers
c.SetHeader("X-Custom-Header", "value")

// Cookies
c.Cookie(&http.Cookie{
    Name:  "session",
    Value: "abc123",
    MaxAge: 3600,
})

cookie, err := c.GetCookie("session")

Context Storage

Store and retrieve values in the context:

// Set a value
c.Set("user_id", "12345")

// Get a value
if val, ok := c.Get("user_id"); ok {
    userID := val.(string)
}

// Must get (panics if not found)
userID := c.MustGet("user_id").(string)

Middleware

Built-in Middleware

Logger

app.Use(middleware.Logger())

Recovery

Recovers from panics and returns a 500 error:

app.Use(middleware.Recovery())

CORS

// Default CORS
app.Use(middleware.CORS())

// Custom CORS
app.Use(middleware.CORS(middleware.CORSConfig{
    AllowOrigins: []string{"https://example.com"},
    AllowMethods: []string{"GET", "POST", "PUT", "DELETE"},
    AllowHeaders: []string{"Content-Type", "Authorization"},
    AllowCredentials: true,
    MaxAge: 3600,
}))

Body Limit

Limit request body size:

app.Use(middleware.BodyLimit(1024 * 1024)) // 1MB

Rate Limiting

app.Use(middleware.RateLimit(middleware.RateLimitConfig{
    Max:    100,
    Window: time.Minute,
}))

Security Headers

app.Use(middleware.Secure())

Custom Middleware

func CustomMiddleware() goexpress.Middleware {
    return func(next goexpress.HandlerFunc) goexpress.HandlerFunc {
        return func(c *goexpress.Context) error {
            // Before request
            start := time.Now()
            
            // Process request
            err := next(c)
            
            // After request
            duration := time.Since(start)
            log.Printf("Request took %v", duration)
            
            return err
        }
    }
}

app.Use(CustomMiddleware())

Route-Specific Middleware

app.GET("/admin", adminHandler, authMiddleware, adminRoleMiddleware)

Authentication

JWT Authentication

import "github.com/yourusername/goexpress/auth"

// Configure JWT
jwtConfig := auth.DefaultJWTConfig("your-secret-key")

// Apply to routes
protected := app.Group("/api", auth.JWT(jwtConfig))
{
    protected.GET("/profile", profileHandler)
}

// Generate a token
token, err := auth.GenerateToken(jwt.MapClaims{
    "user_id": "123",
    "email": "user@example.com",
}, "your-secret-key", 24*time.Hour)

// Verify a token
claims, err := auth.VerifyToken(token, "your-secret-key")

// Refresh a token
newToken, err := auth.RefreshToken(oldToken, "your-secret-key", 24*time.Hour)

Basic Authentication

app.Use(auth.BasicAuth(auth.BasicAuthConfig{
    Validator: func(username, password string) bool {
        return username == "admin" && password == "secret"
    },
}))

API Key Authentication

app.Use(auth.APIKey(auth.APIKeyConfig{
    KeyLookup: "header:X-API-Key",
    Validator: func(key string) bool {
        return key == "valid-api-key"
    },
}))

Session Authentication

// Implement a session store
type MemoryStore struct {
    sessions map[string]map[string]interface{}
    mu       sync.RWMutex
}

func (s *MemoryStore) Get(id string) (map[string]interface{}, error) {
    s.mu.RLock()
    defer s.mu.RUnlock()
    return s.sessions[id], nil
}

func (s *MemoryStore) Set(id string, data map[string]interface{}) error {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.sessions[id] = data
    return nil
}

func (s *MemoryStore) Delete(id string) error {
    s.mu.Lock()
    defer s.mu.Unlock()
    delete(s.sessions, id)
    return nil
}

// Use session middleware
store := &MemoryStore{sessions: make(map[string]map[string]interface{})}
app.Use(auth.Session(auth.DefaultSessionConfig(store)))

Error Handling

HTTP Errors

// Return predefined errors
return goexpress.ErrNotFound
return goexpress.ErrUnauthorized
return goexpress.ErrBadRequest

// Create custom errors
return goexpress.NewHTTPError(400, "Invalid email format")
return goexpress.NewHTTPError(409, "User already exists", "Email is taken")

Global Error Handler

Errors returned by handlers are automatically handled and formatted as JSON:

{
    "error": "Not found",
    "details": null
}

Examples

Complete REST API

package main

import (
    "time"
    "github.com/yourusername/goexpress"
    "github.com/yourusername/goexpress/middleware"
)

type Product struct {
    ID    string  `json:"id"`
    Name  string  `json:"name"`
    Price float64 `json:"price"`
}

var products = make(map[string]Product)

func main() {
    app := goexpress.New()
    
    app.Use(middleware.Logger())
    app.Use(middleware.Recovery())
    app.Use(middleware.CORS())
    
    api := app.Group("/api/v1")
    {
        api.GET("/products", listProducts)
        api.GET("/products/:id", getProduct)
        api.POST("/products", createProduct)
        api.PUT("/products/:id", updateProduct)
        api.DELETE("/products/:id", deleteProduct)
    }
    
    app.Listen("3000")
}

func listProducts(c *goexpress.Context) error {
    list := make([]Product, 0, len(products))
    for _, p := range products {
        list = append(list, p)
    }
    return c.JSON(list)
}

func getProduct(c *goexpress.Context) error {
    id := c.Param("id")
    product, ok := products[id]
    if !ok {
        return goexpress.ErrNotFound
    }
    return c.JSON(product)
}

func createProduct(c *goexpress.Context) error {
    var product Product
    if err := c.BodyParser(&product); err != nil {
        return goexpress.NewHTTPError(400, "Invalid request body")
    }
    
    product.ID = generateID()
    products[product.ID] = product
    
    return c.Status(201).JSON(product)
}

func updateProduct(c *goexpress.Context) error {
    id := c.Param("id")
    if _, ok := products[id]; !ok {
        return goexpress.ErrNotFound
    }
    
    var product Product
    if err := c.BodyParser(&product); err != nil {
        return goexpress.NewHTTPError(400, "Invalid request body")
    }
    
    product.ID = id
    products[id] = product
    
    return c.JSON(product)
}

func deleteProduct(c *goexpress.Context) error {
    id := c.Param("id")
    if _, ok := products[id]; !ok {
        return goexpress.ErrNotFound
    }
    
    delete(products, id)
    return c.Status(204).String("")
}

func generateID() string {
    return fmt.Sprintf("%d", time.Now().UnixNano())
}

Authentication Example

See examples/auth/main.go for a complete authentication example with JWT.

Microservices Example

See examples/microservices/main.go for a complete microservices architecture example.

Best Practices

1. Use Middleware Wisely

// Global middleware for all routes
app.Use(middleware.Logger())
app.Use(middleware.Recovery())

// Group-specific middleware
api := app.Group("/api", rateLimitMiddleware)

// Route-specific middleware
app.GET("/admin", handler, authMiddleware, adminMiddleware)

2. Structure Your Application

myapp/
├── main.go
├── config/
│   └── config.go
├── handlers/
│   ├── users.go
│   └── products.go
├── middleware/
│   └── auth.go
├── models/
│   └── user.go
└── routes/
    └── routes.go

3. Error Handling

Always return appropriate errors:

func getUser(c *goexpress.Context) error {
    id := c.Param("id")
    
    user, err := db.FindUser(id)
    if err == sql.ErrNoRows {
        return goexpress.ErrNotFound
    }
    if err != nil {
        return goexpress.ErrInternalServerError
    }
    
    return c.JSON(user)
}

4. Use Route Groups

api := app.Group("/api")
v1 := api.Group("/v1")
v2 := api.Group("/v2")

v1.GET("/users", v1UsersHandler)
v2.GET("/users", v2UsersHandler)

5. Configuration Management

type Config struct {
    Port      string
    JWTSecret string
    DBUrl     string
}

func LoadConfig() *Config {
    return &Config{
        Port:      os.Getenv("PORT"),
        JWTSecret: os.Getenv("JWT_SECRET"),
        DBUrl:     os.Getenv("DATABASE_URL"),
    }
}

Testing

import (
    "net/http"
    "net/http/httptest"
    "testing"
)

func TestGetUser(t *testing.T) {
    app := goexpress.New()
    app.GET("/users/:id", getUserHandler)
    
    req := httptest.NewRequest(http.MethodGet, "/users/123", nil)
    rec := httptest.NewRecorder()
    
    app.ServeHTTP(rec, req)
    
    if rec.Code != http.StatusOK {
        t.Errorf("Expected status 200, got %d", rec.Code)
    }
}

Performance Tips

1. Use connection pooling for database connections
2. Enable response compression for large payloads
3. Implement caching where appropriate
4. Use rate limiting to prevent abuse
5. Monitor and profile your application

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Acknowledgments

Inspired by Express.js and other Go web frameworks like Fiber and Echo.

Support

• Documentation: https://github.com/yourusername/goexpress
• Issues: https://github.com/yourusername/goexpress/issues
• Discussions: https://github.com/yourusername/goexpress/discussions