Request Delegation

Note: Both C and Lua code support request delegation. In this documentation, C++ function names are used. When working with Lua, the equivalent methods are response:forward, response:include, and response:sendredirect.

Many server-based web architectures utilize a mediator-view design pattern, where the server can delegate or "dispatch" requests to different resources. In the Barracuda App Server, this request delegation is managed by the response object, which can forward a request to static resources (like HTML pages) or dynamic LSP (Lua Server Pages) or CSP (C Server Pages) code. The dispatching happens either by "including" a page or "forwarding" the request to another resource, all while preserving the current state of the request, session, or application.

The response object provides two key methods for request delegation: include and forward.

• Include Method: This allows you to dynamically insert another resource into the response. Included resources cannot modify the HTTP response headers; the headers set by the original resource remain unchanged. Any attempts to alter headers from the included resource are ignored. If the included resource is LSP/CSP-based, it can still access any objects bound to the current request, like session data.
• Forward Method: This method forwards the client's request to another resource, such as a static HTML file or LSP/CSP code. The original resource may perform preparatory tasks before handing over the request to the next resource. Like the include method, the forwarded resource can access the current state of the request. It's important to note that nothing should be written to the response before the forward action takes place, as any existing content in the response buffer will be cleared. Additionally, the forwarded resource can modify HTTP headers, manage session objects, set cookies, or adjust date headers.

Both methods allow the server to seamlessly manage requests behind the scenes, presenting users with the same URL while delivering different content based on the request.

One unique feature of the include and forward methods is the use of relative paths when including other resources. The virtual file system in Barracuda App Server combines directory branches with the same names, making them appear as one unified structure. This allows for resources in duplicate directories, such as an HTML file inside an HttpResRdr instance, to be included using a relative path.

Key Differences Between forward and sendRedirect

The HttpResponse::forward method differs significantly from HttpResponse::sendRedirect. The sendRedirect method triggers the server to send an HTTP 302 response, instructing the client to request a new resource at the specified URL. When the sendRedirect is called, the original request state is discarded once the page completes execution, meaning the new resource has no access to the initial request's data.

Protecting Resources

While the include and forward methods can delegate requests for any type of file, it's important to note that most files can also be accessed directly by users. If you need to protect certain pages from being accessed directly, use hidden files. These server-side includes ensure the resources are only available through the server's delegation process.

Navigation menu generated using response:include

The Dynamic Navigation Menu article shows how to create a server-side generated menu system using Lua's response:include method. This method allows you to build a dynamic menu that is consistently rendered across different pages, making it easy to maintain and update. By including menu elements server-side, you enhance scalability and ensure uniform navigation throughout your site.

For an alternative to using response:include for server-side generated menus, the Interactive Dashboard App article demonstrates how to implement a more advanced routing and content generation system. This approach separates page content from the theme, allowing for more dynamic and modular content management while keeping the site structure clean.