methodoverride

Documentation

Overview

Package methodoverride provides HTTP method override middleware for celeris.

HTML forms can only submit GET and POST requests. This middleware allows clients to tunnel PUT, PATCH, DELETE, and other methods through a POST request by specifying the intended method in a header or form field.

IMPORTANT: Use Server.Pre(), Not Server.Use()

This middleware MUST be registered via celeris.Server.Pre, not celeris.Server.Use. With Server.Use, the router has already matched the request based on the original method, making the override ineffective. Using Server.Use will silently produce wrong routing behavior.

Register the middleware with celeris.Server.Pre so the method is rewritten before routing:

s := celeris.New()
s.Pre(methodoverride.New())

Override Sources

By default, the middleware checks the form field DefaultFormField ("_method") first, then the header DefaultHeader ("X-HTTP-Method-Override"). Only POST requests are eligible for override (configurable via Config.AllowedMethods).

Custom Getters

Use HeaderGetter to read from a specific header only:

s.Pre(methodoverride.New(methodoverride.Config{
    Getter: methodoverride.HeaderGetter("X-Method"),
}))

Use FormFieldGetter to read from a specific form field only:

s.Pre(methodoverride.New(methodoverride.Config{
    Getter: methodoverride.FormFieldGetter("_http_method"),
}))

Use FormThenHeaderGetter to check a custom form field first, then a custom header (same order as the default getter but with custom names):

s.Pre(methodoverride.New(methodoverride.Config{
    Getter: methodoverride.FormThenHeaderGetter("_method", "X-HTTP-Method"),
}))

QueryGetter reads from a URL query parameter. This is provided for parity with Echo but carries security risks: query parameters are embeddable in links and images, potentially enabling cross-site method override attacks. Use only when the security implications are understood.

Target Methods

By default, only PUT, DELETE, and PATCH are valid override targets (configurable via Config.TargetMethods). Override values not in this list are silently ignored, preventing clients from overriding to arbitrary methods such as CONNECT or TRACE.

Validation

Config.AllowedMethods and Config.TargetMethods must not contain empty or whitespace-only strings. The middleware panics at initialization if this constraint is violated.

Skipping

Set Config.Skip to bypass the middleware dynamically, or Config.SkipPaths for exact-match path exclusions.

CSRF Middleware Interaction

Method override changes the request method before CSRF middleware runs. Ensure that overridden methods (PUT, DELETE, PATCH) are NOT in the CSRF middleware's SafeMethods list. See middleware/csrf documentation for details.

Index

• Constants
• func FormFieldGetter(field string) func(*celeris.Context) string
• func FormThenHeaderGetter(field, header string) func(*celeris.Context) string
• func HeaderGetter(header string) func(*celeris.Context) string
• func New(config ...Config) celeris.HandlerFunc
• func QueryGetter(param string) func(*celeris.Context) string
• type Config

Examples

• New
• New (CustomTargets)
• New (FormFieldOnly)
• New (FormThenHeader)
• New (HeaderOnly)
• New (QueryGetter)

Constants

const (
	// DefaultHeader is the default HTTP header checked for method override.
	DefaultHeader = "X-HTTP-Method-Override"

	// DefaultFormField is the default form field checked for method override.
	DefaultFormField = "_method"
)

Functions

func FormFieldGetter

func FormFieldGetter(field string) func(*celeris.Context) string

FormFieldGetter returns a getter that reads the override method from the given form field.

func FormThenHeaderGetter

func FormThenHeaderGetter(field, header string) func(*celeris.Context) string

FormThenHeaderGetter checks the form field first, then the header. This matches the default getter order with custom field/header names.

func HeaderGetter

func HeaderGetter(header string) func(*celeris.Context) string

HeaderGetter returns a getter that reads the override method from the given HTTP header. The header name is lowercased for lookup.

func New

func New(config ...Config) celeris.HandlerFunc

New creates a method override middleware with the given config. The middleware reads an overridden HTTP method from a configurable source (header, form field, or custom getter) and rewrites the request method before routing. Only POST requests are rewritten by default.

Example

package main

import (
	"github.com/goceleris/celeris/middleware/methodoverride"
)

func main() {
	// Register via server.Pre() for pre-routing method override.
	// s := celeris.New()
	// s.Pre(methodoverride.New())
	_ = methodoverride.New()
}

Example (CustomTargets)

package main

import (
	"github.com/goceleris/celeris/middleware/methodoverride"
)

func main() {
	_ = methodoverride.New(methodoverride.Config{
		TargetMethods: []string{"PUT", "DELETE", "PATCH", "GET"},
	})
}

Example (FormFieldOnly)

package main

import (
	"github.com/goceleris/celeris/middleware/methodoverride"
)

func main() {
	// Override from a custom form field only.
	_ = methodoverride.New(methodoverride.Config{
		Getter: methodoverride.FormFieldGetter("_http_method"),
	})
}

Example (FormThenHeader)

package main

import (
	"github.com/goceleris/celeris/middleware/methodoverride"
)

func main() {
	// Check form field first, then header (custom names).
	_ = methodoverride.New(methodoverride.Config{
		Getter: methodoverride.FormThenHeaderGetter("_method", "X-HTTP-Method"),
	})
}

Example (HeaderOnly)

package main

import (
	"github.com/goceleris/celeris/middleware/methodoverride"
)

func main() {
	// Override from a custom header only.
	_ = methodoverride.New(methodoverride.Config{
		Getter: methodoverride.HeaderGetter("X-Method"),
	})
}

Example (QueryGetter)

package main

import (
	"github.com/goceleris/celeris/middleware/methodoverride"
)

func main() {
	// Read override from ?_method query parameter.
	// Security: query params are embeddable in links; use with caution.
	_ = methodoverride.New(methodoverride.Config{
		Getter: methodoverride.QueryGetter("_method"),
	})
}

func QueryGetter

func QueryGetter(param string) func(*celeris.Context) string

QueryGetter returns a getter that reads the override method from the given query parameter. Use with caution: query-based overrides are vulnerable to cross-site attacks via embeddable URLs (e.g., <img src="...?_method=DELETE">). Prefer HeaderGetter for API clients.

Types

type Config

type Config struct {
	// Skip defines a function to skip this middleware for certain requests.
	Skip func(c *celeris.Context) bool

	// SkipPaths lists paths to skip (exact match on c.Path()).
	SkipPaths []string

	// AllowedMethods lists the original HTTP methods eligible for override.
	// Default: ["POST"]. Must not contain empty or whitespace-only strings.
	AllowedMethods []string

	// TargetMethods lists the HTTP methods that can be used as override targets.
	// Override values not in this list are silently ignored.
	// Default: ["PUT", "DELETE", "PATCH"].
	TargetMethods []string

	// Getter extracts the override method from the request. The returned
	// string should be an HTTP method name (e.g. "PUT", "DELETE"). An
	// empty return value means no override.
	// Default: [defaultGetter] (checks form field [DefaultFormField] first,
	// then header [DefaultHeader]).
	Getter func(c *celeris.Context) string
}

Config defines the method override middleware configuration.