![]() |
Qore HttpServer Module Reference 1.3
|
The HttpServer class implements a multithreaded HTTP server. More...
Public Member Functions | |
| 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 | |
| addHandlerToListenerID (softint id, string name, HttpServer::AbstractUrlHandler obj) | |
| adds a request handler to a listener given the listener's id | |
| 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 | |
| addHttpMethod (string m) | |
| add a new supported HTTP method | |
| hash< auto > | addListener (hash< HttpListenerOptionInfo > opts) |
| adds a single global listener to the server | |
| hash< auto > | addListener (int port) |
| adds a single global listener to the server | |
| 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 | |
| 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 | |
| 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. | |
| 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 | |
| constructor (hash< HttpServerOptionInfo > opts) | |
| Creates the server with the given options. | |
| copy () | |
| throws an exception; these objects do not support copying | |
| destructor () | |
| calls stop() and destroys the object | |
| disableDynamicHandler (string name) | |
| Disable dynamic handler. | |
| 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 | |
| hash< auto > | getListenerInfoName (string name) |
| returns a hash of information about the listener given the listener name or bind ID | |
| int | getListenerLogOptions (softstring bind) |
| returns a binary-or'ed product of listener log options corresponding to enabled log options for the given listener | |
| int | getListenerLogOptionsID (softint id) |
| returns a binary-or'ed product of listener log options corresponding to enabled log options for the given listener | |
| hash< string, hash< auto > > | getListeners () |
| returns a hash of listener information | |
| 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 | |
| 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 | |
| reloadListenerCertificate (int id) | |
| Reloads an HTTPS certificate from the original location for the given listener from the listener ID. | |
| reloadListenerCertificateName (string name) | |
| Reloads an HTTPS certificate from the original location for the given listener from the listener name. | |
| removeDynamicHandler (string name, *bool force_immediate) | |
| remove dynamic handler | |
| bool | removeHandlerFromListenerID (softstring id, HttpServer::AbstractHttpRequestHandler handler) |
| remove request handler from a listener given the listener's id | |
| bool | removeHandlerFromListenerID (softstring id, string handler_name) |
| remove request handler from a listener given the listener's id | |
| 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 | |
| setListenerLogOptionsID (softint id, softint code) | |
| turns on or off header and body logging options for receive operations for the given listener | |
| setMaskCode (code maskfunc) | |
| sets the closure or call reference that will be used to mask sensitive data in log messages | |
| setTtl (date ttl) | |
| Sets the connection TTL value. | |
| stop () | |
| stops all listeners; only returns when all connections are closed on all listeners | |
| 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 | |
| stopListenerID (softint id) | |
| stops a single listener based on its listener ID; does not return until all connections on the listener have closed | |
| stopListenerIDNoWait (softint id) | |
| starts the shutdown process for a listener based on its listener ID; returns immediately | |
| stopNoWait () | |
| stops all listeners; does not wait for all connections on the listeners to close | |
| waitStop () | |
| waits for all listeners to be stopped; call after calling HttpServer::stopNoWait() | |
Static Public Member Functions | |
| static string | getHttpServerVersionString () |
| returns the HTTP server version string | |
| static string | getURLFromBind (softstring bind, *string host) |
| returns a complete URL from a bind address | |
| 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 | |
Protected Member Functions | |
| int | getListenerIdFromBindUnlocked (string bind) |
| returns the listener ID from the bind name or throws an exception if not valid | |
| 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 ignored| 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
| 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 ignored| 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
| 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 |
|
protected |
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 used| INVALID-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 used| INVALID-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