Qore HttpServer Module Reference 1.1.3
Loading...
Searching...
No Matches
HttpServer::HttpServer Class Reference

The HttpServer class implements a multithreaded HTTP server. More...

#include <HttpServer.qm.dox.h>

Inheritance diagram for HttpServer::HttpServer:
[legend]

Public Member Methods

 addHandlerToListener (softstring bind, string name, hash< HttpHandlerConfigInfo > info)
 adds a request handler to a listener given the listener's name or bind address
 
 addHandlerToListener (softstring bind, string name, HttpServer::AbstractUrlHandler obj)
 adds a request handler to a listener given the listener's name or bind address
 
 addHandlerToListenerID (softint id, string name, hash< HttpHandlerConfigInfo > info)
 adds a request handler to a listener given the listener's id More...
 
 addHandlerToListenerID (softint id, string name, HttpServer::AbstractUrlHandler obj)
 adds a request handler to a listener given the listener's id More...
 
 addHandlerToListenerID (softint id, string name, string path, *softlist content_type, HttpServer::AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex=True)
 adds a request handler to a listener given the listener's id More...
 
 addHttpMethod (string m)
 add a new supported HTTP method More...
 
hash< auto > addListener (hash< HttpListenerOptionInfo > opts)
 adds a single global listener to the server More...
 
hash< auto > addListener (int port)
 adds a single global listener to the server More...
 
final list< hash< auto > > addListeners (hash< HttpListenerOptionInfo > info, *reference< hash< string, string > > errmap)
 adds one or more dedicated listeners to the server with the given bind address More...
 
final list< hash< auto > > addListeners (string bind, hash< HttpListenerOptionInfo > info, *reference< hash< string, string > > errmap)
 adds one or more dedicated listeners to the server with the given bind address More...
 
 callListenerStopCallback (code stopc, string name, hash< auto > socket_info)
 To call a listener's stop callback.
 
 clearContextInfo ()
 This method is called after each request to clear context info so that it does not leak into other requests. More...
 
 constructor ()
 Creates the server with default options and an empty logger.
 
deprecated constructor (*code logfunc, *code errlogfunc, bool dbg=False, string name=HttpServer::HttpServerString, hash< auto > hdr={ 'X-Powered-By':'Qore/'+Qore::VersionString})
 creates the HttpServer More...
 
 constructor (hash< HttpServerOptionInfo > opts)
 Creates the server with the given options. More...
 
 copy ()
 throws an exception; these objects do not support copying
 
 destructor ()
 calls stop() and destroys the object
 
 disableDynamicHandler (string name)
 Disable dynamic handler. More...
 
bool getDebug ()
 returns the current status of the debug flag
 
int getListenerCount ()
 returns the number of running HTTP listeners
 
hash< auto > getListenerInfo (softint id)
 returns a hash of information about the listener given the listener ID More...
 
hash< auto > getListenerInfoName (string name)
 returns a hash of information about the listener given the listener name or bind ID More...
 
int getListenerLogOptions (softstring bind)
 returns a binary-or'ed product of listener log options corresponding to enabled log options for the given listener More...
 
int getListenerLogOptionsID (softint id)
 returns a binary-or'ed product of listener log options corresponding to enabled log options for the given listener More...
 
hash< string, hash< auto > > getListeners ()
 returns a hash of listener information More...
 
int getListenerTID (softint id)
 gets the TID of a listener based on its listener ID
 
date getTtl ()
 Returns the TTL value.
 
 listenerStarted (int id, hash< auto > sinfo)
 called from listener when the actual listener thread is running More...
 
 log (string fmt,...)
 called to log information to the registered log code
 
 logError (string fmt,...)
 called to log error information to the registered error log code
 
string maskData (string msg)
 masks log messages by removing sensitive data More...
 
 reloadListenerCertificate (int id)
 Reloads an HTTPS certificate from the original location for the given listener from the listener ID. More...
 
 reloadListenerCertificateName (string name)
 Reloads an HTTPS certificate from the original location for the given listener from the listener name. More...
 
 removeDynamicHandler (string name, *bool force_immediate)
 remove dynamic handler More...
 
