Request Forwarding and Inclusion

As described in Request Handling, chaining the request handlers are as straightforward as chaining the Future objects.

Here we describe how to chain a request handler to another URI: forwarding and inclusion.


To forward the request to another URI, you can use HttpConnect.forward.

For example, we can forward to the login page if the current user is not authenticated as follows:

Future foo(HttpConnect connect) {
  if (!isAuthenticated(connect))
    return connect.forward("/login");

  //...handle the request


To include the output of another URI, you can use HttpConnect.include. For example,

Future foo(HttpConnect connect) {
  connect.response.write("The content shown before the included page...");
  return connect.include("/webapp/another").then((_) {
    connect.response.write("The content shown after the included page...");

To protect a URI from accessed directly by the user, you can put it under /webapp. As shown in the previous example, /webapp/another can be accessed only by inclusion (and forwarding).

Difference between forward and inclusion

As their names suggested, you shall use HttpConnect.forward to forward a request to another URI, while using HttpConnect.include to include the output of another URI(s).

It is worth to notice that, from the technical point of view, HttpConnect.forward and HttpConnect.include are the same, except:

  • The included request handler won't be able to update any HTTP headers. Any updates to the HTTP headers in the included request handler are simply ignored.

This subtle difference helps you to include any request handler even if it will update some HTTP headers. On the other hand, you can't write any content to HttpResponse before invoking HttpConnect.forward, unless you're sure the forwarded request handler won't update any HTTP headers.

Notice that HttpResponse will throw an exception if you update the HTTP headers after writing some output. In other words, you can update the HTTP headers only before the first invocation of HttpResponse.write().