Monday, December 31, 2012

Brook Framework, a new web application framework for Free Pascal

Recently, a new post in Lazarus forum surprised me. Somebody, OK, Silvio, announced his new web application framework for Free Pascal with over 15000 lines of code written, having integration with the great Greyhound data access framework, named Brook Framework. OK, so what's interesting from this framework? Keep reading.

Architecture: routes, actions and methods

Even though it's built on top of fcl-web, it doesn't make use of fcl-web architecture. Brook uses the concept of routes as commonly found in frameworks for other programming languages. For each request path (that /something/and/probably/longer thing) you want to support, you register a class (TBrookAction descendant) to handle the request path. The class itself implements method for each HTTP method the class will support (commonly GET and POST, but other methods like HEAD and PUT are also supported). This is, IMHO, a more structured yet flexible way than module-action architecture as used by fcl-web. FYI, the module-action architecture has a hardcoded request path in the form of /module/action or ?module=module-name&action=action-name. This makes the request path difficult to be made search engine friendly because you have to pass additional parameters via param1=value1&param2=value2&param3=value3 and so on. OTOH, Brook allows you to register path in almost free form (taken from TBrookAction.Register documentation):

* - Allows any path. Example:


Can be called as http://localhost/cgi-bin/cgi1, http://localhost/cgi-bin/cgi1/foo/ etc;

/ - Adds an slash to the end of the URL if does not exist. Example:


Can be called as http://localhost/cgi-bin/cgi1/foo or http://localhost/cgi-bin/cgi1/foo/. When called as http://localhost/cgi-bin/cgi1/foo, it will automatically redirected to http://localhost/cgi-bin/cgi1/foo/. If the pathinfo is different from /foo a 404 page is returned;

: - Creates variables URL. Their values can be read from the property Values. Example:


Creates the "myvar", that can be read from the property Values, e.g:


NOTE: Two actions can't be registered with the same pattern except when they are called by means of different HTTP methods.

Data access integration

Actions could optionally have direct data access. To do that, the action must descend from TBrookDBAction instead of TBrookAction. The action could then read/write data from/to database (or something else) while serving a request. Actually, my experience in a good MVC structure teaches me not to tie the request handler and the data persistence layer. But since this is optional in Brook, I can live with it. Besides, it can be a good thing for quick development.

Enough talk...