bool removeHandlerFromListenerID (softstring id, HttpServer::AbstractHttpRequestHandler handler)
 remove request handler from a listener given the listener's id More...
 
bool removeHandlerFromListenerID (softstring id, string handler_name)
 remove request handler from a listener given the listener's id More...
 
 sendHttpError (HttpListener listener, hash< auto > cx, Socket s, int code, *data msg, *InputStream chunked_msg, *hash< auto > extra_hdrs, *string encoding, bool head)
 sends an HTTP error message on the socket
 
 setDebug (bool dbg=True)
 turns on or off debugging; when debugging is enabled more verbose error messages are reported
 
 setDefaultHandler (string name, HttpServer::AbstractHttpRequestHandler obj)
 sets the default request handler when no other handler can be matched
 
 setDynamicHandler (string name, hash< HttpHandlerConfigInfo > info)
 sets a dynamic request handler according to the arguments given
 
 setDynamicHandler (string name, HttpServer::AbstractUrlHandler obj)
 sets a dynamic request handler according to the arguments given
 
 setDynamicHandler (string name, string path, *softlist< softstring > content_types, HttpServer::AbstractHttpRequestHandler obj, *softlist< softstring > special_headers, bool isregex=True)
 sets a dynamic request handler according to the arguments given
 
 setHandler (string name, hash< HttpHandlerConfigInfo > info)
 sets a request handler according to the arguments given
 
 setHandler (string name, HttpServer::AbstractUrlHandler obj)
 sets a request handler according to the arguments given
 
 setHandler (string name, string path, *softlist< softstring > content_types, HttpServer::AbstractHttpRequestHandler obj, *softlist< softstring > special_headers, bool isregex=True)
 sets a request handler according to the arguments given
 
 setListenerLogOptions (softstring bind, softint code)
 turns on or off header and body logging options for receive operations for the given listener More...
 
 setListenerLogOptionsID (softint id, softint code)
 turns on or off header and body logging options for receive operations for the given listener More...
 
 setMaskCode (code maskfunc)
 sets the closure or call reference that will be used to mask sensitive data in log messages More...
 
 setTtl (date ttl)
 Sets the connection TTL value.
 
 stop ()
 stops all listeners; only returns when all connections are closed on all listeners More...
 
 stopListener (softstring bind)
 stops a single listener based on its name or bind address; does not return until all connections on the listener have closed More...
 
 stopListenerID (softint id)
 stops a single listener based on its listener ID; does not return until all connections on the listener have closed More...
 
 stopListenerIDNoWait (softint id)
 starts the shutdown process for a listener based on its listener ID; returns immediately More...
 
 stopNoWait ()
 stops all listeners; does not wait for all connections on the listeners to close More...
 
 waitStop ()
 waits for all listeners to be stopped; call after calling HttpServer::stopNoWait()
 

Static Public Member Methods

static string getHttpServerVersionString ()
 returns the HTTP server version string
 
static string getURLFromBind (softstring bind, *string host)
 returns a complete URL from a bind address More...
 
static nothing setReplyHeaders (Socket s, hash< auto > cx, reference< hash< auto > > rv)
 helper method to set HTTP response headers
 

Public Attributes

const AIFlags = AI_PASSIVE | AI_ADDRCONFIG
 address info flags
 
const CompressionThreshold = 1024
 default threadhold for data compressions; transfers smaller than this size will not be compressed
 
const ContentEncodings
 content-encodings supported; this is a hash to simulate a set with O(ln(n)) access times
 
const DefaultIdleThreads = 10
 default number of idle threads to have waiting for new connections (accross all listeners)
 
const DefaultTtl = 75s
 Default connection time-to-live.
 
const HttpCodes = HttpServer::HttpCodes
 map of HTTP result codes and text messages
 
const HttpMethods
 HTTP methods supported by default.
 
const LLO_RECV_BODY = (1 << 1)
 listener log option: log recv message body
 
const LLO_RECV_HEADERS = (1 << 0)
 
const LLO_SEND_BODY = (1 << 3)
 listener log option: log sent message body
 
