express

README

express

Node's Express, for Go.

express is a fast, minimalist web framework for Go modeled after Express.js. It gives you the familiar Express routing API — app.Get, app.Post, app.Use, route parameters, middleware chains, mountable routers — and chainable request/response helpers, all built on top of the standard library's net/http.

package main

import (
	"log"

	"github.com/malcolmston/express"
)

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

	app.Get("/", func(req *express.Request, res *express.Response, next express.Next) {
		res.Send("Hello World")
	})

	log.Fatal(app.Listen(":3000"))
}

Install

go get github.com/malcolmston/express

Concepts

The handler signature

Every handler has the same three-argument shape as Express:

func(req *express.Request, res *express.Response, next express.Next)

Call next() to pass control to the next matching handler, or next(err) to jump to error-handling middleware.

Routing

app.Get("/users/:id", handler)     // GET with a route parameter
app.Post("/users", handler)        // POST
app.Put("/users/:id", handler)
app.Delete("/users/:id", handler)
app.Patch("/users/:id", handler)
app.All("/health", handler)        // any method
app.Query("/search", handler)      // the new HTTP QUERY method (safe, with a body)

The QUERY method is the emerging IETF safe-with-body method; app.Query mirrors Express's app.query().

Route parameters are read with req.Params("id"). A * in a path is a wildcard captured as the * parameter. Parameters can be optional (:id?) or constrained by a regular expression (:id(\d+)):

app.Get("/users/:id?", handler)      // matches /users and /users/42
app.Get(`/items/:id(\d+)`, handler)  // matches /items/42, not /items/abc

Register method handlers for one path with app.Route, and preprocess a parameter with app.Param:

app.Route("/users").Get(list).Post(create)
app.Param("id", func(req *express.Request, res *express.Response, next express.Next, id string) {
	user, err := db.Find(id)
	if err != nil { next(err); return }
	req.Set("user", user)
	next()
})

Middleware

app.Use(express.Logger())          // app-wide middleware
app.Use(express.Recover())         // recover from panics -> 500
app.Use(express.JSON())            // parse JSON bodies into req.Body()
app.Use("/admin", requireAuth)     // middleware scoped to a path prefix

Middleware runs in registration order. Any handler may short-circuit by writing a response and simply not calling next().

Mountable routers

api := express.NewRouter()
api.Get("/users/:id", getUser)
api.Post("/users", createUser)

app.Use("/api", api)   // routes become /api/users/:id, /api/users

Routers accept options and can be mounted at a parameterized path; use MergeParams so the sub-router sees the parent's captured params:

users := express.NewRouter(express.RouterOptions{
	MergeParams:   true,  // inherit parent params (e.g. :userId)
	CaseSensitive: false, // "/Foo" == "/foo" (default)
	Strict:        false, // "/foo" == "/foo/" (default)
})
users.Get("/profile", func(req *express.Request, res *express.Response, next express.Next) {
	res.Send("profile of " + req.Params("userId"))
})
app.Use("/users/:userId", users) // GET /users/42/profile -> "profile of 42"

Routers nest arbitrarily, each with its own middleware, params, and options.

Error handling

Register a four-argument error handler with Use; it runs only when an upstream handler calls next(err):

app.Use(func(err error, req *express.Request, res *express.Response, next express.Next) {
	res.Status(500).JSON(map[string]string{"error": err.Error()})
})

Request helpers

Method	Description
req.Params(name)	route parameter
req.SetPath(p)	rewrite the path and the router's match path (re-routes)
req.Query(name)	query-string value
req.Get(field)	request header
req.Body()	parsed body (after a body-parser middleware)
req.BodyJSON(&dst)	read + unmarshal the JSON body into dst
req.Is("json")	content-type test
req.Cookie(name)	read a cookie
req.IP(), req.Hostname(), req.Protocol(), req.Secure()	connection info

Response helpers

Method	Description
res.Status(code)	set the status code (chainable)
res.Send(body)	send a string, []byte, or JSON-serializable value
res.JSON(v)	send v as JSON
res.SendStatus(code)	send the status text for code
res.Set(field, value)	set a header
res.Type(t)	set Content-Type ("json", "html", ...)
res.Redirect(url) / res.Redirect(code, url)	redirect
res.Cookie(name, value, opts)	set a cookie
res.SendFile(path)	send a file (Range + conditional GET support)
res.Download(path, name) / res.Attachment(name)	send as a download
res.Render(view, data)	render a template (see Views)
res.Format(map)	content negotiation by Accept
res.ETag(tag) / res.LastModified(t) / res.NotModified()	conditional GET
res.End()	finish with no body

Request negotiation helpers: req.Accepts(...), req.AcceptsLanguages(...), req.AcceptsCharsets(...), req.AcceptsEncodings(...), req.Ranges(size), and req.Fresh(res) / req.Stale(res).

Views

Register a template engine and render views with res.Render. The built-in engine uses html/template (for .html / .tmpl); plug in any engine with app.Engine.

app.Set("views", "./views")     // template directory (default "views")
app.Set("view engine", "html")  // default extension

app.Get("/", func(req *express.Request, res *express.Response, next express.Next) {
	res.Render("index", map[string]any{"Title": "Home"})
})

// Custom engine:
app.Engine(".mustache", func(path string, data any) (string, error) { ... })

Most response methods return *Response so they can be chained: res.Status(201).JSON(user).

Bundled middleware

