flash

README

Flash is a lean web framework inspired by Gin and Fiber, combining their best. Built on the standard net/http.
It prioritizes developer speed and runtime performance - with a tiny, tested and stable API, clean ergonomics, and near‑zero allocations in hot paths.
Ship features fast without sacrificing reliability.

---

Quick Start

package main

import (
    "log"
    "net/http"

    "github.com/goflash/flash/v2"
    "github.com/goflash/flash/v2/middleware"
)

func main() {
    app := flash.New()
    app.Use(middleware.Recover(), middleware.Logger())

    // Easiest endpoint
    app.ANY("/ping", func(c flash.Ctx) error {
        return c.String(http.StatusOK, "pong")
    })

    // Path param with JSON response
    app.GET("/hello/:name", func(c flash.Ctx) error {
        return c.JSON(map[string]any{"hello": c.Param("name")})
    })

    log.Fatal(http.ListenAndServe(":8080", app))
}

More examples: goflash/examples

Features

• net/http compatible - Full compatibility with Go's standard library and HTTP/2
• Fast routing - High-performance routing with support for path parameters and route groups
• Ergonomic context - Clean API with helpers for common operations
• Composable middleware - Built-in middleware for logging, recovery, CORS, sessions, and more
• Static file serving - Serve static assets with flexible configuration
• Request binding - Bind JSON, form, query, and path parameters to structs
• Extensible - Add custom middleware and integrate with any slog-compatible logger

---

Middleware

Flash includes built-in middleware for common web application needs and supports external middleware packages.

Core Middleware

Middleware	Purpose
Buffer	Response buffering to reduce syscalls and set Content-Length
CORS	Cross-origin resource sharing with configurable policies
CSRF	Cross-site request forgery protection using double-submit cookies
Logger	Structured request logging with slog integration
RateLimit	Rate limiting with multiple strategies (token bucket, sliding window, etc.)
Recover	Panic recovery with configurable error responses
RequestID	Request ID generation and correlation
RequestSize	Request body size limiting for DoS protection
Session	Session management with pluggable storage backends
Timeout	Request timeout handling with graceful cancellation

External Middleware

Package	Description	Repository
OpenTelemetry	Distributed tracing and metrics integration	goflash/otel
Validator	Request validation with go-playground/validator	goflash/validator
Compression	Compression middleware for the GoFlash web framework	goflash/compression

---

Installation

go get github.com/goflash/flash/v2

---

Core Concepts

Routing

• Register routes with methods or ANY(). Group routes with shared prefix and middleware. Nested groups are supported and inherit parent prefix and middleware.
• Custom methods: use Handle(method, path, handler) for non-standard verbs.
• Mount net/http handlers with Mount or HandleHTTP.

Routing patterns reference

Routing patterns and behavior follow julienschmidt/httprouter.

Context (Ctx)

flash.Ctx is a wrapper around http.ResponseWriter and *http.Request that provides convenient helpers for common operations:

• Request/Response Access - Direct access to underlying HTTP primitives
• Path & Query Parameters - Extract and parse URL parameters with type conversion
• Request Binding - Bind JSON, form, query, and path data to structs
• Response Writing - Send JSON, text, or raw responses with proper headers
• Context Management - Store and retrieve values in request context

For detailed method documentation, see the Go package documentation.

Request Binding

Flash provides helpers to bind request data to structs using json tags:

• BindJSON - Bind JSON request body
• BindForm - Bind form data (URL-encoded or multipart)
• BindQuery - Bind query parameters
• BindPath - Bind path parameters
• BindAny - Bind from multiple sources with precedence: Path > Body > Query

type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

app.POST("/users/:id", func(c flash.Ctx) error {
    var user User
    if err := c.BindAny(&user); err != nil {
        return c.Status(400).JSON(map[string]string{"error": err.Error()})
    }
    return c.JSON(user)
})

net/http Interoperability

Flash is fully compatible with the standard library. You can:

• Mount any http.Handler using app.Mount(prefix, handler)
• Register individual handlers with app.HandleHTTP(method, path, handler)
• Use Flash apps as http.Handler in other servers

// Mount existing handler
mux := http.NewServeMux()
mux.HandleFunc("/users", userHandler)
app.Mount("/api/", mux)

// Use Flash in standard server
mux := http.NewServeMux()
mux.Handle("/api/", http.StripPrefix("/api", app))

---

Examples

Runnable examples covering various use cases are available at goflash/examples.

For contrib-specific examples look at every specific middleware repository.

---

Benchmarks

Flash is benchmarked against Gin and Fiber across common web application scenarios. Performance is competitive with other major Go web frameworks.

Detailed benchmarks: goflash/benchmarks

---

Contributing

We welcome issues and PRs! Please read CONTRIBUTING.md.

---

⭐ Star this repo if you find it useful!

---

📝 License: MIT | 📧 Support: Create an Issue

Battle tested in private productions.
Released with ❤️ for the Go community.

Documentation

Index

• type App
  • func New() App
• type Ctx
• type DefaultApp
• type DefaultContext
• type ErrorHandler
• type Group
• type Handler
• type Middleware

Types

type App

type App = app.App

App is the public interface of the application, re-exported for convenience.

func New

func New() App

New creates a new App with sensible defaults. Re-exported from app.New.

type Ctx

type Ctx = ctx.Ctx

Ctx is the request context interface, re-exported for convenience.

type DefaultApp

type DefaultApp = app.DefaultApp

DefaultApp is the default implementation (useful when asserting concrete type in tests).

type DefaultContext

type DefaultContext = ctx.DefaultContext

DefaultContext is the concrete context implementation used by the framework.

type ErrorHandler

type ErrorHandler = app.ErrorHandler

ErrorHandler handles errors returned from handlers. Re-exported from app.ErrorHandler.

type Group

type Group = app.Group

Group is a route group for organizing routes. Re-exported from app.Group for convenience.

type Handler

type Handler = app.Handler

Handler is the function signature for goflash route handlers and middleware (after composition). Re-exported from app.Handler.

type Middleware

type Middleware = app.Middleware

Middleware transforms a Handler, enabling composition (e.g., logging, auth). Re-exported from app.Middleware.