shadowfax

KO | EN

gitlite — search

#python #typescript #go #machine-learning #docker #macos #nodejs #java #windows #awesome #cli #vue #mcp #open-source

(★ 15)

An HTTP/1.1 server built on top of TCP using Go.

shadowfax 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Shadowfax

<p align="center"> 
	<img src="gopher_shadowfax.png" height="300px">
</p>
<p align="center">
	<strong>YOU SHALL NOT PASS!</strong>
</p>

[![integration](https://github.com/shravanasati/shadowfax/actions/workflows/integration.yml/badge.svg)](https://github.com/shravanasati/shadowfax/actions/workflows/integration.yml)

A fast, lightweight HTTP/1.1 server built from scratch in Go. Shadowfax implements the HTTP protocol directly on top of TCP sockets, providing a complete web server solution with modern features and abstractions.

> **Note**: This project is built for educational purposes and learning HTTP internals. Not recommended for production usage.

## ✨ Features

### Core HTTP Implementation
- **From-scratch HTTP/1.1 parser** - Custom request parsing without `net/http`
- **Response writer** - Efficient response generation with proper HTTP formatting
- **Chunked transfer encoding** - Support for streaming responses with trailers
- **Content-Length handling** - Automatic body size detection and headers
- **Persistent Connections** - Supports persistent connections via `KeepAliveTimeout` configuration option

### Web Server Abstractions
- **Prefix-tree router** - Fast O(log n) routing with trie-based path matching
- **Dynamic path parameters** - Extract parameters like `/users/:id`
- **Wildcard routes** - Catch-all routes with `/*path` patterns  
- **Method-specific routing** - GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD
- **Automatic HEAD handling** - Auto-generates HEAD responses from GET handlers
- **Method not allowed detection** - Proper 405 responses for unsupported methods

### Advanced Features
- **Middleware support** - Composable request/response middleware chain with built-in logging and basic auth
- **CORS support** - Built-in Cross-Origin Resource Sharing with comprehensive configuration options
- **Panic recovery** - Graceful error handling with customizable recovery
- **Graceful shutdown** - Clean server termination with signal handling
- **Concurrent request handling** - Goroutine-per-request architecture
- **Query parameter parsing** - Easy access to URL query parameters
- **Multiple response types** - Text, JSON, HTML, Template, File, and Stream responses

## 🚀 Quick Start

### Installation

```bash
go mod init your-project
go get github.com/shravanasati/shadowfax
```

### Basic Server

```go
package main

import (
    "log"
    "os"
    "os/signal"
    "syscall"
    
    "github.com/shravanasati/shadowfax/router"
    "github.com/shravanasati/shadowfax/server"
    "github.com/shravanasati/shadowfax/request"
    "github.com/shravanasati/shadowfax/response"
)

func main() {
    // Create a new router
    app := router.NewRouter(nil)
    
    // Add a simple route
    app.Get("/hello", func(r *request.Request) response.Response {
        return response.NewTextResponse("Hello, World!")
    })
    
    // Start the server
    srv, err := server.Serve(server.ServerOpts{
        Address:      ":8080",
        ReadTimeout:  30 * time.Second,
        WriteTimeout: 10 * time.Second,
    }, app.Handler())
    
    if err != nil {
        log.Fatal(err)
    }
    defer srv.Close()
    
    log.Println("Server running on :8080")
    
    // Graceful shutdown
    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
    <-sigChan
    log.Println("Server stopped")
}
```

## 📖 Usage Guide

### Routing

#### Basic Routes

```go
app := router.NewRouter(nil)

// HTTP methods
app.Get("/users", getUsersHandler)
app.Post("/users", createUserHandler) 
app.Put("/users/:id", updateUserHandler)
app.Delete("/users/:id", deleteUserHandler)
app.Patch("/users/:id", patchUserHandler)

// Handle any method
app.Handle("/webhook", webhookHandler)
```

#### Path Parameters

```go
app.Get("/users/:id", func(r *request.Request) response.Response {
    userID := r.PathParams["id"]
    return response.NewTextResponse("User ID: " + userID)
})

app.Get("/files/:category/:filename", func(r *request.Request) response.Response {
    category := r.PathParams["category"]
    filename := r.PathParams["filename"]
    
    return response.NewTextResponse(
        fmt.Sprintf("Category: %s, File: %s", category, filename)
    )
})
```

#### Wildcard Routes

```go
// Matches /api/v1/anything/here
app.Handle("/api/*path", func(r *request.Request) response.Response {
    fullPath := r.PathParams["path"]
    return response.NewTextResponse("API path: " + fullPath)
})
```

#### Subrouters

```go
// Create a subrouter with middleware
apiRouter := router.NewRouter(nil)
apiRouter.Use(authMiddleware)

apiRouter.Get("/profile", profileHandler)
apiRouter.Post("/data", dataHandler)

// Mount the subrouter
app.Handle("/api", apiRouter.Handler())
```

### Request Handling

#### Query Parameters

```go
app.Get("/search", func(r *request.Request) response.Response {
    query := r.Query.Get("q")
    page := r.Query.Get("page")
    filters := r.Query["filter"] // Get all filter values
    
    return response.NewJSONResponse(map[string]any{
        "query": query,
        "page": page, 
        "filters": filters,
    })
})
```

#### Headers

```go
app.Post("/api/data", func(r *request.Request) response.Response {
    contentType := r.Headers.Get("content-type")
    userAgent := r.Headers.Get("user-agent")
    customHeader := r.Headers.Get("x-custom-header")
    
    if contentType != "application/json" {
        return response.NewBaseResponse().WithStatusCode(response.StatusBadRequest)
    }
    
    // Process request...
    return response.NewTextResponse("Data processed")
})
```

#### Request Body

```go
app.Post("/upload", func(r *request.Request) response.Response {
    body := r.Body()
    defer body.Close()
    
    data, err := io.ReadAll(body)
    if err != nil {
        return response.NewBaseResponse().WithStatusCode(response.StatusBadRequest)
    }
    
    // Process the body data...
    return response.NewTextResponse("Upload successful")
})
```

### Response Types

#### Text Response

```go
app.Get("/text", func(r *request.Request) response.Response {
    return response.NewTextResponse("Plain text response")
})
```

#### JSON Response

```go
app.Get("/api/user/:id", func(r *request.Request) response.Response {
    user := map[string]any{
        "id":    r.PathParams["id"],
        "name":  "John Doe", 
        "email": "john@example.com",
    }
    
    resp, err := response.NewJSONResponse(user)
    if err != nil {
        return response.
			NewBaseResponse().
			WithStatusCode(response.StatusInternalServerError)
    }
    
    return resp
})
```

#### HTML Response

```go
app.Get("/", func(r *request.Request) response.Response {
    html := `
    <!DOCTYPE html>
    <html>
    <head><title>Shadowfax</title></head>
    <body><h1>Welcome to Shadowfax!</h1></body>
    </html>
    `
    return response.NewHTMLResponse(html)
})
```

#### Template Response

Render dynamic HTML templates with data:

```go
app.Get("/profile/:username", func(r *request.Request) response.Response {
    username := r.PathParams["username"]
    
    template := `<!DOCTYPE html>
<html>
<head>
    <title>{{.Title}}</title>
</head>
<body>
    <h1>Welcome, {{.Username}}!</h1>
    <p>Last login: {{.LastLogin}}</p>
    <ul>
    {{range .Items}}
        <li>{{.}}</li>
    {{end}}
    </ul>
</body>
</html>`

data := map[string]interface{}{
        "Title":     "User Profile",
        "Username":  username,
        "LastLogin": time.Now().Format("Jan 2, 2006"),
        "Items":     []string{"Dashboard", "Settings", "Logout"},
    }

resp, err := response.NewTemplateResponse(template, data)
    if err != nil {
        return response.NewTextResponse("Template error").WithStatusCode(500)
    }
    
    return resp
})
```

For more complex templates with custom functions:

```go
import "html/template"

app.Get("/advanced", func(r *request.Request) response.Response {
    template := `<h1>{{upper .title}}</h1><p>Count: {{add .count 1}}</p>`
    
    funcMap := template.FuncMap{
        "upper": strings.ToUpper,
        "add": func(a, b int) int { return a + b },
    }
    
    data := map[string]interface{}{
        "title": "hello world",
        "count": 42,
    }
    
    resp, err := response.NewTemplateResponseWithFuncs(template, funcMap, data)
    if err != nil {
        return response.NewTextResponse("Template error").WithStatusCode(500)
    }
    
    return resp
})
```

#### File Response

```go
app.Get("/download/:filename", func(r *request.Request) response.Response {
    filename := r.PathParams["filename"]
    
    file, err := os.Open("./uploads/" + filename)
    if err != nil {
        return response.NewBaseResponse().WithStatusCode(response.StatusNotFound)
    }
    
    return response.NewFileResponse(file).
        WithHeader("Content-Disposition", "attachment; filename="+filename)
})
```

For file responses, the `Content-Type` and `ETag` headers are automatically added to the response.

#### Streaming Response

```go
app.Get("/stream/:duration", func(r *request.Request) response.Response {
    duration, _ := strconv.Atoi(r.PathParams["duration"])
    
    streamFunc := func(w io.Writer, setTrailer response.TrailerSetter) error {
        ticker := time.NewTicker(100 * time.Millisecond)
        defer ticker.Stop()
        
        deadline := time.After(time.Duration(duration) * time.Second)
        
        for {
            select {
            case <-deadline:
                setTrailer("X-Stream-End", time.Now().String())
                return nil
            case t := <-ticker.C:
                fmt.Fprintf(w, "Time: %v\n", t)
            }
        }
    }
    
    return response.
		NewStreamResponse(streamFunc, []string{"X-Stream-End"})
})
```

#### Custom Status Codes and Headers

```go
app.Get("/custom", func(r *request.Request) response.Response {
    return response.NewTextResponse("Custom response").
        WithStatusCode(response.StatusCreated).
        WithHeader("X-Custom", "value").
        WithHeaders(map[string]string{
            "X-API-Version": "1.0",
            "X-Rate-Limit":  "100",
        })
})
```

### Middleware

Shadowfax provides a flexible middleware system that allows you to intercept and modify requests and responses. The framework includes built-in middleware for common use cases and supports custom middleware development.

#### Built-in Middleware

##### Logging Middleware

The logging middleware provides request logging with optional colored output:

```go
package main

import (
    "github.com/shravanasati/shadowfax/middleware"
    "github.com/shravanasati/shadowfax/router"
)

func main() {
    app := router.NewRouter(nil)
    
    // Basic logging (plain text)
    app.Use(middleware.LoggingMiddleware)
    
    // Or colored logging (requires lipgloss)
    app.Use(middleware.LoggingMiddlewareColored)
    
    app.Get("/test", testHandler)
}
```

The logging middleware outputs request information including:
- HTTP method (styled and colored in colored version)
- Request path/target
- Response status code (color-coded by status range)
- Request duration

##### Basic Authentication Middleware

The basic auth middleware provides HTTP Basic Authentication support:

```go
package main

import (
    "github.com/shravanasati/shadowfax/middleware"
    "github.com/shravanasati/shadowfax/router"
)

func main() {
    app := router.NewRouter(nil)
    
    // Configure accounts for basic auth
    accounts := []middleware.Account{
        {Username: "admin", Password: "secret123"},
        {Username: "user", Password: "password"},
    }
    
    // Apply basic auth to specific routes
    protectedRouter := router.NewRouter(nil)
    protectedRouter.Use(middleware.BasicAuthMiddleware(accounts))
    
    protectedRouter.Get("/admin", adminHandler)
    protectedRouter.Post("/admin/config", configHandler)
    
    // Mount the protected routes
    app.Handle("/protected", protectedRouter.Handler())
    
    // Public routes (no auth required)
    app.Get("/", publicHandler)
}
```

The basic auth middleware:
- Validates `Authorization: Basic <credentials>` headers
- Returns 401 Unauthorized for missing or invalid credentials
- Sets appropriate `WWW-Authenticate` headers for browser prompts

##### Static File Serving Handler

The static handler enables efficient serving of static files from your filesystem or embedded resources. It can be used directly as a route handler:

```go
package main

import (
    "github.com/shravanasati/shadowfax/middleware"
    "github.com/shravanasati/shadowfax/router"
)

func main() {
    app := router.NewRouter(nil)
    
    // Serve files from disk
    diskFS := middleware.NewDirFS("./public")
    staticHandler := middleware.NewStaticHandler("filepath", diskFS)
    app.Handle("/static/*filepath", staticHandler)
    
    app.Get("/", homeHandler)
}
```

**Serving Embedded Files:**

```go
//go:embed public/*
var publicFiles embed.FS

func main() {
    app := router.NewRouter(nil)
    
    // Serve embedded files
    embedFS := middleware.NewEmbedFS(publicFiles)
    staticHandler := middleware.NewStaticHandler("filepath", embedFS)
    
    app.Handle("/static/*filepath", staticHandler)
}
```

**Static Handler Features:**
- 🔒 **Path traversal protection** - Prevents `../../../etc/passwd` attacks
- 📁 **Directory support** - Automatically serves `index.html` for directories
- ⚡ **Efficient serving** - Zero-copy file transmission with proper headers
- 🎯 **Content-Type detection** - Automatic MIME type detection
- 📊 **ETag support** - Automatic cache validation headers
- 🔗 **Multiple sources** - Disk, embedded files, or custom implementations

**Complete Example:**

```go
import (
    "embed"
    "os"
    "github.com/shravanasati/shadowfax/middleware"
    "github.com/shravanasati/shadowfax/router"
)

//go:embed assets/*
var embeddedAssets embed.FS

func main() {
    app := router.NewRouter(nil)
    
    var staticFS middleware.NamedReadSeekerFS
    
    // Use embedded files in production, disk files in development
    if os.Getenv("ENV") == "production" {
        staticFS = middleware.NewEmbedFS(embeddedAssets)
    } else {
        staticFS = middleware.NewDirFS("./assets")
    }
    
    // Create static handler for serving files
    staticHandler := middleware.NewStaticHandler("path", staticFS)
    
    // Mount the static file handler
    app.Handle("/assets/*path", staticHandler)
    
    // Dynamic handlers
    app.Get("/api/data", apiHandler)
    
    // 404 handler for missing files/routes
    app.NotFound(notFoundHandler)
}
```

##### CORF (Cross-Origin Request Forgery) Middleware

The CORF middleware provides protection against cross-origin request forgery attacks by validating the origin of requests:

```go
package main

import (
    "github.com/shravanasati/shadowfax/middleware"
    "github.com/shravanasati/shadowfax/router"
)

func main() {
    app := router.NewRouter(nil)
    
    // Create CORF protection
    corf := middleware.NewCrossOriginProtection()
    
    // Add trusted origins that are allowed to make requests
    corf.AddTrustedOrigin("https://myapp.com")
    corf.AddTrustedOrigin("https://www.myapp.com")
    corf.AddTrustedOrigin("http://localhost:3000") // Development
    
    // Apply CORF protection to sensitive endpoints
    apiRouter := router.NewRouter(nil)
    apiRouter.Use(corf.Handler())
    
    apiRouter.Post("/transfer", transferHandler)
    apiRouter.Delete("/account", deleteAccountHandler)
    apiRouter.Patch("/settings", settingsHandler)
    
    app.Handle("/api", apiRouter.Handler())
    
    // Public endpoints without CORF
    app.Get("/", publicHandler)
}
```

**CORF Protection Features:**
- 🛡️ **Origin validation** - Checks `Origin` and `Sec-Fetch-Site` headers
- ✅ **Trusted origin bypass** - Allow specific origins to bypass some checks
- 📋 **Method validation** - Protects against dangerous HTTP methods (POST, PUT, DELETE, PATCH)
- 🔒 **Secure defaults** - Blocks cross-site requests with strict policies
- 🎯 **Flexible configuration** - Set custom denial handlers and trusted origins

**Advanced Configuration:**

```go
corf := middleware.NewCrossOriginProtection()

// Add trusted origins with validation
origins := []string{
    "https://myapp.com",
    "https://api.myapp.com",
    "http://localhost:8080", // Development
}

for _, origin := range origins {
    if err := corf.AddTrustedOrigin(origin); err != nil {
        log.Printf("Invalid origin: %v", err)
        continue
    }
}

// Set a custom denial handler
corf.SetDenyHandler(func(_ *request.Request) response.Response {
    return response.NewJSONResponse(map[string]string{
        "error": "Cross-origin request rejected",
    }).WithStatusCode(response.StatusForbidden)
})

// Apply to routes
app.Use(corf.Handler())
```

**How CORF Works:**

The CORF middleware validates requests using multiple checks:

1. **Same-Origin Detection** - Checks `Sec-Fetch-Site` header
   - `same-origin` - Always allowed (same site)
   - `none` - Usually allowed (top-level navigation)
   - `cross-site` - Blocked by default (needs trusted origin)

2. **Trusted Origin Bypass** - If origin is in trusted list, allows cross-site requests

3. **Secure Method Validation** - Restricts dangerous methods on cross-origin requests

```go
// Example: Protecting a form submission endpoint
app.Post("/api/transfer-funds", func(r *request.Request) response.Response {
    // This will be protected by CORF middleware
    // Cross-site requests without trusted origin will be blocked
    
    amount := r.Query.Get("amount")
    recipient := r.Query.Get("recipient")
    
    // Process transfer...
    
    return response.NewJSONResponse(map[string]string{
        "status": "success",
    })
})
```

#### Custom Middleware

Create your own middleware by implementing the `Middleware` type:

```go
type Middleware func(next server.Handler) server.Handler
```

##### Authentication Middleware

```go
func authMiddleware(next server.Handler) server.Handler {
    return func(r *request.Request) response.Response {
        token := r.Headers.Get("Authorization")
        
        if !isValidToken(token) {
            return response.NewBaseResponse().
                WithStatusCode(response.StatusUnauthorized)
        }
        
        return next(r)
    }
}

// Apply to specific routes
protectedRouter := router.NewRouter(nil)
protectedRouter.Use(authMiddleware)
protectedRouter.Get("/profile", profileHandler)

app.Handle("/api", protectedRouter.Handler())
```

##### Rate Limiting Middleware

```go
import "sync"

var rateLimiter = struct {
    sync.Mutex
    requests map[string][]time.Time
}{requests: make(map[string][]time.Time)}

func rateLimitMiddleware(requestsPerMinute int) router.Middleware {
    return func(next server.Handler) server.Handler {
        return func(r *request.Request) response.Response {
            clientIP := r.Headers.Get("X-Forwarded-For")
            if clientIP == "" {
                clientIP = "unknown"
            }
            
            rateLimiter.Lock()
            defer rateLimiter.Unlock()
            
            now := time.Now()
            requests := rateLimiter.requests[clientIP]
            
            // Filter requests from the last minute
            validRequests := []time.Time{}
            for _, reqTime := range requests {
                if now.Sub(reqTime) < time.Minute {
                    validRequests = append(validRequests, reqTime)
                }
            }
            
            if len(validRequests) >= requestsPerMinute {
                return response.NewTextResponse("Rate limit exceeded").
                    WithStatusCode(response.StatusTooManyRequests)
            }
            
            rateLimiter.requests[clientIP] = append(validRequests, now)
            
            return next(r)
        }
    }
}

app.Use(rateLimitMiddleware(100)) // 100 requests per minute
```

##### Request ID Middleware

```go
import "github.com/google/uuid"

func requestIDMiddleware(next server.Handler) server.Handler {
    return func(r *request.Request) response.Response {
        requestID := r.Headers.Get("X-Request-ID")
        if requestID == "" {
            requestID = uuid.New().String()
        }
        
        resp := next(r)
        return resp.WithHeader("X-Request-ID", requestID)
    }
}

app.Use(requestIDMiddleware)
```

#### Middleware Ordering

Middleware is executed in the order it's added. The last middleware added will be the first to execute:

```go
app.Use(requestIDMiddleware)    // Executes first
app.Use(loggingMiddleware)      // Executes second
app.Use(authMiddleware)         // Executes third

// Execution order: requestID → logging → auth → handler → auth → logging → requestID
```

### CORS (Cross-Origin Resource Sharing)

Shadowfax provides built-in CORS support through router configuration. CORS is essential when building APIs that need to be accessed from web browsers with different origins.

#### Basic CORS Setup

Enable CORS with default settings (allows all origins):

```go
package main

import (
    "github.com/shravanasati/shadowfax/router"
)

func main() {
    // Enable CORS with default configuration
    app := router.NewRouter(&router.RouterOptions{
        EnableCors: true,
    })
    
    app.Get("/api/data", dataHandler)
    app.Post("/api/users", createUserHandler)
}
```

#### Custom CORS Configuration

Configure CORS with specific options for production use:

```go
app := router.NewRouter(&router.RouterOptions{
    EnableCors: true,
    CorsOptions: router.CorsOptions{
        // Allowed origins (specific domains)
        AllowedOrigins: []string{
            "https://myapp.com",
            "https://www.myapp.com",
            "http://localhost:3000", // For development
        },
        
        // Allowed HTTP methods
        AllowedMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
        
        // Allowed headers that can be used during the actual request
        AllowedHeaders: []string{
            "Accept",
            "Authorization", 
            "Content-Type",
            "X-CSRF-Token",
            "X-API-Key",
        },
        
        // Headers that are safe to expose to the API
        ExposedHeaders: []string{
            "X-Request-ID",
            "X-Response-Time",
        },
        
        // Allow cookies and authorization headers
        AllowCredentials: true,
        
        // How long browsers can cache preflight results (in seconds)
        MaxAge: 86400, // 24 hours
        
        // Whether OPTIONS requests should be passed to the next handler
        OptionsPassthrough: false,
    },
})
```

#### CORS Configuration Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `AllowedOrigins` | `[]string` | List of allowed origins. Use `"*"` for all origins | `["*"]` |
| `AllowOriginFunc` | `func(*request.Request, string) bool` | Custom function to validate origins | `nil` |
| `AllowedMethods` | `[]string` | Allowed HTTP methods | `["HEAD", "GET", "POST"]` |
| `AllowedHeaders` | `[]string` | Allowed request headers | `["Origin", "Accept", "Content-Type"]` |
| `ExposedHeaders` | `[]string` | Headers exposed to the client | `[]` |
| `AllowCredentials` | `bool` | Allow cookies and authorization headers | `false` |
| `MaxAge` | `int` | Preflight cache duration in seconds | `0` |
| `OptionsPassthrough` | `bool` | Let OPTIONS requests pass to handlers | `false` |

#### Advanced CORS Examples

##### Wildcard Origins

Support multiple domains with wildcards:

```go
CorsOptions: router.CorsOptions{
    AllowedOrigins: []string{
        "https://*.example.com",    // All subdomains of example.com
        "http://localhost:*",       // Any localhost port
        "https://app.mydomain.com", // Specific domain
    },
}
```

##### Dynamic Origin Validation

Use a custom function for complex origin validation:

```go
CorsOptions: router.CorsOptions{
    AllowOriginFunc: func(r *request.Request, origin string) bool {
        // Allow origins based on API key or other criteria
        apiKey := r.Headers.Get("X-API-Key")
        
        // Check if origin is in allowed list for this API key
        return validateOriginForAPIKey(origin, apiKey)
    },
    AllowCredentials: true,
}
```

##### Development vs Production

Set up different CORS configurations based on environment:

```go
func corsConfig() router.CorsOptions {
    if os.Getenv("ENV") == "production" {
        return router.CorsOptions{
            AllowedOrigins: []string{
                "https://myapp.com",
                "https://www.myapp.com",
            },
            AllowedMethods: []string{"GET", "POST", "PUT", "DELETE"},
            AllowedHeaders: []string{"Authorization", "Content-Type"},
            AllowCredentials: true,
            MaxAge: 86400,
        }
    }
    
    // Development configuration (more permissive)
    return router.CorsOptions{
        AllowedOrigins: []string{"*"},
        AllowedMethods: []string{"GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"},
        AllowedHeaders: []string{"*"},
        AllowCredentials: false,
        MaxAge: 3600,
    }
}

app := router.NewRouter(&router.RouterOptions{
    EnableCors:  true,
    CorsOptions: corsConfig(),
})
```

### Error Handling

#### Server Configuration

Configure server timeouts and recovery options:

```go
srv, err := server.Serve(server.ServerOpts{
    Address:      ":8080",
    ReadTimeout:  30 * time.Second,  // Maximum time to read the entire request
    WriteTimeout: 10 * time.Second,  // Maximum time to write the response
    Recovery: func(r any) response.Response {
        log.Printf("Panic recovered: %v", r)
        return response.NewTextResponse("Internal Server Error").
            WithStatusCode(response.StatusInternalServerError)
    },
}, app.Handler())
```

**Configuration Options:**
- `Address` - Server bind address (e.g., ":8080", "localhost:3000")
- `ReadTimeout` - Maximum duration for reading the entire request (including body)
- `WriteTimeout` - Maximum duration for writing the response
- `KeepAliveTimeout` - Maximum duration for idle connection. Defaults to 0, which disables keep-alive.
- `Recovery` - Custom panic recovery function

#### Custom 404 Handler

```go
app.NotFound(func(r *request.Request) response.Response {
    return response.NewHTMLResponse(`
        <h1>Page Not Found</h1>
        <p>The page you're looking for doesn't exist.</p>
    `).WithStatusCode(response.StatusNotFound)
})
```

#### Panic Recovery

```go
srv, err := server.Serve(server.ServerOpts{
    Address:      ":8080",
    ReadTimeout:  30 * time.Second,
    WriteTimeout: 10 * time.Second,
    Recovery: func(r any) response.Response {
        log.Printf("Panic recovered: %v", r)
        return response.NewTextResponse("Internal Server Error").
            WithStatusCode(response.StatusInternalServerError)
    },
}, app.Handler())
```

### Complete Example

```go
package main

import (
    "fmt"
    "log"
    "os"
    "os/signal"
    "strconv"
    "syscall"
    "time"
    
    "github.com/shravanasati/shadowfax/request"
    "github.com/shravanasati/shadowfax/response" 
    "github.com/shravanasati/shadowfax/router"
    "github.com/shravanasati/shadowfax/server"
)

func main() {
    // Create router with CORS enabled
    app := router.NewRouter(&router.RouterOptions{
        EnableCors: true,
        CorsOptions: router.CorsOptions{
            AllowedOrigins: []string{"*"},
            AllowCredentials: false,
        },
    })
    
    // Global middleware
    app.Use(loggingMiddleware)
    
    // Static routes
    app.Get("/", homeHandler)
    app.Get("/health", healthHandler)
    
    // API routes with parameters
    app.Get("/api/users/:id", getUserHandler)
    app.Post("/api/users", createUserHandler)
    app.Delete("/api/users/:id", deleteUserHandler)
    
    // File operations
    app.Get("/files/*path", fileHandler)
    app.Post("/upload", uploadHandler)
    
    // Streaming endpoint
    app.Get("/stream/:seconds", streamHandler)
    
    // Protected routes
    adminRouter := router.NewRouter(nil)
    adminRouter.Use(authMiddleware)
    adminRouter.Get("/stats", adminStatsHandler)
    adminRouter.Post("/config", adminConfigHandler)
    app.Handle("/admin", adminRouter.Handler())
    
    // Custom error handlers
    app.NotFound(notFoundHandler)
    
    // Start server
    srv, err := server.Serve(server.ServerOpts{
        Address:      ":8080",
        ReadTimeout:  30 * time.Second,
        WriteTimeout: 10 * time.Second,
        Recovery:     panicHandler,
    }, app.Handler())
    
    if err != nil {
        log.Fatal(err)
    }
    defer srv.Close()
    
    log.Println("🚀 Shadowfax server running on :8080")
    
    // Graceful shutdown
    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
    <-sigChan
    log.Println("🛑 Server stopped gracefully")
}

func homeHandler(r *request.Request) response.Response {
    return response.NewHTMLResponse(`
        <h1>Welcome to Shadowfax</h1>
        <p>A fast HTTP/1.1 server built from scratch!</p>
    `)
}

func healthHandler(r *request.Request) response.Response {
    return response.NewJSONResponse(map[string]any{
        "status": "healthy",
        "time":   time.Now().Unix(),
    })
}

func getUserHandler(r *request.Request) response.Response {
    userID := r.PathParams["id"]
    
    user := map[string]any{
        "id":    userID,
        "name":  "User " + userID,
        "email": fmt.Sprintf("user%s@example.com", userID),
    }
    
    resp, _ := response.NewJSONResponse(user)
    return resp
}

func loggingMiddleware(next server.Handler) server.Handler {
    return func(r *request.Request) response.Response {
        start := time.Now()
        resp := next(r)
        
        fmt.Printf("%s %s %d - %v\n", 
            r.Method, r.Target, resp.GetStatusCode(), time.Since(start))
        
        return resp
    }
}

func corsMiddleware(next server.Handler) server.Handler {
    return func(r *request.Request) response.Response {
        resp := next(r)
        return resp.WithHeader("Access-Control-Allow-Origin", "*")
    }
}
```

## 🏗️ Architecture

### Request Flow

1. **TCP Connection** - Accept incoming connections
2. **HTTP Parsing** - Parse HTTP/1.1 request line and headers  
3. **Routing** - Match path against trie-based router
4. **Middleware Chain** - Execute middleware in order
5. **Handler Execution** - Call matched route handler
6. **Response Generation** - Create and write HTTP response
7. **Connection Management** - Handle keep-alive or close

### Router Implementation

Shadowfax uses a **prefix tree (trie)** for efficient route matching:

- **Static segments** - Exact string matches (`/users`)
- **Parameter segments** - Dynamic captures (`/users/:id`) 
- **Wildcard segments** - Catch-all matches (`/files/*path`)

Route precedence: Static → Parameters → Wildcards

### Concurrency Model

- **Goroutine per request** - Each connection handled concurrently
- **Shared router** - Thread-safe routing with immutable trie
- **Graceful shutdown** - Clean termination of active connections

## 🧪 Testing

Run the test suite:

```bash
go test ./...
```

Run tests with coverage:

```bash
go test -cover ./...
```

## 📜 License

This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.

shadowfax

shadowfax 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

shadowfax

shadowfax 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README