• express.JSON() — parse application/json bodies into req.Body().
• express.URLEncoded() — parse form-encoded bodies.
• express.Text() — parse text/plain bodies into req.Body().
• express.Multipart(maxMemory) — parse multipart/form-data (file uploads).
• express.Static(root) — serve static files from a directory.
• express.Session(opts...) — cookie-backed sessions (see below).
• express.Logger() — log method, path, status, and duration.
• express.Recover() — recover from panics and return a 500.

Middleware suite (100+ packages)

Beyond the bundled middleware above, express ships a large catalog of ready-to-use middleware under middleware/ — over 100 independent subpackages spanning security headers, authentication/access control, body & response transforms, rate limiting & traffic control, routing/static helpers, cookies/CSRF/sessions, and dev utilities. Each has a New(...) constructor and is standard-library only.

import (
	"github.com/malcolmston/express/middleware/cors"
	"github.com/malcolmston/express/middleware/helmet"
	"github.com/malcolmston/express/middleware/ratelimit"
	"github.com/malcolmston/express/middleware/compression"
)

app.Use(helmet.New())
app.Use(cors.New(cors.Options{AllowOrigins: []string{"https://example.com"}}))
app.Use(compression.New())
app.Use(ratelimit.New(ratelimit.Options{Max: 100, Window: time.Minute}))

See MIDDLEWARE.md for the full catalog.

Sessions

express.Session() adds a cookie-backed session, persisted through a pluggable SessionStore (an in-memory store is the default). Read and write it with req.Session(); changes are saved automatically just before the response is sent.

app.Use(express.Session(express.SessionOptions{
	Name:   "sid",
	Secure: true, // HTTPS only
	// Store: myRedisStore,
}))

app.Post("/login", func(req *express.Request, res *express.Response, next express.Next) {
	sess := req.Session()
	sess.Regenerate()          // new id on privilege change (anti-fixation)
	sess.Set("userID", "42")
	res.Send("logged in")
})

app.Get("/me", func(req *express.Request, res *express.Response, next express.Next) {
	res.Send("user " + req.Session().GetString("userID"))
})

app.Post("/logout", func(req *express.Request, res *express.Response, next express.Next) {
	req.Session().Destroy()
	res.Send("bye")
})

File uploads & forms

app.Use(express.Multipart(0)) // 0 = 32 MiB default in-memory buffer

app.Post("/avatar", func(req *express.Request, res *express.Response, next express.Next) {
	file, header, err := req.FormFile("avatar")
	if err != nil {
		next(err)
		return
	}
	defer file.Close()
	res.JSON(map[string]any{"filename": header.Filename, "caption": req.FormValue("caption")})
})

req.Form() returns all form values (query + body) as url.Values; req.Files(name) returns every uploaded file header for a field.

Input validation

The validator subpackage provides fluent request validation in the spirit of express-validator. Build a Schema and mount it as middleware that rejects invalid requests with a 400 JSON body — or call Validate on a map directly.

import "github.com/malcolmston/express/validator"

schema := validator.Schema{
	validator.Field("email").Required().Email(),
	validator.Field("age").Optional().IsInt().Min(0).Max(120),
	validator.Field("name").Required().MinLen(2).MaxLen(50),
	validator.Field("role").Required().In("admin", "user"),
}

app.Use(express.JSON())
app.Post("/users", schema.Body(), createUser) // 400 {"errors":[...]} on failure

Available rules: Required, Optional, Email, MinLen, MaxLen, Min, Max, IsInt, IsNumber, In, Matches, and Custom. Use schema.Query() to validate the query string instead of the body.

Streaming & chunked responses

The response supports incremental, flushed output for large or open-ended bodies. *Response implements io.Writer, so it drops into io.Copy and fmt.Fprintf.

// Stream a body chunk-by-chunk (each write is flushed to the client).
app.Get("/stream", func(req *express.Request, res *express.Response, next express.Next) {
	res.Type("text").Stream(func(w io.Writer) error {
		for i := 0; i < 10; i++ {
			fmt.Fprintf(w, "line %d\n", i)
		}
		return nil
	})
})

// Copy a large reader to the client in chunks without buffering it all.
res.SendStream(file)               // default 32 KiB chunks
res.SendChunked(bigBytes, 64<<10)  // fixed-size chunks from memory
res.WriteChunk([]byte("partial"))  // low-level: write + flush
res.Flush()                        // flush buffered data

Server-Sent Events

app.Get("/events", func(req *express.Request, res *express.Response, next express.Next) {
	sse := res.SSE() // sets text/event-stream headers and flushes them
	for {
		select {
		case <-req.Raw.Context().Done():
			return
		case ev := <-updates:
			sse.SendJSON("update", ev)   // event: update\ndata: {...}
		case <-ticker.C:
			sse.Comment("keep-alive")
		}
	}
})

SSEWriter provides Send, SendData, SendJSON, SendID (for Last-Event-ID resumption), Comment, and Retry.

Using with net/http

An *express.Application is an http.Handler, so it drops into anything that speaks net/http — http.Server, httptest, or other middleware:

srv := &http.Server{Addr: ":8080", Handler: app}
srv.ListenAndServe()

Example

A runnable example lives in examples/basic:

go run ./examples/basic

Compatibility

This is a Go re-implementation modeled on Express.js, targeting API/behavior parity and standards-compliant HTTP output. See COMPATIBILITY.md for a feature-by-feature parity table and known gaps.

Companion library

Pair this with passport — a Go port of Passport.js — for pluggable authentication.

License

MIT

Documentation

Overview

Package express is a fast, minimalist web framework for Go, modeled after the Node.js Express framework. It provides a familiar routing API, chainable request/response helpers, and middleware support on top of the standard library's net/http package.

A minimal application looks like this:

app := express.New()