const LLO_SEND_HEADERS = (1 << 2)
 listener log option: log send headers
 
const PollTimeout = 250ms
 default poll timeout in ms
 
const ReadTimeout = HttpServer::ReadTimeout
 default read timeout in ms
 
const Version = HttpServer::HttpServerVersion
 version of the HttpServer's implementation
 

Private Member Methods

int getListenerIdFromBindUnlocked (string bind)
 returns the listener ID from the bind name or throws an exception if not valid More...
 
int getListenerLogOptionsUnlocked (softstring id)
 returns header and body logging options for the given listener as a binary-or'ed value of listener log option codes
 
 setListenerLogOptionsUnlocked (softstring id, int code)
 turns on or off header and body logging options for the given listener according to the option code
 

Detailed Description

The HttpServer class implements a multithreaded HTTP server.

Member Function Documentation

◆ addHandlerToListenerID() [1/3]

HttpServer::HttpServer::addHandlerToListenerID ( softint  id,
string  name,
hash< HttpHandlerConfigInfo info 
)

adds a request handler to a listener given the listener's id

Parameters
idlistener id
namehandler name
infothe handler configuration info to add to the listener
Exceptions
INVALID-LISTENER-ERRORinvalid listener id passed

◆ addHandlerToListenerID() [2/3]

HttpServer::HttpServer::addHandlerToListenerID ( softint  id,
string  name,
HttpServer::AbstractUrlHandler  obj 
)

adds a request handler to a listener given the listener's id

Parameters
idlistener id
namehandler name
objhandler object
Exceptions
INVALID-LISTENER-ERRORinvalid listener id passed

◆ addHandlerToListenerID() [3/3]

HttpServer::HttpServer::addHandlerToListenerID ( softint  id,
string  name,
string  path,
*softlist  content_type,
HttpServer::AbstractHttpRequestHandler  obj,
*softlist  special_headers,
bool  isregex = True 
)

adds a request handler to a listener given the listener's id

Parameters
idlistener id
namehandler name
pathhandler path
content_typehandler's content type
objhandler object
special_headersheaders to match
isregexis the path a regular expression
Exceptions
INVALID-LISTENER-ERRORinvalid listener id passed

◆ addHttpMethod()

HttpServer::HttpServer::addHttpMethod ( string  m)

add a new supported HTTP method

Parameters
mthe HTTP method to add; the string is converted to upper case if necessary

◆ addListener() [1/2]

hash< auto > HttpServer::HttpServer::addListener ( hash< HttpListenerOptionInfo opts)

adds a single global listener to the server

Parameters
optsthe listener options
Returns
a listener info hash; see the return value of HttpServer::HttpServer::getListenerInfo() for the description of the hash returned by this method
Exceptions
HTTPSERVER-ADDLISTENER-ERRORinvalid options; duplicate bind address
Note
if sock begins with a "/" character then it is assumed to be a UNIX socket path and the family key is ignored

◆ addListener() [2/2]

hash< auto > HttpServer::HttpServer::addListener ( int  port)

adds a single global listener to the server

Parameters
portthe port number
Returns
a listener info hash; see the return value of HttpServer::HttpServer::getListenerInfo() for the description of the hash returned by this method
Exceptions
HTTPSERVER-ADDLISTENER-ERRORinvalid options; duplicate bind address

◆ addListeners() [1/2]

final list< hash< auto > > HttpServer::HttpServer::addListeners ( hash< HttpListenerOptionInfo info,
*reference< hash< string, string > >  errmap 
)

adds one or more dedicated listeners to the server with the given bind address

Parameters
infoa listener information hash
errmapan optional reference to a hash of error information keyed by bind address
Returns
a list of listener info hashes; see the return value of HttpServer::getListenerInfo() for the description of each hash element in the list returned by this method
Exceptions
HTTPSERVER-ADDLISTENER-ERRORduplicate bind address
Note
if bind begins with a "/" character then it is assumed to be a UNIX socket path and the family key of the info hash is ignored
Since
HttpServer 0.3.13.1

◆ addListeners() [2/2]

