Configuring Pipeline Stages

Appweb uses a bidirectional pipeline to process requests and generate responses. This consists of a mechanism of queues, packets, buffering and event scheduling. The pipeline architecture is highly optimized and supports the efficient transmission of data without copying.

The request pipeline is comprised of an incoming and outgoing stream. Each stream is in turn comprised of stages.

Stages come in three varieties:

• Handlers
• Filters
• Network Connectors

Handlers are responsible for generating the response content. Filters permute the request or incoming and outgoing data in some way, and network connectors send the final response over the network to the client.

Appweb has a set of handlers for common application and content types. Different handlers service different content. Appweb provides the following handlers: PHP, CGI, ESP, directory listings, and a file handler for static file content. An API is also provided so you can create your own request handlers and pipeline filters and connectors.

Handlers

Appweb handlers typically utilize the Appweb loadable module interface and may be dynamically loaded and configured via the Appweb configuration file. The configuration file defines the handlers to use and the order in which they are matched to a given request.

Handler Processing

The following is an example set of Appweb configuration file directives that loads modules and defines the handlers to process client requests.

LoadModule esp libmod_esp
AddHandler espHandler esp

LoadModule phpHandler libmod_php
AddHandler phpHandler php

The order of the directives is important. When a request is received from a client, the handlers specified in the configuration file will be matched against the request. If a handler does not specify an extension, then it will always match. If the request URL extension matches the extension for a handler, then that handler will be added to the list of handlers for this request.

For example: "http://www.acme.com/myDoc.esp" would match the ".esp" extension for the ejsHandler. The result is a list of handlers that will be applied to the request in the order they appear in the configuration file. The first matching handler to accept the request will be responsible for the request.

Filters

Filters can manipulate the request as it passes through the request pipeline. Typical uses are to compress or encrypt data. Appweb implements Transfer Chunk Encoding and Ranged requests via filters. Filters are configured via the AddInputFilter and AddOutputFilter configuration file directives.

Appweb provides two HTTP protocol filters:

• http1Filter
• http2Filter

These filters implement the HTTP/1 and HTTP/2 protocols. Appweb automatically configures these filters at the end of the pipline and before the network connector. Prior to the HTTP filters, a unifying tailFilter marks the end of the user pipeline before the mandatory HTTP filters.

Connectors

Network connectors are the end of the outgoing stream of the pipeline. Their job is to transmit data back to the client. Appweb supplies one connectors: the net connector.

Please see the document Extending via Pipeline Stages for programming information about how to create Appweb handlers, filters and connectors.