app.Get("/", func(req *express.Request, res *express.Response, next express.Next) {
	res.Send("Hello World")
})

log.Fatal(app.Listen(":3000"))

Index

• Constants
• type Application
  • func New() *Application
  • func (app *Application) Disable(name string) *Application
  • func (app *Application) Disabled(name string) bool
  • func (app *Application) Enable(name string) *Application
  • func (app *Application) Enabled(name string) bool
  • func (app *Application) Engine(ext string, fn EngineFunc) *Application
  • func (app *Application) GetSetting(name string) any
  • func (app *Application) Listen(addr string) error
  • func (app *Application) ListenWithServer(server *http.Server) error
  • func (app *Application) Locals() map[string]any
  • func (app *Application) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (app *Application) Set(name string, value any) *Application
• type CookieOptions
• type EngineFunc
• type ErrorHandler
• type Handler
  • func JSON() Handler
  • func Logger() Handler
  • func Multipart(maxMemory int64) Handler
  • func Recover() Handler
  • func Session(opts ...SessionOptions) Handler
  • func Static(root string) Handler
  • func Text() Handler
  • func URLEncoded() Handler
  • func WrapHandler(h http.Handler) Handler
  • func WrapHandlerFunc(fn func(http.ResponseWriter, *http.Request)) Handler
• type MemorySessionStore
  • func NewMemorySessionStore() *MemorySessionStore
  • func (m *MemorySessionStore) Destroy(id string)
  • func (m *MemorySessionStore) Get(id string) (map[string]any, bool)
  • func (m *MemorySessionStore) Set(id string, data map[string]any)
• type Next
• type ParamHandler
• type Range
• type Request
  • func (req *Request) Accepts(offers ...string) string
  • func (req *Request) AcceptsCharsets(offers ...string) string
  • func (req *Request) AcceptsEncodings(offers ...string) string
  • func (req *Request) AcceptsLanguages(offers ...string) string
  • func (req *Request) AllParams() map[string]string
  • func (req *Request) Body() any
  • func (req *Request) BodyJSON(dst any) error
  • func (req *Request) Cookie(name string) string
  • func (req *Request) Files(name string) []*multipart.FileHeader
  • func (req *Request) Form() url.Values
  • func (req *Request) FormFile(name string) (multipart.File, *multipart.FileHeader, error)
  • func (req *Request) FormValue(name string) string
  • func (req *Request) Fresh(res *Response) bool
  • func (req *Request) Get(field string) string
  • func (req *Request) Header(field string) string
  • func (req *Request) Hostname() string
  • func (req *Request) IP() string
  • func (req *Request) Is(typ string) bool
  • func (req *Request) Method() string
  • func (req *Request) OriginalURL() string
  • func (req *Request) Params(name string) string
  • func (req *Request) Path() string
  • func (req *Request) Protocol() string
  • func (req *Request) Query(name string) string
  • func (req *Request) QueryValues() url.Values
  • func (req *Request) Ranges(size int64) ([]Range, bool)
  • func (req *Request) Secure() bool
  • func (req *Request) Session() *SessionData
  • func (req *Request) Set(key string, value any)
  • func (req *Request) SetBody(v any)
  • func (req *Request) SetPath(p string)
  • func (req *Request) Stale(res *Response) bool
  • func (req *Request) Value(key string) (any, bool)
• type Response
  • func (res *Response) Append(field, value string) *Response
  • func (res *Response) Attachment(filename ...string) *Response
  • func (res *Response) ClearCookie(name string) *Response
  • func (res *Response) Cookie(name, value string, opts *CookieOptions) *Response
  • func (res *Response) Download(path string, filename ...string) error
  • func (res *Response) ETag(tag string) *Response
  • func (res *Response) End()
  • func (res *Response) Flush() bool
  • func (res *Response) Format(handlers map[string]func())
  • func (res *Response) Fresh() bool
  • func (res *Response) GetHeader(field string) string
  • func (res *Response) JSON(v any) *Response
  • func (res *Response) LastModified(t time.Time) *Response
  • func (res *Response) Location(url string) *Response
  • func (res *Response) NotModified()
  • func (res *Response) OnBeforeWrite(fn func())
  • func (res *Response) Redirect(args ...any) *Response
  • func (res *Response) Render(name string, data ...any) error
  • func (res *Response) SSE() *SSEWriter
  • func (res *Response) Send(body any) *Response
  • func (res *Response) SendChunked(data []byte, chunkSize int) error
  • func (res *Response) SendFile(path string) error
  • func (res *Response) SendStatus(code int) *Response
  • func (res *Response) SendStream(r io.Reader, chunkSize ...int) error
  • func (res *Response) Set(field, value string) *Response
  • func (res *Response) Status(code int) *Response
  • func (res *Response) StatusCode() int
  • func (res *Response) Stream(fn func(w io.Writer) error) error
  • func (res *Response) Type(t string) *Response
  • func (res *Response) Vary(field string) *Response
  • func (res *Response) Write(p []byte) (int, error)
  • func (res *Response) WriteChunk(p []byte) (int, error)
  • func (res *Response) WriteString(s string) (int, error)
  • func (res *Response) Written() bool
• type Route
  • func (rt *Route) All(h ...Handler) *Route
  • func (rt *Route) Delete(h ...Handler) *Route
  • func (rt *Route) Get(h ...Handler) *Route
  • func (rt *Route) Patch(h ...Handler) *Route
  • func (rt *Route) Post(h ...Handler) *Route
  • func (rt *Route) Put(h ...Handler) *Route
• type RouteRegistrar
• type Router
  • func NewRouter(opts ...RouterOptions) *Router
  • func (r *Router) All(path string, handlers ...Handler) *Router
  • func (r *Router) Delete(path string, handlers ...Handler) *Router
  • func (r *Router) Get(path string, handlers ...Handler) *Router
  • func (r *Router) Head(path string, handlers ...Handler) *Router
  • func (r *Router) Options(path string, handlers ...Handler) *Router
  • func (r *Router) Param(name string, fn ParamHandler) *Router
  • func (r *Router) Patch(path string, handlers ...Handler) *Router
  • func (r *Router) Post(path string, handlers ...Handler) *Router
  • func (r *Router) Put(path string, handlers ...Handler) *Router
  • func (r *Router) Query(path string, handlers ...Handler) *Router
  • func (r *Router) Route(path string) *Route
  • func (r *Router) Use(args ...any) *Router
• type RouterOptions
• type SSEWriter
  • func (s *SSEWriter) Comment(text string) error
  • func (s *SSEWriter) Retry(ms int) error
  • func (s *SSEWriter) Send(event, data string) error
  • func (s *SSEWriter) SendData(data string) error
  • func (s *SSEWriter) SendID(id, event, data string) error
  • func (s *SSEWriter) SendJSON(event string, v any) error
• type SessionData
  • func (s *SessionData) Delete(key string)
  • func (s *SessionData) Destroy()
  • func (s *SessionData) Get(key string) (any, bool)
  • func (s *SessionData) GetString(key string) string
  • func (s *SessionData) Regenerate() error
  • func (s *SessionData) Set(key string, value any)
• type SessionOptions
• type SessionStore

Constants

const DefaultSessionCookie = "connect.sid"

DefaultSessionCookie is the cookie name used by the session middleware, matching the default used by Node's express-session.

const MethodQuery = "QUERY"

MethodQuery is the QUERY HTTP method token. It is not yet part of the standard library's net/http method constants, so it is defined here.

Types

type Application

type Application struct {
	*Router
	// contains filtered or unexported fields
}

Application is the top-level express app. It embeds a Router so every routing method (Get, Post, Use, ...) is available directly on the app, and adds server lifecycle helpers such as Listen.

func New

func New() *Application

New creates a new express Application.

func (*Application) Disable

func (app *Application) Disable(name string) *Application

Disable turns a boolean setting off.

func (*Application) Disabled

func (app *Application) Disabled(name string) bool

Disabled reports whether a boolean setting is turned off.

func (*Application) Enable

func (app *Application) Enable(name string) *Application

Enable turns a boolean setting on.

func (*Application) Enabled

func (app *Application) Enabled(name string) bool

Enabled reports whether a boolean setting is turned on.

func (*Application) Engine

func (app *Application) Engine(ext string, fn EngineFunc) *Application

Engine registers a template engine for a file extension (e.g. ".html", ".pug"). The extension should include the leading dot.

func (*Application) GetSetting

func (app *Application) GetSetting(name string) any

GetSetting returns the value of a previously configured setting.

func (*Application) Listen

func (app *Application) Listen(addr string) error

Listen binds and listens for connections on the given address, e.g. ":3000". It blocks until the server exits and returns any error from ListenAndServe.

func (*Application) ListenWithServer

func (app *Application) ListenWithServer(server *http.Server) error

ListenWithServer lets callers supply a preconfigured *http.Server (for TLS, custom timeouts, etc.). The app is installed as the server's handler.

func (*Application) Locals

func (app *Application) Locals() map[string]any

Locals returns the application-wide locals map.

func (*Application) ServeHTTP

func (app *Application) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP makes Application satisfy http.Handler so it can be handed to any net/http server, httptest, or wrapped by other middleware.

func (*Application) Set

func (app *Application) Set(name string, value any) *Application

Set assigns a setting name to a value, returning the app for chaining.

type CookieOptions

type CookieOptions struct {
	Path     string
	Domain   string
	MaxAge   int
	Secure   bool
	HTTPOnly bool
	SameSite http.SameSite
}

CookieOptions configures a cookie set via res.Cookie.

type EngineFunc

type EngineFunc func(path string, data any) (string, error)

EngineFunc renders a template file at path with the given data and returns the rendered output. Register one with app.Engine to support a template language.

type ErrorHandler

type ErrorHandler func(err error, req *Request, res *Response, next Next)

ErrorHandler is a handler that additionally receives an error. When a handler calls next(err), express skips ordinary handlers and invokes the next registered ErrorHandler.

type Handler

type Handler func(req *Request, res *Response, next Next)

Handler is the express request handler signature. Every handler receives the request, the response, and a Next function used to pass control to the next matching handler in the stack.

func JSON

func JSON() Handler

JSON returns middleware that parses JSON request bodies into a map[string]any (or []any) and stores the result on req via SetBody. It only acts on requests whose Content-Type is JSON.

func Logger

func Logger() Handler

Logger returns middleware that logs each request's method, path, status, and duration to the standard logger, in a concise Express/morgan-like format.

func Multipart

func Multipart(maxMemory int64) Handler

Multipart returns middleware that parses multipart/form-data request bodies, making fields available via req.FormValue and files via req.FormFile. maxMemory bounds the in-memory buffer (0 uses the 32 MiB default).

func Recover

func Recover() Handler

Recover returns middleware that recovers from panics in downstream handlers and converts them into a 500 response, keeping the server alive.

func Session

func Session(opts ...SessionOptions) Handler

Session returns middleware that loads a per-request session from a cookie and persists changes automatically. Access it in handlers via req.Session().

func Static

func Static(root string) Handler

