This document explains how to set up http servers and filters in the Container.
Before proceeding, familiarize with the Developer Guide.
Set up Http servers
To accept http requests on e.g. port 8090, add an http section with a server to services.xml:
To verify that the new server is running, check the default handler on the root path,
which will return a list of all http servers:
$ curl http://localhost:8090/
Adding an http section to services.xmldisables the default http server at port 8080.
Binding to privileged ports (< 1024) is supported.
Note that this only works when running as a standalone container,
and not when running as a Vespa cluster.
Configure the HTTP Server
Configuration settings for the server can be modified by setting values for the
jdisc.http.connector config inside the server element:
Note that it is not allowed to set the listenPort in the http-server config,
as it conflicts with the port that is set in the port attribute in the server element.
For a complete list of configuration fields that can be set, refer to the config definition schema in
Request filters run before the handler that processes the request, and response filters run after.
They are used for tasks such as authentication, error checking and modifying headers.
Using Filter Chains
Filter chains are set up by using the request-chain and
response-chain elements inside the
Example setting up two request filter chains, and one response filter chain:
Filters that should be used in more than one chain,
must be defined directly in the filtering element,
as shown with request-filter1 in the example above.
To actually use a filter chain, add one or more URI bindings:
These bindings say that both the request chain and the response chain
should be used when the request URI matches http://*/*.
So both a request filter chain and a response filter chain can be used on a single request.
However, only one request chain will be used if there are multiple request chains
that have a binding that matches a request.
And vice versa for response chains.
Refer to the
javadoc for information about which chain that will be used in such cases.
In order to bind a filter chain to a specific server, add the server port to the binding:
A request must match a filter chain if any filter is configured. A 403 response is returned for non-matching request.
This semantic can be disabled - see strict-mode.
Excluding Filters from an Inherited Chain
Say you have a request filter chain that you are binding to most of your URIs.
Now, you want to run almost the same chain on another URI, but you need to exclude one of the filters.
This is done by adding excludes, which takes a space separated list of filter ids,
to the chain element.
Example where a security filter is excluded from an inherited chain for status.html:
Creating a custom Filter
Create an application package
with artifactId filter-bundle.
Create a new file filter-bundle/components/src/main/java/com/yahoo/demo/TestRequestFilter.java: