builtin

Documentation

Overview

Package builtin provides a small, generic set of filters.

Index

• Constants
• func MakeRegistry() filters.Registry
• func NewAppendRequestHeader() filters.Spec
• func NewAppendResponseHeader() filters.Spec
• func NewCompress() filters.Spec
• func NewDropRequestHeader() filters.Spec
• func NewDropResponseHeader() filters.Spec
• func NewHealthCheck() filters.Spec
• func NewModPath() filters.Spec
• func NewRedirect() filters.Spec
• func NewRedirectTo() filters.Spec
• func NewRequestHeader() filters.Spec
• func NewResponseHeader() filters.Spec
• func NewSetRequestHeader() filters.Spec
• func NewSetResponseHeader() filters.Spec
• func NewStatic() filters.Spec
• func NewStatus() filters.Spec
• func NewStripQuery() filters.Spec
• func PreserveHost() filters.Spec

Constants

const (
	// Deprecated: use setRequestHeader or appendRequestHeader
	RequestHeaderName = "requestHeader"

	// Deprecated: use setRequestHeader or appendRequestHeader
	ResponseHeaderName = "responseHeader"

	// Deprecated: use redirectTo
	RedirectName = "redirect"

	SetRequestHeaderName     = "setRequestHeader"
	SetResponseHeaderName    = "setResponseHeader"
	AppendRequestHeaderName  = "appendRequestHeader"
	AppendResponseHeaderName = "appendResponseHeader"
	DropRequestHeaderName    = "dropRequestHeader"
	DropResponseHeaderName   = "dropResponseHeader"

	HealthCheckName  = "healthcheck"
	ModPathName      = "modPath"
	RedirectToName   = "redirectTo"
	StaticName       = "static"
	StripQueryName   = "stripQuery"
	PreserveHostName = "preserveHost"
	StatusName       = "status"
	CompressName     = "compress"
)

Functions

func MakeRegistry

func MakeRegistry() filters.Registry

Returns a Registry object initialized with the default set of filter specifications found in the filters package. (including the builtin and the flowid subdirectories.)

func NewAppendRequestHeader

func NewAppendRequestHeader() filters.Spec

Returns a filter specification that is used to append headers for requests. Instances expect two parameters: the header name and the header value. Name: "appendRequestHeader".

If the header name is 'Host', the filter uses the `SetOutgoingHost()` method to set the header in addition to the standard `Request.Header` map.

func NewAppendResponseHeader

func NewAppendResponseHeader() filters.Spec

Returns a filter specification that is used to append headers for responses. Instances expect two parameters: the header name and the header value. Name: "appendResponseHeader".

func NewCompress

func NewCompress() filters.Spec

Returns a filter specification that is used to compress the response content.

Example:

• -> compress() -> "https://www.example.org"

The filter, when executed on the response path, checks if the response entity can be compressed. To decide, it checks the Content-Encoding, the Cache-Control and the Content-Type headers. It doesn't compress the content if the Content-Encoding is set to other than identity, or the Cache-Control applies the no-transform pragma, or the Content-Type is set to an unsupported value.

The default supported content types are: text/plain, text/html, application/json, application/javascript, application/x-javascript, text/javascript, text/css, image/svg+xml, application/octet-stream.

The default set of MIME types can be reset or extended by passing in the desired types as filter arguments. When extending the defaults, the first argument needs to be "...". E.g. to compress tiff in addition to the defaults:

• -> compress("...", "image/tiff") -> "https://www.example.org"

To reset the supported types, e.g. to compress only HTML, the "..." argument needs to be omitted:

• -> compress("text/html") -> "https://www.example.org"

It is possible to control the compression level, by setting it as the first filter argument, in front of the MIME types. The default compression level is best-speed. The possible values are integers between 0 and 9 (inclusive), where 0 means no-compression, 1 means best-speed and 9 means best-compression. Example:

• -> compress(9, "image/tiff") -> "https://www.example.org"