Static returns middleware that serves files from root. Requests that do not resolve to an existing file fall through to the next handler.

func Text

func Text() Handler

Text returns middleware that reads a text/plain body into req.Body() as a string.

func URLEncoded

func URLEncoded() Handler

URLEncoded returns middleware that parses application/x-www-form-urlencoded request bodies and stores them on req as url.Values.

func WrapHandler

func WrapHandler(h http.Handler) Handler

WrapHandler adapts a standard net/http handler into an express Handler so it can be mounted with app.Use, e.g. to attach a Socket.IO server:

app.Use("/socket.io", express.WrapHandler(io)) // io is an http.Handler

The wrapped handler receives the raw request (req.Raw) and response writer (res.Writer) — so it can hijack the connection for WebSocket upgrades — and is treated as terminal: express does not run later handlers for it.

func WrapHandlerFunc

func WrapHandlerFunc(fn func(http.ResponseWriter, *http.Request)) Handler

WrapHandlerFunc is WrapHandler for an http.HandlerFunc.

type MemorySessionStore

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

MemorySessionStore is an in-memory SessionStore for development and single-process use.

func NewMemorySessionStore

func NewMemorySessionStore() *MemorySessionStore

NewMemorySessionStore creates an empty in-memory session store.

func (*MemorySessionStore) Destroy

func (m *MemorySessionStore) Destroy(id string)

func (*MemorySessionStore) Get

func (m *MemorySessionStore) Get(id string) (map[string]any, bool)

func (*MemorySessionStore) Set

func (m *MemorySessionStore) Set(id string, data map[string]any)

type Next

type Next func(err ...error)

Next advances to the next handler. Calling it with no arguments continues the stack; calling it with a non-nil error jumps to error-handling middleware.

type ParamHandler

type ParamHandler func(req *Request, res *Response, next Next, value string)

ParamHandler processes a captured route parameter before the route's handlers run. It receives the parameter's value and, like any handler, must call next to continue (or next(err) to fail).

type Range

type Range struct {
	Start int64
	End   int64 // inclusive
}

Range represents a single byte range parsed from a Range header.

type Request

type Request struct {
	// Raw is the underlying standard-library request.
	Raw *http.Request
	// contains filtered or unexported fields
}

Request wraps an *http.Request and exposes Express-style accessors for route parameters, query values, headers, and the parsed request body.

func (*Request) Accepts

func (req *Request) Accepts(offers ...string) string

Accepts returns the best match among the offered types for the request's Accept header, or "" when none is acceptable. Offers may be extensions ("html", "json") or full media types ("text/html"). With no offers it returns the client's most-preferred type.

func (*Request) AcceptsCharsets

func (req *Request) AcceptsCharsets(offers ...string) string

AcceptsCharsets returns the best match among the offered charsets for the Accept-Charset header, or "".

func (*Request) AcceptsEncodings

func (req *Request) AcceptsEncodings(offers ...string) string

AcceptsEncodings returns the best match among the offered encodings for the Accept-Encoding header, or "".

func (*Request) AcceptsLanguages

func (req *Request) AcceptsLanguages(offers ...string) string

AcceptsLanguages returns the best match among the offered languages for the Accept-Language header, or "".

func (*Request) AllParams

func (req *Request) AllParams() map[string]string

AllParams returns all captured route parameters.

func (*Request) Body

func (req *Request) Body() any

Body returns the parsed request body. Call one of the Parse* helpers or the body-parser middleware first; otherwise it returns nil.

func (*Request) BodyJSON

func (req *Request) BodyJSON(dst any) error

BodyJSON reads and unmarshals a JSON request body into dst.

func (*Request) Cookie

func (req *Request) Cookie(name string) string

Cookie returns the value of a named cookie, or "" if not present.

func (*Request) Files

func (req *Request) Files(name string) []*multipart.FileHeader

Files returns all uploaded file headers for a form field.

func (*Request) Form

func (req *Request) Form() url.Values

Form parses and returns all form values (query + body) as url.Values.

func (*Request) FormFile

func (req *Request) FormFile(name string) (multipart.File, *multipart.FileHeader, error)

FormFile returns the first uploaded file for the given form field, along with its multipart header. The multipart form must have been parsed first (via the Multipart middleware or by calling FormFile, which parses on demand).

func (*Request) FormValue

func (req *Request) FormValue(name string) string

FormValue parses form data (query + body) and returns a single value.

func (*Request) Fresh

func (req *Request) Fresh(res *Response) bool

Fresh reports whether the client's cached response is still fresh for this request, based on the response's ETag / Last-Modified headers and the request's If-None-Match / If-Modified-Since headers. When true, a handler may send 304 Not Modified instead of a body. Fresh only applies to GET and HEAD.

func (*Request) Get

func (req *Request) Get(field string) string

Get returns a request header value (case-insensitive), Express's req.get.

func (*Request) Header

func (req *Request) Header(field string) string

Header is an alias for Get.

func (*Request) Hostname

func (req *Request) Hostname() string

Hostname returns the host portion of the request, honoring the Host header.

func (*Request) IP

func (req *Request) IP() string

IP returns the remote address of the request.

func (*Request) Is

func (req *Request) Is(typ string) bool

Is reports whether the request's Content-Type matches the given type, e.g. req.Is("json") or req.Is("text/html").

func (*Request) Method

func (req *Request) Method() string

Method returns the request's HTTP method (GET, POST, ...).

func (*Request) OriginalURL

func (req *Request) OriginalURL() string

OriginalURL returns the full request URI as received.

func (*Request) Params

func (req *Request) Params(name string) string

Params returns a captured route parameter by name, or "" if absent.

