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 NewDropQuery() filters.Spec
• func NewDropRequestHeader() filters.Spec
• func NewDropResponseHeader() filters.Spec
• func NewHealthCheck() filters.Spec
• func NewModPath() filters.Spec
• func NewRedirect() filters.Spec
• func NewRedirectLower() filters.Spec
• func NewRedirectTo() filters.Spec
• func NewRequestHeader() filters.Spec
• func NewResponseHeader() filters.Spec
• func NewSetPath() filters.Spec
• func NewSetQuery() 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
• func Redirect(ctx filters.FilterContext, code int, location *url.URL)

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"
	SetPathName         = "setPath"
	RedirectToName      = "redirectTo"
	RedirectToLowerName = "redirectToLower"
	StaticName          = "static"
	StripQueryName      = "stripQuery"
	PreserveHostName    = "preserveHost"
	StatusName          = "status"
	CompressName        = "compress"
	SetQueryName        = "setQuery"
	DropQueryName       = "dropQuery"
)

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 NewDropQuery

func NewDropQuery() filters.Spec

Returns a new dropQuery filter Spec, whose instances drop a corresponding query parameter.

As an EXPERIMENTAL feature: the dropQuery filter provides the possiblity to apply template operations. The current solution supports templates with placeholders of the format: ${param1}, and the placeholders will be replaced with the values of the same name from the wildcards in the Path() predicate. The templating feature will stay in Skipper, but the syntax of the templating may change.

See also: https://github.com/zalando/skipper/issues/182

Name: "dropQuery".

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.ReplaceAllString on the request path. Instances expect two parameters: the expression to match and the replacement string. Name: "modpath".

func NewRedirect

func NewRedirect() filters.Spec

NewRedirect 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 NewRedirectLower

func NewRedirectLower() filters.Spec

NewRedirectLower returns a new filter Spec, whose instances create an HTTP redirect response, which redirects with a lowercase path. It is similar to redTo except that it converts the route path to lower while redirecting Name: "redirectToLower".

func NewRedirectTo

func NewRedirectTo() filters.Spec

NewRedirectTo 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 NewSetPath

func NewSetPath() filters.Spec

Returns a new setPath filter Spec, whose instances replace the request path.

As an EXPERIMENTAL feature: the setPath filter provides the possiblity to apply template operations. The current solution supports templates with placeholders of the format: ${param1}, and the placeholders will be replaced with the values of the same name from the wildcards in the Path() predicate.

See: https://godoc.org/github.com/zalando/skipper/routing#hdr-Wildcards

The templating feature will stay in Skipper, but the syntax of the templating may change.

See also: https://github.com/zalando/skipper/issues/182

Instances expect one parameter: the new path to be set, or the path template to be evaluated.

Name: "setPath".

func NewSetQuery

func NewSetQuery() filters.Spec

Returns a new setQuery filter Spec, whose instances replace the query parameters.

As an EXPERIMENTAL feature: the setPath filter provides the possiblity to apply template operations. The current solution supports templates with placeholders of the format: ${param1}, and the placeholders will be replaced with the values of the same name from the wildcards in the Path() predicate.

See: https://godoc.org/github.com/zalando/skipper/routing#hdr-Wildcards

The templating feature will stay in Skipper, but the syntax of the templating may change.

See also: https://github.com/zalando/skipper/issues/182

Instances expect two parameters: the name and the value to be set, either strings or templates are valid.

Name: "setQuery".

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.

func Redirect

func Redirect(ctx filters.FilterContext, code int, location *url.URL)

Redirect implements the redirect logic as a standalone function.