Recent

Author Topic: Brook - Beginner trying to get started  (Read 1081 times)

RedOctober

  • Sr. Member
  • ****
  • Posts: 379
Brook - Beginner trying to get started
« on: January 19, 2021, 01:58:59 am »
I'm trying to get started learning and using the Brook Framework.  I installed Brooks 5.2.3.0 into my Lazarus 2010 just now. 
The documentation at https://github.com/risoflora/brookfreepascal is a little sparse. 
I can't even find where the Brook "examples" or "demos" directory is on my hard drive.
I need to know how to install all those recommended plugins to assist Brook.
Does anyone have a guide book for Brook beginners to get started? I'll pay, I don't expect it free.
Thanks in advance.

PierceNg

  • Jr. Member
  • **
  • Posts: 70
Re: Brook - Beginner trying to get started
« Reply #1 on: January 19, 2021, 12:25:11 pm »
There are two Brooks:

Brook Free Pascal is pure Pascal. Brook Framework uses a C library web framework. The two are similar but not identical.

Are you familar with Free Pascal style of web server application programming? Does the following look familar?

Code: Pascal  [Select][+][-]
  1. type
  2.   THTTPServer = class(TBrookHTTPServer)
  3.   protected
  4.     procedure DoRequest(ASender: TObject; ARequest: TBrookHTTPRequest;
  5.       AResponse: TBrookHTTPResponse); override;
  6.   end;
  7.  
  8. procedure THTTPServer.DoRequest(ASender: TObject; ARequest: TBrookHTTPRequest;
  9.   AResponse: TBrookHTTPResponse);
  10. begin
  11.   AResponse.Send('Hello world', 'text/plain', 200);
  12. end;

RedOctober

  • Sr. Member
  • ****
  • Posts: 379
Re: Brook - Beginner trying to get started
« Reply #2 on: January 19, 2021, 03:24:39 pm »
Hi Pierce,  Thanks for your help.

Quote
There are two Brooks:

Ooooohhhh.  I did not know that.

I see now, that I have installed the Framework, as shown in the attachment.  I did that just because it was listed in the Lazarus On-Line Package Manager.  I'm not a "purist".  I don't mind using a C library in my Lazarus projects.  I (almost) never mess with coding of the components I use.  If I'm ok with using a Windows DLL (Like QuickPDF by Debenu), then I have to be ok with using a C library for Brook.

Quote
Are you familar with Free Pascal style of web server application programming? Does the following look familar?

Back in the days when I was programming in Delphi, maybe 3 years ago, I successfully built a small web app using Delphi MVC.  It seemed fairly simple, even though it used "tags", which I was unfamiliar with.  I asked Daniele Teti if he wd port DMVC to Lazarus and he said that it was not in the plans, bc Lazarus is much different internally than Delphi.

So I was hoping Brooks wd be the DMVC for Lazarus.  However, Daniele has a book on how to get beginners (and advanced ppl) going on DMVC, and that is what I'm looking for, for Brook.. (or some helpful instruction + the correct example projects that explain in words and demonstrate with code, the proper, version-correct way to do something)

I originally found Brook 3 years ago, but did not use it bc I was told Brook 4 was coming out and it would be very different.  I did not want to base years worth of work on an outdated component.  Now, I see Brook 5 has come out, so I'm excited to get started.





PierceNg

  • Jr. Member
  • **
  • Posts: 70
Re: Brook - Beginner trying to get started
« Reply #3 on: January 19, 2021, 04:35:10 pm »
I see now, that I have installed the Framework, as shown in the attachment.  I did that just because it was listed in the Lazarus On-Line Package Manager.  I'm not a "purist".  I don't mind using a C library in my Lazarus projects.  I (almost) never mess with coding of the components I use.  If I'm ok with using a Windows DLL (Like QuickPDF by Debenu), then I have to be ok with using a C library for Brook.

v5 is Brook Framework. The examples are here, and the application programmer documentation  is here. HTH.

RedOctober

  • Sr. Member
  • ****
  • Posts: 379
Re: Brook - Beginner trying to get started
« Reply #4 on: January 21, 2021, 09:56:53 pm »
Hi Pierce,

I am working my way through the examples.  When I run them, they create what I call "little http servers" that are stand alone.

Q1:  Does Brook always create a stand alone server, or does it create "modules" (I forget what they are called) that "run under" IIS or Apache?   I don't really have a preference.  But I suspect that the stand alone servers need their own port and their own certs/keys/roots to make HTTPS work.

Q2:  I need to quickly get started using HTTPS.  My little web-app has to be secured some how.  My Windows Server 2016 already has a wildcard cert installed for my company domain.  I imagine that if I made a Brook module that runs under IIS or Apache, then Apache wd take care of the security? If Brook is a stand alone server, is there an example of a secured HTTPS server (or web "service"?) in the Examples that I shd get to, that wd demonstrate this? I suspect I'd need a key,root,cert...file(s)?  which are not currently present on my server.

 Thanks in advance.


