Flow action default-request

The default-request action is the standard way to obtain the main content.

Syntax

This action is not configurable.

Example:

<flow>
  <default-request [force-query-rebuild="true"]/>
</flow>

Behavior

The action has no effect if the main content is already present in fit://request/content.

The default-request uses data from the incoming request (accessible in fit://request/request) to define the request for the source server. The recipe is:

  • use the mapped main URL (accessible in DC as request/url)
  • use the incoming method (GET, POST etc.)
  • use the incoming query string
  • use the incoming POST data or uploads
  • use the incoming If-None-Match and If-Modified-Since header if http/pass-cache-headers is enabled (see conf/config.xml)
  • discard all other headers (including cookies)
  • create a new Cookie header from the special FIT cookies
  • apply all matching settings from conf/sources.xml
  • disable follow-redirects

This derives a new request to the source server from the incoming request. The request itself is carried out as any other request and may also be combined with other requests in a parallel requests action. After the response was received, the response body is stored in fit://request/content/main as usual.

The main response status is checked for non-content responses. Redirects are passed downstream. If the setting http/pass-cache-headers is enabled (see conf/config.xml), 304 responses are passed, too. If no content was received, a configurable error-handling/request-errors in conf/config.xml is injected to substitute the main content.

If the setting http/pass-cache-headers is enabled and a client request contains the If-Modified-Since header, the header is passed to the backend. If the backend responds with a 200 OK status code and a Last-Modified header value is equal to or earlier than the value from the If-Modified-Since request header, FIT automatically terminates the flow and sends a 304 Not Modified response without a body to the client.

Since this is the main content, another copy is stored in fit://request/content. This location is special in that it is the default in/out for all flow actions that modify content. It is also the input for the parse action that reads text input and either continues the flow with a parsed DOM or terminates the engine for non-DOM content (such as CSS or JS).

After the flow has finished, the engine expects fit://request/content to contain the main content as a DOM. Adaptive Components, image scaling, URL rewriting and any other built-in action will work on this DOM to craft the final response.

Finally the original status code and headers of the main response will be passed downstream. This may include caching headers, the Content-Disposition header and all X- headers. Any upstream communication errors are translated into a 502 status (except for timeouts, which are indicated by a 504 HTTP status code).

This is the basic modus operandi of the FIT engine.

Changing Request Parameters

If the above recipe for defining the source request is not suitable for your needs, you have three options:

Handling of Query Parameters

Browsers follow strict rules for URL construction when HTML forms are sent as GET requests. However, most URLs are constructed by backend systems that are not required to follow the same encoding rules. For many characters, URL encoding is optional, and some servers may require certain characters to be encoded. A server may even choose different separators for key-value-pairs besides & and =.

Therefore, the original incoming query string is used for outgoing requests, whenever possible.

Although the data source fit://request/request provides a parsed representation of <query> elements for convenient access from the Flow and XSL transformations, the actual URL sent in the backend request is usually read from the url="…" attribute.

There are two cases in which a new query string will be re-assembled and re-encoded: When a request encoding conversion is configured for a source with the <encoding> option or when the sources.xml contains <query/> parameters. To recode key and value strings or to add/overwrite single parameters, it is assumed that the query string follows the x-www-form-urlencoded format.

This behavior can also be configured manually. For example, if query parameters are modified by an xslt action transforming fit://request/request. The action option force-query-rebuild="true" will force the query string to be constructed from the <query> elements to reflect changes not applied to the url="…" attribute.

Another way to deal with backends requiring certain characters not to be URL encoded, is the <query-encoding raw="…" /> request option.

Accessing Response Data

After the action terminates, the response parameters and data is stored for later use.

The body payload (“content”) is stored in fit://request/content/main and is accessible from XPath with content(), which is a shortcut for fit-document('fit://request/content/main').

All headers and the status code is stored in fit://request/content/main/response which is accessible with fit-document(..).

<response content="main" url="fit://site/public/?output=bar" protocol-version="1.1" status="200" statusText="OK">
  <header name="Date" value="Wed, 02 Mar 2016 16:04:34 GMT"/>
  <header name="Server" value="Apache"/>
  <header name="Content-Type" value="text/html"/>
  <body src="fit://request/content/main"/>
</response>

The response data can also be used to examine request errors. In that case, the status code will be zero or negative:

<response content="main" url="http://example.com/" protocol-version="1.1" status="-1" statusText="Loading http://example.com/ is not allowed"/>
<response content="main" url="http://blackhole.webpagetest.org/" protocol-version="0.0" status="-1" statusText="Connection timed out after 3003 milliseconds"/>

A machine usable content type is deduced from the Content-Type header (and maybe the content itself) and set as DC property content/<type>. A typical content section in the DC may look like this:

<content>
  <html/>
  <mime>text/html</mime>
</content>

This is useful to restrict execution of Flow actions for certain content types:

<flow>
  <default-request />
  <dump if="content/mime = 'image/bmp'" />
  <regex pattern="..." replace="..." if="content/js" />
  <parse />
  <xslt src="..." if="content/html" />
</flow>