Pipeline

The pipeline contains all the hooks points available for the bref API. More...

Modules
	Gate
	Connections, data reception and sending events handling.
	Upstream
	Represents the pre-processing of a request.
	Bridge
	Contains hooks to run for content generation.
	Downstream
	Handle all stages between the content generation and sending data back to the client.
Classes
struct	bref::Environment
	This structure defines the environment of a request. More...
struct	bref::Pipeline
	Where the AModule classes register their hooks. More...
Typedefs
typedef BrefValue	bref::ServerConfig
	The value used for the configuration settings of the server.
typedef int	bref::FdType
	Define fd type (system dependant : fd on UNIX systems, HANDLE for Windows systems) for ContentHook.

---

Detailed Description

The pipeline contains all the hooks points available for the bref API.

When a module is initialized by the method AModule::registerHooks(Pipeline &) it initializes its hook points in the Pipeline.

This page describes how the Pipeline class works and how it interacts with the different hook points.

Vocabulary:

• Hook:

  Hooks are RequestHandlers (see below) generators for a given set of arguments. If -- given the argument(s) it received -- a hook decides not to handle a request, a null handler is generated.

  Examples of hooks are: Pipeline::PostParsingHook, Pipeline::OnReceiveHook, ...

  In term of code, a hook is a Function object that returns another Function object. It's often constructed with an Environment and an HttpRequest.

• RequestHandler:

  A request handler (e.g: Pipeline::ConnectionRequestHandler, Pipeline::OnReceiveRequestHandler) is the function object, returned by the hook, that will handle a request. It should be called with the arguments provided by its corresponding hook point (e.g.: the Pipeline::ConnectionRequestHandler takes an HttpResponse and an IpAddress).

  The majority of the request handlers takes an HttpResponse as reference, they can fill its header. When a response is finished, the upstream or bridge elements of the pipeline will directly go to the downstream part.

• Priority

  Used to represent the precedence of one request handler over another, when placed on the same hook point. Depending on the hook point, either all the request handlers will be called, starting with the highest priority, or only the most important one will be called.

  The priority is a floating number between 0.0 and 1.0. Modules should try to follow the following convention (but the value can be adapted):

  • Low Priority: 0.0
  • Normal Priority: 0.5
  • High Priority: 1.0

Example for a CGI module:

1. Register a Pipeline::ContentHook with a high priority (1.0) that returns a valid Pipeline::ContentRequestHandler if it detects a request asking a PHP file (by checking the .php extension for example and some configuration variables), otherwise it should return an empty handler.

1. Create the Pipeline::ContentRequestHandler that creates a process when it's constructed, and has a function operator() that takes each chunk of the request body and send them to the CGI process, and fill a buffer in return.

---

Typedef Documentation

typedef int bref::FdType

Define fd type (system dependant : fd on UNIX systems, HANDLE for Windows systems) for ContentHook.

See also:

ContentHook

typedef BrefValue bref::ServerConfig

The value used for the configuration settings of the server.

A typedef is used here for a better readability.