WebServer class API allows you to start and monitor a web server for the main (host) application as well as each hosted component (see the Web Server object overview). This class is available from the
4D class store.
Web Server object
Web server objects are instantiated with the
WEB Server command.
They provide the following properties and functions:
|v19||support for .sessionCookieSameSite|
WEB Server : 4D. WebServer
WEB Server( option : Integer ) : 4D. WebServer
|option||Integer||->||Web server to get (default if omitted = |
|Resultado||4D.WebServer||<-||Web server object|
WEB Server commandreturns the default Web server object, or the Web server object defined through the option parameter.
By default, if the option parameter is omitted, the command returns a reference to the Web server of the database, i.e. the default Web server. To designate the Web server to return, you can pass one of the following constants in the option parameter:
|1||Current database Web server (default if omitted)|
|2||Web server of the host database of a component|
|3||Web server that received the request (target Web server)|
The returned Web server object contains the current values of the Web server properties.
From your component, you want to know if the Web server of the host database is started:
// Method of a component var $hostWS : 4D.WebServer $hostWS:=WEB Server(Web server host database) If($hostWS.isRunning) ... End if
WEB Server list
WEB Server list : Collection
|Resultado||Coleção||<-||Collection of the available Web server objects|
WEB Server list commandreturns a collection of all Web server objects available in the 4D application.
A 4D application can contain anywhere from one to several Web servers:
- one Web server for the host database (default Web server)
- one Web server for each component.
All available Web servers are returned by the
WEB Server list command, whether they are actually running or not.
The default Web server object is automatically loaded by 4D at startup. On the other hand, each component Web server that you want to use must be instantiated using the
You can use the .name property of the Web server object to identify the project or component to which each Web server object in the list is attached.
We want to know how many running web servers are available:
var $wSList : Collection var $vRun : Integer $wSList:=WEB Server list $vRun:=$wSList.countValues(True;"isRunning") ALERT(String($vRun)+" web server(s) running on "+String($wSList.length)+" available.")
.accessKeyDefined : Boolean
The .accessKeyDefined property containstrue if an access key is defined in the settings of the web server. This property is used by the WebAdmin web server to validate the security configuration of the administration interface.
.certificateFolder : Text
Path of thefolder where the certificate files are located. The path is formatted in POSIX full path using filesystems. When using this property in the
settings parameter of the
.start() function, it can be a
.characterSet : Number
.characterSet : Text
Thecharacter set that the 4D Web Server should use to communicate with browsers connecting to the application. The default value actually depends on the language of the OS. Can be a MIBEnum integer or a Name string, identifiers defined by IANA. Here is the list of identifiers corresponding to the character sets supported by the 4D Web Server:
- 4 = ISO-8859-1
- 12 = ISO-8859-9
- 13 = ISO-8859-10
- 17 = Shift-JIS
- 2024 = Windows-31J
- 2026 = Big5
- 38 = euc-kr
- 106 = UTF-8
- 2250 = Windows-1250
- 2251 = Windows-1251
- 2253 = Windows-1253
- 2255 = Windows-1255
- 2256 = Windows-1256
.cipherSuite : Text
Thecipher list used for the secure protocol. Sets the priority of ciphering algorithms implemented by the 4D web server. Can be a sequence of strings separated by colons (for example "ECDHE-RSA-AES128-..."). See the ciphers page on the OpenSSL site.
.CORSEnabled : Boolean
TheCORS (Cross-origin resource sharing) service status for the web server. For security reasons, "cross-domain" requests are forbidden at the browser level by default. When enabled (True), XHR calls (e.g. REST requests) from Web pages outside the domain can be allowed in your application (you need to define the list of allowed addresses in the CORS domain list, see
CORSSettings below). When disabled (False, default), all cross site requests sent with CORS are ignored. When enabled (True) and a non-allowed domain or method sends a cross site request, it is rejected with a "403 - forbidden" error response.
Default: False (disabled)
For more information about CORS, please refer to the Cross-origin resource sharing page on Wikipedia.
.CORSSettings : Collection
Alist of allowed hosts and methods for the CORS service (see
CORSEnabled property). Each object must contain a host property and, optionally, a methods property:
host (text, mandatory): Domain name or IP address from where external pages are allowed to send data requests to the Server via CORS. Multiple domain attributes can be added to create a white list. If host is not present or empty, the object is ignored. Several syntaxes are supported:
methods (text, optional): Accepted HTTP method(s) for the corresponding CORS host. Separate each method with a ";" (e,g,: "post;get"). If methods is empty, null, or undefined, all methods are enabled.
.debugLog : Number
Thestatus of the HTTP request log file (HTTPDebugLog_nn.txt, stored in the "Logs" folder of the application -- nn is the file number).
- 0 = disabled
- 1 = enabled without body parts (body size is provided in this case)
- 3 = enabled with body parts in response only
- 5 = enabled with body parts in request only
- 7 = enabled with body parts in response and request
.defaultHomepage : Text
Thename of the default home page or "" to not send the custom home page.
.HSTSEnabled : Boolean
TheHTTP Strict Transport Security (HSTS) status. HSTS allows the Web server to declare that browsers should only interact with it via secure HTTPS connections. Browsers will record the HSTS information the first time they receive a response from the web server, then any future HTTP requests will automatically be transformed into HTTPS requests. The length of time this information is stored by the browser is specified with the
HSTSMaxAge property. HSTS requires that HTTPS is enabled on the server. HTTP must also be enabled to allow initial client connections.
.HSTSMaxAge : Number
Themaximum length of time (in seconds) that HSTS is active for each new client connection. This information is stored on the client side for the specified duration.
Default value: 63072000 (2 years).
.HTTPCompressionLevel : Number
Thecompression level for all compressed HTTP exchanges for the 4D HTTP server (client requests or server replies). This selector lets you optimize exchanges by either prioritizing speed of execution (less compression) or the amount of compression (less speed).
- 1 to 9 (where 1 is the fastest compression and 9 the highest).
- -1 = set a compromise between speed and rate of compression.
Default = 1 (faster compression).
.HTTPCompressionThreshold : Number
Thesize threshold (bytes) for requests below which exchanges should not be compressed. This setting is useful in order to avoid losing machine time by compressing small exchanges.
Default compression threshold = 1024 bytes
.HTTPEnabled : Boolean
TheHTTP protocol state.
.HTTPPort : Number
Thelistening IP port number for HTTP.
Default = 80
.HTTPTrace : Boolean
HTTP TRACE. For security reasons, by default the Web server rejects
HTTP TRACE requests with an error 405. When enabled, the web server replies to
HTTP TRACE requests with the request line, header, and body.
.HTTPSEnabled : Boolean TheHTTPS protocol state.
.HTTPSPort : Number Thelistening IP port number for HTTPS.
Default = 443
.inactiveProcessTimeout : Number
This property is not returned in scalable sessions mode.
Thelife duration (in minutes) of the inactive legacy session processes. At the end of the timeout, the process is killed on the server, the
On Web Legacy Close Session database method is called, then the legacy session context is destroyed.
Default = 480 minutes
.inactiveSessionTimeout : Number
This property is not returned in scalable sessions mode.
Thelife duration (in minutes) of inactive legacy sessions (duration set in cookie). At the end of this period, the session cookie expires and is no longer sent by the HTTP client.
Default = 480 minutes
.IPAddressToListen : Text
TheIP address on which the 4D Web Server will receive HTTP requests. By default, no specific address is defined. Both IPv6 string formats and IPv4 string formats are supported.
.isRunning : Boolean
Theweb server running state.
.keepSession : Boolean
True if legacy sessions are enabled in the web server, False otherwise.
.logRecording : Number
Thelog requests (logweb.txt) recording value.
- 0 = Do not record (default)
- 1 = Record in CLF format
- 2 = Record in DLF format
- 3 = Record in ELF format
- 4 = Record in WLF format
.maxConcurrentProcesses : Number
Themaximum number of concurrent web processes supported by the web server. When this number (minus one) is reached, 4D will not create any other processes and returns the HTTP status 503 - Service Unavailable to all new requests.
Possible values: 10 - 32000
Default = 100
.maxRequestSize : Number
Themaximum size (in bytes) of incoming HTTP requests (POST) that the web server is allowed to process. Passing the maximum value (2147483647) means that, in practice, no limit is set. This limit is used to avoid web server saturation due to incoming requests that are too large. If a request reaches this limit, the web server rejects it.
Possible values: 500000 - 2147483647
.maxSessions : Number
This property is not returned in scalable sessions mode.
Themaximum number of simultaneous legacy sessions. When you reach the limit, the oldest legacy session is closed (and
On Web Legacy Close Session database method is called) if the web server needs to create a new one. The number of simultaneous legacy sessions cannot exceed the total number of web processes (
maxConcurrentProcesses property, 100 by default)
.minTLSVersion : Number
Theminimum TLS version accepted for connections. Connection attempts from clients supporting only versions below the minimum will be rejected.
- 1 = TLSv1_0
- 2 = TLSv1_1
- 3 = TLSv1_2 (default)
- 4 = TLSv1_3
If modified, the server must be restarted to use the new value.
.name : Text
Thename of the web server application.
.openSSLVersion : Text
Theversion of the OpenSSL library used.
.perfectForwardSecrecy : Boolean
ThePFS availability on the server.
.rootFolder : Text
Thepath of web server root folder. The path is formatted in POSIX full path using filesystems. When using this property in the
settings parameter, it can be a
.scalableSession : Boolean
True if scalable sessions are used in the web server, and False otherwise.
.sessionCookieDomain : Text
The"domain" field of the session cookie. Used to control the scope of the session cookies. If you set, for example, the value "/*.4d.fr" for this selector, the client will only send a cookie when the request is addressed to the domain ".4d.fr", which excludes servers hosting external static data.
.sessionCookieName : Text
Thename of the cookie used for storing the session ID.
.sessionCookiePath : Text
The"path" field of the session cookie. Used to control the scope of the session cookies. If you set, for example, the value "/4DACTION" for this selector, the client will only send a cookie for dynamic requests beginning with 4DACTION, and not for pictures, static pages, etc.
.sessionCookieSameSite : Text
The"SameSite" session cookie value. Possible values (using constants):
|Web SameSite Strict||"Strict"||Default value - Cookies are only sent in a first-party context|
|Web SameSite Lax||"Lax"||Cookies are also sent on cross-site subrequests but only when a user is navigating to the origin site (i.e. when following a link).|
|Web SameSite None||"None"||Cookies are sent in all contexts, i.e in responses to both first-party and cross-origin requests.|
See the Session Cookie SameSite description for detailed information.
.sessionIPAddressValidation : Boolean
This property is not used in scalable sessions mode (there is no IP address validation).
TheIP address validation for session cookies. For security reasons, by default the web server checks the IP address of each request containing a session cookie and rejects it if this address does not match the IP address used to create the cookie. In some specific applications, you may want to disable this validation and accept session cookies, even when their IP addresses do not match. For example when mobile devices switch between WiFi and 3G/4G networks, their IP address will change. In this case, you can allow clients to be able to continue using their web sessions even when the IP addresses change (this setting lowers the security level of your application).
.start() : Object
.start( settings : Object ) : Object
|settings||Objeto||->||Web server settings to set at startup|
|Resultado||Objeto||<-||Status of the web server startup|
.start() functionstarts the web server on which it is applied, using properties set in the optional settings object parameter.
The web server starts with default settings defined in the settings file of the project or (host database only) using the
WEB SET OPTION command. However, using the settings parameter, you can define customized properties for the web server session.
Customized session settings will be reset when the
.stop() function is called.
The function returns an object describing the Web server launch status. This object can contain the following properties:
|success||Booleano||True if the web server was correctly started, False otherwise|
|errors||Coleção||4D error stack (not returned if the web server started successfully)|
|.errCode||Número||4D error code|
|.message||Texto||Description of the 4D error|
|.componentSignature||Texto||Signature of the internal component which returned the error|
If the Web server was already launched, an error is returned.
var $settings;$result : Object var $webServer : 4D.WebServer $settings:=New object("HTTPPort";8080;"defaultHomepage";"myAdminHomepage.html") $webServer:=WEB Server $result:=$webServer.start($settings) If($result.success) //... End if
| Parameter | Type | | Descrição | | --------- | ---- | | ------------------------------- | | | | | Does not require any parameters |
.stop() functionstops the web server on which it is applied.
If the web server was started, all web connections and web processes are closed, once the currently handled requests are finished. If the web server was not started, the method does nothing.
This function resets the customized web settings defined for the session using the settings parameter of the
.start()function, if any.
To stop the database Web server:
var $webServer : 4D.WebServer $webServer:=WEB Server(Web server database) $webServer.stop()