fphttpserver: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: fphttpserver

New		Line
1	+	## fphttpserver Unit
2	+
3	+	### Intro
4	+
5	+	The fphttpserver unit contains a standalone HTTP server component: TFPHTTPServer. It has the following features:
6	+
7	+	1. Specify any port you want.
8	+	2. SSL capable. It generates a self-signed certificate if needed.
9	+	3. Various threading modes: none, fully threaded or using a thread pool.
10	+	4. Upgrade mechanism.
11	+	5. Event-driven.
12	+	6. Keeps connections (HTTP 1.1).
13	+
14	+	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).
15	+
16	+	### Properties
17	+
18	+	The following properties are available:
19	+
20	+	Active (boolean)
21	+	Set to true to start the server, set to false to stop the server.
22	+
23	+	Port (integer)
24	+	Port number to listen on. Default 80.
25	+
26	+	QueueSize (integer)
27	+	Queue size for the Accept() call.
28	+
29	+	Threaded (boolean)
30	+	Is the server threaded or not?
31	+
32	+	Deprecated in 3.3.1: use ThreadMode instead.
33	+
34	+	ThreadMode (tmNone, tmThread, tmThreadPool)
35	+	Choose how to use threads to process requests. Note that keeping connections open and no threading will not work very well.
36	+
37	+	AcceptIdleTimeout (integer)
38	+	Accepting new connections happens in a loop.
39	+
40	+	This timeout specifies the number of milliseconds to wait before Accept times out, at which point the OnAcceptIdle is called.
41	+
42	+	If zero, the accept call does not time out.
43	+
44	+	KeepConnections (boolean)
45	+	Allow to keep connections (HTTP 1.1).
46	+
47	+	KeepConnectionTimeout (integer)
48	+	Number of milliseconds to wait before closing an open (persistent) connection.
49	+
50	+	OnAllowConnect (event)
51	+	An event handler to decide whether you want to accept a connection or not. This is called before the request is parsed.
52	+
53	+	OnRequest (event)
54	+	An event handler to actually handle requests.
55	+
56	+	The signature of this method is the same as for all other fcl-web request handlers: you get a request and response object.
57	+
58	+	OnRequestError (event)
59	+	Triggered when an exception occurs during a request.
60	+
61	+	OnAcceptIdle (event)
62	+	Triggered when the Accept loop goes idle.
63	+
64	+	### Usage
65	+
66	+	1. Create the component in code (or drop on a form/datamodule in the Lazarus IDE).
67	+	2. Set the port number.
68	+	3. Create an OnRequest handler to handle requests.
69	+	4. At runtime, set the Active property to True. This statement will not return till the server is stopped.
70	+
71	+	### Support for HTTPS
72	+
73	+	Using HTTPS is just setting a property on TFPHTTPServer:
74	+
75	+	``` pascal
76	+	UseSSL := True;
77	+	```
78	+
79	+	And include one of the units that registers an SSL handler: opensslsockets or gnutlssockets.
80	+
81	+	You need to set your certificate details as well:
82	+
83	+	``` pascal
84	+	fServer.UseSSL := fUseSSL;
85	+	if fUseSSL then
86	+	begin
87	+	fServer.CertificateData.KeyPassword := fCertificatePassword;
88	+	fServer.CertificateData.HostName := fCertificateHostName;
89	+	fServer.CertificateData.Certificate.FileName := fCertificateFileName;
90	+	fServer.CertificateData.PrivateKey.FileName := fCertificatePrivateKey;
91	+	end;
92	+	```
93	+
94	+	If you do not set the certificate details, the HTTP server component will generate a temporary certificate, which may lead to a warning being displayed in the browser.
95	+
96	+	This works as of FPC 3.2.2.
97	+
98	+	## fphttapp & custhttpapp Units
99	+
100	+	### Intro
101	+
102	+	The TFPHTTPServer does not route requests. It only sends them through the 'OnRequest' event handler.
103	+
104	+	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.
105	+
106	+	The fphttpapp unit contains simply an initialized version of the THTTPApplication class.
107	+
108	+	### Properties
109	+
110	+	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)
111	+
112	+	Address (string)
113	+	Server address
114	+
115	+	Port (Word)
116	+	TCP/IP port to listen on
117	+
118	+	QueueSize (Word)
119	+	Max connections on queue (for Listen call)
120	+
121	+	OnAllowConnect (Event)
122	+	Called when deciding whether to accept a connection.
123	+
124	+	Threaded (Boolean)
125	+	Use a thread to handle a connection ?
126	+
127	+	LookupHostNames (Boolean)
128	+	Should addresses be matched to hostnames ? (expensive)
129	+
130	+	OnAcceptIdle (Event)
131	+	Event handler called when going Idle while waiting for a connection
132	+
133	+	AcceptIdleTimeout (integer)
134	+	If \>0, when no new connection appeared after timeout, OnAcceptIdle is called.
135	+
136	+	UseSSL (Boolean)
137	+	Use SSL or not
138	+
139	+	HostName (String)
140	+	Hostname to use when using SSL
141	+
142	+	CertificateData (TCertificateData)
143	+	Access to certificate data
144	+
145	+	### Usage
146	+
147	+	The following demonstrates the use of the TFPHTTPApplication class:
148	+
149	+	``` pascal
150	+	program webserver;
151	+
152	+	{$mode objfpc}{$H+}
153	+
154	+	uses
155	+	{$ifdef UNIX}
156	+	cthreads, cmem,
157	+	{$endif}
158	+	fphttpapp, httpdefs, httproute;
159	+
160	+	procedure route1(aReq: TRequest; aResp: TResponse);
161	+	begin
162	+	aResp.Content:='<html><body><h1>Route 1 The Default</h1></body></html>';
163	+	end;
164	+
165	+	procedure route2(aReq: TRequest; aResp: TResponse);
166	+	begin
167	+	aResp.Content:='<html><body><h1>Route 2</h1></body></html>';
168	+	end;
169	+
170	+	begin
171	+	HTTPRouter.RegisterRoute('/', @route1);
172	+	HTTPRouter.RegisterRoute('/2', @route2);
173	+	Application.Port := 1999;
174	+	Application.Threaded := true;
175	+	Application.Initialize;
176	+	Application.Run;
177	+	end.
178	+	```
179	+
180	+	---
181	+	From the Free Pascal wiki, page "fphttpserver", as it stood on 2022-08-24 after a change by Michael, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history