fphttpserver

From Free Pascal wiki
Revision as of 12:59, 4 September 2021 by Michael (talk | contribs) (Created page with "== fphttpserver Unit == === Intro === The `fphttpserver` unit contains a standalone HTTP server component: ''TFPHTTPServer''. It has the following features: # Specify any po...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

fphttpserver Unit

Intro

The `fphttpserver` unit contains a standalone HTTP server component: TFPHTTPServer. It has the following features:

  1. Specify any port you want.
  2. SSL capable. It generates a self-signed certificate if needed.
  3. Various threading modes: none, fully threaded or using a thread pool.
  4. Upgrade mechanism
  5. Event-driven
  6. Keeps connections (HTTP 1.1)

You can drop this component on a form and handle requests. Note that this component does not do any routing of requests, for that, use the TFPHTTPApplication class (see below)

Properties

The following properties are available:

Active (boolean)
Set to true to start the server, set to false to stop the server.
Port (integer)
Port number to listen on. Default 80.
QueueSize (integer)
Queue size for the Accept() call.
Threaded (boolean)
is the server threaded or not ?
Deprecated in 3.3.1 : use ThreadMode instead.
ThreadMode (tmNone,tmThread, tmThreadPool)
Choose how to use threads to process requests. Note that keeping connections open and no threading will not work very well.
AcceptIdleTimeout (integer)
Accepting new connections happens in a loop.
This timeout specifies the number of milliseconds to wait before Accept times out, at which point the OnAcceptIdle is called.
If zero, the accept call does not time out.
KeepConnections (boolean)
Allow to keep connections (HTTP 1.1)
KeepConnectionTimeout (integer)
Number of milliseconds to wait before closing an open (persistent) connection.
OnAllowConnect (Event)
An event handler to decide whether you want to accept a connection or not. This is called before the request is parsed.
OnRequest (Event)
An event handler to actually handle requests.
The signature of this method is the same as for all other fcl-web request handlers: you get a request and response object.
OnRequestError (Event)
Triggered when an exception occurs during a request
OnAcceptIdle
Triggered when the Accept loop goes idle.

Usage

  1. Create the component in code (or drop on a form/datamodule in the Lazarus IDE).
  2. Set the port number.
  3. Create an OnRequest handler to handle requests.
  4. At runtime, set the 'Active' property to True.
This statement will not return till the server is stopped.


fphttapp & custhttpapp Units

Intro

The TFPHTTPServer does not route requests. It only sends them through the 'OnRequest' event handler.

To integrate with the rest of fcl-web, instead use the THTTPApplication or TFPCustomHTTPApplication classes. These classes are descendents of TCustomApplication and handle everything from server setup to routing requests.

The fphttpapp unit contains simply an initialized version of the THTTPApplication class

Properties

In addition to the TCustomWebApplication (common ancestor for all kinds of web application: CGI, FastCGI, Apache Module etc.) the following properties are available: (they mostly map to the properties of the TFPHttpServer class)

Address (string)
Server address
Port (Word)
TCP/IP port to listen on
QueueSize (Word)
Max connections on queue (for Listen call)
OnAllowConnect (Event)
Called when deciding whether to accept a connection.
Threaded (Boolean)
Use a thread to handle a connection ?
LookupHostNames (Boolean)
Should addresses be matched to hostnames ? (expensive)
OnAcceptIdle (Event)
Event handler called when going Idle while waiting for a connection
AcceptIdleTimeout (integer)
If >0, when no new connection appeared after timeout, OnAcceptIdle is called.
UseSSL (Boolean)
Use SSL or not
HostName (String)
Hostname to use when using SSL
CertificateData (TCertificateData)
Access to certificate data

Usage

The following demonstrates the use of the 'TFPHTTPApplication' class:

program webserver;
 
{$mode objfpc}{$H+}
 
uses
  {$ifdef UNIX}
    cthreads, cmem,
  {$endif} 
  fphttpapp, httpdefs, httproute;
 
procedure route1(aReq: TRequest; aResp: TResponse);
begin
  aResp.content:='<html><body><h1>Route 1 The Default</h1></body></html>'
end;
 
procedure route2(aReq: TRequest; aResp: TResponse);
begin
  aResp.content:='<html><body><h1>Route 2</h1></body></html>'
end;
 
begin
  HTTPRouter.registerRoute('/', @route1);
  HTTPRouter.registerRoute('/2', @route2);
  Application.port := 1999;
  Application.threaded := true;
  Application.initialize;
  Application.run;
end.