PierceNg

  • Jr. Member
  • **
  • Posts: 70
Re: Brook - Beginner trying to get started
« Reply #5 on: January 22, 2021, 01:36:05 am »
Q1:  Does Brook always create a stand alone server, or does it create "modules" (I forget what they are called) that "run under" IIS or Apache?   I don't really have a preference.  But I suspect that the stand alone servers need their own port and their own certs/keys/roots to make HTTPS work.

I haven't gone through every single example, but I believe it always does, because it is using a C library libsagui which itself is using libmicrohttpd, which is meant for writing standalone HTTP/S servers.

A standalone server does need to run on an IP address : TCP port pair. For HTTPS, the server needs to have key pair and certificate.

Q2:  I need to quickly get started using HTTPS.  My little web-app has to be secured some how.  My Windows Server 2016 already has a wildcard cert installed for my company domain.  I imagine that if I made a Brook module that runs under IIS or Apache, then Apache wd take care of the security? If Brook is a stand alone server, is there an example of a secured HTTPS server (or web "service"?) in the Examples that I shd get to, that wd demonstrate this? I suspect I'd need a key,root,cert...file(s)?  which are not currently present on my server.

To front your Brook app server with IIS or Apache is called reverse proxying. In that scenario IIS or Apache handles the HTTPS and reverse proxies to your web app in HTTP, provided you are running on the same host or a trusted network.

As for your Brook app handling  HTTPS itself, the class TBrookHTTPServerSecurity in source file BrookHTTPServer.pas deals with certificates and keys. I have not tested this myself.

To get your own keys and certificates for HTTPS, use Let's Encrypt, https://letsencrypt.org/.
   

RedOctober

  • Sr. Member
  • ****
  • Posts: 379
Re: Brook - Beginner trying to get started
« Reply #6 on: February 18, 2021, 05:06:35 pm »
Hi PierceNg,  I'm back onto this project from a short side track.  I have some questions...

1

I have discovered that I am unable to install both Brook 4 and Brook 5 in Lazarus 2.0.10.  I don't know which is "better".  I was leaning a bit toward Brook 4, only bc there is a small "getting started in Lazarus" instruction on the Brook 4 link you posted.  Is there any criteria that wd guide a person to choose one over the other?  Is one faster? Is one more capable? According to the instructions, in Brook 4, I start by creating a CGI app.  But in Brook 5, I can just place a Brook component onto an ordinary Windows app. Is that the correct way to do it?  Will one run faster than the other?

2

At the Brook 4 link in your post, near the bottom, it lists a number of other "plug-ins" for Brook 4.  I have no idea how to install these into Lazarus from Git Hub.  How is that done? What are the steps?

3

In my Lazarus IDE - "Install / Uninstall Packages", there are two (as yet uninstalled) items, that look like they relate to Brook.  They are:   brookdt 1.0  and  brookex 2.0    What are these?  Should I install them only in Brook 4 or only in Brook 5, or not at all?  Or, if I use the On-line Package Manager and install one of the Brooks, will these automatically be included in the install?  I really don't want to mess up my Laz 2.0.10 install, it's working so nice at the moment.

Thanks so much for your help PierceNg!

Too bad there isn't a book on how to do all this.  I'd gladly pay for that.  The existing documentation just seems to be the most basic, getting started, and reference docs for looking up something.  I really need a "Brook for Dummies" type book, that covers everything a newbie needs to know.




egsuh

  • Hero Member
  • *****
  • Posts: 623
Re: Brook - Beginner trying to get started
« Reply #7 on: February 18, 2021, 05:48:42 pm »
AFAIK, Brook for Free Pascal is maintained only for bug fixing.
Currently the developers are focusing on BrookFramework (Brook 5.0 or over).
I did not go deep into Brooks yet. Anyway Brook FreePascal seems to replace the actions of fpweb with classes. I have not really tested Brook Framework yet.
For future support you should choose Brook Framework. Documents are not much available because they are still being developed --- well, Delphi might start with book writers together with development but I don't think "free" Free Pascal developers have such a luxury. So we have to share experiences.

RedOctober

  • Sr. Member
  • ****
  • Posts: 379
Re: Brook - Beginner trying to get started
« Reply #8 on: February 18, 2021, 09:30:08 pm »
Hi egsuh and Pierce, I'm slowly making progress, thanks to your generous help.  I have installed Brook 5, the framework.  I have compiled and run all the LCL examples.  As far as I can see, none of these examples create a HTTPS server.   I will explore  "TBrookHTTPServerSecurity in source file BrookHTTPServer.pas deals with certificates and keys." as recommended by Pierce, but I was wondering if anyone has (or has a link to ) a working example of a Brook Framework server that implements HTTPS ?

