Qore HttpServer Module Reference 1.1.3
|
The HttpServer class implements a multithreaded HTTP server. More...
#include <HttpServer.qm.dox.h>
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 | |
The HttpServer class implements a multithreaded HTTP server.
HttpServer::HttpServer::addHandlerToListenerID | ( | softint | id, |
string | name, | ||
hash< HttpHandlerConfigInfo > | info | ||
) |
adds a request handler to a listener given the listener's id
id | listener id |
name | handler name |
info | the handler configuration info to add to the listener |
INVALID-LISTENER-ERROR | invalid listener id passed |
HttpServer::HttpServer::addHandlerToListenerID | ( | softint | id, |
string | name, | ||
HttpServer::AbstractUrlHandler | obj | ||
) |
adds a request handler to a listener given the listener's id
id | listener id |
name | handler name |
obj | handler object |
INVALID-LISTENER-ERROR | invalid listener id passed |
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
id | listener id |
name | handler name |
path | handler path |
content_type | handler's content type |
obj | handler object |
special_headers | headers to match |
isregex | is the path a regular expression |
INVALID-LISTENER-ERROR | invalid listener id passed |
HttpServer::HttpServer::addHttpMethod | ( | string | m | ) |
add a new supported HTTP method
m | the HTTP method to add; the string is converted to upper case if necessary |
hash< auto > HttpServer::HttpServer::addListener | ( | hash< HttpListenerOptionInfo > | opts | ) |
adds a single global listener to the server
opts | the listener options |
HTTPSERVER-ADDLISTENER-ERROR | invalid options; duplicate bind address |
hash< auto > HttpServer::HttpServer::addListener | ( | int | port | ) |
adds a single global listener to the server
port | the port number |
HTTPSERVER-ADDLISTENER-ERROR | invalid options; duplicate bind address |
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
info | a listener information hash |
errmap | an optional reference to a hash of error information keyed by bind address |
HTTPSERVER-ADDLISTENER-ERROR | duplicate bind address |
bind
begins with a "/" character then it is assumed to be a UNIX socket path and the family key of the info hash is ignoredfinal 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
bind | the 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 |
info | a listener information hash |
errmap | an optional reference to a hash of error information keyed by bind address |
HTTPSERVER-ADDLISTENER-ERROR | duplicate bind address |
bind
begins with a "/" character then it is assumed to be a UNIX socket path and the family key of the info hash is ignoredHttpServer::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
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
logfunc | an 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); }
|
errlogfunc | an 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); }
|
dbg | if 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 |
name | the name of the HTTP server as returned in the Server header (should be formatted according to RFC 2616 section 3.8) |
hdr | a hash of headers to return in every response by default; to clear the default send an empty hash as the argument here |
HttpServer::HttpServer::constructor | ( | hash< HttpServerOptionInfo > | opts | ) |
Creates the server with the given options.
opts | see HttpServerOptionInfo for more info |
HttpServer::HttpServer::disableDynamicHandler | ( | string | name | ) |
Disable dynamic handler.
DISABLEHANDLER-ERROR | if the given dynamic handler does not exist |
|
private |
returns the listener ID from the bind name or throws an exception if not valid
INVALID-LISTENER-ERROR | invalid listener bind address |
hash< auto > HttpServer::HttpServer::getListenerInfo | ( | softint | id | ) |
returns a hash of information about the listener given the listener ID
id | the listener ID |
name:
the listener namehostname:
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 listenersid:
the listener IDbind:
the bind specification usedINVALID-LISTENER-ERROR | invalid listener ID |
hash< auto > HttpServer::HttpServer::getListenerInfoName | ( | string | name | ) |
returns a hash of information about the listener given the listener name or bind ID
name | the listener name or bind ID |
name:
the listener namehostname:
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 listenersid:
the listener IDbind:
the bind specification usedINVALID-LISTENER-ERROR | invalid listener name or bind ID |
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
INVALID-LISTENER-ERROR | invalid listener id passed |
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
INVALID-LISTENER-ERROR | invalid listener id passed |
hash< string, hash< auto > > HttpServer::HttpServer::getListeners | ( | ) |
returns a hash of listener information
|
static |
returns a complete URL from a bind address
bind | the bind address; if for any reason there is a path in the bind address, it will be ignored |
host | the 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 |
HttpServer::HttpServer::listenerStarted | ( | int | id, |
hash< auto > | sinfo | ||
) |
called from listener when the actual listener thread is running
id | the listener ID |
sinfo | a socket information hash as returned by Qore::Socket::getSocketInfo() |
string HttpServer::HttpServer::maskData | ( | string | msg | ) |
HttpServer::HttpServer::reloadListenerCertificate | ( | int | id | ) |
Reloads an HTTPS certificate from the original location for the given listener from the listener ID.
id | the 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
REFRESH-CERTIFICATE-ERROR | not an HTTPS listener or certificate location information not present |
HttpServer::HttpServer::reloadListenerCertificateName | ( | string | name | ) |
Reloads an HTTPS certificate from the original location for the given listener from the listener name.
name | the 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
REFRESH-CERTIFICATE-ERROR | not an HTTPS listener or certificate location information not present |
HttpServer::HttpServer::removeDynamicHandler | ( | string | name, |
*bool | force_immediate | ||
) |
remove dynamic handler
REMOVEHANDLER-ERROR | if the given dynamic handler does not exist |
bool HttpServer::HttpServer::removeHandlerFromListenerID | ( | softstring | id, |
HttpServer::AbstractHttpRequestHandler | handler | ||
) |
remove request handler from a listener given the listener's id
id | listener id |
handler | handler to remove; |
INVALID-LISTENER-ERROR | invalid listener id passed |
bool HttpServer::HttpServer::removeHandlerFromListenerID | ( | softstring | id, |
string | handler_name | ||
) |
remove request handler from a listener given the listener's id
id | listener id |
handler_name | name of handler to remove; |
INVALID-LISTENER-ERROR | invalid listener id passed |
HttpServer::HttpServer::setListenerLogOptions | ( | softstring | bind, |
softint | code | ||
) |
turns on or off header and body logging options for receive operations for the given listener
bind | the name of the listener or bind string |
code | a binary-or'ed product of listener log options; bits set enable logging; bits not set disable logging |
HttpServer::HttpServer::setListenerLogOptionsID | ( | softint | id, |
softint | code | ||
) |
turns on or off header and body logging options for receive operations for the given listener
id | the unique listener ID |
code | a binary-or'ed product of listener log options; bits set enable logging; bits not set disable logging |
INVALID-LISTENER-ERROR | invalid listener id passed |
HttpServer::HttpServer::setMaskCode | ( | code | maskfunc | ) |
sets the closure or call reference that will be used to mask sensitive data in log messages
maskfunc | a closure or call reference that takes a single string argument and returns the masked string |
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
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
bind | listener bind address |
INVALID-LISTENER-ERROR | invalid listener bind address |
HTTP-SERVER-ERROR | cannot stop last listener |
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
id | listener id |
INVALID-LISTENER-ERROR | invalid listener ID |
HTTP-SERVER-ERROR | cannot stop last listener |
HttpServer::HttpServer::stopListenerIDNoWait | ( | softint | id | ) |
starts the shutdown process for a listener based on its listener ID; returns immediately
id | listener id |
INVALID-LISTENER-ERROR | invalid listener ID |
HTTP-SERVER-ERROR | cannot stop last listener |
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