func (*Request) Path

func (req *Request) Path() string

Path returns the request URL path (without query string).

func (*Request) Protocol

func (req *Request) Protocol() string

Protocol returns "https" when the request arrived over TLS, else "http".

func (*Request) Query

func (req *Request) Query(name string) string

Query returns the first value of a query-string parameter.

func (*Request) QueryValues

func (req *Request) QueryValues() url.Values

QueryValues returns the parsed query string as url.Values.

func (*Request) Ranges

func (req *Request) Ranges(size int64) ([]Range, bool)

Ranges parses the request Range header against a resource of the given size, returning the satisfiable byte ranges. It returns (nil, false) when there is no Range header, and (nil, true) when the header is present but unsatisfiable.

func (*Request) Secure

func (req *Request) Secure() bool

Secure reports whether the request was made over a secure connection.

func (*Request) Session

func (req *Request) Session() *SessionData

Session returns the session attached to the request by the Session middleware, or nil if the middleware is not installed.

func (*Request) Set

func (req *Request) Set(key string, value any)

Set stores an arbitrary value on the request for downstream handlers.

func (*Request) SetBody

func (req *Request) SetBody(v any)

SetBody stores a parsed body value (used by body-parsing middleware).

func (*Request) SetPath

func (req *Request) SetPath(p string)

SetPath rewrites the request path and, crucially, the path used by the router to match routes. Middleware that rewrites URLs (rewrite, basepath, ...) must call SetPath rather than mutating req.Raw.URL.Path directly, so that route matching downstream sees the new path. It also updates req.Raw.URL.Path so handlers observe a consistent value.

func (*Request) Stale

func (req *Request) Stale(res *Response) bool

Stale is the negation of Fresh.

func (*Request) Value

func (req *Request) Value(key string) (any, bool)

Value retrieves a value previously stored with Set.

type Response

type Response struct {
	// Writer is the underlying standard-library response writer.
	Writer http.ResponseWriter

	// Locals holds values scoped to this request/response cycle, mirroring
	// Express's res.locals.
	Locals map[string]any
	// contains filtered or unexported fields
}

Response wraps an http.ResponseWriter and provides chainable Express-style helpers for setting status codes, headers, and writing bodies.

func (*Response) Append

func (res *Response) Append(field, value string) *Response

Append adds a value to an existing response header without replacing it.

func (*Response) Attachment

func (res *Response) Attachment(filename ...string) *Response

Attachment sets the Content-Disposition header to attachment. With a filename it also advertises the download name and sets a matching Content-Type.

func (*Response) ClearCookie

func (res *Response) ClearCookie(name string) *Response

ClearCookie expires a cookie on the client.

func (*Response) Cookie

func (res *Response) Cookie(name, value string, opts *CookieOptions) *Response

Cookie sets a Set-Cookie header. opts may be nil for a session cookie.

func (*Response) Download

func (res *Response) Download(path string, filename ...string) error

Download sends the file at path as an attachment, prompting the browser to save it. When filename is empty the base name of path is used.

func (*Response) ETag

func (res *Response) ETag(tag string) *Response

ETag sets a (strong) ETag header from an already-computed tag. The value is quoted if not already.

func (*Response) End

func (res *Response) End()

End finalizes the response with no (further) body.

func (*Response) Flush

func (res *Response) Flush() bool

Flush sends any buffered response data to the client immediately, if the underlying writer supports flushing. It commits the headers first. Returns true when a flush actually occurred.

func (*Response) Format

func (res *Response) Format(handlers map[string]func())

Format performs content negotiation, invoking the handler for the best type the client accepts. Keys are extensions or media types; a "default" key (or the first entry) is used when nothing matches. It responds 406 when there is no match and no default.

func (*Response) Fresh

func (res *Response) Fresh() bool

Fresh reports whether the current request is fresh against the headers set on this response (convenience wrapper around req.Fresh).

func (*Response) GetHeader

func (res *Response) GetHeader(field string) string

GetHeader returns a header value already set on the response.

func (*Response) JSON

func (res *Response) JSON(v any) *Response

JSON serializes v as JSON and writes it with an application/json Content-Type.

func (*Response) LastModified

func (res *Response) LastModified(t time.Time) *Response

LastModified sets the Last-Modified header from t.

func (*Response) Location

func (res *Response) Location(url string) *Response

Location sets the Location response header.

func (*Response) NotModified

func (res *Response) NotModified()

NotModified sends a 304 Not Modified with no body. Use it after setting ETag or Last-Modified when the request is fresh.

func (*Response) OnBeforeWrite

func (res *Response) OnBeforeWrite(fn func())

OnBeforeWrite registers a callback invoked once, immediately before the response headers are committed. Use it to set headers or cookies that depend on work done during the request (e.g. persisting a session).

func (*Response) Redirect

func (res *Response) Redirect(args ...any) *Response

Redirect sends a redirect response. If a status code is provided it is used; otherwise 302 Found is assumed.

func (*Response) Render

func (res *Response) Render(name string, data ...any) error

Render renders a view and sends it as HTML. The view name is resolved against the app's "views" directory and "view engine" setting. Optional data is passed to the template; when omitted, res.Locals is used.

func (*Response) SSE

func (res *Response) SSE() *SSEWriter

SSE prepares the response for Server-Sent Events (sets the text/event-stream headers and flushes them) and returns a writer for emitting events. The handler should keep running to push events, typically until req context is done.

func (*Response) Send

func (res *Response) Send(body any) *Response

Send writes a response body. Strings and []byte are written as-is; any other value is serialized as JSON. It sets a default Content-Type when none is set.

func (*Response) SendChunked

func (res *Response) SendChunked(data []byte, chunkSize int) error

SendChunked writes data to the client split into fixed-size chunks, flushing after each. Useful for pacing a large in-memory response.

func (*Response) SendFile

func (res *Response) SendFile(path string) error

SendFile sends the file at path to the client. It uses http.ServeContent under the hood, so it supports Range requests, conditional GET (If-Modified-Since / If-None-Match), and content-type detection by extension. Returns an error if the file cannot be opened.

func (*Response) SendStatus

func (res *Response) SendStatus(code int) *Response

SendStatus sets the status code and sends its standard text as the body.

func (*Response) SendStream

func (res *Response) SendStream(r io.Reader, chunkSize ...int) error

SendStream copies a reader to the client in chunks, flushing as it goes. It is suited to large or open-ended payloads where buffering the whole body in memory is undesirable. chunkSize defaults to 32 KiB when <= 0.

func (*Response) Set

func (res *Response) Set(field, value string) *Response

Set assigns a response header, returning the response for chaining.

func (*Response) Status

func (res *Response) Status(code int) *Response

Status sets the HTTP status code and returns the response for chaining.

func (*Response) StatusCode

func (res *Response) StatusCode() int

StatusCode returns the currently set status code.

func (*Response) Stream

func (res *Response) Stream(fn func(w io.Writer) error) error

Stream streams a response body produced by fn. fn receives a writer that flushes each write to the client, so data reaches the client incrementally. The Content-Type defaults to application/octet-stream when unset.

res.Stream(func(w io.Writer) error {
	for i := 0; i < 5; i++ {
		fmt.Fprintf(w, "chunk %d\n", i)
	}
	return nil
})

func (*Response) Type

func (res *Response) Type(t string) *Response

Type sets the Content-Type header. Common shorthands ("json", "html", "text") are expanded; anything containing a slash is used verbatim.

func (*Response) Vary

func (res *Response) Vary(field string) *Response

Vary adds a field to the Vary response header.

func (*Response) Write

func (res *Response) Write(p []byte) (int, error)

Write implements io.Writer, committing the status line and headers on the first call. This lets a *Response be used directly as a streaming sink, e.g. with io.Copy or fmt.Fprintf. When no Content-Length is set, net/http streams the body using chunked transfer-encoding automatically.

func (*Response) WriteChunk

func (res *Response) WriteChunk(p []byte) (int, error)

WriteChunk writes a chunk and immediately flushes it to the client — the building block for chunked streaming responses.

func (*Response) WriteString

func (res *Response) WriteString(s string) (int, error)

WriteString writes a string chunk (without flushing).

func (*Response) Written

func (res *Response) Written() bool

Written reports whether the response headers have been committed.

type Route

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

Route binds handlers for multiple HTTP methods to a single path.

func (*Route) All

func (rt *Route) All(h ...Handler) *Route

All registers handlers for every method on the route.

func (*Route) Delete

func (rt *Route) Delete(h ...Handler) *Route

Delete registers DELETE handlers on the route.

func (*Route) Get

func (rt *Route) Get(h ...Handler) *Route

Get registers GET handlers on the route.

func (*Route) Patch

func (rt *Route) Patch(h ...Handler) *Route

Patch registers PATCH handlers on the route.

func (*Route) Post

func (rt *Route) Post(h ...Handler) *Route

Post registers POST handlers on the route.

func (*Route) Put

func (rt *Route) Put(h ...Handler) *Route

Put registers PUT handlers on the route.

type RouteRegistrar

type RouteRegistrar interface {
	// Use mounts middleware, an error handler, or a sub-router, optionally
	// scoped to a leading path prefix.
	Use(args ...any) *Router
	// All registers handlers that run for every HTTP method matching path.
	All(path string, handlers ...Handler) *Router
	// Get registers handlers for GET requests to path.
	Get(path string, handlers ...Handler) *Router
	// Post registers handlers for POST requests to path.
	Post(path string, handlers ...Handler) *Router
	// Put registers handlers for PUT requests to path.
	Put(path string, handlers ...Handler) *Router
	// Delete registers handlers for DELETE requests to path.
	Delete(path string, handlers ...Handler) *Router
	// Patch registers handlers for PATCH requests to path.
	Patch(path string, handlers ...Handler) *Router
	// Head registers handlers for HEAD requests to path.
	Head(path string, handlers ...Handler) *Router
	// Options registers handlers for OPTIONS requests to path.
	Options(path string, handlers ...Handler) *Router
	// Query registers handlers for the QUERY method.
	Query(path string, handlers ...Handler) *Router
	// Param registers a route-parameter callback.
	Param(name string, fn ParamHandler) *Router
	// Route returns a Route for registering several methods on one path.
	Route(path string) *Route
}

RouteRegistrar is the route-registration surface shared by *Router and *Application. An Application embeds *Router, so both types expose exactly the same set of routing methods; capturing them in one interface documents that shared contract and lets helpers accept "anything routes can be registered on" — whether that is the top-level app or a sub-router — without depending on the concrete type.

Every method returns *Router (the receiver, or the embedded router for an Application) so registrations remain chainable.

type Router

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

Router is an isolated instance of middleware and routes. Applications embed a root Router, and additional routers can be created and mounted to compose modular route handlers.

func NewRouter

func NewRouter(opts ...RouterOptions) *Router

NewRouter creates an empty Router with optional options.

func (*Router) All

func (r *Router) All(path string, handlers ...Handler) *Router

All registers handlers that run for every HTTP method matching path.

func (*Router) Delete

func (r *Router) Delete(path string, handlers ...Handler) *Router

