| Qore HttpServer Module Reference 0.9.5

Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | List of all members
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, 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
deprecated | addHandlerToListener (softstring bind, string name, string path, *softlist< softstring > content_types, HttpServer::AbstractHttpRequestHandler obj, *softlist< softstring > special_headers, bool isregex=True)
| adds a request handler to a listener given the listener's name or bind address More...
| 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...
deprecated list< hash< auto > > | 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< auto > | addListener (hash< HttpListenerOptionInfo > opts)
| adds a single global listener to the server More...
deprecated hash< auto > | addListener (softstring bind, *string cert_path, *string key_path, *string name, int family=AF_UNSPEC, *string pwd)
| adds a single global listener to the server More...
final list< hash< auto > > | addListeners (hash< HttpListenerOptionInfo > info)
| adds one or more dedicated listeners to the server with the given bind address More...
deprecated softlist< hash< auto > > | addListeners (softstring bind, *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< hash< auto > > | addListeners (string bind, hash< auto > lp, *code logger, *code errorlogger, *code stopc, *string name, int family=AF_UNSPEC)
| adds a dedicated listener to the server More...
final list< hash< auto > > | addListeners (string bind, hash< HttpListenerOptionInfo > info)
| adds one or more dedicated listeners to the server with the given bind address More...
deprecated final list< hash< auto > > | addListenersWithHandler (string hname, HttpServer::AbstractHttpRequestHandler handler, hash< auto > 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 logfunc, *code errlogfunc, bool dbg=False, string name=HttpServer::HttpServerString, hash< auto > 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< 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
| 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...
| removeDynamicHandler (string name)
| remove dynamic handler
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...
| 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...
| 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< auto > 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 = ...
| HTTP methods supported by default.
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

## Protected 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

## ◆ addHandlerToListener()

deprecated HttpServer::HttpServer::addHandlerToListener | ( | softstring | bind,
|  | string | name,
|  | string | path,
|  | *softlist< softstring > | content_types,
|  | HttpServer::AbstractHttpRequestHandler | obj,
|  | *softlist< softstring > | special_headers,
|  | bool | isregex = `True`
| ) |  |

adds a request handler to a listener given the listener's name or bind address

Deprecated:
  use addHandlerToListener(softstring, string, hash<HttpHandlerConfigInfo>) instead

## ◆ 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

  id | listener id
  name | handler name
  info | the handler configuration info to add to the listener

Exceptions

  INVALID-LISTENER-ERROR | invalid 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

  id | listener id
  name | handler name
  obj | handler object

Exceptions

  INVALID-LISTENER-ERROR | invalid 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

  id | listener id
  name | handler name
  path | handler path
  content_type | handler's content type
  obj | handler object

Exceptions

  INVALID-LISTENER-ERROR | invalid listener id passed

## ◆ addHttpMethod()

HttpServer::HttpServer::addHttpMethod | ( | string | m | ) |

add a new supported HTTP method

Parameters

  m | the HTTP method to add; the string is converted to upper case if necessary

## ◆ addINETListeners()

deprecated list<hash<auto> > 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

Deprecated:
  use addINETListeners(hash<HttpListenerOptionInfo>) instead

## ◆ addListener() [1/2]

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

adds a single global listener to the server

Parameters

  opts | the 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-ERROR | invalid 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]

deprecated hash<auto> HttpServer::HttpServer::addListener | ( | softstring | bind,
|  | *string | cert_path,
|  | *string | key_path,
|  | *string | name,
|  | int | family = `AF_UNSPEC`,
|  | *string | pwd
| ) |  |

adds a single 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

Deprecated:
  use addListener(string, hash<HttpListenerOptionInfo>) instead

## ◆ addListeners() [1/4]

final list<hash<auto> > HttpServer::HttpServer::addListeners | ( | hash< HttpListenerOptionInfo > | info | ) |

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

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

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 key of the info hash is ignored

Since
  HttpServer 0.3.13.1

## ◆ addListeners() [2/4]

deprecated softlist<hash<auto> > HttpServer::HttpServer::addListeners | ( | softstring | bind,
|  | *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

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

Deprecated:
  use addListeners(string, hash<HttpListenerOptionInfo>) instead

## ◆ addListeners() [3/4]

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

adds a dedicated listener to the server

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

Deprecated:
  use addListeners(string, hash<HttpListenerOptionInfo>) instead

## ◆ addListeners() [4/4]

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

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

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

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 key of the info hash is ignored

Since
  HttpServer 0.3.13.1

## ◆ addListenersWithHandler()

deprecated final list<hash<auto> > HttpServer::HttpServer::addListenersWithHandler | ( | string | hname,
|  | HttpServer::AbstractHttpRequestHandler | handler,
|  | hash< auto > | 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

Deprecated:
  use addListeners(string, hash<HttpListenerOptionInfo>) instead

## ◆ constructor()

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

  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

## ◆ getListenerIdFromBindUnlocked()

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

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

Exceptions

  INVALID-LISTENER-ERROR | invalid listener bind address

## ◆ getListenerInfo()

hash<auto> 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

  INVALID-LISTENER-ERROR | invalid 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

  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

  INVALID-LISTENER-ERROR | invalid 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-ERROR | invalid 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-ERROR | invalid 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

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

  id | the listener ID
  sinfo | a 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

## ◆ removeHandlerFromListenerID() [1/2]

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

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

Parameters

  id | listener id
  handler | handler to remove;

Returns
  whether listener was stopped

Exceptions

  INVALID-LISTENER-ERROR | invalid 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

  id | listener id
  handler_name | name of handler to remove;

Returns
  whether listener was stopped

Exceptions

  INVALID-LISTENER-ERROR | invalid 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

  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

## ◆ 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

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

Exceptions

  INVALID-LISTENER-ERROR | invalid 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

  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

## ◆ 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

  id | listener bind address

Exceptions

  INVALID-LISTENER-ERROR | invalid listener bind address
  HTTP-SERVER-ERROR | cannot 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

  id | listener id

Exceptions

  INVALID-LISTENER-ERROR | invalid listener ID
  HTTP-SERVER-ERROR | cannot 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

vprintf
string vprintf(string fmt, auto varg)