final list< hash< auto > > HttpServer::HttpServer::addListeners ( string  bind,
hash< HttpListenerOptionInfo info,
*reference< hash< string, string > >  errmap 
)

adds one or more dedicated listeners to the server with the given bind address

Parameters
bindthe bind address for the dedicated listener; this can be a port number or an address (or hostname) and a port number separated by a colon (ex: "192.168.20.4:8021"); the bind address will overwrite any node and service addresses in the info hash; all possible addresses will be bound to new listeners
infoa listener information hash
errmapan optional reference to a hash of error information keyed by bind address
Returns
a list of listener info hashes; see the return value of HttpServer::getListenerInfo() for the description of each hash element in the list returned by this method
Exceptions
HTTPSERVER-ADDLISTENER-ERRORduplicate bind address
Note
if bind begins with a "/" character then it is assumed to be a UNIX socket path and the family key of the info hash is ignored
Since
HttpServer 0.3.13.1

◆ clearContextInfo()

HttpServer::HttpServer::clearContextInfo ( )

This method is called after each request to clear context info so that it does not leak into other requests.

Reimplement in subclasses if necessarily

Since
HttpServer 1.1.2

◆ constructor() [1/2]

deprecated HttpServer::HttpServer::constructor ( *code  logfunc,
*code  errlogfunc,
bool  dbg = False,
string  name = HttpServer::HttpServerString,
hash< auto >  hdr = { 'X-Powered-By':'Qore/'+Qore::VersionString} 
)

creates the HttpServer

call addListener() to add and start listeners

Parameters
logfuncan optional closure or call reference that will be called with logging information; must take an initial string with optional arguments; ex:
code log = sub (string fmt) { vprintf(fmt, argv); }
errlogfuncan optional closure or call reference that will be called with error information; must take an initial string with optional arguments; ex:
code errloglog = sub (string fmt) { vprintf(fmt, argv); }
dbgif this parameter is set to True, then additional information will be logged when errors occur; note that this parameter is only used if log is not provided
namethe name of the HTTP server as returned in the Server header (should be formatted according to RFC 2616 section 3.8)
hdra hash of headers to return in every response by default; to clear the default send an empty hash as the argument here
Note
A new Logger object is created for the HTTP server using either logfunc or errfunc; if both are given then only logfunc is used and all log messages (including errors) are directed to logfunc. The Logger object's logging level is set according to which of these parameters is included. If neither are included, then no logging is performed
Deprecated:
use constructor(hash<HttpServerOptionInfo>) instead

◆ constructor() [2/2]

HttpServer::HttpServer::constructor ( hash< HttpServerOptionInfo opts)

Creates the server with the given options.

Parameters
optssee HttpServerOptionInfo for more info

◆ disableDynamicHandler()

HttpServer::HttpServer::disableDynamicHandler ( string  name)

Disable dynamic handler.

Exceptions
DISABLEHANDLER-ERRORif the given dynamic handler does not exist

◆ getListenerIdFromBindUnlocked()

int HttpServer::HttpServer::getListenerIdFromBindUnlocked ( string  bind)
private

returns the listener ID from the bind name or throws an exception if not valid

Exceptions
INVALID-LISTENER-ERRORinvalid listener bind address

◆ getListenerInfo()

hash< auto > HttpServer::HttpServer::getListenerInfo ( softint  id)

returns a hash of information about the listener given the listener ID

Parameters
idthe listener ID
Returns
a hash of listener information with the following keys:
  • name: the listener name
  • hostname: the listening interface name if available (ex: "localhost"; note that this key is not present when retrieving information about UNIX sockets)
  • hostname_desc: a descriptive string giving the hostname and the address family if the hostname is available (ex: "ipv6[localhost]"; note that this key is not present when retrieving information about UNIX sockets)
  • address: a string giving the address (ex: "::ffff:0.0.0.0")
  • address_desc: a descriptive string giving the address and the address family (ex: "ipv6[::ffff:0.0.0.0]")
  • port: an integer port number if available (note that this key is not present when retrieving information about UNIX sockets)
  • family: the network address family (see Network Address Family Constants)
  • familystr: a string describing the network address family (ex: "ipv4")
  • proto: the protocol used; either "http" or "https" for secure listeners
  • id: the listener ID
  • bind: the bind specification used
