All Classes Namespaces Functions Variables Groups Pages
HttpServer::HttpServer Class Reference

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

Inheritance diagram for HttpServer::HttpServer:
[legend]

## Public Member Functions

| addHandlerToListener (softstring bind, 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 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, 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
| addHandlerToListenerID (softint id, string name, HttpServer::AbstractUrlHandler obj)
| adds a request handler to a listener given the listener's id
list | addINETListeners (*string node, softstring service, *string cert_path, *string key_path, *string name, int family=AF_UNSPEC, *string pwd)
| adds one or more global listeners according to the bind address More...
hash | addListener (softstring sock, *string cert_path, *string key_path, *string name, int family=AF_UNSPEC, *string pwd)
| adds a global listener to the server More...
final list | addListeners (string bind, hash lp, *code logger, *code errorlogger, *code stopc, *string name, int family=AF_UNSPEC)
| adds a dedicated listener to the server with an explicit/dedicated handler for incoming connections More...
softlist | addListeners (softstring sock, *string cert_path, *string key_path, *string name, int family=AF_UNSPEC, *string pwd)
| adds one or more global listeners according to the bind address More...
final list | addListenersWithHandler (string hname, HttpServer::AbstractHttpRequestHandler handler, hash lp, *code logger, *code errorlogger, *code stopc, *string name, int family=AF_UNSPEC)
| adds a dedicated listener to the server with an explicit/dedicated handler for incoming connections More...
| constructor (*code n_logfunc, *code n_errlogfunc, bool n_dbg=False, string n_name=HttpServer::HttpServerString, hash n_hdr=("X-Powered-By":"Qore/"+Qore::VersionString))
| creates the HttpServer More...
| copy ()
| throws an exception; these objects do not support copying
| destructor ()
| calls stop() and destroys the object
bool | getDebug ()
| returns the current status of the debug flag
int | getListenerCount ()
| returns the number of running HTTP listeners
hash | getListenerInfo (softint id)
| returns a hash of information about the listener given the listener ID More...
hash | 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 | getListeners ()
| returns a hash of listener information More...
int | getListenerTID (softint id)
| gets the TID of a listener based on its listener ID
| listenerStarted (int id, hash 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...
| removeDynamicHandler (string name)
| remove dynamic handler
| sendHttpError (HttpListener listener, hash cx, Socket s, int code, string msg, *hash extra_hdrs, *string encoding)
| 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, string path, *softlist content_type, HttpServer::AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex=True)
| 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
| setHandler (string name, string path, *softlist content_type, HttpServer::AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex=True)
| sets a request handler according to the arguments given
| setHandler (string name, HttpServer::AbstractUrlHandler obj)
| 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...
| 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
| stopListenerID (softint id)
| stops a single listener based on its listener ID; does not return until all connections on the listener have closed
| 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 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 More...
static nothing | setReplyHeaders (Socket s, hash cx, reference< hash > 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 | HttpCodes = HttpServer::HttpCodes
| map of HTTP result codes and text messages
const | HttpMethods
| supported HTTP methods
const | LLO_RECV_BODY = (1 << 1)
| listener log option: log recv message body
const | LLO_RECV_HEADERS = (1 << 0)
| listener log option: log recv headers
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 = 5000
| 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 Functions

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

list HttpServer::HttpServer::addINETListeners | ( | *string | node,
|  | softstring | service,
|  | *string | cert_path,
|  | *string | key_path,
|  | *string | name,
|  | int | family = `AF_UNSPEC`,
|  | *string | pwd
| ) |  |

adds one or more global listeners according to the bind address

Parameters

  node | the bind address for the listener; if not given then the listener will be bound on all interfaces
  service | a service name (which will be lookup up to derive a port number) or port number to bind on
  cert_path | an optional path to an X509 certificate for HTTPS listeners
  key_path | an optional path to a private key file for an X509 certificate for HTTPS listeners
  name | an optional name fo the listener

  family

  one of the following network family constants:
  - AF_INET: for binding an IPv4 socket
  - AF_INET6: for binding an IPv6 socket
  - AF_UNSPEC: for binding a socket with any available address family

  pwd | an optional password for the private key file (PEM format only)

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-ERROR | duplicate bind address

hash HttpServer::HttpServer::addListener | ( | softstring | sock,
|  | *string | cert_path,
|  | *string | key_path,
|  | *string | name,
|  | int | family = `AF_UNSPEC`,
|  | *string | pwd
| ) |  |

adds a global listener to the server

Parameters

  sock | the bind address for the listener
  cert_path | an optional path to an X509 certificate for HTTPS listeners
  key_path | an optional path to a private key file for an X509 certificate for HTTPS listeners
  name | an optional name for the listener; the actual listener name will have the listener id appended to it and will be returned in the `"name"` key in each hash element in the return value for each listener started

  family

  one of the following network family constants:
  - AF_INET: for binding an IPv4 socket
  - AF_INET6: for binding an IPv6 socket
  - AF_UNSPEC: for binding a socket with any available address family

  pwd | an optional password for the private key file (PEM format only)

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-ERROR | duplicate bind address

Note
  if sock begins with a "/" character then it is assumed to be a UNIX socket path and the family argument is ignored

final list HttpServer::HttpServer::addListeners | ( | string | bind,
|  | hash | lp,
|  | *code | logger,
|  | *code | errorlogger,
|  | *code | stopc,
|  | *string | name,
|  | int | family = `AF_UNSPEC`
| ) |  |

adds a dedicated listener to the server with an explicit/dedicated handler for incoming connections

Parameters

  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"`)

  lp

  a hash with the following keys:
  - `cert_path:` (optional) a path to an X509 certificate for HTTPS listeners
  - `key_path:` (optional) a path to a private key file for an X509 certificate for HTTPS listeners
  - `key_password:` (optional) an optional string giving the password for the private key (PEM format only)
  - `cert:` (optional) a Qore::SSLCertificate object for HTTPS listeners
  - `key:` (optional) a Qore::SSLPrivateKey object for HTTPS listeners

  logger | an optional closure or call reference that will be called with logging information; if this is not set, then the logger set in the HttpServer::constructor() will be used instead
  errorlogger | an optional closure or call reference that will be called with error information; if this is not set, then the error logger set in the HttpServer::constructor() will be used instead
  stopc | an optional closure or call reference that will be called immediately after the listener is stopped
  name | an optional name for the listener; the actual listener name will have the listener id appended to it and will be returned in the `"name"` key in each hash element in the return value for each listener started

  family

  one of the following network family constants:
  - AF_INET: for binding an IPv4 socket
  - AF_INET6: for binding an IPv6 socket
  - AF_UNSPEC: for binding a socket with any available address family

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-ERROR | duplicate bind address

Note
  if `bind` begins with a "/" character then it is assumed to be a UNIX socket path and the family argument is ignored

Since
  HttpServer 0.3.11

softlist HttpServer::HttpServer::addListeners | ( | softstring | sock,
|  | *string | cert_path,
|  | *string | key_path,
|  | *string | name,
|  | int | family = `AF_UNSPEC`,
|  | *string | pwd
| ) |  |

adds one or more global listeners according to the bind address

Parameters

  sock | the bind address for the listener
  cert_path | an optional path to an X509 certificate for HTTPS listeners
  key_path | an optional path to a private key file for an X509 certificate for HTTPS listeners
  name | an optional name for the listener; the actual listener name will have the listener id appended to it and will be returned in the `"name"` key in each hash element in the return value for each listener started

  family

  one of the following network family constants:
  - AF_INET: for binding an IPv4 socket
  - AF_INET6: for binding an IPv6 socket
  - AF_UNSPEC: for binding a socket with any available address family

  pwd | an optional password for the private key file (PEM format only)

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-ERROR | duplicate bind address

Note
  if sock begins with a `"/"` character then it is assumed to be a UNIX socket path and the family argument is ignored

final list HttpServer::HttpServer::addListenersWithHandler | ( | string | hname,
|  | HttpServer::AbstractHttpRequestHandler | handler,
|  | hash | lp,
|  | *code | logger,
|  | *code | errorlogger,
|  | *code | stopc,
|  | *string | name,
|  | int | family = `AF_UNSPEC`
| ) |  |

adds a dedicated listener to the server with an explicit/dedicated handler for incoming connections

Parameters

  hname | the name of the handler
  handler | the HttpServer::AbstractHttpRequestHandler object that will handle incoming connections

  lp

  a hash with the following keys:
  - `cert_path:` (optional) a path to an X509 certificate for HTTPS listeners
  - `key_path:` (optional) a path to a private key file for an X509 certificate for HTTPS listeners
  - `key_password:` (optional) an optional string giving the password for the private key (PEM format only)
  - `cert:` (optional) a Qore::SSLCertificate object for HTTPS listeners
  - `key:` (optional) a Qore::SSLPrivateKey object for HTTPS listeners
  - `url:` (required) the path for matching incoming requests (use "/" for dedicated listeners); this is more important for handlers on the global listeners; this is a regular expression unless isregex is False
  - `isregex:` (optional) a boolean value determining if the url (= path value) is a regular expression or a simple string; if this key is not present, then url is assumed to the a regular expression
  - `bind:` (required) 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"`)
  - `content_type:` (optional) an optional string or list of string content types to match
  - `special_headers:` (optional) a string or a list of strings giving special headers that when matched will direct requests to the given handler

  logger | an optional closure or call reference that will be called with logging information; if this is not set, then the logger set in the HttpServer::constructor() will be used instead
  errorlogger | an optional closure or call reference that will be called with error information; if this is not set, then the error logger set in the HttpServer::constructor() will be used instead
  stopc | an optional closure or call reference that will be called immediately after the listener is stopped
  name | an optional name for the listener; the actual listener name will have the listener id appended to it and will be returned in the `"name"` key in each hash element in the return value for each listener started

  family

  one of the following network family constants:
  - AF_INET: for binding an IPv4 socket
  - AF_INET6: for binding an IPv6 socket
  - AF_UNSPEC: for binding a socket with any available address family

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

  SETHANDLER-ERROR | HTTP request handler already exists with the given name; non-string entry in special_header list
  HTTPSERVER-ADDLISTENER-ERROR | missing or invalid `"bind"` or `"url"` entry in the `lp` argument; duplicate bind address

Note
  if `bind` begins with a "/" character then it is assumed to be a UNIX socket path and the family argument is ignored

HttpServer::HttpServer::constructor | ( | *code | n_logfunc,
|  | *code | n_errlogfunc,
|  | bool | n_dbg = `False`,
|  | string | n_name = `HttpServer::HttpServerString`,
|  | hash | n_hdr = `("X-Powered-By":"Qore/"+Qore::VersionString)`
| ) |  |

creates the HttpServer

call addListener() to add and start listeners

Parameters

  n_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); }
  n_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); }
  n_dbg | if this parameter is set to True, then additional information will be logged when errors occur
  n_name | the name of the HTTP server as returned in the Server header (should be formatted according to RFC 2616 section 3.8 http://tools.ietf.org/html/rfc2616#section-3.8)
  n_hdr | a hash of headers to return in every response by default; to clear the default send an empty hash as the argument here

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

private

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

Exceptions

  HTTP-SERVER-ERROR | unknown bind name

hash HttpServer::HttpServer::getListenerInfo | ( | softint | id | ) |

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

Parameters

  id | the 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

  HTTP-SERVER-ERROR | invalid listener ID

hash HttpServer::HttpServer::getListenerInfoName | ( | string | name | ) |

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

Parameters

  name | the 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

  HTTP-SERVER-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

Since
  HttpServer 0.3.11

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

Since
  HttpServer 0.3.11

hash 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

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

static

returns a complete URL from a bind address

Parameters

  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

Note
  reexported from HttpServerUtil::get_url_from_bind()

HttpServer::HttpServer::listenerStarted | ( | int | id,
|  | hash | sinfo
| ) |  |

called from listener when the actual listener thread is running

Parameters

  id | the listener ID
  sinfo | a socket information hash as returned by Qore::Socket::getSocketInfo()

Since
  HttpServer 0.3.11

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

masks log messages by removing sensitive data

See Also
  setMaskCode()

Since
  HttpServer 0.3.12

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

  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

Since
  HttpServer 0.3.11

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

  id | the unique listener ID
  code | a binary-or'ed product of listener log options; bits set enable logging; bits not set disable logging

Since
  HttpServer 0.3.11

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

  maskfunc | a closure or call reference that takes a single string argument and returns the masked string

See Also
  maskData()

Since
  HttpServer 0.3.12

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::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