Delete registers handlers for DELETE requests to path.

func (*Router) Get

func (r *Router) Get(path string, handlers ...Handler) *Router

Get registers handlers for GET requests to path.

func (*Router) Head

func (r *Router) Head(path string, handlers ...Handler) *Router

Head registers handlers for HEAD requests to path.

func (*Router) Options

func (r *Router) Options(path string, handlers ...Handler) *Router

Options registers handlers for OPTIONS requests to path.

func (*Router) Param

func (r *Router) Param(name string, fn ParamHandler) *Router

Param registers a callback that runs when name is captured as a route parameter, once per request, before the matched route's handlers — the equivalent of Express's app.param(). Typical use is to load a record by id.

func (*Router) Patch

func (r *Router) Patch(path string, handlers ...Handler) *Router

Patch registers handlers for PATCH requests to path.

func (*Router) Post

func (r *Router) Post(path string, handlers ...Handler) *Router

Post registers handlers for POST requests to path.

func (*Router) Put

func (r *Router) Put(path string, handlers ...Handler) *Router

Put registers handlers for PUT requests to path.

func (*Router) Query

func (r *Router) Query(path string, handlers ...Handler) *Router

Query registers handlers for the HTTP QUERY method (https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-latest.html), a safe, idempotent method that carries a request body — like GET, but with a payload used to describe the query. Express added app.query() for it; this is the Go equivalent.

func (*Router) Route

func (r *Router) Route(path string) *Route

Route returns a Route bound to path, allowing several HTTP methods to be registered for the same path in a chain — the equivalent of app.route(path):

app.Route("/users").
	Get(list).
	Post(create)

func (*Router) Use

func (r *Router) Use(args ...any) *Router

Use mounts middleware, optionally scoped to a path prefix. It accepts an optional leading string path followed by any mix of Handler, ErrorHandler, and *Router values:

app.Use(logger)                  // app-wide middleware
app.Use("/api", apiRouter)       // mount a sub-router at /api
app.Use(errorHandler)            // error-handling middleware

type RouterOptions

type RouterOptions struct {
	// CaseSensitive makes route matching case-sensitive ("/Foo" != "/foo").
	// The default (false) matches case-insensitively, like Express.
	CaseSensitive bool
	// Strict enables strict routing, distinguishing "/foo" from "/foo/".
	// The default (false) treats a trailing slash as optional.
	Strict bool
	// MergeParams makes a mounted sub-router inherit the parameters captured by
	// its parent (e.g. a :userId in the mount path). The default (false) scopes
	// each router to its own parameters.
	MergeParams bool
}

RouterOptions configures a Router, mirroring Express's router options.

type SSEWriter

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

SSEWriter writes Server-Sent Events to the client. Obtain one with res.SSE().

func (*SSEWriter) Comment

func (s *SSEWriter) Comment(text string) error

Comment emits an SSE comment line (often used as a keep-alive heartbeat).

func (*SSEWriter) Retry

func (s *SSEWriter) Retry(ms int) error

Retry tells the client how long (in ms) to wait before reconnecting.

func (*SSEWriter) Send

func (s *SSEWriter) Send(event, data string) error

Send emits a named event with a data payload. Multi-line data is split into multiple data: lines per the SSE spec.

func (*SSEWriter) SendData

func (s *SSEWriter) SendData(data string) error

SendData emits an unnamed (message) event carrying data.

func (*SSEWriter) SendID

func (s *SSEWriter) SendID(id, event, data string) error

SendID emits an event that also sets the SSE id field (for Last-Event-ID resumption).

func (*SSEWriter) SendJSON

func (s *SSEWriter) SendJSON(event string, v any) error

SendJSON marshals v to JSON and emits it as a named event.

type SessionData

type SessionData struct {
	// Values holds the session data.
	Values map[string]any
	// contains filtered or unexported fields
}

SessionData is the per-request session object exposed to handlers via req.Session(). Values are read and written with Get/Set; changes are persisted automatically before the response is sent.

func (*SessionData) Delete

func (s *SessionData) Delete(key string)

Delete removes a session value.

func (*SessionData) Destroy

func (s *SessionData) Destroy()

Destroy marks the session for removal; the cookie is cleared on response.

func (*SessionData) Get

func (s *SessionData) Get(key string) (any, bool)

Get returns a session value and whether it was present.

func (*SessionData) GetString

func (s *SessionData) GetString(key string) string

GetString returns a string session value, or "" if missing / not a string.

func (*SessionData) Regenerate

func (s *SessionData) Regenerate() error

Regenerate issues a fresh session id, discarding the old one. Call this on privilege changes such as login to defeat session fixation.

func (*SessionData) Set

func (s *SessionData) Set(key string, value any)

Set stores a session value and marks the session dirty.

type SessionOptions

type SessionOptions struct {
	// Name is the session cookie name (default "connect.sid").
	Name string
	// Store persists sessions (default an in-memory store).
	Store SessionStore
	// Secure marks the cookie Secure (HTTPS only).
	Secure bool
	// HTTPOnly marks the cookie HttpOnly (default true).
	HTTPOnly bool
	// SameSite sets the cookie SameSite policy (default Lax).
	SameSite http.SameSite
	// MaxAge sets the cookie Max-Age in seconds (0 = session cookie).
	MaxAge int
}

SessionOptions configures the session middleware.

type SessionStore

type SessionStore interface {
	Get(id string) (map[string]any, bool)
	Set(id string, data map[string]any)
	Destroy(id string)
}

SessionStore persists session data keyed by an opaque id. Implementations must be safe for concurrent use.