Exceptions
INVALID-LISTENER-ERRORinvalid listener ID

◆ getListenerInfoName()

hash< auto > HttpServer::HttpServer::getListenerInfoName ( string  name)

returns a hash of information about the listener given the listener name or bind ID

Parameters
namethe listener name or bind ID
Returns
a hash of listener information with the following keys:
  • name: the listener name
  • hostname: the listening interface name if available (ex: "localhost"; note that this key is not present when retrieving information about UNIX sockets)
  • hostname_desc: a descriptive string giving the hostname and the address family if the hostname is available (ex: "ipv6[localhost]"; note that this key is not present when retrieving information about UNIX sockets)
  • address: a string giving the address (ex: "::ffff:0.0.0.0")
  • address_desc: a descriptive string giving the address and the address family (ex: "ipv6[::ffff:0.0.0.0]")
  • port: an integer port number if available (note that this key is not present when retrieving information about UNIX sockets)
  • family: the network address family (see Network Address Family Constants)
  • familystr: a string describing the network address family (ex: "ipv4")
  • proto: the protocol used; either "http" or "https" for secure listeners
  • id: the listener ID
  • bind: the bind specification used
Exceptions
INVALID-LISTENER-ERRORinvalid listener name or bind ID

◆ getListenerLogOptions()

int HttpServer::HttpServer::getListenerLogOptions ( softstring  bind)

returns a binary-or'ed product of listener log options corresponding to enabled log options for the given listener

Exceptions
INVALID-LISTENER-ERRORinvalid listener id passed
Since
HttpServer 0.3.11

◆ getListenerLogOptionsID()

int HttpServer::HttpServer::getListenerLogOptionsID ( softint  id)

returns a binary-or'ed product of listener log options corresponding to enabled log options for the given listener

Exceptions
INVALID-LISTENER-ERRORinvalid listener id passed
Since
HttpServer 0.3.11

◆ getListeners()

hash< string, hash< auto > > HttpServer::HttpServer::getListeners ( )

returns a hash of listener information

Returns
a hash of listener info hashes keyed by listener ID; see the return value of HttpServer::getListenerInfo() for the description of each hash value

◆ getURLFromBind()

static string HttpServer::HttpServer::getURLFromBind ( softstring  bind,
*string  host 
)
static

returns a complete URL from a bind address

Parameters
bindthe bind address; if for any reason there is a path in the bind address, it will be ignored
hostthe hostname to use in case the bind string is only a port number; if none is passed or the value passed is equal to the return value of Qore::gethostname(), then "localhost" is used
Note
reexported from HttpServer::http_get_url_from_bind()

◆ listenerStarted()

HttpServer::HttpServer::listenerStarted ( int  id,
hash< auto >  sinfo 
)

called from listener when the actual listener thread is running

Parameters
idthe listener ID
sinfoa socket information hash as returned by Qore::Socket::getSocketInfo()
Since
HttpServer 0.3.11

◆ maskData()

string HttpServer::HttpServer::maskData ( string  msg)

masks log messages by removing sensitive data

See also
setMaskCode()
Since
HttpServer 0.3.12

◆ reloadListenerCertificate()

HttpServer::HttpServer::reloadListenerCertificate ( int  id)

Reloads an HTTPS certificate from the original location for the given listener from the listener ID.

Parameters
idthe listener ID

Subsequent connections will use the new certificate definition; the listener must have been started with the location information for the X.509 certificate and private key, or a REFRESH-CERTIFICATE-ERROR exception is raised

Exceptions
REFRESH-CERTIFICATE-ERRORnot an HTTPS listener or certificate location information not present
Since
HttpServer 1.1

◆ reloadListenerCertificateName()

HttpServer::HttpServer::reloadListenerCertificateName ( string  name)

Reloads an HTTPS certificate from the original location for the given listener from the listener name.

Parameters
namethe listener name or bind address

Subsequent connections will use the new certificate definition; the listener must have been started with the location information for the X.509 certificate and private key, or a REFRESH-CERTIFICATE-ERROR exception is raised