The filter also checks the incoming request, if it accepts the supported encodings, explicitly stated in the Accept-Encoding header. The filter currently supports gzip and deflate. It does not assume that the client accepts any encoding if the Accept-Encoding header is not set. It ignores * in the Accept-Encoding header.

When compressing the response, it updates the response header. It deletes the the Content-Length value triggering the proxy to always return the response with chunked transfer encoding, sets the Content-Encoding to the selected encoding and sets the Vary: Accept-Encoding header, if missing.

The compression happens in a streaming way, using only a small internal buffer.

func NewDropRequestHeader

func NewDropRequestHeader() filters.Spec

Returns a filter specification that is used to delete headers for requests. Instances expect one parameter: the header name. Name: "dropRequestHeader".

func NewDropResponseHeader

func NewDropResponseHeader() filters.Spec

Returns a filter specification that is used to delete headers for responses. Instances expect one parameter: the header name. Name: "dropResponseHeader".

func NewHealthCheck

func NewHealthCheck() filters.Spec

Creates a new filter Spec, whose instances set the status code of the response to 200 OK. Name: "healthcheck".

func NewModPath

func NewModPath() filters.Spec

Returns a new modpath filter Spec, whose instances execute regexp.ReplaceAll on the request path. Instances expect two parameters: the expression to match and the replacement string. Name: "modpath".

func NewRedirect

func NewRedirect() filters.Spec

Returns a new filter Spec, whose instances create an HTTP redirect response. Marks the request as served. Instances expect two parameters: the redirect status code and the redirect location. Name: "redirect".

This filter is deprecated, use RedirectTo instead.

func NewRedirectTo

func NewRedirectTo() filters.Spec

Returns a new filter Spec, whose instances create an HTTP redirect response. It shunts the request flow, meaning that the filter chain on the request path is not continued. The request is not forwarded to the backend. Instances expect two parameters: the redirect status code and the redirect location. Name: "redirectTo".

func NewRequestHeader

func NewRequestHeader() filters.Spec

Deprecated: use setRequestHeader or appendRequestHeader

func NewResponseHeader

func NewResponseHeader() filters.Spec

Deprecated: use setRequestHeader or appendRequestHeader

func NewSetRequestHeader

func NewSetRequestHeader() filters.Spec

Returns a filter specification that is used to set headers for requests. Instances expect two parameters: the header name and the header value. Name: "setRequestHeader".

If the header name is 'Host', the filter uses the `SetOutgoingHost()` method to set the header in addition to the standard `Request.Header` map.

func NewSetResponseHeader

func NewSetResponseHeader() filters.Spec

Returns a filter specification that is used to set headers for responses. Instances expect two parameters: the header name and the header value. Name: "setResponseHeader".

func NewStatic

func NewStatic() filters.Spec

Returns a filter Spec to serve static content from a file system location. Behaves similarly to net/http.FileServer. It shunts the route.

Filter instances of this specification expect two parameters: a request path prefix and a local directory path. When processing a request, it clips the prefix from the request path, and appends the rest of the path to the directory path. Then, it uses the resulting path to serve static content from the file system.

Name: "static".

func NewStatus

func NewStatus() filters.Spec

Creates a filter specification whose instances set the status of the response to a fixed value regardless of backend response.

func NewStripQuery

func NewStripQuery() filters.Spec

Returns a filter Spec to strip query parameters from the request and optionally transpose them to request headers.

It always removes the query parameter from the request URL, and if the first filter parameter is "true", preserves the query parameter in the form of x-query-param-<queryParamName>: <queryParamValue> headers, so that ?foo=bar becomes x-query-param-foo: bar

Name: "stripQuery".

func PreserveHost

func PreserveHost() filters.Spec

Returns a filter specification whose filter instances are used to override the `proxyPreserveHost` behavior for individual routes.

Instances expect one argument, with the possible values: "true" or "false", where "true" means to use the Host header from the incoming request, and "false" means to use the host from the backend address.

The filter takes no effect in either case if another filter modifies the outgoing host header to a value other than the one in the incoming request or in the backend address.