So let's get started, we'll be using Lazarus for easiness.

  1. Download brook here
  2. Extract it somewhere, open packages/brookex.lpk with Lazarus and install, this will register entries for easily creating new brook projects in Project->New Project menu
  3. Next, pick up one of the available data access backends. Since I'm currently playing a lot with Greyhound, I pick up brookgreyhoundrt.lpk. You may pick something else if you like such as ZEOS or ADS backend.
  4. After Lazarus restart, pick Project->New Project menu, you'll see 2 new entries named "Simple CGI Application" and "Full CGI / FastCGI Application". Pick up the latter as it provides more features
  5. A dialog with form will appear, the fields are intuitive so I guess I don't have to explain. Just fill the form and press Next
  6. Another dialog will appear. Here you can set the actions you want and their respective path, optionally setting which one will be the default (if no specific path given the request). There's a button "Patterns help" that redirects to TBrookAction.Register documentation exactly like in the previous section. When you're done, press Next
  7. Congratulations! Simply skip (doh)
  8. A project will be created with one unit per action you register, and a bunch of predefined files: 404.html, 500.html, Brokers.pas and the .lpr. The most important file is Brokers.pas. This unit acts as a central configuration settings. So, whatever configuration you need, set it here. You'll see that it already registers the 404 and 500 page. For FastCGI application, you can set port here by using:
    TBrookFCGIApplication(BrookApp.Instance).Port := {Your port number here};
    Don't forget to add BrookApplication and BrookFCLFCGIBroker to the uses clause
  9. Now open up an action unit and you'll see the Get method is already overriden with a default content. You can edit that later to produce html or whatever output you want. For now, we just want to test that it works
  10. Build the project and run (in case of FastCGI) or copy to your webserver's cgi directory (in case of CGI)
  11. Now go to your browser and type the url to your application, I personally use FastCGI with Nginx on port 8080, and if my action is /index/, I'll type in my browser: http://localhost:8080/index/
  12. If you see your output, then you've managed to make it work. Feel free to improve
  13. Pascal for web? Why not? ;)


  1. Hello,

    Excellent post man! :)

    I'm indicating this post here in Brazil, in Lazarus-BR group.

    Thank very much and happy new year friend!

    Silvio Clécio.

    1. Thanks, I have no thought you'll find the post this fast :p

  2. Wow, we can post it on the official lists and Lazarus forum. What do you think? :)

  3. salam kenal mas leledumbo, i have installed lazarus 1.0.4 and fpc 2.6.1 stable release from sourceforge. but always failed to install brook. may you show me step by step to install it. the article above looks succesfully installation. im newbie on lazarus. trims.

    1. Brook requires fpc 2.6.1 (near 2.6.2) or newer. If you get it from sourceforge then it must be 2.6.0 (at the time this article is written). Since lazarus 1.0.8 (containing fpc 2.6.2) has just been released, you might want to try that.

  4. Silvio thanx for mail notify about this framework

  5. Any chance for a more detailed nginx setup?
    I'd be much appreciated.


    1. Hmm..I don't use nginx to use brook (integrated webserver is better :)), but I have some experience with it + fpweb. I'll have to dig in my harddisk first though.

    2. I read this:

      10. Build the project and run (in case of FastCGI)

      11. Now go to your browser and type the url to your application, I personally use FastCGI with Nginx on port 8080

      and my understanding is that you've built a FastCGI with Brook and run it on nginx.

      I'm particularly interested in the (close) details of this setup.

      If you can find the time, like I said, I'd be much appreciated. Thanks.


    3. Whoops, maybe I should put "anymore" after "nginx" in my reply above :">

      There's nothing fancy actually, just use below template, replacing the variables with your setup:

      server {
      listen ;
      error_log debug;

      location / {
      fastcgi_split_path_info ^()(/?.+)$;
      # A handy function that became available in 0.7.31 that breaks down
      # The path information based on the provided regex expression
      # This is handy for requests such as file.php/some/paths/here/

      fastcgi_param PATH_INFO $fastcgi_path_info;
      fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info;

      fastcgi_param QUERY_STRING $query_string;
      fastcgi_param REQUEST_METHOD $request_method;
      fastcgi_param CONTENT_TYPE $content_type;
      fastcgi_param CONTENT_LENGTH $content_length;

      fastcgi_param SCRIPT_NAME $fastcgi_script_name;
      fastcgi_param SCRIPT_FILENAME $fastcgi_script_name;
      fastcgi_param REQUEST_URI $request_uri;
      fastcgi_param DOCUMENT_URI $document_uri;
      fastcgi_param DOCUMENT_ROOT $document_root;
      fastcgi_param SERVER_PROTOCOL $server_protocol;

      fastcgi_param GATEWAY_INTERFACE CGI/1.1;
      fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;

      fastcgi_param REMOTE_ADDR $remote_addr;
      fastcgi_param REMOTE_PORT $remote_port;
      fastcgi_param SERVER_ADDR $server_addr;
      fastcgi_param SERVER_PORT $server_port;
      fastcgi_param SERVER_NAME $server_name;

      fastcgi_param HTTPS $https;

      fastcgi_pass ;
      fastcgi_index index;

  6. Hi Lele (and Silvio) I would like to use ssl on an embedded webserver.
    How should I do that?


    1. Only fphttpclient currently has SSL support, fphttpserver does not (yet). Need to wait for Michael (or someone else including you) to commit such a feature.