extras

README

Router Adapters

This package provides router adapters for different routing backends.

Available Adapters

1. BunRouter (Recommended)

Default adapter - High performance, modern API

import (
    "github.com/xraph/forge"
    "github.com/xraph/forge/extras"
)

router := forge.NewRouter(
    forge.WithAdapter(extras.NewBunRouterAdapter()),
    forge.WithContainer(container),
)

Features:

• Fast route matching
• Modern API design
• Path parameters: /users/:id
• Wildcard routes: /files/*

2. Chi Router

Clean, composable router from go-chi

router := forge.NewRouter(
    forge.WithAdapter(extras.NewChiAdapter()),
    forge.WithContainer(container),
)

Features:

• Middleware-first design
• Sub-router mounting
• Path parameters: /users/{id}

3. HTTPRouter

Extremely fast router from julienschmidt

router := forge.NewRouter(
    forge.WithAdapter(extras.NewHTTPRouterAdapter()),
    forge.WithContainer(container),
)

Features:

• Fastest route matching
• Minimal allocations
• Path parameters: /users/:id

Default Behavior

If no adapter is specified, the router uses a simple in-memory adapter for basic functionality. For production use, explicitly specify one of the above adapters.

Choosing an Adapter

Adapter	Performance	Features	Use Case
BunRouter	⚡⚡⚡ High	Modern, full-featured	Recommended for most apps
Chi	⚡⚡ Good	Middleware-focused	Apps with complex middleware
HTTPRouter	⚡⚡⚡ Highest	Minimal, fast	High-throughput APIs

Example

package main

import (
    "net/http"
    "github.com/xraph/forge"
    "github.com/xraph/forge/extras"
)

func main() {
    // Create container
    container := forge.NewContainer()
    
    // Create router with BunRouter adapter
    router := forge.NewRouter(
        forge.WithAdapter(extras.NewBunRouterAdapter()),
        forge.WithContainer(container),
        forge.WithRecovery(),
    )
    
    // Register routes
    router.GET("/", func(ctx forge.Context) error {
        return ctx.String(200, "Hello from BunRouter!")
    })
    
    router.GET("/users/:id", func(ctx forge.Context) error {
        id := ctx.Param("id")
        return ctx.JSON(200, map[string]string{
            "id": id,
            "name": "User " + id,
        })
    })
    
    // Start server
    http.ListenAndServe(":8080", router)
}

Documentation

Index

• func GetHTTPRouterParams(r *http.Request) httprouter.Params
• func NewBunRouterAdapter() forge.RouterAdapter
• func NewChiAdapter() forge.RouterAdapter
• func NewHTTPRouterAdapter() forge.RouterAdapter
• type BunRouterAdapter
  • func (a *BunRouterAdapter) Close() error
  • func (a *BunRouterAdapter) Handle(method, path string, handler http.Handler)
  • func (a *BunRouterAdapter) Mount(path string, handler http.Handler)
  • func (a *BunRouterAdapter) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (a *BunRouterAdapter) UseGlobal(middleware func(http.Handler) http.Handler)
• type ChiAdapter
  • func (a *ChiAdapter) Close() error
  • func (a *ChiAdapter) Handle(method, path string, handler http.Handler)
  • func (a *ChiAdapter) Mount(path string, handler http.Handler)
  • func (a *ChiAdapter) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (a *ChiAdapter) UseGlobal(middleware func(http.Handler) http.Handler)
• type HTTPRouterAdapter
  • func (a *HTTPRouterAdapter) Close() error
  • func (a *HTTPRouterAdapter) Handle(method, path string, handler http.Handler)
  • func (a *HTTPRouterAdapter) Mount(path string, handler http.Handler)
  • func (a *HTTPRouterAdapter) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (a *HTTPRouterAdapter) UseGlobal(middleware func(http.Handler) http.Handler)

Functions

func GetHTTPRouterParams

func GetHTTPRouterParams(r *http.Request) httprouter.Params

GetHTTPRouterParams retrieves httprouter params from context.

func NewBunRouterAdapter

func NewBunRouterAdapter() forge.RouterAdapter

NewBunRouterAdapter creates a BunRouter adapter (default).

func NewChiAdapter

func NewChiAdapter() forge.RouterAdapter

NewChiAdapter creates a Chi router adapter.

func NewHTTPRouterAdapter

func NewHTTPRouterAdapter() forge.RouterAdapter

NewHTTPRouterAdapter creates an HTTPRouter adapter.

Types

type BunRouterAdapter

type BunRouterAdapter struct {
	// contains filtered or unexported fields
}

BunRouterAdapter wraps uptrace/bunrouter.

func (*BunRouterAdapter) Close

func (a *BunRouterAdapter) Close() error

Close cleans up resources.

func (*BunRouterAdapter) Handle

func (a *BunRouterAdapter) Handle(method, path string, handler http.Handler)

Handle registers a route.

func (*BunRouterAdapter) Mount

func (a *BunRouterAdapter) Mount(path string, handler http.Handler)

Mount registers a sub-handler.

func (*BunRouterAdapter) ServeHTTP

func (a *BunRouterAdapter) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP dispatches requests.

func (*BunRouterAdapter) UseGlobal

func (a *BunRouterAdapter) UseGlobal(middleware func(http.Handler) http.Handler)

UseGlobal registers global middleware that runs before routing. This middleware will run for ALL requests, even those that don't match any route. This is critical for CORS preflight handling.

type ChiAdapter

type ChiAdapter struct {
	// contains filtered or unexported fields
}

ChiAdapter wraps go-chi/chi router.

func (*ChiAdapter) Close

func (a *ChiAdapter) Close() error

Close cleans up resources.

func (*ChiAdapter) Handle

func (a *ChiAdapter) Handle(method, path string, handler http.Handler)

Handle registers a route.

func (*ChiAdapter) Mount

func (a *ChiAdapter) Mount(path string, handler http.Handler)

Mount registers a sub-handler.

func (*ChiAdapter) ServeHTTP

func (a *ChiAdapter) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP dispatches requests.

func (*ChiAdapter) UseGlobal

func (a *ChiAdapter) UseGlobal(middleware func(http.Handler) http.Handler)

UseGlobal registers global middleware that runs before routing. This middleware will run for ALL requests, even those that don't match any route. This is critical for CORS preflight handling.

type HTTPRouterAdapter

type HTTPRouterAdapter struct {
	// contains filtered or unexported fields
}

HTTPRouterAdapter wraps julienschmidt/httprouter.

func (*HTTPRouterAdapter) Close

func (a *HTTPRouterAdapter) Close() error

Close cleans up resources.

func (*HTTPRouterAdapter) Handle

func (a *HTTPRouterAdapter) Handle(method, path string, handler http.Handler)

Handle registers a route.

func (*HTTPRouterAdapter) Mount

func (a *HTTPRouterAdapter) Mount(path string, handler http.Handler)

Mount registers a sub-handler.

func (*HTTPRouterAdapter) ServeHTTP

func (a *HTTPRouterAdapter) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP dispatches requests.

func (*HTTPRouterAdapter) UseGlobal

func (a *HTTPRouterAdapter) UseGlobal(middleware func(http.Handler) http.Handler)

UseGlobal registers global middleware that runs before routing. This middleware will run for ALL requests, even those that don't match any route. This is critical for CORS preflight handling.