bayou.form

Class FormParser

java.lang.Object

bayou.form.FormParser

public class FormParser
extends Object

Parses form data from http requests. See parse(uri) and parse(request).

See also FormData.parse(uri) and FormData.parse(request) which use this parser with default configuration.

Config

A parser can be configured by methods like charset(Charset). These methods return `this` for method chaining. For example

     FormParser parser = new FormParser()
         .charset(StandardCharsets.US_ASCII)
         .maxFileEntries(3)
         ;

     parser.parse(...);
 

A parser can be cached to parse multiple requests concurrently, as long as its configuration is no longer modified.

     static final FormParser parser = new FormParser().maxFileEntries(0); // disallow file upload
 

CSRF Detection

By default, detectCsrf is enabled. If a request is POST, parse(request) uses the following heuristics to determine that the request is not CSRF.

• The CSRF token in the form field matches the token in the cookie. See csrfTokenName(String) and CsrfToken.
• The "Origin" request header matches the "Host" header, e.g. "Origin: http://localhost:8080".
• The "Referer" request header matches the "Host" header, e.g. "Referer: http://localhost:8080/show".

Otherwise, parse(request) fails with CsrfException. Note that false detection is possible - the request is suspected as CSRF while in reality it is legitimate. See Generate a response for a CsrfException

Constructor Summary

Constructors

Constructor and Description
FormParser() Create a parser with default settings.

Method Summary

Instance Methods
FormData	parse(CharSequence uri) Parse the URI for form data.
Async<FormData>	parse(HttpRequest request) Parse the request for POST form data.
FormParser	charset(Charset charset) The charset, used for decoding bytes to chars.
FormParser	detectCsrf(boolean detectCsrf) Whether to detect CSRF.
FormParser	csrfTokenName(String csrfTokenName) The name of the CSRF token.
FormParser	maxEntryKeyBytes(int maxEntryKeyBytes) Max length of any entry key, in bytes.
FormParser	maxParamEntries(int maxParamEntries) Max number of parameter entries.
FormParser	maxParamValueTotalBytes(long maxParamValueTotalBytes) Max length of all parameter values combined, in bytes
FormParser	maxFileEntries(int maxFileEntries) Max number of file entries
FormParser	maxFileNameBytes(int maxFileNameBytes) Max length of filename in any file entry, in bytes.
FormParser	maxFileSize(long maxFileSize) Max size of any file.
FormParser	tmpFileDir(String tmpFileDir) The tmp dir for storing files.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FormParser

public FormParser()

Create a parser with default settings.

Use methods like charset(Charset) to configure the parser after construction.

Method Detail

parse

public FormData parse(CharSequence uri)
               throws ParseException,
                      OverLimitException

Parse the URI for form data.

The query component of the URI is expected to be "application/x-www-form-urlencoded".

This method can be used for any request URI, regardless of the request method.

Throws:

ParseException - the query component of the URI is not valid "application/x-www-form-urlencoded".

OverLimitException - a conf limit is exceeded, for example "maxParamEntries"

parse

public Async<FormData> parse(HttpRequest request)

Parse the request for POST form data.

If the request method is POST, and the Content-Type is "multipart/form-data" or "application/x-www-form-urlencoded", the request body is parsed accordingly.

This is an Async action. The action may fail with the following exceptions:

• ParseException - the request does not contain valid POST form data
• OverLimitException - a conf limit is exceeded, for example "maxParamEntries"
• CsrfException - the request is suspected to be CSRF
• Exception - other errors, e.g. network error while reading request body

charset

public FormParser charset(Charset charset)

The charset, used for decoding bytes to chars.

default: UTF-8

Returns:

`this`

detectCsrf

public FormParser detectCsrf(boolean detectCsrf)

Whether to detect CSRF.

default: true

Returns:

`this`

csrfTokenName

public FormParser csrfTokenName(String csrfTokenName)

The name of the CSRF token.

default: CsrfToken.DEFAULT_NAME

Returns:

`this`

maxEntryKeyBytes

public FormParser maxEntryKeyBytes(int maxEntryKeyBytes)

Max length of any entry key, in bytes.

default: 64

Returns:

`this`

maxParamEntries

public FormParser maxParamEntries(int maxParamEntries)

Max number of parameter entries.

default: 256

Returns:

`this`

maxParamValueTotalBytes

public FormParser maxParamValueTotalBytes(long maxParamValueTotalBytes)

Max length of all parameter values combined, in bytes

default: 16*1024 (16KB)

Returns:

`this`

maxFileEntries

public FormParser maxFileEntries(int maxFileEntries)

Max number of file entries

default: 1

Returns:

`this`

maxFileNameBytes

public FormParser maxFileNameBytes(int maxFileNameBytes)

Max length of filename in any file entry, in bytes.

default: 256

Returns:

`this`

maxFileSize

public FormParser maxFileSize(long maxFileSize)

Max size of any file.

default: 16*1024*1024 (16MB)

Returns:

`this`

tmpFileDir

public FormParser tmpFileDir(String tmpFileDir)

The tmp dir for storing files.

default: "/tmp/bayou/form_data_files"

Returns:

`this`