Echo Extensions

A collection of opinionated extensions and utilities for the Echo web framework, providing useful scaffolding and additional functionality to make Echo development easier and more productive.

Features

• Swagger Integration: Easily configure and mount Swagger documentation for your Echo applications
• Prefix Handling: Utilities for properly formatting URL prefixes for various extension endpoints
• Healthcheck Endpoint: Automatic healthcheck endpoint configuration
• Custom Middleware: Pre-configured middlewares for logging, CORS, and recovery
• Prometheus Metrics: Built-in HTTP traffic metrics exposed on a dedicated, opt-out metrics server
• Graceful Shutdown: Both the application and metrics servers drain in-flight requests on SIGINT/SIGTERM
• Flexible Routing: Simple group-based routing with middleware support
• Environment Awareness: Different behavior based on environment (production vs development)

Configuration Options

ServerConfig

Main configuration for the Echo server instance.

Option	Description	Default Value
PathPrefix	Base path prefix for all routes	/
Host	Server host address	0.0.0.0
Port	Server port	8080
HealthcheckPath	Path suffix for the healthcheck endpoint	/healthcheck
SkipPaths	Paths to skip for certain middleware (e.g., logging)	["/", "/healthcheck"]
ExtraCORSHeaders	Additional CORS headers to include beyond the defaults	[]
SwaggerConfig	Swagger documentation configuration	See below
MetricsConfig	Prometheus metrics server configuration	See below

SwaggerConfig

Configuration options for Swagger documentation integration.

Option	Description	Default Value
Prefix	URL path prefix for accessing Swagger documentation	/docs

MetricsConfig

Configuration for the dedicated Prometheus metrics server. The metrics server runs on its own port, separate from application traffic, and is enabled by default.

Option	Description	Default Value
Disabled	Opt out of the metrics server and instrumentation entirely	false
Path	HTTP path the metrics are exposed on	/metrics
Port	Port the metrics server listens on	9090

Exposed metrics

HTTP traffic is instrumented via middleware on the main server. OPTIONS requests (CORS preflight) are ignored, and routes are reported using their templated form (e.g. /users/:id) to keep label cardinality bounded.

Metric	Type	Labels	Description
http_requests_total	Counter	method, route, status	Total HTTP requests served
http_request_duration_seconds	Histogram	method, route, status	Request latency in seconds (buckets: 5ms → 10s)
http_requests_in_flight	Gauge	—	Requests currently being served

Environment Variables

Variable	Description	Default
APP_ENV	Application environment (local, development, production)	local
SWAGGER_CREDENTIALS	Basic auth credentials for Swagger docs in format username:password	:

Usage

// Basic server with default configuration
server := echoext.New()
server.Start()

// Server with custom configuration
config := echoext.ServerConfig{
    PathPrefix:      "/api/v1",
    Host:            "localhost",
    Port:            3000,
    HealthcheckPath: "/health",
    SkipPaths:       []string{"/metrics", "/status"},
    ExtraCORSHeaders: []string{"X-Api-Key", "X-Custom-Header"},
    SwaggerConfig: echoext.SwaggerConfig{
        Prefix: "/swagger",
    },
    // Metrics are enabled by default. Customize the path/port, or set
    // Disabled: true to opt out.
    MetricsConfig: echoext.MetricsConfig{
        Path: "/metrics",
        Port: 9090,
    },
}
server := echoext.New(config)

// Creating route groups
server.Group("/users", func(g *echo.Group) {
    g.GET("", listUsers)
    g.POST("", createUser)
    g.GET("/:id", getUser)
})

// Access underlying echo instance
e := server.Engine()

// Start boots the main server and the metrics server, then blocks until a
// SIGINT/SIGTERM is received, at which point both are gracefully shut down.
if err := server.Start(); err != nil {
    log.Fatal(err)
}

Middleware

The server comes preconfigured with several middleware:

• Logger: Logs HTTP requests with customizable path skipping
• Recovery: Recovers from panics and returns 500 internal server error
• CORS: Configures Cross-Origin Resource Sharing with sensible defaults
  • Default headers include: Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization, accept, origin, Cache-Control, X-Requested-With
  • Can be extended with custom headers via the ExtraCORSHeaders configuration option
• Metrics: Records Prometheus HTTP traffic metrics (enabled by default; skips OPTIONS requests and uses templated route labels)

Extended Context

The extension provides an enhanced Context interface that extends Echo's standard Context with additional type-safe getter methods. These methods simplify the retrieval of typed values from context storage.

Type-Safe Getter Methods

Method	Return Type	Description
GetString(key string)	string	Retrieves a string value from context storage
GetBool(key string)	bool	Retrieves a boolean value from context storage
GetInt(key string)	int	Retrieves an int value from context storage
GetInt8(key string)	int8	Retrieves an int8 value from context storage
GetInt16(key string)	int16	Retrieves an int16 value from context storage
GetInt32(key string)	int32	Retrieves an int32 value from context storage
GetInt64(key string)	int64	Retrieves an int64 value from context storage
GetUint(key string)	uint	Retrieves a uint value from context storage
GetUint8(key string)	uint8	Retrieves a uint8 value from context storage
GetUint16(key string)	uint16	Retrieves a uint16 value from context storage
GetUint32(key string)	uint32	Retrieves a uint32 value from context storage
GetUint64(key string)	uint64	Retrieves a uint64 value from context storage
GetFloat64(key string)	float64	Retrieves a float64 value from context storage

Each method automatically performs type assertion on the value stored in context, returning the zero value of the respective type if the value is not of the expected type or not found.

Usage Example

// Store a value in context
c.Set("user_id", 123)

// Later, retrieve it with type safety
userID := c.GetInt("user_id") // Returns 123 as int

// If the wrong type is stored, it returns the zero value
invalidID := c.GetString("user_id") // Returns "" (empty string)

// Example with middleware setting values
func AuthMiddleware(next echoext.HandlerFunc) echoext.HandlerFunc {
    return func(c echoext.Context) error {
        // Set values that can be retrieved with type safety in handlers
        c.Set("user_id", 42)
        c.Set("is_admin", true)
        return next(c)
    }
}

// Handler using the type-safe getters
func MyHandler(c echoext.Context) error {
    userID := c.GetInt("user_id")      // 42
    isAdmin := c.GetBool("is_admin")   // true
    
    // Use the values...
    return c.JSON(http.StatusOK, map[string]interface{}{
        "userId": userID,
        "isAdmin": isAdmin,
    })
}