Exceptions
REFRESH-CERTIFICATE-ERRORnot an HTTPS listener or certificate location information not present
Since
HttpServer 1.1

◆ removeDynamicHandler()

HttpServer::HttpServer::removeDynamicHandler ( string  name,
*bool  force_immediate 
)

remove dynamic handler

Exceptions
REMOVEHANDLER-ERRORif the given dynamic handler does not exist

◆ removeHandlerFromListenerID() [1/2]

bool HttpServer::HttpServer::removeHandlerFromListenerID ( softstring  id,
HttpServer::AbstractHttpRequestHandler  handler 
)

remove request handler from a listener given the listener's id

Parameters
idlistener id
handlerhandler to remove;
Returns
whether listener was stopped
Exceptions
INVALID-LISTENER-ERRORinvalid listener id passed

◆ removeHandlerFromListenerID() [2/2]

bool HttpServer::HttpServer::removeHandlerFromListenerID ( softstring  id,
string  handler_name 
)

remove request handler from a listener given the listener's id

Parameters
idlistener id
handler_namename of handler to remove;
Returns
whether listener was stopped
Exceptions
INVALID-LISTENER-ERRORinvalid listener id passed

◆ setListenerLogOptions()

HttpServer::HttpServer::setListenerLogOptions ( softstring  bind,
softint  code 
)

turns on or off header and body logging options for receive operations for the given listener

Example:
http.setListenerLogOptions("app", LLO_RECV_HEADERS|LLO_SEND_HEADERS);
Parameters
bindthe name of the listener or bind string
codea binary-or'ed product of listener log options; bits set enable logging; bits not set disable logging
Since
HttpServer 0.3.11

◆ setListenerLogOptionsID()

HttpServer::HttpServer::setListenerLogOptionsID ( softint  id,
softint  code 
)

turns on or off header and body logging options for receive operations for the given listener

Example:
http.setListenerLogOptionsID(0, LLO_RECV_HEADERS|LLO_SEND_HEADERS);
Parameters
idthe unique listener ID
codea binary-or'ed product of listener log options; bits set enable logging; bits not set disable logging
Exceptions
INVALID-LISTENER-ERRORinvalid listener id passed
Since
HttpServer 0.3.11

◆ setMaskCode()

HttpServer::HttpServer::setMaskCode ( code  maskfunc)

sets the closure or call reference that will be used to mask sensitive data in log messages

Example
http_server.setMaskCode(string sub (string msg) { return do_mask(msg); });
Parameters
maskfunca closure or call reference that takes a single string argument and returns the masked string
See also
maskData()
Since
HttpServer 0.3.12

◆ stop()

HttpServer::HttpServer::stop ( )

stops all listeners; only returns when all connections are closed on all listeners

do not call stop() after calling stopNoWait(); it can cause a deadlock

◆ stopListener()

HttpServer::HttpServer::stopListener ( softstring  bind)

stops a single listener based on its name or bind address; does not return until all connections on the listener have closed

Parameters
bindlistener bind address
Exceptions
INVALID-LISTENER-ERRORinvalid listener bind address
HTTP-SERVER-ERRORcannot stop last listener

◆ stopListenerID()

HttpServer::HttpServer::stopListenerID ( softint  id)

stops a single listener based on its listener ID; does not return until all connections on the listener have closed

Parameters
idlistener id
Exceptions
INVALID-LISTENER-ERRORinvalid listener ID
HTTP-SERVER-ERRORcannot stop last listener

◆ stopListenerIDNoWait()

HttpServer::HttpServer::stopListenerIDNoWait ( softint  id)

starts the shutdown process for a listener based on its listener ID; returns immediately

Parameters
idlistener id
Exceptions
INVALID-LISTENER-ERRORinvalid listener ID
HTTP-SERVER-ERRORcannot stop last listener

◆ stopNoWait()

HttpServer::HttpServer::stopNoWait ( )

stops all listeners; does not wait for all connections on the listeners to close

do not call stop() after calling stopNoWait(); it can cause a deadlock