methodoverride

package
v14.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: BSD-3-Clause, BSD-3-Clause Imports: 5 Imported by: 0

README

HTTP Method Override

Some clients can only send GET and POST. An HTML form is the common case: it cannot issue a PUT or a DELETE. This middleware reads the intended method from a header, a form field, or a query parameter, and rewrites the request method before routing, so one handler registered on PUT serves both a real PUT and a POST that asked for one.

Features of Iris Method Override Middleware

The Iris method override middleware offers a variety of features to handle HTTP method overriding efficiently. These features include:

  1. Customizable Methods: Define which HTTP methods can be overridden.
  2. Custom Headers: Specify custom headers to determine the method override.
  3. Form Field Support: Use form fields to specify the method override.
  4. Query Parameter Support: Use query parameters to specify the method override.
  5. Save Original Method: Optionally save the original HTTP method for later use.

Installation

To use the Iris method override middleware, you need to import it in your Iris application:

import "github.com/kataras/iris/v14/middleware/methodoverride"

Usage

Basic Setup

To use the method override middleware, you need to import the necessary packages and configure the middleware in your Iris application. Here is a basic example:

package main

import (
	"github.com/kataras/iris/v14"
	"github.com/kataras/iris/v14/middleware/methodoverride"
)

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

	// Create the method override middleware
	mo := methodoverride.New(methodoverride.Options{
		SaveOriginalMethodContextKey: "_originalMethod",
	})

	// Register the middleware with UseRouter
	app.UseRouter(mo)

	app.Post("/path", func(ctx iris.Context) {
		ctx.WriteString("POST response")
	})

	app.Delete("/path", func(ctx iris.Context) {
		ctx.WriteString("DELETE response")
	})

	app.Listen(":8080")
}
Customizable Methods

You can define which HTTP methods can be overridden using the Methods option. By default, only the POST method can be overridden. Here is an example:

mo := methodoverride.New(methodoverride.Options{
	Methods: []string{"POST", "PUT"},
})
Custom Headers

You can specify custom headers to determine the method override using the Headers option. By default, the middleware checks the following headers: X-HTTP-Method, X-HTTP-Method-Override, and X-Method-Override. Here is an example:

mo := methodoverride.New(methodoverride.Options{
	Headers: []string{"X-Custom-Method"},
})
Form Field Support

You can use form fields to specify the method override using the FormField option. By default, the middleware checks the _method form field. Here is an example:

mo := methodoverride.New(methodoverride.Options{
	FormField: "_method",
})
Query Parameter Support

You can use query parameters to specify the method override using the Query option. By default, the middleware checks the _method query parameter. Here is an example:

mo := methodoverride.New(methodoverride.Options{
	Query: "_method",
})
Save Original Method

You can optionally save the original HTTP method for later use with SaveOriginalMethodContextKey. Here is an example:

mo := methodoverride.New(methodoverride.Options{
	SaveOriginalMethodContextKey: "_originalMethod",
})

A cross-site form POST needs no preflight and carries the victim's cookies, so the default _method query and form lookups let a hostile page reach a DELETE-only route. Set HeadersOnly to accept the override from a request header alone, which a browser cannot set cross-site without a preflight:

mo := methodoverride.New(methodoverride.Options{
	HeadersOnly: true,
})
Example

Here is a complete example demonstrating how to use the method override middleware with an Iris application:

package main

import (
	"github.com/kataras/iris/v14"
	"github.com/kataras/iris/v14/middleware/methodoverride"
)

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

	// Create the method override middleware
	mo := methodoverride.New(methodoverride.Options{
		SaveOriginalMethodContextKey: "_originalMethod",
	})

	// Register the middleware with UseRouter
	app.UseRouter(mo)

	app.Post("/path", func(ctx iris.Context) {
		ctx.WriteString("POST response")
	})

	app.Delete("/path", func(ctx iris.Context) {
		ctx.WriteString("DELETE response")
	})

	app.Listen(":8080")
}

Documentation

Overview

Package methodoverride lets clients that cannot issue PUT, PATCH or DELETE send a POST carrying the intended method instead.

Its entry point is New(Options), which returns a Handler to register with Application.UseRouter. Read the SECURITY WARNING on New before using the zero-value Options.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func New

func New(opts Options) context.Handler

New returns a new method override wrapper which can be registered with `Application.UseRouter`.

Use this wrapper when you expecting clients that do not support certain HTTP operations such as DELETE or PUT for security reasons. This wrapper will accept a method, based on criteria, to override the POST method with.

Read more at: https://github.com/kataras/iris/issues/1325 SECURITY WARNING: the defaults accept "_method" from the QUERY STRING and the FORM BODY, not only from a header.

A cross-site form POST needs no preflight and carries the victim's cookies, so

<form method="POST" action="https://victim/api/account?_method=DELETE">

reaches a route that only accepts DELETE - a route whose author may well have assumed a browser could never make a cross-site DELETE. A custom header does force a preflight, which is why HeadersOnly is the safe configuration:

app.UseRouter(methodoverride.New(methodoverride.Options{HeadersOnly: true}))

The defaults are kept for backwards compatibility. Only POST is overridable, so a GET can never be turned into a DELETE.

Types

type GetterFunc

type GetterFunc func(*context.Context) string

GetterFunc is the type signature for declaring custom logic to extract the method name which a POST request will be replaced with.

type Options

type Options struct {
	// Methods are the request methods that may be overridden.
	//
	// Defaults to POST only. Values are upper-cased.
	// Set to a non-nil empty slice to disable overriding entirely, which leaves
	// the middleware registered but inert.
	Methods []string

	// Headers a client can send to specify the method to override with,
	// checked in order and before FormField and Query.
	//
	// Defaults to X-HTTP-Method, X-HTTP-Method-Override and X-Method-Override.
	// Set to a non-nil empty slice to never read the method from a header.
	Headers []string

	// HeadersOnly restricts the override to the request headers, which a browser
	// cannot set cross-site without a preflight: FormField and Query are ignored.
	//
	// This is the recommended configuration; see the SECURITY WARNING on New.
	//
	// Defaults to false.
	HeadersOnly bool

	// FormField is the form field carrying the method to override with,
	// checked after Headers.
	//
	// Example field:
	//	<input type="hidden" name="_method" value="DELETE">
	//
	// Defaults to "_method". Ignored when HeadersOnly is true.
	FormField string

	// Query is the URL query parameter carrying the method to override with,
	// checked after FormField.
	//
	// Example URL query string:
	//	http://localhost:8080/path?_method=DELETE
	//
	// Defaults to "_method". Ignored when HeadersOnly is true.
	Query string

	// Getters are custom extractors, consulted in order after the built-in ones.
	// The first non-empty return value wins.
	//
	// Defaults to nil.
	Getters []GetterFunc

	// SaveOriginalMethodContextKey, when not empty, saves the original request
	// method on Context.Values() under this key; read it back with
	// ctx.Values().GetString(key).
	//
	// Defaults to empty: the original method is not saved.
	SaveOriginalMethodContextKey string
}

Options holds the configuration of the method override wrapper. The zero value is valid and reproduces the defaults documented on each field.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL