Skip to main content
Version: Next

WebServer

The WebServer class API allows you to start and monitor a web server for the your application. This class is available from the 4D class store.

Web server objects are instantiated with the webServer command.

Functions and properties​

.certificateFolder : string    folder where the certificate files are located
.characterSet : number
.characterSet : string    character set that the Web Server should use to communicate with browsers connecting to the application
.cipherSuite : string    cipher list used for the secure protocol
.CORSEnabled : boolean    CORS (Cross-origin resource sharing) service status for the web server
.CORSSettings : collection    list of allowed hosts and methods for the CORS service
.debugLog : number    status of the HTTP request log file
.defaultHomepage : string    name of the default home page
.HSTSEnabled : boolean    HTTP Strict Transport Security (HSTS) status
.HSTSMaxAge : number    maximum length of time (in seconds) that HSTS is active for each new client connection
.HTTPCompressionLevel : number    compression level for all compressed HTTP exchanges for the HTTP server (client requests or server replies)
.HTTPCompressionThreshold : number    size threshold (bytes) for requests below which exchanges should not be compressed
.HTTPEnabled : boolean    HTTP protocol state
.HTTPPort : number    listening IP port number for HTTP
.HTTPSEnabled : boolean    HTTPS protocol state
.HTTPSPort : number    listening IP port number for HTTPS
.HTTPTrace : boolean    activation of HTTP TRACE
.IPAddressToListen : string    IP address on which the Web Server will receive HTTP requests
.isRunning : boolean    web server running state
.keepSession : boolean    Always false
.logRecording : number    log requests (logweb.txt) recording value
.maxRequestSize : number    maximum size (in bytes) of incoming HTTP requests (POST) that the web server is allowed to process
.minTLSVersion : number    minimum TLS version accepted for connections
.name : string    name of the web server application
.openSSLVersion : string    version of the OpenSSL library used
.perfectForwardSecrecy : boolean    PFS availability on the server
.rootFolder : string    path of web server root folder
.scalableSession : boolean    Always true
.sessionCookieDomain : string    "domain" field of the session cookie
.sessionCookieName : string    name of the cookie used for storing the session ID
.sessionCookiePath : string    "path" field of the session cookie
.sessionCookieSameSite : string    "SameSite" session cookie value
.sessionIPAddressValidation : boolean    IP address validation for session cookies
.start() : Object
.start( settings : Object ) : Object    starts the web server
.stop()    stops the web server

.certificateFolder​

.certificateFolder : string

Path of the folder 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 Folder object.

.characterSet​

.characterSet : number
.characterSet : string

The character set that the Web Server should use to communicate with browsers connecting to the application The default value is UTF-8. 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 Qodly 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​

.cipherSuite : string

The cipher list used for the secure protocol Sets the priority of ciphering algorithms implemented by the Qodly 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​

.CORSEnabled : boolean

The CORS (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​

.CORSSettings : collection

Contains the list 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​

.debugLog : number

The status 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​

.defaultHomepage : string

The name of the default home page or "" to not send the custom home page.

.HSTSEnabled​

.HSTSEnabled : boolean

The HTTP 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​

.HSTSMaxAge : number

The maximum 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​

.HTTPCompressionLevel : number

The compression level for all compressed HTTP exchanges for the 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).

Possible values:

  • 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​

.HTTPCompressionThreshold : number

The size 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​

.HTTPEnabled : boolean

The HTTP protocol state

.HTTPPort​

.HTTPPort : number

The listening IP port number for HTTP

Default = 80

.HTTPSEnabled​

.HTTPSEnabled : boolean

The HTTPS protocol state

.HTTPSPort​

.HTTPSPort : number

The listening IP port number for HTTPS

Default = 443

.HTTPTrace​

.HTTPTrace : boolean

The activation of 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.

.IPAddressToListen​

.IPAddressToListen : string

The IP address on which the Web Server will receive HTTP requests By default, no specific address is defined ("0.0.0.0"). Both IPv6 string formats and IPv4 string formats are supported.

.isRunning​

.isRunning : boolean

Read-only property

The web server running state

.keepSession​

.keepSession : boolean

Always false

.logRecording​

.logRecording : number

The log 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

.maxRequestSize​

.maxRequestSize : number

Contains the maximum 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

.minTLSVersion​

.minTLSVersion : number

The minimum TLS version accepted for connections Connection attempts from clients supporting only versions below the minimum will be rejected.

Possible values:

  • 3 = TLSv1_2
  • 4 = TLSv1_3 (default)

If modified, the server must be restarted to use the new value.

.name​

.name : string

Read-only property

The name of the web server application

.openSSLVersion​

.openSSLVersion : string

Read-only property

The version of the OpenSSL library used

.perfectForwardSecrecy​

.perfectForwardSecrecy : boolean

Read-only property

The PFS availability on the server

.rootFolder​

.rootFolder : string

The path 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 Folder object.

.scalableSession​

.scalableSession : boolean

Always true

.sessionCookieDomain​

.sessionCookieDomain : string

The "domain" field of the session cookie Used to control the scope of the session cookies. If you set, for example, the value "/*.myCompany.com" for this selector, the client will only send a cookie when the request is addressed to the domain ".myCompany.com", which excludes servers hosting external static data.

.sessionCookieName​

.sessionCookieName : string

The name of the cookie used for storing the session ID

Read-only property

.sessionCookiePath​

.sessionCookiePath : string

The "path" field of the session cookie Used to control the scope of the session cookies. If you set, for example, the value "/QACTION" for this selector, the client will only send a cookie for dynamic requests beginning with QACTION, and not for pictures, static pages, etc.

.sessionCookieSameSite​

.sessionCookieSameSite : string

The "SameSite" session cookie value Possible values (using constants):

ConstantValueDescription
Web SameSite Strict"Strict"Default value - Cookies are only sent in a first-party context, i.e. context matching the domain of the current site, and never to third-party websites.
Web SameSite Lax"Lax"Cookies are also sent on cross-site subrequests (for example to load images or frames into a third-party site), 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. When "None" value is used, the cookie Secure attribute must also be set (or the cookie will be blocked).

This property allows you to declare if your cookie should be restricted to a first-party or same-site context, as a protection from some cross-site request forgery attacks (CSRF).

For a detailed description of the SameSite attribute, please refer to the Mozilla documentation or this web.dev page.

The Secure attribute value of the session cookie is automatically set to "True" if the connection is HTTPS (whatever the SameSite attribute value).

.sessionIPAddressValidation​

.sessionIPAddressValidation : boolean

The IP 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/5G 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()​

.start() : Object
.start( settings : Object ) : Object

ParameterTypeDescription
settingsObject→Web server settings to set at startup
ResultObject←Status of the web server startup

The .start() function starts the web server using properties set in the optional settings object parameter.

The web server starts with default settings defined in the settings file of the project. However, using the settings parameter, you can define customized properties for the web server session.

All properties of Web Server objects can be customized, except read-only properties (.isRunning, .name, .openSSLVersion, .perfectForwardSecrecy, and [.sessionCookieName(#sessioncookiename)]).

Customized session settings will be reset when the .stop() function is called.

Returned object​

The function returns an object describing the Web server launch status. This object can contain the following properties:

PropertyTypeDescription
successbooleantrue if the web server was correctly started, false otherwise
errorscollectionError stack (not returned if the web server started successfully)
[].errCodenumberError code
[].messagestringDescription of the error
[].componentSignaturestringSignature of the internal component which returned the error

If the Web server was already launched, an error is returned.

Example​

 var settings,result : object
 var webServer : 4D.WebServer

 settings = { HSTSEnabled: true, defaultHomepage:"myHomepage.html" }

 result = webServer.start(settings)
 if(result.success)
  //...
 end

.stop()​

.stop()

ParameterTypeDescription
Does not require any parameters

The .stop() function stops the web server

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 function does nothing.

This function resets the customized web settings defined for the session using the settings parameter of the .start() function, if any.

Example​

To stop the Web server:

 webServer.stop()