| Qore HttpServer Module Reference 1.4

Loading...
Searching...
No Matches
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
| 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 status_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

## Detailed Description

The HttpServer class implements a multithreaded HTTP server.

## Member Function Documentation

## ◆ addHandlerToListenerID() [1/3]

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

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

Parameters

  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
  special_headers | headers to match
  isregex | is the path a regular expression

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

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

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

adds a single global listener to the server

Parameters

  port | the port number

Returns
  a listener info hash; see the return value of HttpServer::HttpServer::getListenerInfo() for the description of the hash returned by this method

Exceptions

  HTTPSERVER-ADDLISTENER-ERROR | invalid options; duplicate bind address

## ◆ addListeners() [1/2]

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

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

Parameters

  info | a listener information hash
  errmap | an optional reference to a hash of error information keyed by bind address

Returns
  a list of listener info hashes; see the return value of HttpServer::getListenerInfo() for the description of each hash element in the list returned by this method

Exceptions

  HTTPSERVER-ADDLISTENER-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/2]

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

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

Parameters

  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

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

## ◆ clearContextInfo()

HttpServer::HttpServer::clearContextInfo | ( |  | ) |

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

Reimplement in subclasses if necessarily

Since
  HttpServer 1.1.2

## ◆ constructor() [1/2]

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

creates the HttpServer

call addListener() to add and start listeners

Parameters

  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

Note
  A new Logger object is created for the HTTP server using either logfunc or errfunc; if both are given then only logfunc is used and all log messages (including errors) are directed to logfunc. The Logger object's logging level is set according to which of these parameters is included. If neither are included, then no logging is performed

Deprecated
  use constructor(hash<HttpServerOptionInfo>) instead

## ◆ constructor() [2/2]

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

Creates the server with the given options.

Parameters

  opts | see HttpServerOptionInfo for more info

## ◆ disableDynamicHandler()

HttpServer::HttpServer::disableDynamicHandler | ( | string | name | ) |

Disable dynamic handler.

Exceptions

  DISABLEHANDLER-ERROR | if the given dynamic handler does not exist

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

## ◆ reloadListenerCertificate()

HttpServer::HttpServer::reloadListenerCertificate | ( | int | id | ) |

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

Parameters

  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

Exceptions

  REFRESH-CERTIFICATE-ERROR | not an HTTPS listener or certificate location information not present

Since
  HttpServer 1.1

## ◆ reloadListenerCertificateName()

HttpServer::HttpServer::reloadListenerCertificateName | ( | string | name | ) |

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

Parameters

  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

Exceptions

  REFRESH-CERTIFICATE-ERROR | not an HTTPS listener or certificate location information not present

Since
  HttpServer 1.1

## ◆ removeDynamicHandler()

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

remove dynamic handler

Exceptions

  REMOVEHANDLER-ERROR | if the given dynamic handler does not exist

## ◆ removeHandlerFromListenerID() [1/2]

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

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

Parameters

  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

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

## ◆ stopListenerIDNoWait()

HttpServer::HttpServer::stopListenerIDNoWait | ( | softint | id | ) |

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

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