RedOctober

  • Sr. Member
  • ****
  • Posts: 379
Re: Brook - Beginner trying to get started
« Reply #9 on: February 20, 2021, 10:49:21 pm »
Lazarus 2.0.10 on Windows Server 2016

I'm getting started with building the most simple Brook server.  I have reviewed the examples. 
Questions: 
1)  Is it necessary to always include the compiler directive {$MODE DELPHI}  and remove the {$mode objfpc}{$H+} , if so why?
2)  How do I handle incoming parameters in the URL?  That's, I think, where the URL "tells" the brook server what it's looking for (like "customers" or "clients" or "inventory", etc.)  None of the examples deal with that. 

egsuh

  • Hero Member
  • *****
  • Posts: 623
Re: Brook - Beginner trying to get started
« Reply #10 on: February 21, 2021, 12:33:38 am »
It is not necessary to include {$mode ...}, but one mode must be chosen by default setting. You may define project default mode at project options.  Syntaxes are slightly different. For example,

              OnClick :=  @Myfunction;   {$mode objfpc}
              OnClick := Myfunction;  {$mode delphi}

Incoming parameters ... Are you talking of query parameters? They should be in ARequest.QueryFields (in GET method) or in ARequest.ContentFields (in the case of POST). I'm not talking about Brook. Just general web approach^^.  But I can't think of other options.

RedOctober

  • Sr. Member
  • ****
  • Posts: 379
Re: Brook - Beginner trying to get started
« Reply #11 on: February 21, 2021, 01:15:37 am »
Sorry, I shd have included an example.  Here is the parameter I'm speaking of:

http://localhost:5250/?RUOK


It's the part after the ? that are the parameters I'm speaking of. Is that how to call Brook "functions" (or are those "paths") using REST ?

"RUOK" stands for "Are You OK?". It is just a basic function that I want to use to allow a monitoring program to get a 200 response back (or not).  It has no login, no other parameters.

Next:  I will be wanting to display a few buttons to the end user.  Some will ask for a list of appointments, some will be for "book the displayed appointment for me".

So in my "outgoing" (response) I will send out an HTML page with these links embedded.  How shd those links be formatted so that one is a GET (to get the list of available appointments) and the other is a POST (to book an open appointment for the end user)

I'm thinking that in my "brook_svrRequest" I will have to create a bunch of...

... if this path was sent, do this...
... if this other path was sent, do that...

kind of thing.  What is the proper syntax for all the "if this path was sent"... things?







egsuh

  • Hero Member
  • *****
  • Posts: 623
Re: Brook - Beginner trying to get started
« Reply #12 on: February 21, 2021, 01:35:20 am »
I guess Brook supports path or actions. These should be expressed as

        localhost:5250/RUOK    (not after "?")

And you define the necessary actions under each path or action.

Adding something after ? is stored in the queryfields. ARequest.QueryFields is TStringList type.  It should look like

         http://localhost:5250?RUOK=Yes 

and at the server, you can extract the value in following way:

     if ARequest.QueryFields.Values['RUOK'] = 'Yes' then begin
          .................
     end;       


And "GET" and "POST" are methods that browsers use to send data to the webserver. They are defined in the <form method= ... > section of HTML.  ... may be either of "GET" or "POST".

AGAIN I'm talking only in general fp-web principles. I found Brook FreePascal is similar. Please share me your experience with Brook Framework.

RedOctober

  • Sr. Member
  • ****
  • Posts: 379
Re: Brook - Beginner trying to get started
« Reply #13 on: February 21, 2021, 02:40:50 am »
Hi egsuh.  Thank you for your generous help.  My app will be so simple, I think I will post the code here, once I get it working, to:

a)  Allow Brook aficionados to ensure it passes the "smell" test.
b)  Benefit other beginners


PierceNg

  • Jr. Member
  • **
  • Posts: 70
Re: Brook - Beginner trying to get started
« Reply #14 on: February 21, 2021, 02:50:28 am »
I'm thinking that in my "brook_svrRequest" I will have to create a bunch of...

... if this path was sent, do this...
... if this other path was sent, do that...

kind of thing.  What is the proper syntax for all the "if this path was sent"... things?

This is called URL routing. See Examples/Console/FPC/urlrouter.lpr. Code-wise, each route subclasses TBrookRoute, then set up the routes using an instance of your subclass of TBrookURLRouter.

So you'd have TRouteHome for your default route /, TRouteHeartbeat say for your RUOK pinging, TRouteAppointment and so on.

So in my "outgoing" (response) I will send out an HTML page with these links embedded.  How shd those links be formatted so that one is a GET (to get the list of available appointments) and the other is a POST (to book an open appointment for the end user)

This is basic web application programming  know-how. If you are unclear about this stuff, maybe you should start with fpweb, since (I guess) more people on this forum will be able to answer your questions than if you use Brook.

 

TinyPortal © 2005-2018